velotype 0.8.0

Velarium IR to .pyi stub generation (velotype backend)

velotype

Role in Velarium: IR → .pyi — render Velarium (ModelSpec) IR as minimal stub text, and expose the velotype CLI for quick IR export and stub generation from live classes.

PyPI	pypi.org/project/velotype
Repository	github.com/eddiethedean/velarium
Python	3.10+ (follows velarium)
Depends on	velarium on PyPI (required)
CLI	velotype ir, velotype stub, velotype batch stub / batch ir (--cache-dir, --no-cache), velotype watch stub (optional extra [watch]); also python -m velotype

The IR types and builders live in velarium. velotype re-exports the same public IR symbols and builder entry points as velarium (including modelspec_from_pydantic_model and modelspec_from_attrs_class when extras are installed); prefer from velarium import … in new code when you only need IR. See docs/model-sources.md for optional dependencies.

Stub output: generate_pyi / render_typespec aim for valid, checker-friendly .pyi text. Optional generate_pyi arguments include module_docstring, header / footer, include_all (emits __all__), and style ("default" banner vs "minimal"). Optional format_stub_text(..., backend="ruff") runs ruff format - when available. Advanced TypeKind values (protocol, nominal, paramspec, typevartuple, and bare typevar in fields) are rendered as typing.Any in stubs so generated files do not invent TypeVar/ParamSpec declarations; the JSON IR still carries name / qualname / module for tooling.

Topic	Doc
Stub fallbacks	docs/supported-annotations.md
Guarantees, imports, CI mypy / Pyright	docs/stub-compatibility.md
Performance, batch cache	docs/performance.md
CLI trust model, JSON limits	docs/security.md
Public API, IR format_version	docs/api-reference.md, docs/stability.md, docs/migration-ir.md

Install

pip install velotype

From the monorepo root:

uv sync --group dev
# or
pip install -e packages/velarium -e "packages/velotype[dev]"

CLI

velotype ir myapp.models:User
velotype ir myapp.models:User -o user.ir.json
velotype stub myapp.models:User -o user.pyi
velotype batch stub myapp.models --out-dir stubs/
velotype batch ir myapp.models --out-dir ir-json/ --merge
# pip install 'velotype[watch]'
velotype watch stub myapp.models --out-dir stubs/

Batch walks an importable package for dataclasses and writes one .pyi (or merged.pyi with --merge) or JSON per model. Exit codes and failures: docs/troubleshooting-cli.md. Tutorial: docs/tutorial-stubs.md.

Library

from velarium import modelspec_from_dataclass, dumps_model_spec
from velotype import format_stub_text, generate_pyi

spec = modelspec_from_dataclass(MyModel)
print(generate_pyi(spec))
# Optional: print(format_stub_text(generate_pyi(spec), backend="ruff"))

Version

__version__ is in velotype/__init__.py (Hatch dynamic metadata in this package’s pyproject.toml).

See also

• docs/modelspec-ir.md — IR schema
• docs/model-sources.md — builders (dataclass, TypedDict, Pydantic, attrs) and velarium extras
• docs/stub-compatibility.md — stub guarantees and CI validation
• docs/valarium.md — ecosystem and backends
• Repository README
• Documentation index
• Roadmap — Phases 0.5–0.8 (tooling, performance, hardening, API/IR stability prep)
• Changelog

License

MIT — see LICENSE.