pydantic-fixturegen 1.0.0__py3-none-any.whl

pydantic_fixturegen/__init__.py

@@ -0,0 +1,7 @@
+"""Top-level package for pydantic-fixturegen."""
+
+from .core.version import get_tool_version
+
+__all__ = ["__version__", "get_tool_version"]
+
+__version__ = get_tool_version()

pydantic_fixturegen/cli/__init__.py

@@ -0,0 +1,85 @@
+"""Command line interface for pydantic-fixturegen."""
+
+from __future__ import annotations
+
+import builtins
+from importlib import import_module
+
+import typer
+from typer.main import get_command
+
+
+def _load_typer(import_path: str) -> typer.Typer:
+    module_name, attr = import_path.split(":", 1)
+    module = import_module(module_name)
+    loaded = getattr(module, attr)
+    if not isinstance(loaded, typer.Typer):
+        raise TypeError(f"Attribute {attr!r} in module {module_name!r} is not a Typer app.")
+    return loaded
+
+
+def _invoke(import_path: str, ctx: typer.Context) -> None:
+    sub_app = _load_typer(import_path)
+    command = get_command(sub_app)
+    args = builtins.list(ctx.args)
+    result = command.main(
+        args=args,
+        prog_name=ctx.command_path,
+        standalone_mode=False,
+    )
+    if isinstance(result, int):
+        raise typer.Exit(code=result)
+
+
+app = typer.Typer(
+    help="pydantic-fixturegen command line interface",
+    invoke_without_command=True,
+    context_settings={
+        "allow_extra_args": True,
+        "ignore_unknown_options": True,
+    },
+)
+
+
+@app.callback(invoke_without_command=True)
+def _root(ctx: typer.Context) -> None:  # noqa: D401
+    if ctx.invoked_subcommand is None:
+        _invoke("pydantic_fixturegen.cli.list:app", ctx)
+        raise typer.Exit()
+
+
+def _proxy(name: str, import_path: str, help_text: str) -> None:
+    context_settings = {
+        "allow_extra_args": True,
+        "ignore_unknown_options": True,
+    }
+
+    @app.command(name, context_settings=context_settings)
+    def command(ctx: typer.Context) -> None:
+        _invoke(import_path, ctx)
+
+    command.__doc__ = help_text
+
+
+_proxy(
+    "list",
+    "pydantic_fixturegen.cli.list:app",
+    "List Pydantic models from modules or files.",
+)
+_proxy(
+    "gen",
+    "pydantic_fixturegen.cli.gen:app",
+    "Generate artifacts for discovered models.",
+)
+_proxy(
+    "doctor",
+    "pydantic_fixturegen.cli.doctor:app",
+    "Inspect models for coverage and risks.",
+)
+_proxy(
+    "explain",
+    "pydantic_fixturegen.cli.gen.explain:app",
+    "Explain generation strategies per model field.",
+)
+
+__all__ = ["app"]

pydantic_fixturegen/cli/doctor.py

@@ -0,0 +1,235 @@
+"""CLI command for inspecting project health."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import typer
+from pydantic import BaseModel
+
+from pydantic_fixturegen.core.errors import DiscoveryError, PFGError
+from pydantic_fixturegen.core.providers import create_default_registry
+from pydantic_fixturegen.core.schema import FieldSummary, summarize_model_fields
+from pydantic_fixturegen.core.strategies import StrategyBuilder, StrategyResult, UnionStrategy
+from pydantic_fixturegen.plugins.loader import get_plugin_manager
+
+from .gen._common import (
+    JSON_ERRORS_OPTION,
+    DiscoveryMethod,
+    clear_module_cache,
+    discover_models,
+    load_model_class,
+    render_cli_error,
+    split_patterns,
+)
+
+PATH_ARGUMENT = typer.Argument(..., help="Path to a Python module containing Pydantic models.")
+
+INCLUDE_OPTION = typer.Option(
+    None,
+    "--include",
+    "-i",
+    help="Comma-separated pattern(s) of fully-qualified model names to include.",
+)
+
+EXCLUDE_OPTION = typer.Option(
+    None,
+    "--exclude",
+    "-e",
+    help="Comma-separated pattern(s) of fully-qualified model names to exclude.",
+)
+
+AST_OPTION = typer.Option(False, "--ast", help="Use AST discovery only (no imports executed).")
+
+HYBRID_OPTION = typer.Option(False, "--hybrid", help="Combine AST and safe import discovery.")
+
+TIMEOUT_OPTION = typer.Option(
+    5.0,
+    "--timeout",
+    min=0.1,
+    help="Timeout in seconds for safe import execution.",
+)
+
+MEMORY_LIMIT_OPTION = typer.Option(
+    256,
+    "--memory-limit-mb",
+    min=1,
+    help="Memory limit in megabytes for safe import subprocess.",
+)
+
+
+app = typer.Typer(invoke_without_command=True, subcommand_metavar="")
+
+
+@dataclass
+class ModelReport:
+    model: type[BaseModel]
+    coverage: tuple[int, int]
+    issues: list[str]
+
+
+def doctor(  # noqa: D401 - Typer callback
+    ctx: typer.Context,
+    path: str = PATH_ARGUMENT,
+    include: str | None = INCLUDE_OPTION,
+    exclude: str | None = EXCLUDE_OPTION,
+    ast_mode: bool = AST_OPTION,
+    hybrid_mode: bool = HYBRID_OPTION,
+    timeout: float = TIMEOUT_OPTION,
+    memory_limit_mb: int = MEMORY_LIMIT_OPTION,
+    json_errors: bool = JSON_ERRORS_OPTION,
+) -> None:
+    _ = ctx  # unused
+    try:
+        _execute_doctor(
+            target=path,
+            include=include,
+            exclude=exclude,
+            ast_mode=ast_mode,
+            hybrid_mode=hybrid_mode,
+            timeout=timeout,
+            memory_limit_mb=memory_limit_mb,
+        )
+    except PFGError as exc:
+        render_cli_error(exc, json_errors=json_errors)
+
+
+app.callback(invoke_without_command=True)(doctor)
+
+
+def _resolve_method(ast_mode: bool, hybrid_mode: bool) -> DiscoveryMethod:
+    if ast_mode and hybrid_mode:
+        raise DiscoveryError("Choose only one of --ast or --hybrid.")
+    if hybrid_mode:
+        return "hybrid"
+    if ast_mode:
+        return "ast"
+    return "import"
+
+
+def _execute_doctor(
+    *,
+    target: str,
+    include: str | None,
+    exclude: str | None,
+    ast_mode: bool,
+    hybrid_mode: bool,
+    timeout: float,
+    memory_limit_mb: int,
+) -> None:
+    path = Path(target)
+    if not path.exists():
+        raise DiscoveryError(f"Target path '{target}' does not exist.", details={"path": target})
+    if not path.is_file():
+        raise DiscoveryError("Target must be a Python module file.", details={"path": target})
+
+    clear_module_cache()
+
+    method = _resolve_method(ast_mode, hybrid_mode)
+    discovery = discover_models(
+        path,
+        include=split_patterns(include),
+        exclude=split_patterns(exclude),
+        method=method,
+        timeout=timeout,
+        memory_limit_mb=memory_limit_mb,
+    )
+
+    if discovery.errors:
+        raise DiscoveryError("; ".join(discovery.errors))
+
+    for warning in discovery.warnings:
+        if warning.strip():
+            typer.secho(f"warning: {warning.strip()}", err=True, fg=typer.colors.YELLOW)
+
+    if not discovery.models:
+        typer.echo("No models discovered.")
+        return
+
+    registry = create_default_registry(load_plugins=True)
+    builder = StrategyBuilder(registry, plugin_manager=get_plugin_manager())
+
+    reports: list[ModelReport] = []
+    for model_info in discovery.models:
+        try:
+            model_cls = load_model_class(model_info)
+        except RuntimeError as exc:
+            raise DiscoveryError(str(exc)) from exc
+        reports.append(_analyse_model(model_cls, builder))
+
+    _render_report(reports)
+
+
+def _analyse_model(model: type[BaseModel], builder: StrategyBuilder) -> ModelReport:
+    total_fields = 0
+    covered_fields = 0
+    issues: list[str] = []
+
+    try:
+        strategies = builder.build_model_strategies(model)
+    except ValueError as exc:  # missing provider
+        summaries = summarize_model_fields(model)
+        message = str(exc)
+        return ModelReport(
+            model=model,
+            coverage=(0, len(summaries)),
+            issues=[message],
+        )
+
+    summaries = summarize_model_fields(model)
+
+    for field_name, strategy in strategies.items():
+        total_fields += 1
+        summary = summaries[field_name]
+        covered, field_issues = _strategy_status(summary, strategy)
+        if covered:
+            covered_fields += 1
+        issues.extend(f"{model.__name__}.{field_name}: {msg}" for msg in field_issues)
+
+    return ModelReport(model=model, coverage=(covered_fields, total_fields), issues=issues)
+
+
+def _strategy_status(summary: FieldSummary, strategy: StrategyResult) -> tuple[bool, list[str]]:
+    if isinstance(strategy, UnionStrategy):
+        issue_messages: list[str] = []
+        covered = True
+        for choice in strategy.choices:
+            choice_ok, choice_issues = _strategy_status(choice.summary, choice)
+            if not choice_ok:
+                covered = False
+                issue_messages.extend(choice_issues)
+        return covered, issue_messages
+
+    messages: list[str] = []
+    if strategy.enum_values:
+        return True, messages
+
+    if summary.type in {"model", "dataclass"}:
+        return True, messages
+
+    if strategy.provider_ref is None:
+        messages.append(f"no provider for type '{summary.type}'")
+        return False, messages
+
+    if summary.type == "any":
+        messages.append("falls back to generic type")
+    return True, messages
+
+
+def _render_report(reports: list[ModelReport]) -> None:
+    for report in reports:
+        covered, total = report.coverage
+        coverage_pct = (covered / total * 100) if total else 100.0
+        typer.echo(f"Model: {report.model.__module__}.{report.model.__name__}")
+        typer.echo(f"  Coverage: {covered}/{total} fields ({coverage_pct:.0f}%)")
+        if report.issues:
+            typer.echo("  Issues:")
+            for issue in report.issues:
+                typer.echo(f"    - {issue}")
+        else:
+            typer.echo("  Issues: none")
+        typer.echo("")
+
+
+__all__ = ["app"]

pydantic_fixturegen/cli/gen/__init__.py

@@ -0,0 +1,23 @@
+"""Grouping for generation-related CLI commands."""
+
+from __future__ import annotations
+
+import typer
+
+from .explain import app as explain_app
+from .fixtures import register as register_fixtures
+from .json import register as register_json
+from .schema import register as register_schema
+
+app = typer.Typer(help="Generate data artifacts from Pydantic models.")
+
+register_json(app)
+register_schema(app)
+register_fixtures(app)
+app.add_typer(
+    explain_app,
+    name="explain",
+    help="Explain generation strategy per model field.",
+)
+
+__all__ = ["app"]

pydantic_fixturegen/cli/gen/_common.py

@@ -0,0 +1,139 @@
+"""Shared helpers for generation CLI commands."""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from types import ModuleType
+from typing import Literal
+
+import typer
+from pydantic import BaseModel
+
+from pydantic_fixturegen.core.errors import PFGError
+from pydantic_fixturegen.core.introspect import (
+    IntrospectedModel,
+    IntrospectionResult,
+    discover,
+)
+
+__all__ = [
+    "JSON_ERRORS_OPTION",
+    "clear_module_cache",
+    "discover_models",
+    "load_model_class",
+    "render_cli_error",
+    "split_patterns",
+]
+
+
+_module_cache: dict[str, ModuleType] = {}
+
+
+JSON_ERRORS_OPTION = typer.Option(
+    False,
+    "--json-errors",
+    help="Emit structured JSON errors to stdout.",
+)
+
+
+def clear_module_cache() -> None:
+    """Clear cached module imports used during CLI execution."""
+
+    _module_cache.clear()
+
+
+def split_patterns(raw: str | None) -> list[str]:
+    if not raw:
+        return []
+    return [part.strip() for part in raw.split(",") if part.strip()]
+
+
+DiscoveryMethod = Literal["ast", "import", "hybrid"]
+
+
+def discover_models(
+    path: Path,
+    *,
+    include: Sequence[str] | None = None,
+    exclude: Sequence[str] | None = None,
+    method: DiscoveryMethod = "import",
+    timeout: float = 5.0,
+    memory_limit_mb: int = 256,
+) -> IntrospectionResult:
+    return discover(
+        [path],
+        method=method,
+        include=list(include or ()),
+        exclude=list(exclude or ()),
+        public_only=False,
+        safe_import_timeout=timeout,
+        safe_import_memory_limit_mb=memory_limit_mb,
+    )
+
+
+def load_model_class(model_info: IntrospectedModel) -> type[BaseModel]:
+    module = _load_module(model_info.module, Path(model_info.locator))
+    attr = getattr(module, model_info.name, None)
+    if not isinstance(attr, type) or not issubclass(attr, BaseModel):
+        raise RuntimeError(
+            f"Attribute {model_info.name!r} in module "
+            f"{module.__name__} is not a Pydantic BaseModel."
+        )
+    return attr
+
+
+def render_cli_error(error: PFGError, *, json_errors: bool) -> None:
+    if json_errors:
+        payload = {"error": error.to_payload()}
+        typer.echo(json.dumps(payload, indent=2))
+    else:
+        typer.secho(f"{error.kind}: {error}", err=True, fg=typer.colors.RED)
+        if error.hint:
+            typer.secho(f"hint: {error.hint}", err=True, fg=typer.colors.YELLOW)
+    raise typer.Exit(code=int(error.code))
+
+
+def _load_module(module_name: str, locator: Path) -> ModuleType:
+    module = _module_cache.get(module_name)
+    if module is not None:
+        return module
+
+    existing = sys.modules.get(module_name)
+    if existing is not None:
+        existing_path = getattr(existing, "__file__", None)
+        if existing_path and Path(existing_path).resolve() == locator.resolve():
+            _module_cache[module_name] = existing
+            return existing
+
+    return _import_module_by_path(module_name, locator)
+
+
+def _import_module_by_path(module_name: str, path: Path) -> ModuleType:
+    if not path.exists():
+        raise RuntimeError(f"Could not locate module source at {path}.")
+
+    sys_path_entry = str(path.parent.resolve())
+    if sys_path_entry not in sys.path:
+        sys.path.insert(0, sys_path_entry)
+
+    unique_name = module_name
+    if module_name in sys.modules:
+        unique_name = f"{module_name}_pfg_{len(_module_cache)}"
+
+    spec = importlib.util.spec_from_file_location(unique_name, path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Failed to load module from {path}.")
+
+    module = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(module)
+    except Exception as exc:  # pragma: no cover - surface to caller
+        raise RuntimeError(f"Error importing module {path}: {exc}") from exc
+
+    _module_cache[module_name] = module
+    return module

pydantic_fixturegen/cli/gen/explain.py

@@ -0,0 +1,145 @@
+"""CLI command to explain strategies for models and fields."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from pydantic import BaseModel
+
+from pydantic_fixturegen.core.errors import DiscoveryError, PFGError
+from pydantic_fixturegen.core.providers import create_default_registry
+from pydantic_fixturegen.core.schema import summarize_model_fields
+from pydantic_fixturegen.core.strategies import StrategyBuilder, StrategyResult, UnionStrategy
+from pydantic_fixturegen.plugins.loader import get_plugin_manager
+
+from ._common import (
+    JSON_ERRORS_OPTION,
+    clear_module_cache,
+    discover_models,
+    load_model_class,
+    render_cli_error,
+    split_patterns,
+)
+
+PATH_ARGUMENT = typer.Argument(..., help="Path to a Python module containing Pydantic models.")
+
+INCLUDE_OPTION = typer.Option(
+    None,
+    "--include",
+    "-i",
+    help="Comma-separated pattern(s) of fully-qualified model names to include.",
+)
+
+EXCLUDE_OPTION = typer.Option(
+    None,
+    "--exclude",
+    "-e",
+    help="Comma-separated pattern(s) of fully-qualified model names to exclude.",
+)
+
+
+app = typer.Typer(invoke_without_command=True, subcommand_metavar="")
+
+
+def explain(  # noqa: D401 - Typer callback
+    ctx: typer.Context,
+    path: str = PATH_ARGUMENT,
+    include: str | None = INCLUDE_OPTION,
+    exclude: str | None = EXCLUDE_OPTION,
+    json_errors: bool = JSON_ERRORS_OPTION,
+) -> None:
+    _ = ctx  # unused
+    try:
+        _execute_explain(
+            target=path,
+            include=include,
+            exclude=exclude,
+        )
+    except PFGError as exc:
+        render_cli_error(exc, json_errors=json_errors)
+    except ValueError as exc:
+        render_cli_error(DiscoveryError(str(exc)), json_errors=json_errors)
+
+
+app.callback(invoke_without_command=True)(explain)
+
+
+def _execute_explain(*, target: str, include: str | None, exclude: str | None) -> None:
+    path = Path(target)
+    if not path.exists():
+        raise ValueError(f"Target path '{target}' does not exist.")
+    if not path.is_file():
+        raise ValueError("Target must be a Python module file.")
+
+    clear_module_cache()
+
+    discovery = discover_models(
+        path,
+        include=split_patterns(include),
+        exclude=split_patterns(exclude),
+    )
+
+    if discovery.errors:
+        raise ValueError("; ".join(discovery.errors))
+
+    for warning in discovery.warnings:
+        if warning.strip():
+            typer.secho(f"warning: {warning.strip()}", err=True, fg=typer.colors.YELLOW)
+
+    if not discovery.models:
+        typer.echo("No models discovered.")
+        return
+
+    registry = create_default_registry(load_plugins=True)
+    builder = StrategyBuilder(registry, plugin_manager=get_plugin_manager())
+
+    for model_info in discovery.models:
+        model_cls = load_model_class(model_info)
+        _render_model_report(model_cls, builder)
+
+
+def _render_model_report(model: type[BaseModel], builder: StrategyBuilder) -> None:
+    typer.echo(f"Model: {model.__module__}.{model.__name__}")
+    summaries = summarize_model_fields(model)
+    strategies = {}
+    field_failures: dict[str, str] = {}
+    for name, model_field in model.model_fields.items():
+        summary = summaries[name]
+        try:
+            strategies[name] = builder.build_field_strategy(
+                model,
+                name,
+                model_field.annotation,
+                summary,
+            )
+        except ValueError as exc:
+            field_failures[name] = str(exc)
+
+    for field_name, strategy in strategies.items():
+        summary = summaries[field_name]
+        typer.echo(f"  Field: {field_name}")
+        typer.echo(f"    Type: {summary.type}")
+        _render_strategy(strategy, indent="    ")
+    for field_name, message in field_failures.items():
+        typer.echo(f"  Field: {field_name}")
+        typer.echo("    Type: unknown")
+        typer.echo(f"    Issue: {message}")
+    typer.echo("")
+
+
+def _render_strategy(strategy: StrategyResult, indent: str) -> None:
+    if isinstance(strategy, UnionStrategy):
+        typer.echo(f"{indent}Union policy: {strategy.policy}")
+        for idx, choice in enumerate(strategy.choices, start=1):
+            typer.echo(f"{indent}  Option {idx} -> type: {choice.summary.type}")
+            _render_strategy(choice, indent=f"{indent}    ")
+        return
+
+    typer.echo(f"{indent}Provider: {strategy.provider_name}")
+    if strategy.enum_values:
+        typer.echo(f"{indent}Enum values: {strategy.enum_values}")
+    typer.echo(f"{indent}p_none: {strategy.p_none}")
+
+
+__all__ = ["app"]