spaghettimap 0.3.0__tar.gz

spaghettimap-0.3.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.3
+Name: spaghettimap
+Version: 0.3.0
+Summary: Add your description here
+Author: Fowler
+Author-email: Fowler <matty01fowler@gmail.com>
+Requires-Dist: jmespath>=1.1.0
+Requires-Dist: pydantic>=2.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# spaghettimap
+
+A Python library for **pydantic model-to-model conversion** powered by [JMESPath](https://jmespath.org/).
+
+## Features
+
+- Map any pydantic `BaseModel` to another using a declarative schema
+- Schema values can be **JMESPath expressions**, **Python callables**, or a **dict** combining both with an optional `transform`
+- Full support for all **JMESPath built-in functions** (`length`, `sort`, `max_by`, `contains`, `join`, `keys`, `to_string`, …)
+- **Custom JMESPath functions** via `jmespath.functions.Functions` subclass
+- **Filter expressions**, multi-select hash/list, pipe expressions, wildcards, and or-expressions
+- Solid **error handling** with `ConfigurationError`, `MappingError`, and `FieldMappingError` – all with clear, field-specific messages
+- **Fail-fast config checks** for invalid JMESPath expressions and schema fields missing from the target model
+- Pydantic validators (`@field_validator`, `@model_validator`) and type coercion run on the target model automatically
+- `map_many()` for batch conversion of model lists
+
+## Installation
+
+```bash
+pip install spaghettimap
+# or with uv
+uv add spaghettimap
+```
+
+## Quick Start
+
+```python
+from pydantic import BaseModel
+from spaghettimap import Mapper, MappingConfig
+
+class Source(BaseModel):
+    first_name: str
+    last_name: str
+    contact: dict  # {"email": "...", "phone": "..."}
+    tags: list[dict]  # [{"name": "...", "weight": 1.0}]
+
+class Target(BaseModel):
+    full_name: str
+    email: str
+    tag_count: int
+    upper_name: str
+
+mapper = Mapper()
+mapper.add_config(
+    MappingConfig(
+        from_type=Source,
+        to_type=Target,
+        schema={
+            # Python callable
+            "full_name": lambda d: f"{d['first_name']} {d['last_name']}",
+            # Nested JMESPath expression
+            "email": "contact.email",
+            # JMESPath built-in function
+            "tag_count": "length(tags)",
+            # JMESPath expression + Python transform
+            "upper_name": {"expression": "first_name", "transform": str.upper},
+        },
+    )
+)
+
+result: Target = mapper.map(source_instance, Target)
+```
+
+## Schema Value Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `str` | JMESPath expression | `"contact.email"`, `"tags[*].name"`, `"length(tags)"` |
+| `Callable[[dict], Any]` | Python function receiving the full source dict | `lambda d: d["x"] + d["y"]` |
+| `dict` | `{"expression": str\|Callable, "transform": Callable}` | `{"expression": "price", "transform": lambda p: f"£{p:.2f}"}` |
+
+## Custom JMESPath Functions
+
+```python
+import jmespath.functions
+from spaghettimap import Mapper, MappingConfig
+
+class MyFunctions(jmespath.functions.Functions):
+    @jmespath.functions.signature({"types": ["string"]})
+    def _func_upper(self, value: str) -> str:
+        return value.upper()
+
+mapper.add_config(
+    MappingConfig(
+        from_type=Source,
+        to_type=Target,
+        schema={"name": "upper(first_name)"},
+        custom_functions=MyFunctions(),
+    )
+)
+```
+
+## Batch Mapping
+
+```python
+results: list[Target] = mapper.map_many(source_list, Target)
+```
+
+## Error Hierarchy
+
+```
+SpaghettimapMapperError
+├── ConfigurationError   – invalid config (bad types, missing keys, unregistered pair)
+└── MappingError         – runtime mapping failure
+    └── FieldMappingError – failure for a specific field (has .field attribute)
+```

spaghettimap-0.3.0/README.md

@@ -0,0 +1,106 @@
+# spaghettimap
+
+A Python library for **pydantic model-to-model conversion** powered by [JMESPath](https://jmespath.org/).
+
+## Features
+
+- Map any pydantic `BaseModel` to another using a declarative schema
+- Schema values can be **JMESPath expressions**, **Python callables**, or a **dict** combining both with an optional `transform`
+- Full support for all **JMESPath built-in functions** (`length`, `sort`, `max_by`, `contains`, `join`, `keys`, `to_string`, …)
+- **Custom JMESPath functions** via `jmespath.functions.Functions` subclass
+- **Filter expressions**, multi-select hash/list, pipe expressions, wildcards, and or-expressions
+- Solid **error handling** with `ConfigurationError`, `MappingError`, and `FieldMappingError` – all with clear, field-specific messages
+- **Fail-fast config checks** for invalid JMESPath expressions and schema fields missing from the target model
+- Pydantic validators (`@field_validator`, `@model_validator`) and type coercion run on the target model automatically
+- `map_many()` for batch conversion of model lists
+
+## Installation
+
+```bash
+pip install spaghettimap
+# or with uv
+uv add spaghettimap
+```
+
+## Quick Start
+
+```python
+from pydantic import BaseModel
+from spaghettimap import Mapper, MappingConfig
+
+class Source(BaseModel):
+    first_name: str
+    last_name: str
+    contact: dict  # {"email": "...", "phone": "..."}
+    tags: list[dict]  # [{"name": "...", "weight": 1.0}]
+
+class Target(BaseModel):
+    full_name: str
+    email: str
+    tag_count: int
+    upper_name: str
+
+mapper = Mapper()
+mapper.add_config(
+    MappingConfig(
+        from_type=Source,
+        to_type=Target,
+        schema={
+            # Python callable
+            "full_name": lambda d: f"{d['first_name']} {d['last_name']}",
+            # Nested JMESPath expression
+            "email": "contact.email",
+            # JMESPath built-in function
+            "tag_count": "length(tags)",
+            # JMESPath expression + Python transform
+            "upper_name": {"expression": "first_name", "transform": str.upper},
+        },
+    )
+)
+
+result: Target = mapper.map(source_instance, Target)
+```
+
+## Schema Value Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `str` | JMESPath expression | `"contact.email"`, `"tags[*].name"`, `"length(tags)"` |
+| `Callable[[dict], Any]` | Python function receiving the full source dict | `lambda d: d["x"] + d["y"]` |
+| `dict` | `{"expression": str\|Callable, "transform": Callable}` | `{"expression": "price", "transform": lambda p: f"£{p:.2f}"}` |
+
+## Custom JMESPath Functions
+
+```python
+import jmespath.functions
+from spaghettimap import Mapper, MappingConfig
+
+class MyFunctions(jmespath.functions.Functions):
+    @jmespath.functions.signature({"types": ["string"]})
+    def _func_upper(self, value: str) -> str:
+        return value.upper()
+
+mapper.add_config(
+    MappingConfig(
+        from_type=Source,
+        to_type=Target,
+        schema={"name": "upper(first_name)"},
+        custom_functions=MyFunctions(),
+    )
+)
+```
+
+## Batch Mapping
+
+```python
+results: list[Target] = mapper.map_many(source_list, Target)
+```
+
+## Error Hierarchy
+
+```
+SpaghettimapMapperError
+├── ConfigurationError   – invalid config (bad types, missing keys, unregistered pair)
+└── MappingError         – runtime mapping failure
+    └── FieldMappingError – failure for a specific field (has .field attribute)
+```

spaghettimap-0.3.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "spaghettimap"
+version = "0.3.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [{ name = "Fowler", email = "matty01fowler@gmail.com" }]
+requires-python = ">=3.12"
+dependencies = ["jmespath>=1.1.0", "pydantic>=2.0"]
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.0.2", "pytest-cov>=6.0"]
+
+[tool.semantic_release]
+branch = "main"
+commit_parser = "conventional"
+version_toml = ["pyproject.toml:project.version"]
+build_command = "uv build"
+major_on_zero = false
+allow_zero_version = true

spaghettimap-0.3.0/src/spaghettimap/__init__.py

@@ -0,0 +1,19 @@
+"""jmespath-mapper – pydantic model-to-model conversion via JMESPath."""
+
+from .config import MappingConfig
+from .exceptions import (
+    ConfigurationError,
+    FieldMappingError,
+    SpaghettimapMapperError,
+    MappingError,
+)
+from .mapper import Mapper
+
+__all__ = [
+    "Mapper",
+    "MappingConfig",
+    "SpaghettimapMapperError",
+    "ConfigurationError",
+    "MappingError",
+    "FieldMappingError",
+]

spaghettimap-0.3.0/src/spaghettimap/config.py

@@ -0,0 +1,193 @@
+"""MappingConfig definition and schema validation."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+import jmespath
+import jmespath.exceptions
+import jmespath.functions
+from pydantic import BaseModel
+
+from .exceptions import ConfigurationError
+
+# A schema value can be:
+#   - str                        → JMESPath expression
+#   - Callable[[dict], Any]      → Python function receiving the source model dict
+#   - dict                       → {"expression": str | Callable, "transform": Callable (optional)}
+FieldMapping = str | Callable[..., Any] | dict[str, Any]
+
+
+def _is_basemodel_subclass(typ: Any) -> bool:
+    try:
+        return isinstance(typ, type) and issubclass(typ, BaseModel)
+    except TypeError:
+        return False
+
+
+class MappingConfig:
+    """
+    Configuration describing how to map from one pydantic model type to another.
+
+    Parameters
+    ----------
+    from_type:
+        The source pydantic ``BaseModel`` subclass.
+    to_type:
+        The target pydantic ``BaseModel`` subclass.
+    schema:
+        A mapping of *target field name* → field mapping.  Optional – if
+        omitted (or ``None``), *passthrough* is automatically enabled so that
+        all target fields are auto-mapped from source fields of the same name.
+
+        Each value may be:
+
+        * **str** – a JMESPath expression evaluated against the source model
+          serialised to a plain ``dict``.
+        * **Callable[[dict], Any]** – a Python callable that receives the full
+          source dict and returns the field value.
+        * **dict** – must contain an ``"expression"`` key (``str`` or
+          ``Callable``) and an optional ``"transform"`` key (``Callable``)
+          applied to the extracted value after the expression is evaluated.
+
+    passthrough:
+        When ``True``, any target field *not* covered by *schema* is
+        automatically filled from the source field with the **same name**
+        (if one exists).  Fields already produced by *schema* are never
+        overwritten.  Defaults to ``False`` unless *schema* is omitted/``None``,
+        in which case it is set to ``True`` automatically.
+
+    custom_functions:
+        An optional instance of a :class:`jmespath.functions.Functions`
+        subclass that provides additional JMESPath functions available to
+        *all* expressions in this config.
+
+    Raises
+    ------
+    ConfigurationError
+        If ``from_type`` or ``to_type`` are not pydantic ``BaseModel``
+        subclasses, or if any schema value has an unsupported type.
+    """
+
+    def __init__(
+        self,
+        from_type: type[BaseModel],
+        to_type: type[BaseModel],
+        schema: dict[str, FieldMapping] | None = None,
+        custom_functions: jmespath.functions.Functions | None = None,
+        passthrough: bool = False,
+    ) -> None:
+        if not _is_basemodel_subclass(from_type):
+            raise ConfigurationError(
+                f"'from_type' must be a pydantic BaseModel subclass, got {from_type!r}"
+            )
+        if not _is_basemodel_subclass(to_type):
+            raise ConfigurationError(
+                f"'to_type' must be a pydantic BaseModel subclass, got {to_type!r}"
+            )
+        if schema is None:
+            # No schema provided → enable passthrough automatically.
+            schema = {}
+            passthrough = True
+        elif not isinstance(schema, dict):
+            raise ConfigurationError(
+                f"'schema' must be a dict, got {type(schema).__name__!r}"
+            )
+
+        for key, value in schema.items():
+            if not isinstance(key, str):
+                raise ConfigurationError(
+                    f"All schema keys must be strings; got key {key!r} of type {type(key).__name__!r}"
+                )
+            _validate_field_mapping(key, value)
+
+        unknown_fields = [
+            field for field in schema if field not in to_type.model_fields
+        ]
+        if unknown_fields:
+            raise ConfigurationError(
+                f"Schema contains field(s) not present on target model {to_type.__name__!r}: "
+                f"{unknown_fields!r}"
+            )
+
+        if custom_functions is not None and not isinstance(
+            custom_functions, jmespath.functions.Functions
+        ):
+            raise ConfigurationError(
+                "'custom_functions' must be an instance of jmespath.functions.Functions "
+                f"(or a subclass), got {type(custom_functions).__name__!r}"
+            )
+
+        self.from_type = from_type
+        self.to_type = to_type
+        self.schema = schema
+        self.passthrough = passthrough
+        self.custom_functions = custom_functions
+        self._target_field_names = tuple(to_type.model_fields.keys())
+        self._jmespath_options = (
+            jmespath.Options(custom_functions=custom_functions)
+            if custom_functions is not None
+            else None
+        )
+        self._compiled_expressions = _compile_schema_expressions(schema)
+
+    def __repr__(self) -> str:
+        return (
+            f"MappingConfig("
+            f"from_type={self.from_type.__name__!r}, "
+            f"to_type={self.to_type.__name__!r}, "
+            f"fields={list(self.schema.keys())!r}, "
+            f"passthrough={self.passthrough!r})"
+        )
+
+
+def _validate_field_mapping(key: str, value: FieldMapping) -> None:
+    """Raise ConfigurationError if *value* is not a valid field mapping."""
+    if isinstance(value, (str, Callable)):  # type: ignore[arg-type]
+        return
+    if isinstance(value, dict):
+        if "expression" not in value:
+            raise ConfigurationError(
+                f"Schema value for field '{key}' is a dict but is missing the required "
+                f"'expression' key. Got keys: {list(value.keys())!r}"
+            )
+        expr = value["expression"]
+        if not isinstance(expr, str) and not callable(expr):
+            raise ConfigurationError(
+                f"'expression' for field '{key}' must be a str or callable, "
+                f"got {type(expr).__name__!r}"
+            )
+        transform = value.get("transform")
+        if transform is not None and not callable(transform):
+            raise ConfigurationError(
+                f"'transform' for field '{key}' must be callable, "
+                f"got {type(transform).__name__!r}"
+            )
+        return
+    raise ConfigurationError(
+        f"Schema value for field '{key}' must be a str, callable, or dict; "
+        f"got {type(value).__name__!r}"
+    )
+
+
+def _compile_schema_expressions(schema: dict[str, FieldMapping]) -> dict[str, Any]:
+    """Pre-compile all string JMESPath expressions in *schema*."""
+    compiled: dict[str, Any] = {}
+    for key, value in schema.items():
+        if isinstance(value, str):
+            compiled[key] = _compile_expression(key, value)
+            continue
+        if isinstance(value, dict):
+            expr = value.get("expression")
+            if isinstance(expr, str):
+                compiled[key] = _compile_expression(key, expr)
+    return compiled
+
+
+def _compile_expression(field_name: str, expression: str) -> Any:
+    try:
+        return jmespath.compile(expression)
+    except jmespath.exceptions.JMESPathError as exc:
+        raise ConfigurationError(
+            f"Invalid JMESPath expression for field '{field_name}': {expression!r}: {exc}"
+        ) from exc

spaghettimap-0.3.0/src/spaghettimap/exceptions.py

@@ -0,0 +1,29 @@
+"""Custom exceptions for jmespath-mapper."""
+
+from __future__ import annotations
+
+
+class SpaghettimapMapperError(Exception):
+    """Base exception for all jmespath-mapper errors."""
+
+
+class ConfigurationError(SpaghettimapMapperError):
+    """Raised when a MappingConfig is invalid."""
+
+
+class MappingError(SpaghettimapMapperError):
+    """Raised when a mapping operation fails at runtime."""
+
+
+class FieldMappingError(MappingError):
+    """Raised when mapping a specific field fails."""
+
+    def __init__(
+        self, field: str, reason: str, source_exception: BaseException | None = None
+    ) -> None:
+        self.field = field
+        self.reason = reason
+        message = f"Failed to map field '{field}': {reason}"
+        super().__init__(message)
+        if source_exception is not None:
+            self.__cause__ = source_exception

spaghettimap-0.3.0/src/spaghettimap/mapper.py

@@ -0,0 +1,256 @@
+"""Mapper class and internal evaluation helpers."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar, cast
+
+import jmespath
+import jmespath.exceptions
+import jmespath.functions
+from pydantic import BaseModel, ValidationError
+
+from .config import FieldMapping, MappingConfig, _is_basemodel_subclass
+from .exceptions import ConfigurationError, FieldMappingError, MappingError
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class Mapper:
+    """
+    Holds one or more :class:`MappingConfig` objects and performs pydantic
+    model-to-model conversions using JMESPath.
+
+    Usage
+    -----
+    ::
+
+        mapper = Mapper()
+        mapper.add_config(
+            MappingConfig(
+                from_type=SourceModel,
+                to_type=TargetModel,
+                schema={
+                    "name": "firstName",
+                    "email": "contact.email",
+                    "tag_count": "length(tags)",
+                    "upper_name": {"expression": "firstName", "transform": str.upper},
+                    "computed": lambda d: d["x"] + d["y"],
+                },
+            )
+        )
+        result: TargetModel = mapper.map(source_instance, TargetModel)
+    """
+
+    def __init__(self) -> None:
+        # Keyed by (from_type, to_type) pairs for O(1) lookup.
+        self._configs: dict[tuple[type[BaseModel], type[BaseModel]], MappingConfig] = {}
+
+    # ------------------------------------------------------------------
+    # Config management
+    # ------------------------------------------------------------------
+
+    def add_config(self, config: MappingConfig) -> None:
+        """
+        Register a :class:`MappingConfig`.
+
+        If a config already exists for the same ``(from_type, to_type)`` pair
+        it is silently replaced.
+
+        Raises
+        ------
+        ConfigurationError
+            If *config* is not a :class:`MappingConfig` instance.
+        """
+        if not isinstance(config, MappingConfig):
+            raise ConfigurationError(
+                f"Expected a MappingConfig instance, got {type(config).__name__!r}"
+            )
+        self._configs[(config.from_type, config.to_type)] = config
+
+    def get_config(
+        self, from_type: type[BaseModel], to_type: type[BaseModel]
+    ) -> MappingConfig | None:
+        """Return the registered config for *from_type* → *to_type*, or ``None``."""
+        return self._configs.get((from_type, to_type))
+
+    def _resolve_config(
+        self, from_type: type[BaseModel], to_type: type[BaseModel]
+    ) -> MappingConfig | None:
+        """Return config for *from_type*→*to_type*, allowing BaseModel ancestry fallback."""
+        config = self.get_config(from_type, to_type)
+        if config is not None:
+            return config
+
+        for base in from_type.__mro__[1:]:
+            if not _is_basemodel_subclass(base):
+                continue
+            inherited = self.get_config(cast(type[BaseModel], base), to_type)
+            if inherited is not None:
+                return inherited
+        return None
+
+    # ------------------------------------------------------------------
+    # Mapping
+    # ------------------------------------------------------------------
+
+    def map(self, source: BaseModel, to_type: type[T]) -> T:
+        """
+        Map *source* to a validated instance of *to_type*.
+
+        Raises
+        ------
+        ConfigurationError
+            If *source* is not a BaseModel instance, *to_type* is not a
+            BaseModel subclass, or no config is registered for the pair.
+        FieldMappingError
+            If evaluating a field expression or transform raises an exception.
+        MappingError
+            If pydantic validation of the constructed target model fails.
+        """
+        if not isinstance(source, BaseModel):
+            raise ConfigurationError(
+                f"'source' must be a pydantic BaseModel instance, got {type(source).__name__!r}"
+            )
+        if not _is_basemodel_subclass(to_type):
+            raise ConfigurationError(
+                f"'to_type' must be a pydantic BaseModel subclass, got {to_type!r}"
+            )
+
+        config = self._resolve_config(type(source), to_type)
+        if config is None:
+            raise ConfigurationError(
+                f"No mapping config registered for {type(source).__name__!r} → {to_type.__name__!r}. "
+                f"Call add_config() with a MappingConfig for this pair first."
+            )
+
+        # Serialise to a plain dict; nested BaseModel instances become dicts.
+        source_dict: dict[str, Any] = source.model_dump(mode="python")
+
+        compiled_expressions = config._compiled_expressions
+        result: dict[str, Any] = {
+            field: _evaluate_field_mapping(
+                field,
+                mapping,
+                source_dict,
+                compiled_expressions.get(field),
+                config._jmespath_options,
+            )
+            for field, mapping in config.schema.items()
+        }
+
+        if config.passthrough:
+            for field_name in config._target_field_names:
+                if field_name not in result and field_name in source_dict:
+                    result[field_name] = source_dict[field_name]
+
+        try:
+            return to_type.model_validate(result)
+        except ValidationError as exc:
+            raise MappingError(
+                f"Pydantic validation failed while constructing {to_type.__name__!r} "
+                f"from mapped data: {exc}"
+            ) from exc
+
+    def map_many(self, sources: list[BaseModel], to_type: type[T]) -> list[T]:
+        """
+        Map a list of source instances to a list of *to_type* instances.
+
+        Raises
+        ------
+        ConfigurationError
+            If *sources* is not a list.
+        """
+        if not isinstance(sources, list):
+            raise ConfigurationError(
+                f"'sources' must be a list, got {type(sources).__name__!r}"
+            )
+        return [self.map(source, to_type) for source in sources]
+
+    def __repr__(self) -> str:
+        pairs = [f"{f.__name__!r}→{t.__name__!r}" for f, t in self._configs]
+        return f"Mapper(configs=[{', '.join(pairs)}])"
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _evaluate_field_mapping(
+    field_name: str,
+    mapping: FieldMapping,
+    source_dict: dict[str, Any],
+    compiled_expression: Any | None,
+    jmespath_options: jmespath.Options | None,
+) -> Any:
+    """Evaluate a single field mapping against *source_dict*."""
+    try:
+        if isinstance(mapping, str):
+            return _eval_jmespath(
+                field_name,
+                mapping,
+                source_dict,
+                jmespath_options,
+                compiled_expression,
+            )
+
+        if callable(mapping):
+            return mapping(source_dict)
+
+        if isinstance(mapping, dict):
+            expr = mapping["expression"]
+            value = (
+                _eval_jmespath(
+                    field_name,
+                    expr,
+                    source_dict,
+                    jmespath_options,
+                    compiled_expression,
+                )
+                if isinstance(expr, str)
+                else expr(source_dict)
+            )
+            transform = mapping.get("transform")
+            return transform(value) if transform is not None else value
+
+        raise FieldMappingError(
+            field_name, f"Unsupported mapping type {type(mapping).__name__!r}"
+        )
+
+    except FieldMappingError:
+        raise
+    except Exception as exc:
+        raise FieldMappingError(field_name, str(exc), source_exception=exc) from exc
+
+
+def _eval_jmespath(
+    field_name: str,
+    expression: str,
+    source_dict: dict[str, Any],
+    options: jmespath.Options | None,
+    compiled_expression: Any | None = None,
+) -> Any:
+    """Compile and search a JMESPath expression with clear error messaging."""
+    try:
+        compiled = (
+            compiled_expression
+            if compiled_expression is not None
+            else jmespath.compile(expression)
+        )
+    except jmespath.exceptions.JMESPathError as exc:
+        raise FieldMappingError(
+            field_name,
+            f"Invalid JMESPath expression {expression!r}: {exc}",
+            source_exception=exc,
+        ) from exc
+
+    try:
+        if options is None:
+            return compiled.search(source_dict)
+        return compiled.search(source_dict, options=options)
+    except jmespath.exceptions.JMESPathError as exc:
+        raise FieldMappingError(
+            field_name,
+            f"JMESPath evaluation error for expression {expression!r}: {exc}",
+            source_exception=exc,
+        ) from exc