# 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) |

## 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.

### Generated output

For a schema like:
```capnp
struct Person {
  name @0 :Text;
  age  @1 :Int32;
}

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

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

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