typantic 0.1.0__py3-none-any.whl

typantic/__init__.py

@@ -0,0 +1,8 @@
+"""typantic — Auto-generate Typer CLI interfaces from Pydantic models."""
+
+from importlib.metadata import version
+
+from typantic._decorator import pydantic_to_typer
+
+__version__ = version("typantic")
+__all__ = ["pydantic_to_typer"]

typantic/_decorator.py

@@ -0,0 +1,159 @@
+"""Core decorator for converting Pydantic models to Typer CLI interfaces."""
+
+import inspect
+import types
+from collections.abc import Callable
+from functools import wraps
+from typing import Annotated, Any, Union, get_args, get_origin, get_type_hints
+
+import typer
+from pydantic import BaseModel, ValidationError
+
+
+def _extract_base_type(annotation: object) -> object:
+    """Strip ``Annotated`` validator metadata, keeping the structural type.
+
+    Recursively walks through ``Annotated``, ``Union``, ``list``, and
+    ``tuple`` wrappers, discarding everything except the base types that
+    Typer can interpret.
+
+    Args:
+        annotation: A (possibly nested) type annotation to unwrap.
+
+    Returns:
+        The base type with all Pydantic validator metadata removed.
+
+    Examples:
+        >>> from typing import Annotated
+        >>> from pydantic import AfterValidator, Field
+        >>> _extract_base_type(Annotated[float, Field(description="x")])
+        <class 'float'>
+    """
+    if get_origin(annotation) is Annotated:
+        inner = get_args(annotation)[0]
+        return _extract_base_type(inner)
+
+    if get_origin(annotation) in (Union, types.UnionType):
+        cleaned = tuple(_extract_base_type(a) for a in get_args(annotation))
+        return Union[cleaned]  # noqa: UP007
+
+    if get_origin(annotation) is list:
+        args = get_args(annotation)
+        if args:
+            return list[_extract_base_type(args[0])]  # type: ignore[misc]
+
+    if get_origin(annotation) is tuple:
+        args = get_args(annotation)
+        if args:
+            cleaned = tuple(_extract_base_type(a) for a in args)
+            return tuple[cleaned]  # type: ignore[valid-type]
+
+    return annotation
+
+
+def pydantic_to_typer(
+    model_cls: type[BaseModel],
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Rewrite a function's signature so Typer sees individual CLI params.
+
+    The parameters are derived from the fields of ``model_cls``.
+
+    Mapping rules:
+        - ``kw_only=False``  ->  ``typer.Argument``
+        - ``kw_only=True`` (or unset)  ->  ``typer.Option``
+        - ``Field(description=...)``  ->  ``help=...``
+        - ``Field(default=...)``  ->  Typer default value
+        - ``Field(default_factory=...)``  ->  factory is called once at
+          decoration time to supply the Typer default
+
+    The decorated function receives the **validated** Pydantic model
+    instance, so all ``AfterValidator`` / ``BeforeValidator`` logic runs
+    as usual.
+
+    Args:
+        model_cls: The Pydantic model class whose fields define the CLI
+            parameters.
+
+    Returns:
+        A decorator that transforms a ``func(model)`` signature into one
+        that Typer can introspect.
+
+    Example:
+        >>> import typer
+        >>> app = typer.Typer()
+        >>> @app.command()
+        ... @pydantic_to_typer(MyConfig)
+        ... def run(config: MyConfig): ...
+    """
+
+    def decorator(
+        func: Callable[..., Any],
+    ) -> Callable[..., Any]:
+        new_params: list[inspect.Parameter] = []
+        new_annotations: dict[str, object] = {}
+
+        resolved_hints = get_type_hints(
+            model_cls,
+            include_extras=True,
+        )
+
+        for name, field_info in model_cls.model_fields.items():
+            base_type = _extract_base_type(resolved_hints[name])
+            help_text = field_info.description or ""
+
+            typer_meta: typer.models.ArgumentInfo | typer.models.OptionInfo
+            if field_info.kw_only is False:
+                typer_meta = typer.Argument(
+                    help=help_text,
+                    show_default=False,
+                )
+            else:
+                typer_meta = typer.Option(help=help_text)
+
+            annotated = Annotated[base_type, typer_meta]  # type: ignore[valid-type]
+            new_annotations[name] = annotated
+
+            default: object
+            if field_info.is_required():
+                default = inspect.Parameter.empty
+            elif field_info.default_factory is not None:
+                default = field_info.default_factory()  # type: ignore[call-arg]
+            else:
+                default = field_info.default
+
+            new_params.append(
+                inspect.Parameter(
+                    name,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD
+                    if field_info.kw_only is False
+                    else inspect.Parameter.KEYWORD_ONLY,
+                    default=default,
+                    annotation=annotated,
+                ),
+            )
+
+        new_params.sort(
+            key=lambda p: (
+                p.kind == inspect.Parameter.KEYWORD_ONLY,
+                p.default is not inspect.Parameter.empty,
+            ),
+        )
+
+        @wraps(func)
+        def wrapper(**kwargs: object) -> object:
+            try:
+                model = model_cls(**kwargs)
+            except ValidationError as exc:
+                messages: list[str] = []
+                for err in exc.errors():
+                    loc = ".".join(str(p) for p in err["loc"])
+                    msg = str(err["msg"])
+                    messages.append(f"{loc}: {msg}" if loc else msg)
+                raise typer.BadParameter("\n  ".join(messages)) from exc
+            return func(model)
+
+        wrapper.__signature__ = inspect.Signature(new_params)  # type: ignore[attr-defined]
+        wrapper.__annotations__ = new_annotations
+        return wrapper
+
+    return decorator

typantic-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: typantic
+Version: 0.1.0
+Summary: Auto-generate Typer CLI interfaces from Pydantic models.
+Keywords: typer,pydantic,cli,validation
+Author: Kilian Schnelle
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.9
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/KiSchnelle/typantic
+Project-URL: Repository, https://github.com/KiSchnelle/typantic
+Project-URL: Issues, https://github.com/KiSchnelle/typantic/issues
+Project-URL: Changelog, https://github.com/KiSchnelle/typantic/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# typantic
+
+[![CI](https://github.com/KiSchnelle/typantic/actions/workflows/ci.yml/badge.svg)](https://github.com/KiSchnelle/typantic/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/typantic.svg)](https://pypi.org/project/typantic/)
+[![Python](https://img.shields.io/pypi/pyversions/typantic.svg)](https://pypi.org/project/typantic/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Auto-generate [Typer](https://typer.tiangolo.com/) CLI interfaces from [Pydantic](https://docs.pydantic.dev/) models.
+
+Define your config **once** as a Pydantic model with validators, and get a
+fully-typed CLI for free — no duplication, no drift.
+
+## Installation
+
+```bash
+pip install typantic
+```
+
+## Quick start
+
+```python
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from pydantic import AfterValidator, BaseModel, Field
+
+from typantic import pydantic_to_typer
+
+
+# 1. Define your config with validators
+class Config(BaseModel):
+    images: Annotated[
+        list[Path],
+        Field(description="Image folders to process.", kw_only=False),
+    ]
+    output: Annotated[
+        Path,
+        AfterValidator(Path.resolve),
+        Field(description="Output directory.", kw_only=True),
+    ]
+    threshold: Annotated[
+        float,
+        Field(default=0.5, description="Detection threshold.", kw_only=True),
+    ]
+    seed: Annotated[
+        int | None,
+        Field(default=None, description="Random seed.", kw_only=True),
+    ]
+
+
+# 2. Use the decorator — that's it
+app = typer.Typer()
+
+@app.command()
+@pydantic_to_typer(Config)
+def run(config: Config):
+    """Process images with validation."""
+    print(config)
+
+if __name__ == "__main__":
+    app()
+```
+
+```
+$ python example.py --help
+
+ Usage: example.py [OPTIONS] IMAGES...
+
+ Process images with validation.
+
+╭─ Arguments ──────────────────────────────────────────────────╮
+│ *  images  IMAGES...  Image folders to process.  [required]  │
+╰──────────────────────────────────────────────────────────────╯
+╭─ Options ────────────────────────────────────────────────────╮
+│ *  --output     PATH     Output directory.  [required]       │
+│    --threshold  FLOAT    Detection threshold.  [default: 0.5]│
+│    --seed       INTEGER  Random seed.                        │
+│    --help                Show this message and exit.         │
+╰──────────────────────────────────────────────────────────────╯
+```
+
+## How it works
+
+The `@pydantic_to_typer(Model)` decorator:
+
+1. Reads `Model.model_fields` to discover field names, types, descriptions, and defaults
+2. Strips `Annotated` validator metadata to extract the base types Typer understands
+3. Maps `kw_only=False` → `typer.Argument`, `kw_only=True` → `typer.Option`
+4. Rewrites the function's `__signature__` so Typer sees the expanded parameters
+5. At call time, passes the raw CLI values into `Model(...)` so all Pydantic validators run
+
+Your function receives the **validated model instance** — validators, `default_factory`, union types, and everything else works exactly as in Pydantic.
+
+## Features
+
+| Pydantic                          | CLI result                              |
+|-----------------------------------|-----------------------------------------|
+| `kw_only=False`                   | `typer.Argument` (positional)           |
+| `kw_only=True` or unset           | `typer.Option` (`--flag`)               |
+| `Field(description=...)`          | `help=...` in the CLI                   |
+| `Field(default=...)`              | Default value shown in `--help`         |
+| `Field(default_factory=...)`      | Factory called once at decoration time  |
+| `int \| None`                     | Optional CLI option                     |
+| `list[Path]`                      | Variadic positional argument            |
+| `AfterValidator`, `BeforeValidator` | Run at call time via Pydantic         |
+
+## Requirements
+
+- Python ≥ 3.12
+- Pydantic ≥ 2.0
+- Typer ≥ 0.9
+
+## License
+
+MIT

typantic-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+typantic/__init__.py,sha256=nv08fEyBZu66_WApKnXjtPWYEsbQqXIK75arb7spGkE,234
+typantic/_decorator.py,sha256=VGt9JmkZpwQJIHWY2lT-9kl_x8doiMRed73vrMLNJ7Y,5461
+typantic/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+typantic-0.1.0.dist-info/WHEEL,sha256=i9aSRDivn5iP9LaR1BLQX2GNAuriQWPsFwbbWygTX2k,81
+typantic-0.1.0.dist-info/METADATA,sha256=1CAqXhU191gpg701-7P5sMfs1MNma8XGVSUinxjV6GM,5372
+typantic-0.1.0.dist-info/RECORD,,

typantic-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.15
+Root-Is-Purelib: true
+Tag: py3-none-any