pyrmute 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

pyrmute/model_version.py

@@ -3,6 +3,8 @@
 from dataclasses import dataclass
 from typing import Self
 
+from .exceptions import InvalidVersionError
+
 
 @dataclass(frozen=True, order=True)
 class ModelVersion:
@@ -29,19 +31,25 @@ class ModelVersion:
             Parsed Version instance.
 
         Raises:
-            ValueError: If version string format is invalid.
+            InvalidVersionError: If version string format is invalid.
         """
-        parts = version_str.split(".")
-        if len(parts) != 3:  # noqa: PLR2004
-            raise ValueError(f"Invalid version format: {version_str}")
-
         try:
-            major, minor, patch = int(parts[0]), int(parts[1]), int(parts[2])
+            parts = version_str.split(".")
+            if len(parts) != 3:  # noqa: PLR2004
+                raise InvalidVersionError(
+                    version_str, "Version must have exactly 3 parts (major.minor.patch)"
+                )
+
+            major, minor, patch = map(int, parts)
             if major < 0 or minor < 0 or patch < 0:
-                raise ValueError(f"Invalid version format: {version_str}")
+                raise InvalidVersionError(
+                    version_str, "Version parts must be positive integers"
+                )
             return cls(major, minor, patch)
         except ValueError as e:
-            raise ValueError(f"Invalid version format: {version_str}") from e
+            raise InvalidVersionError(
+                version_str, f"Version parts must be integers: {e}"
+            ) from e
 
     def __str__(self: Self) -> str:
         """Return string representation of version.

pyrmute/types.py

@@ -1,6 +1,9 @@
 """Type aliases needed in the package."""
 
+from __future__ import annotations
+
 from collections.abc import Callable
+from dataclasses import dataclass
 from typing import Any, TypeAlias, TypeVar
 
 from pydantic import BaseModel
@@ -9,18 +12,27 @@ from .model_version import ModelVersion
 
 DecoratedBaseModel = TypeVar("DecoratedBaseModel", bound=BaseModel)
 
-JsonValue: TypeAlias = dict[str, Any] | list[Any] | str | int | float | bool | None
+JsonValue: TypeAlias = (
+    int | float | str | bool | None | list["JsonValue"] | dict[str, "JsonValue"]
+)
 JsonSchema: TypeAlias = dict[str, JsonValue]
-JsonSchemaDefinitions: TypeAlias = dict[str, JsonSchema]
+JsonSchemaDefinitions: TypeAlias = dict[str, JsonValue]
 JsonSchemaGenerator: TypeAlias = Callable[[type[BaseModel]], JsonSchema]
 SchemaGenerators: TypeAlias = dict[ModelVersion, JsonSchemaGenerator]
 
-MigrationData: TypeAlias = dict[str, Any]
-MigrationFunc: TypeAlias = Callable[[MigrationData], MigrationData]
-
+ModelData: TypeAlias = dict[str, Any]
+MigrationFunc: TypeAlias = Callable[[ModelData], ModelData]
 MigrationKey: TypeAlias = tuple[ModelVersion, ModelVersion]
 MigrationMap: TypeAlias = dict[MigrationKey, MigrationFunc]
 
 ModelName: TypeAlias = str
 ModelMetadata: TypeAlias = tuple[ModelName, ModelVersion]
 VersionedModels: TypeAlias = dict[ModelVersion, type[BaseModel]]
+
+
+@dataclass
+class NestedModelInfo:
+    """Contains information about nested models."""
+
+    name: str
+    version: ModelVersion

pyrmute-0.3.0.dist-info/METADATA

@@ -0,0 +1,352 @@
+Metadata-Version: 2.4
+Name: pyrmute
+Version: 0.3.0
+Summary: Pydantic model migrations and schemas
+Author-email: Matt Ferrera <mattferrera@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/mferrera/pyrmute
+Project-URL: Repository, https://github.com/mferrera/pyrmute
+Project-URL: Documentation, https://github.com/mferrera/pyrmute
+Keywords: pydantic,migration,versioning,schema
+Classifier: Development Status :: 3 - Alpha
+Classifier: Topic :: Utilities
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Natural Language :: English
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic
+Provides-Extra: dev
+Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# pyrmute
+[![ci](https://img.shields.io/github/actions/workflow/status/mferrera/pyrmute/ci.yml?branch=main&logo=github&label=ci)](https://github.com/mferrera/pyrmute/actions?query=event%3Apush+branch%3Amain+workflow%3Aci)
+[![pypi](https://img.shields.io/pypi/v/pyrmute.svg)](https://pypi.python.org/pypi/pyrmute)
+[![versions](https://img.shields.io/pypi/pyversions/pyrmute.svg)](https://github.com/mferrera/pyrmute)
+[![license](https://img.shields.io/github/license/mferrera/pyrmute.svg)](https://github.com/mferrera/pyrmute/blob/main/LICENSE)
+
+Pydantic model migrations and schema management with semantic versioning.
+
+pyrmute handles the complexity of data model evolution so you can confidently
+make changes without breaking your production systems. Version your models,
+define transformations, and let pyrmute automatically migrate legacy data
+through multiple versions.
+
+**Key Features**
+
+- **Version your models** - Track schema evolution with semantic versioning
+- **Automatic migration chains** - Transform data across multiple versions
+  (1.0.0 → 2.0.0 → 3.0.0) in a single call
+- **Type-safe transformations** - Migrations return validated Pydantic models,
+  catching errors before they reach production
+- **Flexible schema export** - Generate JSON schemas for all versions with
+  support for `$ref`, custom generators, and nested models
+- **Production-ready** - Batch processing, parallel execution, and streaming
+  support for large datasets
+- **Only one dependency** - Pydantic
+
+## Help
+
+See [documentation](https://mferrera.github.io/pyrmute/) for complete guides
+and API reference.
+
+## Installation
+
+```bash
+pip install pyrmute
+```
+
+## Quick Start
+
+```python
+from pydantic import BaseModel
+from pyrmute import ModelManager, ModelData
+
+manager = ModelManager()
+
+
+# Version 1: Simple user model
+@manager.model("User", "1.0.0")
+class UserV1(BaseModel):
+    name: str
+    age: int
+
+
+# Version 2: Split name into components
+@manager.model("User", "2.0.0")
+class UserV2(BaseModel):
+    first_name: str
+    last_name: str
+    age: int
+
+
+# Version 3: Add email and make age optional
+@manager.model("User", "3.0.0")
+class UserV3(BaseModel):
+    first_name: str
+    last_name: str
+    email: str
+    age: int | None = None
+
+
+# Define how to migrate between versions
+@manager.migration("User", "1.0.0", "2.0.0")
+def split_name(data: ModelData) -> ModelData:
+    parts = data["name"].split(" ", 1)
+    return {
+        "first_name": parts[0],
+        "last_name": parts[1] if len(parts) > 1 else "",
+        "age": data["age"],
+    }
+
+
+@manager.migration("User", "2.0.0", "3.0.0")
+def add_email(data: ModelData) -> ModelData:
+    return {
+        **data,
+        "email": f"{data['first_name'].lower()}@example.com"
+    }
+
+
+# Migrate legacy data to the latest version
+legacy_data = {"name": "John Doe", "age": 30}  # or, legacy.model_dump()
+current_user = manager.migrate(legacy_data, "User", "1.0.0", "3.0.0")
+
+print(current_user)
+# UserV3(first_name='John', last_name='Doe', email='john@example.com', age=30)
+```
+
+## Advanced Usage
+
+### Compare Model Versions
+
+```python
+# See exactly what changed between versions
+diff = manager.diff("User", "1.0.0", "3.0.0")
+print(f"Added: {diff.added_fields}")
+print(f"Removed: {diff.removed_fields}")
+# Render a changelog to Markdown
+print(diff.to_markdown(header_depth=4))
+```
+
+With `header_depth=4` the output can be embedded nicely into this document.
+
+#### User: 1.0.0 → 3.0.0
+
+##### Added Fields
+
+- `email: str` (required)
+- `first_name: str` (required)
+- `last_name: str` (required)
+
+##### Removed Fields
+
+- `name`
+
+##### Modified Fields
+
+- `age` - type: `int` → `int | None` - now optional - default added: `None`
+
+##### Breaking Changes
+
+- ⚠️ New required field 'last_name' will fail for existing data without defaults
+- ⚠️ New required field 'first_name' will fail for existing data without defaults
+- ⚠️ New required field 'email' will fail for existing data without defaults
+- ⚠️ Removed fields 'name' will be lost during migration
+- ⚠️ Field 'age' type changed - may cause validation errors
+
+
+### Batch Processing
+
+```python
+# Migrate thousands of records efficiently
+legacy_users = [
+    {"name": "Alice Smith", "age": 28},
+    {"name": "Bob Johnson", "age": 35},
+    # ... thousands more
+]
+
+# Parallel processing for CPU-intensive migrations
+users = manager.migrate_batch(
+    legacy_users,
+    "User",
+    from_version="1.0.0",
+    to_version="3.0.0",
+    parallel=True,
+    max_workers=4,
+)
+```
+
+### Streaming Large Datasets
+
+```python
+# Process huge datasets without loading everything into memory
+def load_users_from_database() -> Iterator[dict[str, Any]]:
+    yield from database.stream_users()
+
+
+# Migrate and save incrementally
+for user in manager.migrate_batch_streaming(
+    load_users_from_database(),
+    "User",
+    from_version="1.0.0",
+    to_version="3.0.0",
+    chunk_size=1000
+):
+    database.save(user)
+```
+
+### Test Your Migrations
+
+```python
+# Validate migration logic with test cases
+results = manager.test_migration(
+    "User",
+    from_version="1.0.0",
+    to_version="2.0.0",
+    test_cases=[
+        # (input, expected_output)
+        (
+            {"name": "Alice Smith", "age": 28},
+            {"first_name": "Alice", "last_name": "Smith", "age": 28}
+        ),
+        (
+            {"name": "Bob", "age": 35},
+            {"first_name": "Bob", "last_name": "", "age": 35}
+        ),
+    ]
+)
+
+# Use in your test suite
+assert results.all_passed, f"Migration failed: {results.failures}"
+```
+
+### Export JSON Schemas
+
+```python
+# Generate schemas for all versions
+manager.dump_schemas("schemas/")
+# Creates: User_v1.0.0.json, User_v2.0.0.json, User_v3.0.0.json
+
+# Use separate files with $ref for nested models with 'enable_ref=True'.
+manager.dump_schemas(
+    "schemas/",
+    separate_definitions=True,
+    ref_template="https://api.example.com/schemas/{model}_v{version}.json"
+)
+```
+
+### Auto-Migration
+
+```python
+# Skip writing migration functions for simple changes
+@manager.model("Config", "1.0.0")
+class ConfigV1(BaseModel):
+    timeout: int = 30
+
+
+@manager.model("Config", "2.0.0", backward_compatible=True)
+class ConfigV2(BaseModel):
+    timeout: int = 30
+    retries: int = 3  # New field with default
+
+
+# No migration function needed - defaults are applied automatically
+config = manager.migrate({"timeout": 60}, "Config", "1.0.0", "2.0.0")
+# ConfigV2(timeout=60, retries=3)
+```
+
+## Real-World Example
+
+```python
+from datetime import datetime
+from pydantic import BaseModel, EmailStr
+from pyrmute import ModelManager, ModelData
+
+manager = ModelManager()
+
+
+# API v1: Basic order
+@manager.model("Order", "1.0.0")
+class OrderV1(BaseModel):
+    id: str
+    items: list[str]
+    total: float
+
+
+# API v2: Add customer info
+@manager.model("Order", "2.0.0")
+class OrderV2(BaseModel):
+    id: str
+    items: list[str]
+    total: float
+    customer_email: EmailStr
+
+
+# API v3: Structured items and timestamps
+@manager.model("Order", "3.0.0")
+class OrderItemV3(BaseModel):
+    product_id: str
+    quantity: int
+    price: float
+
+
+@manager.model("Order", "3.0.0")
+class OrderV3(BaseModel):
+    id: str
+    items: list[OrderItemV3]
+    total: float
+    customer_email: EmailStr
+    created_at: datetime
+
+
+# Define migrations
+@manager.migration("Order", "1.0.0", "2.0.0")
+def add_customer_email(data: ModelData) -> ModelData:
+    return {**data, "customer_email": "customer@example.com"}
+
+
+@manager.migration("Order", "2.0.0", "3.0.0")
+def structure_items(data: ModelData) -> ModelData:
+    # Convert simple strings to structured items
+    structured_items = [
+        {
+            "product_id": item,
+            "quantity": 1,
+            "price": data["total"] / len(data["items"])
+        }
+        for item in data["items"]
+    ]
+    return {
+        **data,
+        "items": structured_items,
+        "created_at": datetime.now().isoformat()
+    }
+
+# Migrate old orders from your database
+old_order = {"id": "123", "items": ["widget", "gadget"], "total": 29.99}
+new_order = manager.migrate(old_order, "Order", "1.0.0", "3.0.0")
+database.save(new_order)
+```
+
+## Contributing
+
+For guidance on setting up a development environment and how to make a
+contribution to pyrmute, see [Contributing to
+pyrmute](https://mferrera.github.io/pyrmute/contributing/).
+
+## Reporting a Security Vulnerability
+
+See our [security
+policy](https://github.com/mferrera/pyrmute/security/policy).

pyrmute-0.3.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+pyrmute/__init__.py,sha256=vB0WBe3CukMBDnK0XP4qqehbMM4z_TUQMcTVPCUyt6Q,1082
+pyrmute/_migration_manager.py,sha256=KregnRUKqF1TC9XIpGAHpQvFlnRTEnp2X6Q2sAay8D4,12489
+pyrmute/_registry.py,sha256=iUjMPd6CYgyvWT8PxZqHWBZnsHrX25fOPDi_-k_QDJs,6124
+pyrmute/_schema_manager.py,sha256=eun8PTL9Gv1XAMVKmE3tYmjdrcf701-IapUXjb6WDL0,12122
+pyrmute/_version.py,sha256=5zTqm8rgXsWYBpB2M3Zw_K1D-aV8wP7NsBLrmMKkrAQ,704
+pyrmute/exceptions.py,sha256=Q57cUuzzMdkIl5Q0_VyLobpdB0WcrE0ggfC-LBoX2Uo,1681
+pyrmute/migration_testing.py,sha256=dOR8BDzmz4mFAI4hFtDUCEMS8Qc8qqD_iOV0qRai-qM,4967
+pyrmute/model_diff.py,sha256=vMa2NTYFqt9E7UYDZH4PQmLcoxQw5Sj-nPpUHB_53Ig,9594
+pyrmute/model_manager.py,sha256=e3UKFo79pkseCUFXIzW2_onu3GYjAnY1FR4JR_QF-Gc,24596
+pyrmute/model_version.py,sha256=ftNDuJlN3S5ZKQK8DKqqwfBDRiz4rGCYn-aJ3n6Zmqk,2025
+pyrmute/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyrmute/types.py,sha256=56IH8Rl9AmVh_w3V6PbSSEwaPrBSfc4pYrtcxodvlT0,1187
+pyrmute-0.3.0.dist-info/licenses/LICENSE,sha256=otWInySiZeGwhHqQQ7n7nxM5QBSBe2CzeGEmQDZEz8Q,1119
+pyrmute-0.3.0.dist-info/METADATA,sha256=jnRgO76ovFaktYKqq5BMf4tpUc_DYO_drET7c1hPVk0,9580
+pyrmute-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyrmute-0.3.0.dist-info/top_level.txt,sha256=C8QtzqE6yBHkeewSp1QewvsyeHj_VQLYjSa5HLtMiow,8
+pyrmute-0.3.0.dist-info/RECORD,,

pyrmute-0.1.0.dist-info/METADATA

@@ -1,130 +0,0 @@
-Metadata-Version: 2.4
-Name: pyrmute
-Version: 0.1.0
-Summary: Pydantic model migrations and schemas
-Author-email: Matt Ferrera <mattferrera@gmail.com>
-License: MIT
-Project-URL: Homepage, https://github.com/mferrera/pyrmute
-Project-URL: Repository, https://github.com/mferrera/pyrmute
-Project-URL: Documentation, https://github.com/mferrera/pyrmute
-Keywords: pydantic,migration,versioning,schema
-Classifier: Development Status :: 3 - Alpha
-Classifier: Topic :: Utilities
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Natural Language :: English
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pydantic
-Provides-Extra: dev
-Requires-Dist: mypy; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: pytest-mock; extra == "dev"
-Requires-Dist: pytest-xdist; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Dynamic: license-file
-
-# pyrmute
-
-[![ci](https://img.shields.io/github/actions/workflow/status/mferrera/pyrmute/ci.yml?branch=main&logo=github&label=ci)](https://github.com/mferrera/pyrmute/actions?query=event%3Apush+branch%3Amain+workflow%3Aci)
-[![pypi](https://img.shields.io/pypi/v/pyrmute.svg)](https://pypi.python.org/pypi/pyrmute)
-[![versions](https://img.shields.io/pypi/pyversions/pyrmute.svg)](https://github.com/mferrera/pyrmute)
-[![license](https://img.shields.io/github/license/pyrmute/pyrmute.svg)](https://github.com/mferrera/pyrmute/blob/main/LICENSE)
-
-Pydantic model migrations and schema management with semantic versioning.
-
-Pyrmute helps you evolve your data models over time without breaking changes.
-Version your Pydantic models, define migrations between versions, and
-automatically transform legacy data to current schemas. Export JSON schemas
-for all versions to maintain API contracts.
-
-**Key features:**
-- **Version your models** - Use semantic versioning to track model evolution
-- **Automatic migrations** - Chain migrations across multiple versions (1.0.0 → 2.0.0 → 3.0.0)
-- **Validated transformations** - Migrations return validated Pydantic models by default
-- **Schema export** - Generate JSON schemas for all versions, with support for `$ref` to external schemas and custom schema generators
-- **Nested model support** - Automatically migrates nested Pydantic models
-
-## Help
-
-See [documentation](https://mferrera.github.io/pyrmute/) for more details.
-
-## Installation
-
-Install using `pip install -U pyrmute`.
-
-## Simple Example
-
-```python
-from pydantic import BaseModel
-from pyrmute import ModelManager, MigrationData
-
-manager = ModelManager()
-
-
-@manager.model("User", "1.0.0")
-class UserV1(BaseModel):
-    """Version 1.0.0: Initial user model."""
-    name: str
-    age: int
-
-
-@manager.model("User", "2.0.0")
-class UserV2(BaseModel):
-    """Version 2.0.0: Split name into first/last."""
-    first_name: str
-    last_name: str
-    age: int
-
-
-@manager.model("User", "3.0.0")
-class UserV3(BaseModel):
-    """Version 3.0.0: Add email, make age optional."""
-    first_name: str
-    last_name: str
-    email: str
-    age: int | None = None
-
-
-# Define migrations
-@manager.migration("User", "1.0.0", "2.0.0")
-def split_name(data: MigrationData) -> MigrationData:
-    parts = data["name"].split(" ", 1)
-    return {
-        "first_name": parts[0],
-        "last_name": parts[1] if len(parts) > 1 else "",
-        "age": data["age"],
-    }
-
-
-@manager.migration("User", "2.0.0", "3.0.0")
-def add_email(data: MigrationData) -> MigrationData:
-    return {**data, "email": f"{data['first_name'].lower()}@example.com"}
-
-
-# Migrate old data forward, from raw data or dumped from the Pydantic model
-legacy_data = {"name": "John Doe", "age": 30}
-# Returns a validated Pydantic model
-current_user = manager.migrate(legacy_data, "User", "1.0.0", "3.0.0")
-
-print(current_user)
-# first_name='John' last_name='Doe' email='john@example.com' age=30
-
-# Export schemas for all versions
-manager.dump_schemas("schemas/")
-# Creates: schemas/User_v1.0.0.json, schemas/User_v2.0.0.json, schemas/User_v3.0.0.json
-```
-
-## Contributing
-
-For guidance on setting up a development environment and how to make a
-contribution to pyrmute, see
-[Contributing to pyrmute](https://mferrera.github.io/pyrmute/contributing/).
-
-## Reporting a Security Vulnerability
-
-See our [security policy](https://github.com/mferrera/pyrmute/security/policy).

pyrmute-0.1.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-pyrmute/__init__.py,sha256=wGuYwo2F3zPXnB_HLJsmjt7jbZVfCcyVwf0J78KvwzA,516
-pyrmute/_migration_manager.py,sha256=Z9Ie-fxJmOsmBw7oGWGHDrcNvr0aANlO6AqnBmJyYSA,9521
-pyrmute/_registry.py,sha256=_fZGRQtdkfCsrCrF6GLUuMmHmyq8up9hF6aS9FboQZA,5572
-pyrmute/_schema_manager.py,sha256=UdDC9j5nI-ljy9zKnfjhukzM4zfF-Edwu6P7CsdI7Xw,12581
-pyrmute/_version.py,sha256=5jwwVncvCiTnhOedfkzzxmxsggwmTBORdFL_4wq0ZeY,704
-pyrmute/model_manager.py,sha256=6rh0hXzZAaGv245RpVaAgjIRJ9s5DLmaRbsJAgwGQuQ,8289
-pyrmute/model_version.py,sha256=_vyLcIfOzHXrumPqzDSuNZMAZGqFh1ZYv6g933O_aH0,1801
-pyrmute/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pyrmute/types.py,sha256=NmlBA0ohFjpAIyZ6EvhbEigBV645LCZ-k8vaHjtB7Z4,978
-pyrmute-0.1.0.dist-info/licenses/LICENSE,sha256=otWInySiZeGwhHqQQ7n7nxM5QBSBe2CzeGEmQDZEz8Q,1119
-pyrmute-0.1.0.dist-info/METADATA,sha256=0t3BYtlBAYNORci6prJdVpgzA9Q8A0kjHvTrw8cJCNs,4515
-pyrmute-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pyrmute-0.1.0.dist-info/top_level.txt,sha256=C8QtzqE6yBHkeewSp1QewvsyeHj_VQLYjSa5HLtMiow,8
-pyrmute-0.1.0.dist-info/RECORD,,