capnpc-py/README.md

# 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](https://capnproto.org/install.html) |

## Installation

```bash
pip install capnpc-py
```

## Usage

```bash
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

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

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

## Example

Input (`addressbook.capnp`):
```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`):
```python
"""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](https://pdm-project.org/) for project management.

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

## License

MIT