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

pyrmute/schema_config.py

@@ -0,0 +1,130 @@
+"""Schema configuration for customized schema generation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Self
+
+from pydantic.json_schema import GenerateJsonSchema
+
+if TYPE_CHECKING:
+    from .types import JsonSchemaGenerator, JsonSchemaMode
+
+
+@dataclass
+class SchemaConfig:
+    """Configuration for JSON schema generation.
+
+    This class provides fine-grained control over how Pydantic generates JSON schemas,
+    supporting both callable generators and Pydantic's GenerateJsonSchema classes.
+
+    Attributes:
+        schema_generator: Custom schema generator. Can be either:
+            - A callable taking (type[BaseModel]) -> JsonSchema
+            - A subclass of pydantic.json_schema.GenerateJsonSchema
+        mode: Schema generation mode - 'validation' for input validation or
+            'serialization' for output serialization.
+        by_alias: Whether to use field aliases in the schema.
+        ref_template: Template for JSON schema $ref URIs.
+        extra_kwargs: Additional arguments to pass to model_json_schema().
+
+    Example (Callable Generator):
+        >>> def custom_generator(model: type[BaseModel]) -> JsonSchema:
+        ...     schema = model.model_json_schema()
+        ...     schema["x-custom"] = "metadata"
+        ...     return schema
+        >>>
+        >>> config = SchemaConfig(
+        ...     schema_generator=custom_generator,
+        ...     mode="validation"
+        ... )
+
+    Example (GenerateJsonSchema Class):
+        >>> from pydantic.json_schema import GenerateJsonSchema
+        >>>
+        >>> class CustomSchemaGenerator(GenerateJsonSchema):
+        ...     def generate(
+        ...         self,
+        ...         schema: Mapping[str, Any],
+        ...         mode: JsonSchemaMode = "validation"
+        ...     ) -> JsonSchema:
+        ...         json_schema = super().generate(schema, mode=mode)
+        ...         json_schema["x-custom"] = "metadata"
+        ...         return json_schema
+        >>>
+        >>> config = SchemaConfig(
+        ...     schema_generator=CustomSchemaGenerator,
+        ...     mode="validation",
+        ...     by_alias=True
+        ... )
+    """
+
+    schema_generator: JsonSchemaGenerator | type[GenerateJsonSchema] | None = None
+    mode: JsonSchemaMode = "validation"
+    by_alias: bool = True
+    ref_template: str = "#/$defs/{model}"
+    extra_kwargs: dict[str, Any] = field(default_factory=dict)
+
+    def merge_with(self: Self, other: SchemaConfig | None) -> SchemaConfig:
+        """Merge this config with another, with other taking precedence.
+
+        Args:
+            other: Configuration to merge with (overrides this config).
+
+        Returns:
+            New SchemaConfig with merged values.
+        """
+        if other is None:
+            return self
+
+        return SchemaConfig(
+            schema_generator=other.schema_generator or self.schema_generator,
+            mode=other.mode if other.mode != "validation" else self.mode,
+            by_alias=other.by_alias if not other.by_alias else self.by_alias,
+            ref_template=other.ref_template
+            if other.ref_template != "#/$defs/{model}"
+            else self.ref_template,
+            extra_kwargs={**self.extra_kwargs, **other.extra_kwargs},
+        )
+
+    def to_kwargs(self: Self) -> dict[str, Any]:
+        """Convert config to kwargs for model_json_schema().
+
+        Note: If schema_generator is a callable (JsonSchemaGenerator type), it cannot be
+        passed to model_json_schema() and must be handled separately by calling it
+        directly.
+
+        Returns:
+            Dictionary of arguments for Pydantic's model_json_schema(). If
+            schema_generator is a callable, it will NOT be included.
+        """
+        kwargs = {
+            "mode": self.mode,
+            "by_alias": self.by_alias,
+            "ref_template": self.ref_template,
+            **self.extra_kwargs,
+        }
+
+        # Only add schema_generator if it's a GenerateJsonSchema class
+        # Callable generators are handled separately
+        if (
+            self.schema_generator is not None
+            and isinstance(self.schema_generator, type)
+            and issubclass(self.schema_generator, GenerateJsonSchema)
+        ):
+            kwargs["schema_generator"] = self.schema_generator
+
+        return kwargs
+
+    def is_callable_generator(self: Self) -> bool:
+        """Check if schema_generator is a callable function.
+
+        Returns:
+            True if schema_generator is a callable (not a class).
+        """
+        if self.schema_generator is None:
+            return False
+
+        return callable(self.schema_generator) and not isinstance(
+            self.schema_generator, type
+        )

pyrmute/types.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Any, TypeAlias, TypeVar
+from typing import Any, Literal, TypeAlias, TypeVar
 
 from pydantic import BaseModel
 
@@ -16,9 +16,10 @@ JsonValue: TypeAlias = (
     int | float | str | bool | None | list["JsonValue"] | dict[str, "JsonValue"]
 )
 JsonSchema: TypeAlias = dict[str, JsonValue]
+JsonSchemaMode = Literal["validation", "serialization"]
 JsonSchemaDefinitions: TypeAlias = dict[str, JsonValue]
 JsonSchemaGenerator: TypeAlias = Callable[[type[BaseModel]], JsonSchema]
-SchemaGenerators: TypeAlias = dict[ModelVersion, JsonSchemaGenerator]
+SchemaTransformer = Callable[[JsonSchema], JsonSchema]
 
 ModelData: TypeAlias = dict[str, Any]
 MigrationFunc: TypeAlias = Callable[[ModelData], ModelData]

{pyrmute-0.3.0.dist-info → pyrmute-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrmute
-Version: 0.3.0
+Version: 0.5.0
 Summary: Pydantic model migrations and schemas
 Author-email: Matt Ferrera <mattferrera@gmail.com>
 License: MIT
@@ -56,6 +56,43 @@ through multiple versions.
   support for large datasets
 - **Only one dependency** - Pydantic
 
+## When to Use pyrmute
+
+pyrmute is useful for handling schema evolution in production systems:
+
+- **Configuration files** - Upgrade user config files as your CLI/desktop app
+  evolves (`.apprc`, `config.json`, `settings.yaml`)
+- **Message queues & event streams** - Handle messages from multiple service
+  versions publishing different schemas (Kafka, RabbitMQ, SQS)
+- **ETL & data imports** - Import CSV/JSON/Excel files exported over years
+  with evolving structures
+- **ML model serving** - Manage feature schema evolution across model versions
+  and A/B tests
+- **API versioning** - Support multiple API versions with automatic
+  request/response migration
+- **Database migrations** - Transparently migrate legacy data on read without
+  downtime
+- **Data archival** - Process historical data dumps with various schema
+  versions
+
+See the [examples/](examples/) directory for complete, runnable code
+demonstrating these patterns.
+
+## When Not to Use
+
+pyrmute may not be the right choice if you have:
+
+- **High-throughput systems** - Runtime migration adds latency to hot paths.
+  Use upfront batch migrations instead.
+- **Multi-language services** - Python-only. Use Protobuf, Avro, or JSON
+  Schema for polyglot architectures.
+- **Existing schema registries** - Already using Confluent/AWS Glue? Stick
+  with them for compatibility enforcement and governance.
+- **Stable schemas** - Models rarely change? Traditional migration tools are
+  simpler and more maintainable.
+- **Database DDL changes** - pyrmute transforms data, not database schemas.
+  Alembic/Flyway or other ORMs may still be needed to alter tables.
+
 ## Help
 
 See [documentation](https://mferrera.github.io/pyrmute/) for complete guides
@@ -232,6 +269,71 @@ results = manager.test_migration(
 assert results.all_passed, f"Migration failed: {results.failures}"
 ```
 
+### Bidirectional Migrations
+
+```python
+# Support both upgrades and downgrades
+@manager.migration("Config", "2.0.0", "1.0.0")
+def downgrade_config(data: ModelData) -> ModelData:
+    """Rollback to v1 format."""
+    return {k: v for k, v in data.items() if k in ["setting1", "setting2"]}
+
+# Useful for:
+# - Rolling back deployments
+# - Normalizing outputs from multiple model versions
+# - Supporting legacy systems during transitions
+```
+
+### Nested Model Migrations
+
+```python
+# Automatically migrates nested Pydantic models
+@manager.model("Address", "1.0.0")
+class AddressV1(BaseModel):
+    street: str
+    city: str
+
+@manager.model("Address", "2.0.0")
+class AddressV2(BaseModel):
+    street: str
+    city: str
+    postal_code: str
+
+@manager.model("User", "2.0.0")
+class UserV2(BaseModel):
+    name: str
+    address: AddressV2  # Nested model
+
+# When migrating User, Address is automatically migrated too
+@manager.migration("Address", "1.0.0", "2.0.0")
+def add_postal_code(data: ModelData) -> ModelData:
+    return {**data, "postal_code": "00000"}
+```
+
+### Discriminated Unions
+
+```python
+from typing import Literal, Union
+from pydantic import Field
+
+# Handle complex type hierarchies
+@manager.model("CreditCard", "1.0.0")
+class CreditCardV1(BaseModel):
+    type: Literal["credit_card"] = "credit_card"
+    card_number: str
+
+@manager.model("PayPal", "1.0.0")
+class PayPalV1(BaseModel):
+    type: Literal["paypal"] = "paypal"
+    email: str
+
+@manager.model("Payment", "1.0.0")
+class PaymentV1(BaseModel):
+    method: Union[CreditCardV1, PayPalV1] = Field(discriminator="type")
+
+# Migrations respect discriminated unions
+```
+
 ### Export JSON Schemas
 
 ```python
@@ -267,79 +369,146 @@ config = manager.migrate({"timeout": 60}, "Config", "1.0.0", "2.0.0")
 # ConfigV2(timeout=60, retries=3)
 ```
 
-## Real-World Example
+## Real-World Examples
+
+### Configuration File Evolution
+
+```python
+# Your CLI tool evolves over time
+@manager.model("AppConfig", "1.0.0")
+class AppConfigV1(BaseModel):
+    api_key: str
+    debug: bool = False
+
+@manager.model("AppConfig", "2.0.0")
+class AppConfigV2(BaseModel):
+    api_key: str
+    api_endpoint: str = "https://api.example.com"
+    log_level: Literal["DEBUG", "INFO", "ERROR"] = "INFO"
+
+@manager.migration("AppConfig", "1.0.0", "2.0.0")
+def upgrade_config(data: dict) -> dict:
+    return {
+        "api_key": data["api_key"],
+        "api_endpoint": "https://api.example.com",
+        "log_level": "DEBUG" if data.get("debug") else "INFO",
+    }
+
+# Load and auto-upgrade user's config file
+def load_config(config_path: Path) -> AppConfigV2:
+    with open(config_path) as f:
+        data = json.load(f)
+
+    version = data.get("_version", "1.0.0")
+
+    # Migrate to current version
+    config = manager.migrate(
+        data,
+        "AppConfig",
+        from_version=version,
+        to_version="2.0.0"
+    )
+
+    # Save upgraded config with version tag
+    with open(config_path, "w") as f:
+        json.dump({**config.model_dump(), "_version": "2.0.0"}, f, indent=2)
+
+    return config
+```
+
+### Message Queue Consumer
 
 ```python
-from datetime import datetime
-from pydantic import BaseModel, EmailStr
-from pyrmute import ModelManager, ModelData
+# Handle messages from multiple service versions
+@manager.model("OrderEvent", "1.0.0")
+class OrderEventV1(BaseModel):
+    order_id: str
+    customer_email: str
+    items: list[dict]  # Unstructured
+
+@manager.model("OrderEvent", "2.0.0")
+class OrderEventV2(BaseModel):
+    order_id: str
+    customer_email: str
+    items: list[OrderItem]  # Structured
+    total: Decimal
+
+def process_message(message: dict, schema_version: str) -> None:
+    # Migrate to current schema regardless of source version
+    event = manager.migrate(
+        message,
+        "OrderEvent",
+        from_version=schema_version,
+        to_version="2.0.0"
+    )
+    # Process with current schema only
+    fulfill_order(event)
+```
 
-manager = ModelManager()
+### ETL Data Import
 
+```python
+# Import historical exports with evolving schemas
+import csv
+
+def import_customers(file_path: Path, file_version: str) -> None:
+    with open(file_path) as f:
+        reader = csv.DictReader(f)
+
+        # Stream migration for memory efficiency
+        for customer in manager.migrate_batch_streaming(
+            reader,
+            "Customer",
+            from_version=file_version,
+            to_version="3.0.0",
+            chunk_size=1000
+        ):
+            database.save(customer)
+
+# Handle files from different years
+import_customers("exports/2022_customers.csv", "1.0.0")
+import_customers("exports/2023_customers.csv", "2.0.0")
+import_customers("exports/2024_customers.csv", "3.0.0")
+```
 
-# 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()
-    }
+### ML Model Serving
 
-# 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)
+```python
+# Route requests to appropriate model versions
+class InferenceService:
+    def predict(self, features: dict, request_version: str) -> BaseModel:
+        # Determine target model version (A/B testing, gradual rollout, etc.)
+        model_version = self.get_model_version(features["user_id"])
+
+        # Migrate request to model's expected format
+        model_input = manager.migrate(
+            features,
+            "PredictionRequest",
+            from_version=request_version,
+            to_version=model_version
+        )
+
+        # Run inference
+        prediction = self.models[model_version].predict(model_input)
+
+        # Normalize output for logging/analytics
+        return manager.migrate(
+            prediction,
+            "PredictionResponse",
+            from_version=model_version,
+            to_version="3.0.0"
+        )
 ```
 
+See [examples/](examples/) for complete runnable code:
+- `config_file_migration.py` - CLI/desktop app config file evolution
+- `message_queue_consumer.py` - Kafka/RabbitMQ/SQS consumer handling multiple
+  schemas
+- `etl_data_import.py` - CSV/JSON/Excel import pipeline with historical data
+- `ml_inference_pipeline.py` - ML model serving with feature evolution
+- `advanced_features.py` - Complex Pydantic features (unions, nested models,
+  validators)
+
 ## Contributing
 
 For guidance on setting up a development environment and how to make a

pyrmute-0.5.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+pyrmute/__init__.py,sha256=vgq5e3jmr2FHmSnnnf-Kvl4Y6oGra3BDl5p_CaHDYLQ,1234
+pyrmute/_migration_manager.py,sha256=TFws66RsEdKLpvjDDQB1pKgeeyUe5WoutacTaeDsZoE,26154
+pyrmute/_registry.py,sha256=eEhMagcpUeZSPNZlIAuTzXcCkPGHTxfaIfEYEoEiFU8,5680
+pyrmute/_schema_manager.py,sha256=9NmyooG92gcOMOYNLRuC8isGUvivIf_Hp8kdVC8lmu8,18622
+pyrmute/_version.py,sha256=fvHpBU3KZKRinkriKdtAt3crenOyysELF-M9y3ozg3U,704
+pyrmute/exceptions.py,sha256=Q57cUuzzMdkIl5Q0_VyLobpdB0WcrE0ggfC-LBoX2Uo,1681
+pyrmute/migration_testing.py,sha256=fpKT2u7pgPRpswb4PUvbd-fQ3W76svNWvEVYVDmb3Dg,5066
+pyrmute/model_diff.py,sha256=vMa2NTYFqt9E7UYDZH4PQmLcoxQw5Sj-nPpUHB_53Ig,9594
+pyrmute/model_manager.py,sha256=EC3xN4Jve77Fk3xJjC3KrU_sY3Eoae-ucJE8wQ3bO3M,27778
+pyrmute/model_version.py,sha256=ftNDuJlN3S5ZKQK8DKqqwfBDRiz4rGCYn-aJ3n6Zmqk,2025
+pyrmute/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyrmute/schema_config.py,sha256=ttM4a1-EUUlxmsol6L4rN_Mse-77Y-yidn0ezojy0uY,4767
+pyrmute/types.py,sha256=rzRxOYfh4WPVR1KoNT3vC3UjuBlTarMnNL6Z1Y5icrw,1237
+pyrmute-0.5.0.dist-info/licenses/LICENSE,sha256=otWInySiZeGwhHqQQ7n7nxM5QBSBe2CzeGEmQDZEz8Q,1119
+pyrmute-0.5.0.dist-info/METADATA,sha256=QOv8NMAZ_sw-k2bFOHXM79XGnPUBArt4PRELq5cUdMY,15169
+pyrmute-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyrmute-0.5.0.dist-info/top_level.txt,sha256=C8QtzqE6yBHkeewSp1QewvsyeHj_VQLYjSa5HLtMiow,8
+pyrmute-0.5.0.dist-info/RECORD,,

pyrmute-0.3.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-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,,