rylai 0.3.3

Generate Python .pyi stub files from pyo3-annotated Rust source code statically without compilation

Rylai

Generate Python .pyi stub files from pyo3-annotated Rust source code — statically, without compilation.

Features

• Parses #[pymodule], #[pyfunction], and #[pyclass] annotations directly from Rust source
• Maps Rust types to Python types automatically (i32 → int, Vec<T> → list[T], Option<T> → T | None, etc.)
• Extracts doc comments and emits them as Python docstrings
• Generates one .pyi file per top-level #[pymodule]; when classes use #[pyclass(module = "...")], emits additional sibling .pyi files under -o (first module segment is implicit) so type checkers and runtime __module__ agree
• Python-version-aware output (T | None for ≥ 3.10, t.Optional[T] for older; t.Self for ≥ 3.11; stubs always include import typing as t for consistent [[add_content]] placement)
• Generates __all__ in every stub listing public top-level exports; names starting with _ are excluded by default; configurable globally and per file via [[all]]
• Optional [[add_content]]: inject extra Python (e.g. version branches, shared type aliases) into specific generated .pyi files by path under -o
• Zero-config by default; optionally configured via rylai.toml

Why Rylai?

Compared with other tools that generate .pyi stubs for PyO3 projects, Rylai offers:

• No compilation — Rylai parses Rust source code directly (via syn). You don’t need to build the crate or depend on compiled artifacts, so stub generation is fast and works even when the project doesn’t compile (e.g. missing native deps or wrong toolchain).
• No code changes — No need to add build scripts, #[cfg] blocks, or extra annotations to your Rust code. Point Rylai at your crate root and it reads existing #[pymodule] / #[pyfunction] / #[pyclass] as-is.
• No Python version lock-in — Stubs are plain text. You generate them once and use them with any Python version; there’s no dependency on a specific Python interpreter or ABI, so you avoid “built for Python 3.x” issues and cross-version workflows stay simple.

Together, this makes Rylai easy to integrate into CI, docs, or local dev without touching your PyO3 code or your Python environment.

Installation

Choose one of the following:

Method	Command	Notes
Cargo	cargo install rylai	Build from source and install to ~/.cargo/bin
uv	uv tool install rylai	Install to uv tools dir; requires publish to PyPI first
uvx	uvx rylai	Run without installing (same as uv; requires PyPI release)
crgx	crgx rylai	Run pre-built binary without compiling; requires crgx and a GitHub Release

For local development:

cargo install --path .

Usage

The path you pass is the project root — the folder that contains Cargo.toml (and usually a src/ directory). Rylai scans all .rs files under that project’s src/ and uses the root for rylai.toml, pyproject.toml, etc.

# Run in the current directory (must be the project root with Cargo.toml)
rylai

# Specify the project root explicitly (folder containing Cargo.toml)
rylai path/to/my_crate

# Write stubs to a custom output directory
rylai path/to/my_crate --output path/to/out/

# Use a custom config file
rylai --config path/to/rylai.toml

For developers (this repo)

You don’t need to install the binary. Use cargo run and pass arguments after --:

# Default: writes .pyi files into the example crate root (examples/pyo3_sample/)
cargo run -- examples/pyo3_sample

# Recommended for this repo: stubs next to the Python package (Maturin `python-source` layout)
cargo run -- examples/pyo3_sample --output examples/pyo3_sample/python/pyo3_sample

# Show help
cargo run -- --help

Anything after -- is forwarded to the rylai binary.

Example

The crate under examples/pyo3_sample/ has two #[pyclass] types in submodules pyo3_sample.aa and pyo3_sample.bb, with methods that return the other type (to exercise cross-stub imports). After:

cargo run -- examples/pyo3_sample --output examples/pyo3_sample/python/pyo3_sample

you get pyo3_sample.pyi (top-level functions) together with aa.pyi and bb.pyi in the output directory. Submodule stubs use absolute imports such as from pyo3_sample.bb import B so Pyright/mypy resolve pyo3_sample.aa / pyo3_sample.bb. For example aa.pyi contains:

from pyo3_sample.bb import B

__all__ = [
    "A",
]

@t.final
class A:
    def make_b(self) -> B: ...

See examples/pyo3_sample/src/lib.rs for the full Rust source.

Multi-module stubs (#[pyclass(module = "...")])

If you annotate a class with PyO3’s module attribute, e.g. #[pyclass(module = "abcd.efg")], Rylai will emit multiple .pyi files instead of a single flat stub. -o is treated as the first segment of the Python module path (the top-level #[pymodule] name). So for -o stubs/ and pymodule abcd, submodule abcd.efg is written to stubs/efg.pyi, not stubs/abcd/efg.pyi. The root stub is stubs/abcd.pyi. Only deeper paths add folders after that first segment (e.g. abcd.abcd.ff → abcd/ff.pyi under -o; abcd.abcd.abcd.gg → abcd/abcd/gg.pyi). If #[pyclass(module = "pkg.pkg")] resolves to the same file as the root stub (pkg.pyi), those classes are merged into pkg.pyi. If no class has module set, behavior is unchanged: one {name}.pyi per top-level #[pymodule]. If everything is routed to submodules so the root stub would be empty, Rylai still writes abcd.pyi (possibly empty, but still carrying the pymodule docstring when present).

When #[pyclass(module = "...")] does not start with {pymodule}. (for example pymodule _pkg and module = "pkg.abc"), the extension name and the public Python package can differ: Rylai still collects items from that #[pymodule], but emits those classes by dropping the first dotted segment of module (the public top-level package) and mirroring the rest under -o — e.g. stubs/abc.pyi, or stubs/cba/foo.pyi for pkg.cba.foo. #[pyfunction] and classes without module stay in {pymodule}.pyi (e.g. stubs/_pkg.pyi).

When using --output / -o, you can point either at a parent directory (e.g. stubs/ → stubs/abcd.pyi and stubs/efg.pyi) or directly at the package directory whose name matches the top-level #[pymodule] (e.g. -o python/abcd → python/abcd/abcd.pyi and python/abcd/efg.pyi). If two different layout paths still resolve to the same output file, Rylai reports a duplicate-path error; point -o at a parent directory so distinct stubs land on different paths.

Runtime __module__ for pyfunction / m.add may follow Maturin’s module-name (e.g. abcd.abcd), but Rylai still emits those symbols into the top-level #[pymodule] stub (abcd.pyi) together with any #[pyclass] that has no module = "..." attribute. Only classes with an explicit #[pyclass(module = "...")] are written to the matching submodule stub.

When a stub references a #[pyclass] type that is emitted in another submodule (e.g. a return type uses a class defined under abcd.ff while generating ee.pyi), Rylai prepends absolute imports such as from abcd.ff import SomeClass (after typing / pathlib imports) so Pyright and mypy can resolve the name.

Configuration

You can configure rylai in either (or both) of these places:

• rylai.toml in the crate root
• [tool.rylai] in pyproject.toml

When both exist, duplicate keys are resolved in favor of rylai.toml; all other options from both files apply. Array tables (e.g. [[override]], [[add_content]], [[all]], and their [[tool.rylai.*]] forms) are replaced as a whole by the same key in rylai.toml, not merged item-by-item. All sections are optional.

Example rylai.toml:

# Root-level keys (e.g. format) should appear before any [section] or [[array]] to avoid being parsed as part of a table.
# After generating .pyi files, run these commands with the generated .pyi paths appended.
# Only use when you trust this config file — commands are executed as configured.
# Each command must be executable (on PATH or use a full path); rylai will error if it cannot be run.
# Empty or whitespace-only entries are ignored.
# You may need "uvx ruff" or "uv/pdm run ruff" instead of "ruff"
format = ["ruff format", "ruff check --select I --fix"]

[output]
# Target Python version — affects t.Optional[T] vs T | None syntax (default: "3.10")
python_version = "3.10"

# Prepend auto-generated header comment (default: true)
add_header = true

# Include names that start with `_` (private / dunder) in __all__ (default: false).
# Can be overridden per file with [[all]].
all_include_private = false

[fallback]
# What to emit when a type cannot be resolved statically:
#   "any"   — emit t.Any and print a warning (default)
#   "error" — abort with an error
#   "skip"  — silently omit the item
strategy = "any"

[features]
# cfg features to treat as active during parsing
enabled = ["some_feature"]

[type_map]
# Custom Rust type → Python type overrides
"numpy::PyReadonlyArray1" = "numpy.ndarray"
"numpy::PyReadonlyArray2" = "numpy.ndarray"

# [type_map] limitations (read this if a mapping seems ignored):
# - Keys must be Rust *path* types: a single identifier (e.g. PyBbox, PyColor) or a qualified path
#   (e.g. crate::types::MyHandle). Rylai derives the lookup key from path segments only.
# - Anonymous tuple types written in source, e.g. (u8, u8, u8, u8), are *not* path types and
#   cannot appear as keys. They are always stubbed as tuple[...] from their elements. To emit a
#   single Python name (e.g. PyColor), define `type PyColor = (u8, u8, u8, u8);`, use `PyColor` in
#   signatures and fields, then add "PyColor" = "Color" under [type_map].
# - If a Rust `type` alias is listed here, Rylai keeps that alias name when generating stubs
#   (instead of expanding it), so nested uses like Vec<ThatAlias> still resolve to your Python type.
# - If two keys share the same last path segment but map to different Python types, Rylai warns on
#   stderr, omits the ambiguous short-name lookup, and does not preserve that alias name during
#   expansion (use a single consistent target or disambiguate with a bare key only when unique).

[[override]]
# Single-line def/class header for a top-level item (Rust `///` doc is copied into the .pyi when present).
# You do not need a trailing `...`; Rylai adds `    ...` as the body when there is no Rust doc.
# For `#[pyfunction]`, the last segment of `item` may be the Python-exposed name *or* the Rust `fn` ident
# (they differ when `#[pyo3(name = "...")]` is set), e.g. `tablers::get_intersections_from_edges` or
# `tablers::py_get_intersections_from_edges` for the same export.
item = "my_module::complex_function"
stub = "def complex_function(x: t.Any, **kwargs: t.Any) -> dict[str, t.Any]:"

# #[pyclass] / #[pymethods] methods: same `[[override]]` mechanism as top-level items.
# `item` is `{logical_module}::{class}::{method}` — instance methods, @staticmethod, @classmethod,
# @property / setter, and #[new] when you want a custom __init__ line in the .pyi.
#
# `logical_module` (first segment) is the **Python module for the .pyi file where that class is
# emitted**, not “always the #[pymodule] name”. It matches how Rylai splits output:
#   - Classes without #[pyclass(module = "...")] (and all module-level functions/constants) use the
#     top-level #[pymodule] name, e.g. `pkg` for `pkg.pyi`.
#   - A class with #[pyclass(module = "pkg.abc")] is emitted into that submodule’s stub; use the
#     **exact** `module = "..."` string as the first segment, e.g. `pkg.abc::MyClass::method`,
#     not `pkg::...` (unless layout merges that stub into the root file — then the root module name
#     applies).
# `class` may be the Rust struct name or the Python #[pyclass(name = "...")] name. `method` is the
# Rust fn ident or #[pyo3(name = "...")]. For #[new], Rylai already emits `def __init__(...)`;
# override when you need a different signature (e.g. **kwargs: Unpack[...]). You may match with
# `...::__init__` as the method segment for #[new] only.
# Suffix form: `item` may end with `::Class::method` (no bare method name — ambiguous).
[[override]]
item = "my_module::Widget::reload"
stub = "def reload(self, force: bool = False) -> None:"

# Instead of `stub`, you may set `param_types` and/or `return_type` (mutually exclusive with `stub`).
# `param_types`: table mapping parameter names → full annotation after `:`. `return_type`: one string
# for the whole return annotation. Rylai still builds `def ...` from Rust and `#[pyo3(signature)]`;
# parameter types come from Rust except where listed in `param_types`; return type from Rust unless
# `return_type` is set. Keys use the bare name (`kwargs` / `**kwargs` normalized the same). Only for
# module-level functions and class methods. Unused `param_types` keys → warning. `#[new]` / setters
# still emit `-> None` in stubs; `return_type` applies to other methods and to module functions.
# [[override]]
# item = "my_module::f"
# param_types = { "**kwargs" = "Unpack[KwargsItems]" }
# return_type = "dict[str, t.Any]"

# Optional: per-file __all__ rules (path is relative to -o, use /, same convention as add_content).
# Multiple [[all]] entries for the same file are merged (include/exclude sets are unioned;
# the last matching include_private wins).
[[all]]
file = "my_package.pyi"
# Override the global all_include_private for this file only (optional).
include_private = true
# Force these already-emitted top-level names into __all__ even if they start with `_` (optional).
include = ["_special_export"]
# Always remove these names from __all__ — highest priority, beats include (optional).
exclude = ["InternalHelper"]

# Optional: splice raw Python into a generated file (path is relative to -o, use /; must match a stub emitted in this run)
[[add_content]]
file = "my_package/sub.pyi"
location = "after-import-typing" # head | tail | after-import-typing
content = """
from my_package._internal import KwargsItems
"""

For class-method overrides, the first segment of item is the logical Python module of the stub file that contains that class: usually the #[pymodule] name for the root .pyi, or the full #[pyclass(module = "...")] string (e.g. pkg.abc) when Rylai emits a separate submodule stub — not the pymodule name in that case.

location:

• head — inserted right after the # Auto-generated by rylai... banner (and its following blank line), suitable for file-level notes or comments. If output.add_header is false so that banner is absent, the snippet is inserted at the very beginning of the file.
• after-import-typing — inserted immediately after the first line import typing as t (every stub includes this line; use ruff check --select F401 --fix if you need to drop an unused import — ruff format does not remove imports).
• tail — appended at end of file.

If file does not match any .pyi path produced in that run, Rylai exits with an error. Omit the .pyi suffix only when the last path segment has no extension; otherwise use the same relative names as under -o (e.g. pkg/aaa.pyi).

For each [[add_content]] entry, if content does not already end with a newline, Rylai appends one so you do not need to write a trailing \n in TOML (you may still include it if you prefer).

__all__ generation

Every generated stub includes an __all__ list of all top-level public exports. The list is emitted after any import lines and before the first def / class / constant declaration.

Default behaviour: names whose Python identifier starts with _ (including dunder names such as __version__) are excluded from __all__. All other top-level symbols — functions, classes, constants, and inline sub-modules — are included in declaration order.

Priority rules (highest first):

1. Per-file exclude — name is always absent from __all__.
2. Per-file include — for a top-level name that Rylai already emitted in this stub, keep it in __all__ even when it would be dropped by the _ filter (does not invent entries for symbols that were not generated).
3. Per-file include_private — overrides the global all_include_private for that file only.
4. Global output.all_include_private.
5. Default (false): _-prefixed names are excluded.

[[all]] entries follow the same file path convention as [[add_content]] (relative to -o, forward slashes, optional .pyi suffix). Multiple entries for the same file are merged: include/exclude sets are unioned; the last matching include_private wins.

Names added via [[add_content]] are not automatically added to __all__ — manage those yourself (e.g. by appending to __all__ in a tail snippet).

The same options can be set in pyproject.toml under [tool.rylai]:

[tool.rylai.output]
python_version = "3.10"

[tool.rylai.fallback]
strategy = "any"

[tool.rylai.type_map]
# Same rules as root [type_map] above (Rust paths only; literal tuples need a `type` alias + map).
"numpy::PyReadonlyArray1" = "numpy.ndarray"

[[tool.rylai.override]]
item = "my_module::complex_function"
stub = "def complex_function(x: t.Any, **kwargs: t.Any) -> dict[str, t.Any]:"

[[tool.rylai.add_content]]
file = "mymod.pyi"
location = "tail"
content = "X: t.TypeAlias = int"

[[tool.rylai.all]]
file = "mymod.pyi"
exclude = ["InternalHelper"]

[tool.rylai]
format = ["isort", "black"]

Supported Type Mappings

Rust type	Python type
Scalars
i8 … i128, u8 … u128, isize, usize	int
f32, f64	float
bool	bool
str, String, char	str
()	None
Bytes
&[u8], [u8]	bytes
Vec<u8>	bytes
Path-like
Path, PathBuf (incl. std::path::*)	Path | str / t.Union[Path, str]
Containers
Option<T>	T | None / t.Optional[T]
Vec<T>	list[T]
(T1, T2, ...) (non-empty tuple)	tuple[T1, T2, ...]
HashMap<K,V>, BTreeMap<K,V>, IndexMap<K,V>	dict[K, V]
HashSet<T>, BTreeSet<T>	set[T]
PyO3 types
PyResult<T>, Result<T, E>	T (errors become Python exceptions)
Py<T>, Bound<T>, Borrowed<T>	recurse into T
PyRef<T>, PyRefMut<T>	recurse into T
PyBytes	bytes
PyByteArray	bytearray
PyString	str
PyDict, PyList, PyTuple, PySet	dict, list, tuple, set
PyAny, PyObject	t.Any
Other
Self (in #[pymethods])	t.Self (py ≥ 3.11) or class name
#[pyclass] structs/enums	Python class name (from crate)
Unknown types	t.Any (configurable via [fallback])

Limitation

Rylai is purely static: it parses Rust source for #[pymodule], #[pyfunction], #[pyclass], etc., and does not run the compiler. It is therefore not a good fit for cases where concrete information is only known after compilation (e.g. declarative macros that generate Python bindings at compile time, or types/signatures that only exist in compiled artifacts).

For more complex projects, or when you rely on type/signature information that only exists after a build, a build-based approach is a better choice — for example pyo3-stub-gen, which compiles the extension first and then generates stubs from runtime/compilation artifacts.

For relatively simple projects where PyO3 bindings are mostly hand-annotated with straightforward types, Rylai’s speed, no-compile workflow, and zero intrusion are strong advantages. This is especially true when you have Python version requirements (e.g. supporting versions below 3.10 which pyo3-stub-gen does not support). In that case, avoid Python-related PyO3 code that is hard to analyze without compilation — for example declarative macros that expand at compile time and inject #[pyfunction] / #[pyclass]; Rylai cannot see those statically and may not generate the corresponding stubs correctly.

Related support is planned, but Rylai cannot generate stubs for all possible PyO3 code.

Contributing

Before committing, run the pre-commit checks with prek. See CONTRIBUTING.md for details.

License

LICENSE