velotype 0.4.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 (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

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

Exit codes: 2 for bad target syntax, missing module, unresolvable import path, or target not a class; 1 when the class is not a dataclass (or other modelspec_from_dataclass failure).

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 — Phase 0.4 (stub quality)
• Changelog

License

MIT — see LICENSE.