pycapnp is a Python wrapper for the C++ implementation of the Cap'n Proto data interchange format and RPC system. It provides insanely fast serialization and deserialization, often outperforming Protocol Buffers. The library is actively maintained, with regular releases bringing performance improvements, new features, and compatibility updates.
pip install pycapnpVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to define a Cap'n Proto schema (dynamically for brevity), build a message by initializing a root object and its fields, and then serialize and deserialize it. It highlights the use of `capnp.load()` for schemas, initializing structs and lists, and safely reading messages using `capnp.alloc_builder()` and `capnp.alloc_reader()` context managers.
Migrate all RPC implementations and calls to use Python's `asyncio` event loop. Refer to the updated RPC documentation and examples.
Upgrade your Python environment to Python 3.8 or newer.
Ensure you have a C++14 compatible compiler (GCC 6.1+, Clang 6+, MSVC 2017+) and Python development headers. If facing issues, consider pre-installing the C++ Cap'n Proto library (version 1.0+) or explicitly controlling the bundling process during installation (e.g., `pip install . -C force-bundled-libcapnp=True`).
Always use `with capnp.alloc_builder() as builder:` or `with capnp.alloc_reader(data) as reader:` patterns when interacting with Cap'n Proto messages.
For current versions (>=2.0.0) running Python 3.8+, 'Text' fields are unicode strings. Ensure proper encoding/decoding if interfacing with older systems or different language bindings.
Ensure you have a C++14 compatible compiler (e.g., GCC 6+ or Clang 6+), CMake, and Ninja installed. On Linux, also ensure Python development headers are installed (e.g., `sudo apt-get install python3-dev` for Python 3). If `pycapnp` still fails to build, try forcing it to bundle the C++ Cap'n Proto library: `pip install pycapnp --no-binary :all: -C force-bundled-libcapnp=True`.
After defining your schema in a `.capnp` file (e.g., `myschema.capnp`), you need to compile it into a Python module. This is usually done by importing it directly in your Python code, which triggers `pycapnp`'s import hook to compile it: `import myschema_capnp` (assuming `myschema.capnp` exists in the Python path or current directory).
Ensure proper object ownership and lifecycle, especially with readers and builders. Avoid accessing union members without first checking `which()`. For RPC, ensure the event loop is running correctly, and if experiencing issues with older versions, update `pycapnp` to the latest version, as many memory-related bugs and segfaults have been addressed in recent releases.
When installing, explicitly tell `pip` to use `libc++` by setting environment variables: `export CXXFLAGS="-stdlib=libc++" && export CFLAGS="-stdlib=libc++" && pip install pycapnp`.