116 lines
2.8 KiB
Markdown
116 lines
2.8 KiB
Markdown
# 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
|