muotti 0.1.0__tar.gz

muotti-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 The Bolinette Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

muotti-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: muotti
+Version: 0.1.0
+Summary: Map objects onto other objects: protocols, profiles and a pluggable value converter.
+Author: Pierre Chat
+Author-email: Pierre Chat <pierrechat@outlook.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Requires-Dist: escondite>=0.1.2
+Requires-Dist: mirino>=0.1.0
+Requires-Dist: peritype>=0.8.0
+Requires-Dist: pydantic>=2.12.5 ; extra == 'pydantic'
+Requires-Python: >=3.13
+Provides-Extra: pydantic
+Description-Content-Type: text/markdown
+
+# Muotti
+
+Muotti maps an object onto another object.
+It reads the fields of a source, converts them to the types the destination expects, and builds or updates that destination.
+
+Muotti knows nothing about any particular kind of object, and is taught one shape at a time through object protocols.
+Dataclasses, `TypedDict`s, mappings, sequences, plain classes and pydantic models are the ones that come with it.
+Muotti is used by the [Bolinette project](https://github.com/bolinette) to build payloads, responses and configuration sections.
+
+```python
+from dataclasses import dataclass
+from muotti import DataclassProtocol, Mapper
+
+
+@dataclass
+class UserPayload:
+    name: str
+    age: int
+
+
+@dataclass
+class User:
+    name: str
+    age: int
+    active: bool = True
+
+
+mapper = Mapper()
+mapper.add_protocol(DataclassProtocol())
+
+assert mapper.map(User, UserPayload("Bob", 42)) == User("Bob", 42, active=True)
+```
+
+## Installation
+
+```shell
+$ pip install muotti             # or use your preferred package manager
+$ pip install muotti[pydantic]   # with the pydantic protocol and value converter
+```
+
+## Requirements
+
+Muotti requires Python 3.13 (or newer).
+It depends on [peritype](https://pypi.org/project/peritype/) to read types at runtime, on [mirino](https://pypi.org/project/mirino/) for the paths it names fields with, and on [escondite](https://pypi.org/project/escondite/) for the decorators.
+[pydantic](https://pypi.org/project/pydantic/) is only needed for the `pydantic` extra.
+
+## Object protocols
+
+An `ObjectProtocol` teaches Muotti one kind of object: which fields a type has, how to read one from an instance, and how to build the type from the values collected for it.
+A mapper starts empty, and resolves the first protocol that matches a type, in decreasing `priority`.
+
+```python
+from muotti import DataclassProtocol, Mapper, MappingProtocol
+
+mapper = Mapper()
+mapper.add_protocol(DataclassProtocol())
+mapper.add_protocol(MappingProtocol())
+
+assert mapper.map(dict[str, object], User, {"name": "Bob", "age": 42}).name == "Bob"
+```
+
+Some protocols know the fields of their type up front, such as the dataclass one.
+Others are source-driven and take the keys they are given, which is how a `dict`, a `list` or a `set` destination is filled.
+
+Writing a protocol is how a new kind of object is supported: subclass `ObjectProtocol`, implement `matches`, `fields`, `read_field` and `construct`, and give it a `priority` above the bundled ones if it must win over them.
+
+## Mapping and merging
+
+`map(dest_cls, src)` builds a new instance, and takes the source class from the source itself.
+`map(src_cls, dest_cls, src)` is the form to use when the source cannot describe itself, a `dict` being the usual case.
+`merge(src, dest)` maps into an instance that already exists, and leaves the fields absent from the source alone.
+
+```python
+user = mapper.map(User, UserPayload("Bob", 42))
+mapper.merge(UserPayload("Alice", 30), user)
+
+assert user == User("Alice", 30, active=True)
+```
+
+A field missing from the source is an error, unless the destination has a default for it or accepts `None`.
+With `validate=True`, every field is tried and the failures are collected in a single `ValidationError` instead of raising on the first one.
+
+```python
+from muotti.errors import ValidationError
+
+try:
+    mapper.map(dict[str, object], User, {"name": "Bob"}, validate=True)
+except ValidationError as err:
+    assert [str(e.dest) for e in err.errors] == ["User.age"]
+```
+
+## Profiles
+
+Field names do not always line up, and a `Profile` is where that is written down.
+`register` opens a sequence between two types, and `for_attr` points at a destination field with a lambda.
+That lambda receives an expression recorder, not an instance, so `lambda d: d.name` records the path to the field instead of reading anything.
+
+```python
+from muotti import Mapper, Profile
+
+
+@dataclass
+class Account:
+    full_name: str
+
+
+class AccountProfile(Profile):
+    def __init__(self) -> None:
+        super().__init__()
+        self.register(Account, User).for_attr(
+            lambda d: d.name,
+            lambda opt: opt.map_from(lambda s: s.full_name),
+        ).for_attr(
+            lambda d: d.age,
+            lambda opt: opt.default(lambda: 0),
+        )
+
+
+mapper.load_profiles([AccountProfile()])
+
+assert mapper.map(User, Account("Bob")) == User("Bob", 0, active=True)
+```
+
+Besides `map_from` and `default`, an option can `ignore` a field, mark it `read_only`, `allow_write` on a field the protocol reports as immutable, or force a type with `use_type`.
+A sequence can also run a function `before_mapping` or `after_mapping`, and `include` another pair of types to inherit its overrides.
+
+`assert_configuration_valid` walks every loaded sequence and raises a `MappingConfigurationError` listing each destination field that is required, has no default, and has nothing in the source to fill it.
+It is meant to run once at startup, rather than to discover the problem on the first request.
+
+## Value conversion
+
+Everything that is not a nested object ends up at a value converter, and that converter is a protocol:
+
+```python
+class ValueConverter(Protocol):
+    def convert(self, value: Any, spec: FieldSpec, dest: ExpressionNode, src: ExpressionNode) -> Any: ...
+```
+
+A mapper uses `BasicValueConverter` unless it is given another one.
+It passes a value through when it already has the target type, and otherwise applies a small set of conversions.
+Numbers convert between themselves, `str` and `bytes` convert into each other, a string becomes a `UUID`, a `Decimal`, a `PurePath` or an `Enum` member, an ISO 8601 string becomes a `datetime`, a `date` or a `time`, and a number of seconds becomes a `timedelta`.
+Lists, sets, tuples and dicts are converted element by element, and the members of a union are tried in order, the ones the value already matches first.
+With `strict=True` nothing is converted, and only a value that already has the right type is accepted.
+
+```python
+from datetime import date
+from muotti import BasicValueConverter, Mapper
+
+
+@dataclass
+class Event:
+    day: date
+    tags: set[str]
+
+
+mapper = Mapper(BasicValueConverter())
+mapper.add_protocol(DataclassProtocol())
+mapper.add_protocol(MappingProtocol())
+
+event = mapper.map(dict[str, object], Event, {"day": "2026-09-18", "tags": ["a", "a", "b"]})
+assert event == Event(date(2026, 9, 18), {"a", "b"})
+```
+
+The `pydantic` extra brings a second converter, which hands the value to a `TypeAdapter` and follows pydantic's own rules.
+It is the one to use when those rules are what the rest of an application already expects.
+
+```python
+from muotti import Mapper
+from muotti.pydantic import PydanticProtocol, PydanticValueConverter
+
+mapper = Mapper(PydanticValueConverter())
+mapper.add_protocol(PydanticProtocol())
+```
+
+The two converters do not accept exactly the same values, so a mapper that used to run on pydantic should be given `PydanticValueConverter` explicitly rather than left on the default.
+
+## Discovery through a cache
+
+`mapping` and `mapping_protocol` record a profile or a protocol class in an [escondite](https://pypi.org/project/escondite/) cache when the module is imported, and `load_from_cache` instantiates everything the cache holds.
+An application collects its profiles this way instead of importing each one by hand.
+
+```python
+from escondite import Cache
+from muotti import Mapper, Profile, mapping
+
+cache = Cache()
+
+
+@mapping(cache=cache)
+class AccountProfile(Profile): ...
+
+
+mapper = Mapper()
+mapper.load_from_cache(cache)
+```
+
+Both decorators take the bare and the parametrized form, and fall back to escondite's global cache when none is given.
+Registering by hand with `add_protocol` and `load_profiles` works just as well, the cache is a convenience.
+
+## Reference
+
+### Bundled protocols
+
+| Protocol                            | Destination                                   | Priority |
+| ----------------------------------- | --------------------------------------------- | -------- |
+| `PydanticProtocol`                  | `pydantic.BaseModel`, in `muotti.pydantic`    | 90       |
+| `TypedDictProtocol`                 | `TypedDict`, with `NotRequired` and totality  | 80       |
+| `DataclassProtocol`                 | `@dataclass` types                            | 70       |
+| `MappingProtocol`                   | `dict` and other mappings, source-driven      | 20       |
+| `SequenceProtocol` / `SetProtocol`  | `list`, `tuple` / `set`, `frozenset`          | 20       |
+| `PlainObjectProtocol`               | Any class with annotated attributes           | 0        |
+
+### Errors
+
+All errors derive from `muotti.errors.MuottiError`, and a `MappingError` carries the `dest` and `src` paths the failure happened on.
+
+| Error                        | Raised when                                                        |
+| ---------------------------- | ------------------------------------------------------------------ |
+| `SourceNotFoundError`        | A required destination field has nothing in the source             |
+| `DestinationNotNullableError`| `None` reached a field that does not accept it                     |
+| `ConversionError`            | A value could not be converted to the type of its field            |
+| `InstantiationError`         | The destination type rejected the values collected for it          |
+| `ImmutableFieldError`        | A field cannot be written to                                       |
+| `NoProtocolError`            | No `ObjectProtocol` matched the destination type                   |
+| `ValidationError`            | Raised with `validate=True`, and holds every error in `errors`     |
+| `MappingConfigurationError`  | `assert_configuration_valid` found fields nothing can fill         |
+
+## License
+
+Muotti is released under the MIT license, see [LICENSE.txt](LICENSE.txt).

muotti-0.1.0/README.md

@@ -0,0 +1,230 @@
+# Muotti
+
+Muotti maps an object onto another object.
+It reads the fields of a source, converts them to the types the destination expects, and builds or updates that destination.
+
+Muotti knows nothing about any particular kind of object, and is taught one shape at a time through object protocols.
+Dataclasses, `TypedDict`s, mappings, sequences, plain classes and pydantic models are the ones that come with it.
+Muotti is used by the [Bolinette project](https://github.com/bolinette) to build payloads, responses and configuration sections.
+
+```python
+from dataclasses import dataclass
+from muotti import DataclassProtocol, Mapper
+
+
+@dataclass
+class UserPayload:
+    name: str
+    age: int
+
+
+@dataclass
+class User:
+    name: str
+    age: int
+    active: bool = True
+
+
+mapper = Mapper()
+mapper.add_protocol(DataclassProtocol())
+
+assert mapper.map(User, UserPayload("Bob", 42)) == User("Bob", 42, active=True)
+```
+
+## Installation
+
+```shell
+$ pip install muotti             # or use your preferred package manager
+$ pip install muotti[pydantic]   # with the pydantic protocol and value converter
+```
+
+## Requirements
+
+Muotti requires Python 3.13 (or newer).
+It depends on [peritype](https://pypi.org/project/peritype/) to read types at runtime, on [mirino](https://pypi.org/project/mirino/) for the paths it names fields with, and on [escondite](https://pypi.org/project/escondite/) for the decorators.
+[pydantic](https://pypi.org/project/pydantic/) is only needed for the `pydantic` extra.
+
+## Object protocols
+
+An `ObjectProtocol` teaches Muotti one kind of object: which fields a type has, how to read one from an instance, and how to build the type from the values collected for it.
+A mapper starts empty, and resolves the first protocol that matches a type, in decreasing `priority`.
+
+```python
+from muotti import DataclassProtocol, Mapper, MappingProtocol
+
+mapper = Mapper()
+mapper.add_protocol(DataclassProtocol())
+mapper.add_protocol(MappingProtocol())
+
+assert mapper.map(dict[str, object], User, {"name": "Bob", "age": 42}).name == "Bob"
+```
+
+Some protocols know the fields of their type up front, such as the dataclass one.
+Others are source-driven and take the keys they are given, which is how a `dict`, a `list` or a `set` destination is filled.
+
+Writing a protocol is how a new kind of object is supported: subclass `ObjectProtocol`, implement `matches`, `fields`, `read_field` and `construct`, and give it a `priority` above the bundled ones if it must win over them.
+
+## Mapping and merging
+
+`map(dest_cls, src)` builds a new instance, and takes the source class from the source itself.
+`map(src_cls, dest_cls, src)` is the form to use when the source cannot describe itself, a `dict` being the usual case.
+`merge(src, dest)` maps into an instance that already exists, and leaves the fields absent from the source alone.
+
+```python
+user = mapper.map(User, UserPayload("Bob", 42))
+mapper.merge(UserPayload("Alice", 30), user)
+
+assert user == User("Alice", 30, active=True)
+```
+
+A field missing from the source is an error, unless the destination has a default for it or accepts `None`.
+With `validate=True`, every field is tried and the failures are collected in a single `ValidationError` instead of raising on the first one.
+
+```python
+from muotti.errors import ValidationError
+
+try:
+    mapper.map(dict[str, object], User, {"name": "Bob"}, validate=True)
+except ValidationError as err:
+    assert [str(e.dest) for e in err.errors] == ["User.age"]
+```
+
+## Profiles
+
+Field names do not always line up, and a `Profile` is where that is written down.
+`register` opens a sequence between two types, and `for_attr` points at a destination field with a lambda.
+That lambda receives an expression recorder, not an instance, so `lambda d: d.name` records the path to the field instead of reading anything.
+
+```python
+from muotti import Mapper, Profile
+
+
+@dataclass
+class Account:
+    full_name: str
+
+
+class AccountProfile(Profile):
+    def __init__(self) -> None:
+        super().__init__()
+        self.register(Account, User).for_attr(
+            lambda d: d.name,
+            lambda opt: opt.map_from(lambda s: s.full_name),
+        ).for_attr(
+            lambda d: d.age,
+            lambda opt: opt.default(lambda: 0),
+        )
+
+
+mapper.load_profiles([AccountProfile()])
+
+assert mapper.map(User, Account("Bob")) == User("Bob", 0, active=True)
+```
+
+Besides `map_from` and `default`, an option can `ignore` a field, mark it `read_only`, `allow_write` on a field the protocol reports as immutable, or force a type with `use_type`.
+A sequence can also run a function `before_mapping` or `after_mapping`, and `include` another pair of types to inherit its overrides.
+
+`assert_configuration_valid` walks every loaded sequence and raises a `MappingConfigurationError` listing each destination field that is required, has no default, and has nothing in the source to fill it.
+It is meant to run once at startup, rather than to discover the problem on the first request.
+
+## Value conversion
+
+Everything that is not a nested object ends up at a value converter, and that converter is a protocol:
+
+```python
+class ValueConverter(Protocol):
+    def convert(self, value: Any, spec: FieldSpec, dest: ExpressionNode, src: ExpressionNode) -> Any: ...
+```
+
+A mapper uses `BasicValueConverter` unless it is given another one.
+It passes a value through when it already has the target type, and otherwise applies a small set of conversions.
+Numbers convert between themselves, `str` and `bytes` convert into each other, a string becomes a `UUID`, a `Decimal`, a `PurePath` or an `Enum` member, an ISO 8601 string becomes a `datetime`, a `date` or a `time`, and a number of seconds becomes a `timedelta`.
+Lists, sets, tuples and dicts are converted element by element, and the members of a union are tried in order, the ones the value already matches first.
+With `strict=True` nothing is converted, and only a value that already has the right type is accepted.
+
+```python
+from datetime import date
+from muotti import BasicValueConverter, Mapper
+
+
+@dataclass
+class Event:
+    day: date
+    tags: set[str]
+
+
+mapper = Mapper(BasicValueConverter())
+mapper.add_protocol(DataclassProtocol())
+mapper.add_protocol(MappingProtocol())
+
+event = mapper.map(dict[str, object], Event, {"day": "2026-09-18", "tags": ["a", "a", "b"]})
+assert event == Event(date(2026, 9, 18), {"a", "b"})
+```
+
+The `pydantic` extra brings a second converter, which hands the value to a `TypeAdapter` and follows pydantic's own rules.
+It is the one to use when those rules are what the rest of an application already expects.
+
+```python
+from muotti import Mapper
+from muotti.pydantic import PydanticProtocol, PydanticValueConverter
+
+mapper = Mapper(PydanticValueConverter())
+mapper.add_protocol(PydanticProtocol())
+```
+
+The two converters do not accept exactly the same values, so a mapper that used to run on pydantic should be given `PydanticValueConverter` explicitly rather than left on the default.
+
+## Discovery through a cache
+
+`mapping` and `mapping_protocol` record a profile or a protocol class in an [escondite](https://pypi.org/project/escondite/) cache when the module is imported, and `load_from_cache` instantiates everything the cache holds.
+An application collects its profiles this way instead of importing each one by hand.
+
+```python
+from escondite import Cache
+from muotti import Mapper, Profile, mapping
+
+cache = Cache()
+
+
+@mapping(cache=cache)
+class AccountProfile(Profile): ...
+
+
+mapper = Mapper()
+mapper.load_from_cache(cache)
+```
+
+Both decorators take the bare and the parametrized form, and fall back to escondite's global cache when none is given.
+Registering by hand with `add_protocol` and `load_profiles` works just as well, the cache is a convenience.
+
+## Reference
+
+### Bundled protocols
+
+| Protocol                            | Destination                                   | Priority |
+| ----------------------------------- | --------------------------------------------- | -------- |
+| `PydanticProtocol`                  | `pydantic.BaseModel`, in `muotti.pydantic`    | 90       |
+| `TypedDictProtocol`                 | `TypedDict`, with `NotRequired` and totality  | 80       |
+| `DataclassProtocol`                 | `@dataclass` types                            | 70       |
+| `MappingProtocol`                   | `dict` and other mappings, source-driven      | 20       |
+| `SequenceProtocol` / `SetProtocol`  | `list`, `tuple` / `set`, `frozenset`          | 20       |
+| `PlainObjectProtocol`               | Any class with annotated attributes           | 0        |
+
+### Errors
+
+All errors derive from `muotti.errors.MuottiError`, and a `MappingError` carries the `dest` and `src` paths the failure happened on.
+
+| Error                        | Raised when                                                        |
+| ---------------------------- | ------------------------------------------------------------------ |
+| `SourceNotFoundError`        | A required destination field has nothing in the source             |
+| `DestinationNotNullableError`| `None` reached a field that does not accept it                     |
+| `ConversionError`            | A value could not be converted to the type of its field            |
+| `InstantiationError`         | The destination type rejected the values collected for it          |
+| `ImmutableFieldError`        | A field cannot be written to                                       |
+| `NoProtocolError`            | No `ObjectProtocol` matched the destination type                   |
+| `ValidationError`            | Raised with `validate=True`, and holds every error in `errors`     |
+| `MappingConfigurationError`  | `assert_configuration_valid` found fields nothing can fill         |
+
+## License
+
+Muotti is released under the MIT license, see [LICENSE.txt](LICENSE.txt).

muotti-0.1.0/muotti/__init__.py

@@ -0,0 +1,31 @@
+from muotti._absence import (
+    ABSENT as ABSENT,
+    Generation as Generation,
+    MapMode as MapMode,
+    Maybe as Maybe,
+    is_present as is_present,
+)
+from muotti._spec import FieldOverride as FieldOverride, FieldSpec as FieldSpec, NO_OVERRIDE as NO_OVERRIDE
+from muotti._utils import (
+    dict_value_type as dict_value_type,
+    element_type as element_type,
+    is_value_type as is_value_type,
+    main_class as main_class,
+)
+from muotti._protocol import ObjectProtocol as ObjectProtocol, ProtocolRegistry as ProtocolRegistry
+from muotti._protocols import (
+    DataclassProtocol as DataclassProtocol,
+    MappingProtocol as MappingProtocol,
+    PlainObjectProtocol as PlainObjectProtocol,
+    SequenceProtocol as SequenceProtocol,
+    SetProtocol as SetProtocol,
+    TypedDictProtocol as TypedDictProtocol,
+)
+from muotti._value import BasicValueConverter as BasicValueConverter, ValueConverter as ValueConverter
+from muotti._profiles import (
+    MappingOptions as MappingOptions,
+    Profile as Profile,
+    SequenceBuilder as SequenceBuilder,
+)
+from muotti._decorators import mapping as mapping, mapping_protocol as mapping_protocol
+from muotti._mapper import Mapper as Mapper

muotti-0.1.0/muotti/_absence.py

@@ -0,0 +1,42 @@
+from enum import Enum, auto
+from typing import Final, Self, TypeGuard, override
+
+
+class _Absent:
+    __slots__ = ()
+    _instance: "_Absent | None" = None
+
+    def __new__(cls) -> Self:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance  # pyright: ignore[reportReturnType]
+
+    @override
+    def __repr__(self) -> str:
+        return "ABSENT"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+ABSENT: Final[_Absent] = _Absent()
+
+type Maybe[T] = T | _Absent
+
+
+def is_present[T](value: Maybe[T]) -> TypeGuard[T]:
+    return value is not ABSENT
+
+
+class Generation(Enum):
+    NONE = auto()
+
+    CLIENT_DEFAULT = auto()
+
+    SERVER_GENERATED = auto()
+
+
+class MapMode(Enum):
+    CREATE = auto()
+
+    MERGE = auto()

muotti-0.1.0/muotti/_decision.py

@@ -0,0 +1,60 @@
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import Any
+
+from muotti._absence import MapMode, Maybe, is_present
+from muotti._spec import FieldOverride, FieldSpec
+from muotti.errors import DestinationNotNullableError, MappingError, SourceNotFoundError
+
+
+class Action(Enum):
+    ASSIGN = auto()
+    SKIP = auto()
+    FAIL = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class Decision:
+    action: Action
+    value: Any = None
+    error: type[MappingError] = MappingError
+    reason: str = ""
+
+
+def decide(presence: Maybe[Any], spec: FieldSpec, mode: MapMode, override: FieldOverride) -> Decision:
+    if override.ignore:
+        return Decision(Action.SKIP)
+
+    writable = spec.writable or override.allow_write
+    if override.read_only:
+        writable = False
+
+    if not writable:
+        return Decision(Action.SKIP)
+
+    if is_present(presence):
+        if presence is None and not spec.nullable:
+            return Decision(
+                Action.FAIL,
+                error=DestinationNotNullableError,
+                reason="cannot bind a None value to a non-nullable field",
+            )
+        return Decision(Action.ASSIGN, value=presence)
+
+    if mode is MapMode.MERGE:
+        return Decision(Action.SKIP)
+
+    if override.default_factory is not None:
+        return Decision(Action.ASSIGN, value=override.default_factory())
+
+    if spec.self_populating:
+        return Decision(Action.SKIP)
+
+    if spec.nullable:
+        return Decision(Action.ASSIGN, value=None)
+
+    return Decision(
+        Action.FAIL,
+        error=SourceNotFoundError,
+        reason="source path not found and destination has no default",
+    )

muotti-0.1.0/muotti/_decorators.py

@@ -0,0 +1,50 @@
+from collections.abc import Callable
+from typing import Any, overload
+
+from escondite import Cache
+
+from muotti._profiles import Profile
+from muotti._protocol import ObjectProtocol
+
+MAPPING_PROFILE_CACHE_KEY = "__muotti_profile__"
+MAPPING_PROTOCOL_CACHE_KEY = "__muotti_protocol__"
+
+
+@overload
+def mapping[ProfileT: Profile](cls: type[ProfileT], /, *, cache: Cache | None = None) -> type[ProfileT]: ...
+@overload
+def mapping[ProfileT: Profile](*, cache: Cache | None = None) -> Callable[[type[ProfileT]], type[ProfileT]]: ...
+def mapping(*args: Any, cache: Cache | None = None) -> Any:
+    def decorator(cls: type[Profile]) -> type[Profile]:
+        Cache.with_fallback(cache).add(MAPPING_PROFILE_CACHE_KEY, cls)
+        return cls
+
+    match args:
+        case ():
+            return decorator
+        case (cls,):
+            return decorator(cls)
+        case _:
+            raise TypeError
+
+
+@overload
+def mapping_protocol[ProtocolT: ObjectProtocol](
+    cls: type[ProtocolT], /, *, cache: Cache | None = None
+) -> type[ProtocolT]: ...
+@overload
+def mapping_protocol[ProtocolT: ObjectProtocol](
+    *, cache: Cache | None = None
+) -> Callable[[type[ProtocolT]], type[ProtocolT]]: ...
+def mapping_protocol(*args: Any, cache: Cache | None = None) -> Any:
+    def decorator(cls: type[ObjectProtocol]) -> type[ObjectProtocol]:
+        Cache.with_fallback(cache).add(MAPPING_PROTOCOL_CACHE_KEY, cls)
+        return cls
+
+    match args:
+        case ():
+            return decorator
+        case (cls,):
+            return decorator(cls)
+        case _:
+            raise TypeError