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.

Multi-file projects

capnp compile -opy --src-prefix=. src/schema.capnp

Cross-file type references automatically produce relative imports in the generated stubs.

Example

Input (addressbook.capnp):

struct Person {
  name @0 :Text;
  age  @1 :Int32;
  phones @2 :List(PhoneNumber);

  struct PhoneNumber {
    number @0 :Text;
    type @1 :Type;
    enum Type { mobile @0; home @1; work @2; }
  }
}

Output (addressbook_capnp.pyi):

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

class Person:
    name: str
    age: int
    phones: Sequence[Person.PhoneNumber | Person.PhoneNumberBuilder | Person.PhoneNumberReader]

    class PhoneNumber:
        Type = Literal["mobile", "home", "work"]
        type: Type
        number: str
        ...

    @staticmethod
    def new_message(**kwargs) -> PersonBuilder: ...
    def to_dict(self) -> dict: ...

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

class PersonBuilder(Person):
    def to_bytes(self) -> bytes: ...
    def as_reader(self) -> PersonReader: ...
    ...

Supported Features

Feature	Status
Structs (Reader / Builder classes)	✅
Enums (Literal[...] aliases)	✅
Nested types	✅
Lists (Sequence[T])	✅
Unions (which() / @overload init())	✅
Groups	✅
Self-referencing structs	✅
Constants (primitives, enums)	✅
Generics (TypeVar, Generic[T], brand resolution)	✅
Interfaces (RPC: Client / Server classes)	✅
Cross-file imports (relative . imports)	✅
Annotations ($Cxx.name, etc.)	⏳

Development

Uses PDM for project management.

git clone https://github.com/NCBM/capnpc-py
cd capnp-py
pdm install      # installs dependencies + dev tools
pdm run pytest   # run tests

License

MIT