capnpc-py

Cap'n Proto Python type stub generator — a capnp compile plugin.

Generates .pyi type stub files for Cap'n Proto schemas, providing IDE autocompletion and static type checking support via Pyright/Pylance.

Requirements

• Python >= 3.10
• pycapnp >= 2.0.0 (Python package, installed automatically)
• Cap'n Proto >= 1.0 (system package, must be installed separately)

Installing Cap'n Proto

Platform	Command
Arch Linux	sudo pacman -S capnproto
Ubuntu/Debian	sudo apt install capnproto
macOS	brew install capnp
Windows	Download from capnproto.org

Installation

pip install capnpc-py

Usage

capnp compile -opy myschema.capnp

This generates myschema_capnp.pyi — a Python type stub file that type checkers can use. Runtime import (import myschema_capnp) is handled automatically by pycapnp's import hook.

Generated output

For a schema like:

struct Person {
  name @0 :Text;
  age  @1 :Int32;
}

enum Gender { male @0; female @1; }

myschema_capnp.pyi:

"""Auto-generated type stub for myschema.capnp"""
from __future__ import annotations
from collections.abc import Iterator, Sequence
from contextlib import contextmanager
from typing import IO, Literal

Gender = Literal["male", "female"]

class Person:
    name: str
    age: int

    @staticmethod
    def new_message(**kwargs) -> PersonBuilder: ...
    @staticmethod
    @contextmanager
    def from_bytes(data: bytes, ...) -> Iterator[PersonReader]: ...
    @staticmethod
    def from_bytes_packed(data: bytes, ...) -> PersonReader: ...
    def to_dict(self) -> dict: ...

class PersonReader(Person):
    def as_builder(self) -> PersonBuilder: ...

class PersonBuilder(Person):
    @staticmethod
    def from_dict(dictionary: dict) -> PersonBuilder: ...
    def copy(self) -> PersonBuilder: ...
    def to_bytes(self) -> bytes: ...
    def to_bytes_packed(self) -> bytes: ...
    def to_segments(self) -> list[bytes]: ...
    def as_reader(self) -> PersonReader: ...
    @staticmethod
    def write(file: IO[bytes]): ...
    @staticmethod
    def write_packed(file: IO[bytes]): ...

Development

Uses PDM for project management.

git clone https://github.com/capnproto/pycapnp  # or your fork
cd capnp-py
pdm install      # installs dependencies + dev tools
pdm run pytest   # run tests

Supported Features

Feature	Status
Structs (Reader/Builder classes)	✅
Enums (Literal aliases)	✅
Nested types	✅
Lists (Sequence[T])	✅
Unions (which/init)	✅
Self-referencing structs	✅
Interfaces (RPC)	⏳ Phase 3
Constants	⏳ Phase 2
Generics	⏳ Phase 2

License

MIT