124 lines
3.0 KiB
Markdown
124 lines
3.0 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/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
|