pyverge 0.2.0__py3-none-any.whl

pyverge/__init__.py

@@ -0,0 +1,9 @@
+"""pyverge - versioned models and schemas with migrations."""
+
+from . import migration
+from ._version import __version__
+
+__all__ = [
+    "__version__",
+    "migration",
+]

pyverge/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

pyverge/cli/__init__.py

@@ -0,0 +1 @@
+"""The pyverge CLI subpackage."""

pyverge/cli/_helpers.py

@@ -0,0 +1,206 @@
+"""Helper functions for the CLI."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import typer
+
+
+def load_json_file(path: Path) -> Any:
+    """Load JSON file."""
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except FileNotFoundError as e:
+        raise FileNotFoundError(f"Data file not found: {path}") from e
+    except json.JSONDecodeError as e:
+        raise json.JSONDecodeError(f"Invalid JSON in {path}", e.doc, e.pos) from e
+
+
+def write_json_file(path: Path, data: dict[str, Any]) -> None:
+    """Write JSON file."""
+    try:
+        with open(path, "w") as f:
+            json.dump(data, f, indent=2)
+            f.write("\n")
+    except PermissionError as e:
+        raise PermissionError(f"Cannot write to {path}: Permission denied") from e
+    except OSError as e:
+        raise OSError(f"Failed to write {path}: {e}") from e
+
+
+def create_example_models_file(path: Path) -> None:
+    """Create example models.py file."""
+    if path.exists():
+        typer.secho(f"Skipping: {path} already exists", fg=typer.colors.YELLOW)
+        return
+
+    try:
+        path.write_text('''"""Versioned models managed by pyverge."""
+
+from typing import Literal
+
+import semver
+from pydantic import BaseModel
+
+from pyverge.migration import (
+    MigrationSettings,
+    ModelManager,
+    PydanticModelAdapter,
+)
+
+# Create a scoped manager class
+UserManager = ModelManager[semver.Version].scoped(
+    PydanticModelAdapter(),
+    settings=MigrationSettings(),
+)
+
+
+# Version 1: Initial user model
+@UserManager.model()
+class UserV1(BaseModel):
+    """User model v1.0.0"""
+    kind: Literal["User"] = "User"
+    version: Literal["1.0.0"] = "1.0.0"
+    name: str
+    email: str
+
+
+# Version 2: Add age field
+@UserManager.model()
+class UserV2(BaseModel):
+    """User model v2.0.0"""
+    kind: Literal["User"] = "User"
+    version: Literal["2.0.0"] = "2.0.0"
+    name: str
+    email: str
+    age: int | None = None
+
+
+# Define migration
+@UserManager.migration("User", "1.0.0", "2.0.0")
+def add_age_field(data: dict) -> dict:
+    """Add optional age field."""
+    return {**data, "age": None}
+
+
+# Export manager instance for CLI discovery
+__manager__ = UserManager()
+
+
+# Alternative: Factory function pattern
+# def create_manager():
+#     """Factory function for creating manager with custom setup."""
+#     return UserManager()
+#
+# __manager__ = create_manager
+''')
+        typer.secho(f"Created {path}", fg=typer.colors.GREEN)
+    except OSError as e:
+        typer.secho(f"Failed to create {path}: {e}", fg=typer.colors.RED)
+        raise
+
+
+def create_single_manager_config(project_dir: Path, use_pyproject: bool) -> None:
+    """Create single manager configuration."""
+    try:
+        if use_pyproject:
+            config_file = project_dir / "pyproject.toml"
+            config_content = """[tool.pyverge]
+manager = "models"
+"""
+            if config_file.exists():
+                typer.echo(f"\nAdd this to {config_file}:")
+                typer.echo(config_content)
+            else:
+                config_file.write_text(f"""[project]
+name = "{project_dir.name}"
+version = "0.1.0"
+
+{config_content}""")
+                typer.secho(f"Created {config_file}", fg=typer.colors.GREEN)
+        else:
+            config_file = project_dir / "pyverge.toml"
+            if not config_file.exists():
+                config_file.write_text("""[pyverge]
+manager = "models"
+
+# Optional: Use factory function
+# manager = "models:create_manager"
+
+# Optional: Pass initialization arguments
+# init_args = []
+# [pyverge.init_kwargs]
+# debug = false
+""")
+                typer.secho(f"Created {config_file}", fg=typer.colors.GREEN)
+    except OSError as e:
+        typer.secho(f"Failed to create config: {e}", fg=typer.colors.RED)
+        raise
+
+
+def create_multi_manager_config(project_dir: Path, use_pyproject: bool) -> None:
+    """Create multi-manager configuration."""
+    try:
+        if use_pyproject:
+            config_content = """[tool.pyverge.managers]
+default = "models"
+api_v1 = "api.v1.models"
+api_v2 = "api.v2.models"
+
+# Optional: Configure specific manager with init args
+# [tool.pyverge.managers.api_v1]
+# manager = "api.v1.models:create_manager"
+# init_args = ["production"]
+"""
+        else:
+            config_content = """[pyverge.managers]
+default = "models"
+api_v1 = "api.v1.models"
+api_v2 = "api.v2.models"
+
+# Optional: Configure specific manager with init args
+# [pyverge.managers.api_v1]
+# manager = "api.v1.models:create_manager"
+# init_args = ["production"]
+"""
+
+        config_file = project_dir / (
+            "pyproject.toml" if use_pyproject else "pyverge.toml"
+        )
+
+        if config_file.exists() and use_pyproject:
+            typer.echo(f"\nAdd this to {config_file}:")
+            typer.echo(config_content)
+        else:
+            if use_pyproject:
+                config_file.write_text(f"""[project]
+name = "{project_dir.name}"
+version = "0.1.0"
+
+{config_content}""")
+            else:
+                config_file.write_text(config_content)
+            typer.secho(f"Created {config_file}", fg=typer.colors.GREEN)
+    except OSError as e:
+        typer.secho(f"Failed to create config: {e}", fg=typer.colors.RED)
+        raise
+
+
+def print_next_steps(multiple: bool) -> None:
+    """Print next steps after initialization."""
+    if multiple:
+        typer.echo("\nMultiple managers configured:")
+        typer.echo("  • default (models)")
+        typer.echo("  • api_v1 (api.v1.models)")
+        typer.echo("  • api_v2 (api.v2.models)")
+        typer.echo("\nCommands:")
+        typer.echo("  pyverge managers              - List all managers")
+        typer.echo("  pyverge info api_v1           - Show manager details")
+        typer.echo("  pyverge validate -M api_v1 ...  - Use specific manager")
+    else:
+        typer.echo("\nNext steps:")
+        typer.echo("  1. Edit models.py to add your models")
+        typer.echo("  2. Run: pyverge info")
+        typer.echo("  3. Run: pyverge validate -d data.json -s User -v 1.0.0")

pyverge/cli/config.py

@@ -0,0 +1,64 @@
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from pyverge.migration import ModelManager
+
+
+class ConfigError(Exception):
+    """Configuration loading error."""
+
+
+def resolve_manager(spec: str) -> ModelManager:
+    """Resolve a manager from a ``module_path:object_path`` spec."""
+
+    if ":" not in spec:
+        raise ConfigError(f"Manager spec must be 'module:object_path', got '{spec}'")
+
+    module_path, object_path = spec.split(":", 1)
+    cwd = Path.cwd()
+    module = _import_module(cwd, module_path)
+    obj: Any = module
+    for part in object_path.split("."):
+        obj = getattr(obj, part)
+    if not isinstance(obj, ModelManager):
+        raise ConfigError(
+            f"Manager '{spec}' resolved to {type(obj).__name__}, "
+            "expected a ModelManager"
+        )
+    return obj
+
+
+def _import_module(cwd: Path, module_path: str) -> ModuleType:
+    """Import a module, falling back to a local file when not on the path."""
+    try:
+        return importlib.import_module(module_path)
+    except ImportError as e:
+        module_file = cwd / module_path.replace(".", "/")
+        if not module_file.suffix:
+            module_file = module_file.with_suffix(".py")
+
+        if not module_file.exists():
+            raise ConfigError(f"Cannot import module '{module_path}': {e}") from e
+
+        spec = importlib.util.spec_from_file_location(module_path, module_file)
+        if spec is None or spec.loader is None:
+            raise ConfigError(f"Cannot load module from {module_file}") from e
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_path] = module
+        spec.loader.exec_module(module)
+        return module
+
+
+def list_managers_from_module(module_path: str) -> list[str]:
+    """Return the names of ``ModelManager`` instances/subclasses in *module_path*."""
+    module = importlib.import_module(module_path)
+    return [
+        name
+        for name, value in vars(module).items()
+        if isinstance(value, ModelManager)
+        or (isinstance(value, type) and issubclass(value, ModelManager))
+    ]

pyverge/cli/main.py

@@ -0,0 +1,175 @@
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from pydantic import ValidationError
+from rich.console import Console
+from rich.table import Table
+
+from ._helpers import (
+    load_json_file,
+)
+from .config import (
+    ConfigError,
+    list_managers_from_module,
+    resolve_manager,
+)
+
+app = typer.Typer(help="Schema evolution and migrations for versioned models")
+console = Console()
+
+ManagerOption = Annotated[
+    str,
+    typer.Option(
+        ...,
+        "--manager",
+        "-m",
+        help="Manager import path (module:object_path)",
+    ),
+]
+
+
+@app.command()
+def check(
+    data: Annotated[
+        Path, typer.Option(..., "--data", "-d", help="Path to data file (JSON)")
+    ],
+    schema: Annotated[str, typer.Option(..., "--schema", "-s", help="Schema name")],
+    version: Annotated[
+        str, typer.Option(..., "--version", "-v", help="Schema version")
+    ],
+    manager: ManagerOption,
+) -> None:
+    """Check a payload against a schema version."""
+    try:
+        mgr = resolve_manager(manager)
+        data_dict = load_json_file(data)
+
+        mgr.validate(data_dict, schema, version)
+
+        typer.secho(f"✓ Valid against {schema} v{version}", fg=typer.colors.GREEN)
+        raise typer.Exit(0)
+
+    except ValidationError as e:
+        typer.secho("✗ Validation failed", fg=typer.colors.RED)
+        typer.secho("\nValidation errors:", fg=typer.colors.RED)
+        for error in e.errors():
+            field = ".".join(str(loc) for loc in error["loc"])
+            typer.echo(f"  • {field}: {error['msg']}")
+        raise typer.Exit(1) from e
+    except ConfigError as e:
+        typer.secho(str(e), fg=typer.colors.RED)
+        raise typer.Exit(1) from e
+    except FileNotFoundError as e:
+        typer.secho(f"File not found: {e}", fg=typer.colors.RED)
+        raise typer.Exit(1) from e
+    except json.JSONDecodeError as e:
+        typer.secho(f"Invalid JSON in {data}: {e}", fg=typer.colors.RED)
+        raise typer.Exit(1) from e
+    except typer.Exit:
+        raise
+    except Exception as e:
+        typer.secho(f"Validation error: {e}", fg=typer.colors.RED)
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def managers(
+    module: Annotated[
+        str, typer.Argument(..., help="Module path to inspect for managers")
+    ],
+) -> None:
+    """List ModelManagers defined in a module."""
+    try:
+        names = list_managers_from_module(module)
+
+        table = Table(title=f"Managers in {module}")
+        table.add_column("Name", style="cyan")
+
+        for name in sorted(names):
+            table.add_row(name)
+
+        console.print(table)
+
+    except ImportError as e:
+        typer.secho(f"Cannot import module '{module}': {e}", fg=typer.colors.RED)
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def info(
+    manager: Annotated[
+        str, typer.Argument(..., help="Manager import path (module:object_path)")
+    ],
+) -> None:
+    """Show information about a specific manager."""
+    try:
+        mgr = resolve_manager(manager)
+
+        typer.secho(f"Manager: {manager}", bold=True)
+        typer.echo("")
+
+        versions = mgr.list_versions()
+        models = sorted({v.model.__name__ for v in versions})
+
+        if not models:
+            typer.secho("No models registered", fg=typer.colors.YELLOW)
+            return
+
+        typer.secho("Registered Models:", bold=True)
+        typer.echo("")
+
+        for model_name in models:
+            typer.secho(f"  {model_name}", bold=True)
+            for v in versions:
+                if v.model.__name__ == model_name:
+                    typer.echo(f"    • v{v.version[1]}")
+
+        typer.echo(f"\nTotal: {len(models)} models")
+
+    except ConfigError as e:
+        typer.secho(str(e), fg=typer.colors.RED)
+        raise typer.Exit(1) from e
+    except typer.Exit:
+        raise
+    except Exception as e:
+        typer.secho(str(e), fg=typer.colors.RED)
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def diff(
+    schema: Annotated[str, typer.Option(..., "--schema", "-s", help="Schema name")],
+    from_version: Annotated[
+        str, typer.Option(..., "--from", "-f", help="Source version")
+    ],
+    to_version: Annotated[str, typer.Option(..., "--to", "-t", help="Target version")],
+    manager: ManagerOption,
+    format: Annotated[
+        str, typer.Option(..., "--format", help="Output format (json)")
+    ] = "json",
+) -> None:
+    """Show differences between schema versions."""
+    try:
+        mgr = resolve_manager(manager)
+        diff_result = mgr.diff(schema, from_version, to_version)
+
+        if format == "json":
+            typer.echo(json.dumps(diff_result.render(), indent=2, default=str))
+        else:
+            typer.secho(f"Unknown format: {format}", fg=typer.colors.RED)
+            raise typer.Exit(1)
+
+    except ConfigError as e:
+        typer.secho(str(e), fg=typer.colors.RED)
+        raise typer.Exit(1) from e
+    except typer.Exit:
+        raise
+    except Exception as e:
+        typer.secho(f"Diff error: {e}", fg=typer.colors.RED)
+        raise typer.Exit(1) from e
+
+
+if __name__ == "__main__":
+    app()

pyverge/migration/__init__.py

@@ -0,0 +1,86 @@
+from . import types
+from .adapters import PydanticModelAdapter
+from .diff import PydanticDiff
+from .engine import Engine
+from .exceptions import (
+    DiscoveryError,
+    DiscoveryValidationError,
+    EngineError,
+    MaxDepthExceededError,
+    MigrationAlreadyRegisteredError,
+    MigrationError,
+    MigrationMissingFieldError,
+    MigrationNotFoundError,
+    MigrationPathIntegrityError,
+    ModelAlreadyRegisteredError,
+    ModelNotFoundError,
+    RegistryError,
+    VersionedModelError,
+)
+from .executor import LevelParallelExecutor, SequentialExecutor, StepExecutor
+from .graph import GraphBuilder, GraphEntry, MigrationGraph
+from .hooks import MigrationHook, OTELHook
+from .manager import ModelManager
+from .models import (
+    DiscoverySettings,
+    MigrationSettings,
+    VersioningSettings,
+)
+from .policy import (
+    earliest_target_resolver,
+    fixed_target_resolver,
+    latest_target_resolver,
+    multi_target_resolver,
+    skip_target_resolver,
+)
+from .registry import Registry
+from .strategy import DefaultEntryMigration, EntryMigration
+from .versioning import SentinelEdge, SentinelNode, VersionEdge, VersionNode
+from .walker import CompoundKeyWalker, PydanticWalker
+
+__all__ = [
+    "CompoundKeyWalker",
+    "DefaultEntryMigration",
+    "DiscoveryError",
+    "DiscoverySettings",
+    "DiscoveryValidationError",
+    "Engine",
+    "EngineError",
+    "EntryMigration",
+    "GraphBuilder",
+    "GraphEntry",
+    "LevelParallelExecutor",
+    "MaxDepthExceededError",
+    "MigrationAlreadyRegisteredError",
+    "MigrationError",
+    "MigrationGraph",
+    "MigrationHook",
+    "MigrationMissingFieldError",
+    "MigrationNotFoundError",
+    "MigrationPathIntegrityError",
+    "MigrationSettings",
+    "ModelAlreadyRegisteredError",
+    "ModelManager",
+    "ModelNotFoundError",
+    "OTELHook",
+    "PydanticDiff",
+    "PydanticModelAdapter",
+    "PydanticWalker",
+    "Registry",
+    "RegistryError",
+    "SentinelEdge",
+    "SentinelNode",
+    "SequentialExecutor",
+    "StepExecutor",
+    "VersionEdge",
+    "VersionNode",
+    "VersionedModelError",
+    "VersioningSettings",
+    "compile_target_spec",
+    "earliest_target_resolver",
+    "fixed_target_resolver",
+    "latest_target_resolver",
+    "multi_target_resolver",
+    "skip_target_resolver",
+    "types",
+]