ypres 1.1.2__py3-none-any.whl

ypres/__init__.py

@@ -0,0 +1,43 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from ypres.fields import (
+    BoolField,
+    DateField,
+    DateTimeField,
+    Field,
+    FloatField,
+    IntField,
+    MethodField,
+    StaticField,
+    StrField,
+)
+from ypres.serializer import (
+    AsyncDictSerializer,
+    AsyncSerializer,
+    DictSerializer,
+    Serializer,
+)
+
+try:
+    __version__ = version("ypres")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+__author__ = "Andrew Hankinson"
+__license__ = "MIT"
+
+__all__ = [
+    "Serializer",
+    "DictSerializer",
+    "AsyncSerializer",
+    "AsyncDictSerializer",
+    "Field",
+    "BoolField",
+    "IntField",
+    "FloatField",
+    "MethodField",
+    "StrField",
+    "StaticField",
+    "DateField",
+    "DateTimeField",
+]

ypres/fields.py

@@ -0,0 +1,210 @@
+import types
+from datetime import date, datetime, time
+from typing import Any
+
+
+class Field:
+    """:class:`Field` is used to define what attributes will be serialized.
+
+    A :class:`Field` maps a property or function on an object to a value in the
+    serialized result. Subclass this to make custom fields. For most simple
+    cases, overriding :meth:`Field.to_value` should give enough flexibility. If
+    more control is needed, override :meth:`Field.as_getter`.
+
+    :param str attr: The attribute to get on the object, using the same format
+        as ``operator.attrgetter``. If this is not supplied, the name this
+        field was assigned to on the serializer will be used.
+    :param bool call: Whether the value should be called after it is retrieved
+        from the object. Useful if an object has a method to be serialized.
+    :param str label: A label to use as the name of the serialized field
+        instead of using the attribute name of the field.
+    :param bool required: Whether the field is required. If set to ``False``,
+        :meth:`Field.to_value` will not be called if the value is ``None``.
+    :param: bool emit_none: Whether the field will emit an explicit ``None``
+        value if the value being serialized is ``None``. By default, fields
+        that evaluate to ``None`` will be removed from the output. Set this
+        to ``True`` to keep the value in the output.
+    """
+
+    #: Set to ``True`` if the value function returned from
+    #: :meth:`Field.as_getter` requires the serializer to be passed in as the
+    #: first argument. Otherwise, the object will be the only parameter.
+    getter_takes_serializer: bool = False
+    __slots__ = ["attr", "call", "label", "required", "emit_none"]
+
+    def __init__(
+        self,
+        attr: str | None = None,
+        call: bool = False,
+        label: str | None = None,
+        required: bool = True,
+        emit_none: bool = False,
+    ):
+        self.attr: str | None = attr
+        self.call: bool = call
+        self.label: str | None = label
+        self.required: bool = required
+        self.emit_none = emit_none
+
+    def to_value(self, value: Any):
+        """Transform the serialized value.
+
+        Override this method to clean and validate values serialized by this
+        field. For example to implement an ``int`` field: ::
+
+            def to_value(self, value):
+                return int(value)
+
+        :param value: The value fetched from the object being serialized.
+        """
+        return value
+
+    to_value._ypres_base_implementation = True  # type: ignore
+
+    def is_to_value_overridden(self) -> bool:
+        to_value = self.to_value
+        # If to_value isn't a method, it must have been overridden.
+        if not isinstance(to_value, types.MethodType):
+            return True
+        return not getattr(to_value, "_ypres_base_implementation", False)
+
+    def as_getter(self, serializer_field_name: str, serializer_cls: Any):
+        """Returns a function that fetches an attribute from an object.
+
+        Return ``None`` to use the default getter for the serializer defined in
+        :attr:`Serializer.default_getter`.
+
+        When a :class:`Serializer` is defined, each :class:`Field` will be
+        converted into a getter function using this method. During
+        serialization, each getter will be called with the object being
+        serialized, and the return value will be passed through
+        :meth:`Field.to_value`.
+
+        If a :class:`Field` has ``getter_takes_serializer = True``, then the
+        getter returned from this method will be called with the
+        :class:`Serializer` instance as the first argument, and the object
+        being serialized as the second.
+
+        :param str serializer_field_name: The name this field was assigned to
+            on the serializer.
+        :param serializer_cls: The :class:`Serializer` this field is a part of.
+        """
+        return None
+
+
+class StaticField(Field):
+    """A :class:`Field` that simply repeats a static value."""
+
+    __slots__ = ["value"]
+
+    def __init__(
+        self,
+        value: Any,
+        attr: str | None = None,
+        call: bool = False,
+        label: str | None = None,
+        required: bool = True,
+    ) -> None:
+        super().__init__(attr, call, label, required)
+        self.value: Any = value
+
+    def to_value(self, value: Any) -> Any:
+        return self.value
+
+    def as_getter(self, serializer_field_name: str, serializer_cls: Any) -> Any:
+        return self.to_value
+
+
+class StrField(Field):
+    """A :class:`Field` that converts the value to a string.
+
+    Since Python will happily cast `None` to the string `"None"`,
+    this method ensures that values of `None` are handled and
+    passed through, instead of cast.
+    """
+
+    to_value: Any = staticmethod(lambda s: str(s) if s else None)
+
+
+class IntField(Field):
+    """A :class:`Field` that converts the value to an integer."""
+
+    to_value: Any = staticmethod(int)
+
+
+class FloatField(Field):
+    """A :class:`Field` that converts the value to a float."""
+
+    to_value: Any = staticmethod(float)
+
+
+class BoolField(Field):
+    """A :class:`Field` that converts the value to a boolean.
+
+    Python will cast a value of `None` to the boolean value of False,
+    so this method ensures values of `None` are passed through instead
+    of cast to a boolean value.
+    """
+
+    to_value: Any = staticmethod(lambda b: bool(b) if b is not None else None)
+
+
+class MethodField(Field):
+    """A :class:`Field` that calls a method on the :class:`Serializer`.
+
+    This is useful if a :class:`Field` needs to serialize a value that may come
+    from multiple attributes on an object. For example: ::
+
+        class FooSerializer(Serializer):
+            plus = MethodField()
+            minus = MethodField('do_minus')
+
+            def get_plus(self, foo_obj):
+                return foo_obj.bar + foo_obj.baz
+
+            def do_minus(self, foo_obj):
+                return foo_obj.bar - foo_obj.baz
+
+        foo = Foo(bar=5, baz=10)
+        FooSerializer(foo).data
+        # {'plus': 15, 'minus': -5}
+
+    :param str method: The method on the serializer to call. Defaults to
+        ``'get_<field name>'``.
+    """
+
+    getter_takes_serializer = True
+    __slots__ = ["method"]
+
+    def __init__(self, method: str | None = None, **kwargs):  # type: ignore
+        super().__init__(**kwargs)
+        self.method: str | None = method
+
+    def as_getter(self, serializer_field_name: str, serializer_cls: Any):
+        method_name: str | None = self.method
+        if method_name is None:
+            method_name = f"get_{serializer_field_name}"
+        return getattr(serializer_cls, method_name)
+
+
+# From https://github.com/PKharlamov/drf-serpy/blob/master/drf_serpy/fields.py
+class DateField(Field):
+    """A `Field` that converts the value to a date format."""
+
+    __slots__ = ["_date_format"]
+    date_format = "%Y-%m-%d"
+
+    def __init__(self, date_format: str | None = None, **kwargs):
+        super().__init__(**kwargs)
+        self._date_format = date_format or self.date_format
+
+    def to_value(self, value: datetime | time | date) -> str | None:
+        if value:
+            return value.strftime(self._date_format)
+        return None
+
+
+class DateTimeField(DateField):
+    """A `Field` that converts the value to a date time format."""
+
+    date_format = "%Y-%m-%dT%H:%M:%S.%fZ"

ypres/serializer.py

@@ -0,0 +1,569 @@
+import inspect
+import operator
+from abc import abstractmethod
+from collections.abc import AsyncIterable, Callable, Iterable, Mapping
+from typing import Any, NamedTuple
+from warnings import deprecated
+
+from ypres import Field
+
+
+class FieldDefinitions(NamedTuple):
+    name: str
+    getter: Callable
+    to_value: Any
+    call: bool
+    required: bool
+    pass_self: bool
+    emit_none: bool
+    getter_is_coro: bool
+    toval_is_coro: bool
+
+
+class SerializerBase(Field):
+    __slots__: list = [
+        "instance",
+        "many",
+        "context",
+        "_emit_none",
+        "_data",
+        "_serialized",
+        "_serialized_many",
+    ]
+
+    def __init__(
+        self,  # type: ignore
+        instance: Any | None = None,
+        many: bool = False,
+        context: dict | None = None,
+        emit_none: bool = False,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        if instance and isinstance(instance, list) and not many:
+            # if we're serializing a list but have not set many=True then raise a value error.
+            raise ValueError("Cannot serialize an object from a list.")
+        elif (
+            instance
+            and many
+            and (
+                not isinstance(instance, Iterable | AsyncIterable)
+                or isinstance(instance, dict)
+            )
+        ):
+            # if we're not serializing a list (or some iterable object EXCEPT dicts) and many=True,
+            # then raise a value error.
+            raise ValueError("Cannot serialize a list from an object.")
+
+        self.instance: Any = instance
+        self.many: bool = many
+        self.context: dict = context or {}
+        self._emit_none = emit_none
+        self._serialized: dict | None = None
+        self._serialized_many: list | None = None
+
+    @staticmethod
+    @abstractmethod
+    def default_getter(k: str) -> Any: ...
+
+    _field_map: dict = {}
+    _compiled_fields: list[FieldDefinitions] = []
+    _compiled_sync_fields: list[Callable] = []
+
+
+class SerializerMeta(type):
+    @staticmethod
+    def _get_fields(direct_fields: Mapping, serializer_cls) -> dict:
+        field_map: dict = {}
+        # Get all the fields from base classes.
+        for cls in serializer_cls.__mro__[::-1]:
+            if issubclass(cls, SerializerBase):
+                field_map.update(cls._field_map)
+        field_map.update(direct_fields)
+        return field_map
+
+    @staticmethod
+    def _compile_fields(field_map: dict, serializer_cls) -> list[FieldDefinitions]:
+        return [
+            _compile_field_to_tuple(field, name, serializer_cls)
+            for name, field in field_map.items()
+        ]
+
+    def __new__(mcs, name, bases, attrs: dict):
+        # Fields declared directly on the class.
+        direct_fields: dict = {}
+
+        # Take all the Fields from the attributes.
+        for attr_name, field in attrs.items():
+            if isinstance(field, Field):
+                direct_fields[attr_name] = field
+        for k in direct_fields:
+            del attrs[k]
+
+        real_cls = super().__new__(mcs, name, bases, attrs)
+
+        field_map = mcs._get_fields(direct_fields, real_cls)
+        compiled_fields = mcs._compile_fields(field_map, real_cls)
+        compiled_sync_fields = _compile_sync_fields(compiled_fields)
+
+        real_cls._field_map = field_map  # type: ignore
+        real_cls._compiled_fields = compiled_fields  # type: ignore
+        real_cls._compiled_sync_fields = compiled_sync_fields  # type: ignore
+
+        return real_cls
+
+
+def _compile_field_to_tuple(
+    field: Field, name: str, serializer_cls: type[SerializerBase]
+) -> FieldDefinitions:
+    getter = field.as_getter(name, serializer_cls)
+    if getter is None:
+        getter = serializer_cls.default_getter(field.attr or name)
+
+    getter_is_coro: bool = inspect.iscoroutinefunction(getter)
+
+    # Only set a to_value function if it has been overridden for performance.
+    to_value: Callable | None = None
+    if field.is_to_value_overridden():
+        to_value = field.to_value
+
+    # we only need to check if to_value is a coroutine if it is not None.
+    toval_is_coro: bool = inspect.iscoroutinefunction(to_value) if to_value else False
+    # Set the field name to a supplied label; defaults to the attribute name.
+    name = field.label or name
+
+    return FieldDefinitions(
+        name=name,
+        getter=getter,
+        to_value=to_value,
+        call=field.call,
+        required=field.required,
+        pass_self=field.getter_takes_serializer,
+        emit_none=field.emit_none,
+        getter_is_coro=getter_is_coro,
+        toval_is_coro=toval_is_coro,
+    )
+
+
+def _compile_sync_fields(
+    fields: list[FieldDefinitions],
+) -> list[Callable]:
+    return [_make_sync_field_writer(field) for field in fields]
+
+
+def _required_self_call_tval(name: str, getter: Callable, tval: Callable, emit_none: bool) -> Callable:
+    if emit_none:
+        def emit(serializer, instance, out):
+            out[name] = tval(getter(serializer, instance)())
+    else:
+        def emit(serializer, instance, out):
+            result = tval(getter(serializer, instance)())
+            if result is None:
+                return
+            out[name] = result
+    return emit
+
+
+def _required_self_call(name: str, getter: Callable, _tval: Callable | None, emit_none: bool) -> Callable:
+    if emit_none:
+        def emit(serializer, instance, out):
+            out[name] = getter(serializer, instance)()
+    else:
+        def emit(serializer, instance, out):
+            result = getter(serializer, instance)()
+            if result is None:
+                return
+            out[name] = result
+    return emit
+
+
+def _required_self_tval(name: str, getter: Callable, tval: Callable, emit_none: bool) -> Callable:
+    if emit_none:
+        def emit(serializer, instance, out):
+            out[name] = tval(getter(serializer, instance))
+    else:
+        def emit(serializer, instance, out):
+            result = tval(getter(serializer, instance))
+            if result is None:
+                return
+            out[name] = result
+    return emit
+
+
+def _required_self(name: str, getter: Callable, _tval: Callable | None, emit_none: bool) -> Callable:
+    if emit_none:
+        def emit(serializer, instance, out):
+            out[name] = getter(serializer, instance)
+    else:
+        def emit(serializer, instance, out):
+            result = getter(serializer, instance)
+            if result is None:
+                return
+            out[name] = result
+    return emit
+
+
+def _optional_self_call_tval(name: str, getter: Callable, tval: Callable, emit_none: bool) -> Callable:
+    def emit(serializer, instance, out):
+        try:
+            result = getter(serializer, instance)
+        except (KeyError, AttributeError):
+            return
+        if result is None:
+            if emit_none:
+                out[name] = None
+            return
+        result = tval(result())
+        if result is None and not emit_none:
+            return
+        out[name] = result
+    return emit
+
+
+def _optional_self_call(name: str, getter: Callable, _tval: Callable | None, emit_none: bool) -> Callable:
+    def emit(serializer, instance, out):
+        try:
+            result = getter(serializer, instance)
+        except (KeyError, AttributeError):
+            return
+        if result is None:
+            if emit_none:
+                out[name] = None
+            return
+        result = result()
+        if result is None and not emit_none:
+            return
+        out[name] = result
+    return emit
+
+
+def _optional_self_tval(name: str, getter: Callable, tval: Callable, emit_none: bool) -> Callable:
+    def emit(serializer, instance, out):
+        try:
+            result = getter(serializer, instance)
+        except (KeyError, AttributeError):
+            return
+        if result is None:
+            if emit_none:
+                out[name] = None
+            return
+        result = tval(result)
+        if result is None and not emit_none:
+            return
+        out[name] = result
+    return emit
+
+
+def _optional_self(name: str, getter: Callable, _tval: Callable | None, emit_none: bool) -> Callable:
+    def emit(serializer, instance, out):
+        try:
+            result = getter(serializer, instance)
+        except (KeyError, AttributeError):
+            return
+        if result is None:
+            if emit_none:
+                out[name] = None
+            return
+        out[name] = result
+    return emit
+
+
+def _required_call_tval(name: str, getter: Callable, tval: Callable, emit_none: bool) -> Callable:
+    if emit_none:
+        def emit(serializer, instance, out):
+            out[name] = tval(getter(instance)())
+    else:
+        def emit(serializer, instance, out):
+            result = tval(getter(instance)())
+            if result is None:
+                return
+            out[name] = result
+    return emit
+
+
+def _required_call(name: str, getter: Callable, _tval: Callable | None, emit_none: bool) -> Callable:
+    if emit_none:
+        def emit(serializer, instance, out):
+            out[name] = getter(instance)()
+    else:
+        def emit(serializer, instance, out):
+            result = getter(instance)()
+            if result is None:
+                return
+            out[name] = result
+    return emit
+
+
+def _required_tval(name: str, getter: Callable, tval: Callable, emit_none: bool) -> Callable:
+    if emit_none:
+        def emit(serializer, instance, out):
+            out[name] = tval(getter(instance))
+    else:
+        def emit(serializer, instance, out):
+            result = tval(getter(instance))
+            if result is None:
+                return
+            out[name] = result
+    return emit
+
+
+def _required_plain(name: str, getter: Callable, _tval: Callable | None, emit_none: bool) -> Callable:
+    if emit_none:
+        def emit(serializer, instance, out):
+            out[name] = getter(instance)
+    else:
+        def emit(serializer, instance, out):
+            result = getter(instance)
+            if result is None:
+                return
+            out[name] = result
+    return emit
+
+
+def _optional_call_tval(name: str, getter: Callable, tval: Callable, emit_none: bool) -> Callable:
+    def emit(serializer, instance, out):
+        try:
+            result = getter(instance)
+        except (KeyError, AttributeError):
+            return
+        if result is None:
+            if emit_none:
+                out[name] = None
+            return
+        result = tval(result())
+        if result is None and not emit_none:
+            return
+        out[name] = result
+    return emit
+
+
+def _optional_call(name: str, getter: Callable, _tval: Callable | None, emit_none: bool) -> Callable:
+    def emit(serializer, instance, out):
+        try:
+            result = getter(instance)
+        except (KeyError, AttributeError):
+            return
+        if result is None:
+            if emit_none:
+                out[name] = None
+            return
+        result = result()
+        if result is None and not emit_none:
+            return
+        out[name] = result
+    return emit
+
+
+def _optional_tval(name: str, getter: Callable, tval: Callable, emit_none: bool) -> Callable:
+    def emit(serializer, instance, out):
+        try:
+            result = getter(instance)
+        except (KeyError, AttributeError):
+            return
+        if result is None:
+            if emit_none:
+                out[name] = None
+            return
+        result = tval(result)
+        if result is None and not emit_none:
+            return
+        out[name] = result
+    return emit
+
+
+def _optional_plain(name: str, getter: Callable, _tval: Callable | None, emit_none: bool) -> Callable:
+    def emit(serializer, instance, out):
+        try:
+            result = getter(instance)
+        except (KeyError, AttributeError):
+            return
+        if result is None:
+            if emit_none:
+                out[name] = None
+            return
+        out[name] = result
+    return emit
+
+
+# Each key is `(pass_self, required, call, has_to_value)`.
+# The selected factory returns a specialized writer for that exact field shape,
+# so the runtime serializer loop does not need to branch on these flags.
+_SYNC_FIELD_WRITER_FACTORIES: dict[tuple[bool, bool, bool, bool], Callable] = {
+    (True, True, True, True): _required_self_call_tval,
+    (True, True, True, False): _required_self_call,
+    (True, True, False, True): _required_self_tval,
+    (True, True, False, False): _required_self,
+    (True, False, True, True): _optional_self_call_tval,
+    (True, False, True, False): _optional_self_call,
+    (True, False, False, True): _optional_self_tval,
+    (True, False, False, False): _optional_self,
+    (False, True, True, True): _required_call_tval,
+    (False, True, True, False): _required_call,
+    (False, True, False, True): _required_tval,
+    (False, True, False, False): _required_plain,
+    (False, False, True, True): _optional_call_tval,
+    (False, False, True, False): _optional_call,
+    (False, False, False, True): _optional_tval,
+    (False, False, False, False): _optional_plain,
+}
+
+
+def _make_sync_field_writer(field: FieldDefinitions) -> Callable:
+    # `bool(field.to_value)` is the compile-time "has transform" flag used by
+    # the dispatch table above. The actual callable is still passed through to
+    # the selected factory for execution.
+    key = (field.pass_self, field.required, field.call, bool(field.to_value))
+    factory = _SYNC_FIELD_WRITER_FACTORIES[key]
+    return factory(field.name, field.getter, field.to_value, field.emit_none)
+
+
+class Serializer(SerializerBase, metaclass=SerializerMeta):
+    default_getter: Any = operator.attrgetter
+
+    def _serialize(self, instance: Any, fields: list[FieldDefinitions]) -> dict:
+        v: dict = {}
+
+        for emit in self._compiled_sync_fields:
+            emit(self, instance, v)
+
+        return v
+
+    def to_value(self, value: Any) -> list | dict:
+        if self.many:
+            return self._serialize_list(value)
+        return self._serialize_dict(value)
+
+    def _serialize_dict(self, instance: Any) -> dict:
+        self._serialized = self._serialize(instance, self._compiled_fields)
+        return self._serialized or {}
+
+    def _serialize_list(self, instance: Any) -> list:
+        self._serialized_many = [
+            self._serialize(o, self._compiled_fields) for o in instance
+        ]
+        return self._serialized_many or []
+
+    @property
+    @deprecated("Use the .serialized and .serialized_many properties.")
+    def data(self) -> list | dict:
+        """Get the serialized data from the :class:`Serializer`.
+
+        The data will be cached for future accesses.
+        """
+        # Cache the data for next time .data is called.
+        return self.to_value(self.instance)
+
+    @property
+    def serialized(self) -> dict:
+        if self._serialized is not None:
+            return self._serialized
+        return self._serialize_dict(self.instance)
+
+    @property
+    def serialized_many(self) -> list:
+        if self._serialized_many is not None:
+            return self._serialized_many
+        return self._serialize_list(self.instance)
+
+
+class DictSerializer(Serializer):
+    default_getter: Any = operator.itemgetter
+
+
+class AsyncSerializer(SerializerBase, metaclass=SerializerMeta):
+    default_getter: Any = operator.attrgetter
+
+    async def _serialize(self, instance: Any, fields: list[FieldDefinitions]) -> dict:
+        v: dict = {}
+        for (
+            name,
+            getter,
+            tval,
+            call,
+            required,
+            pass_self,
+            emit_none,
+            getter_coro,
+            toval_coro,
+        ) in fields:
+            try:
+                if getter_coro:
+                    result = (
+                        await getter(self, instance)
+                        if pass_self
+                        else await getter(instance)
+                    )
+                else:
+                    result = getter(self, instance) if pass_self else getter(instance)
+            except (KeyError, AttributeError):
+                if required:
+                    raise
+                continue
+
+            if result is None and not required:
+                if emit_none:
+                    v[name] = result
+                    continue
+                continue
+
+            if call:
+                result = result()
+
+            if tval:
+                if toval_coro:
+                    result = await tval(result)
+                else:
+                    result = tval(result)
+
+            if result is None and not emit_none:
+                continue
+
+            v[name] = result
+
+        return v
+
+    async def to_value(self, value: Any) -> list | dict:
+        if self.many:
+            return await self._serialize_list(value)
+        return await self._serialize_dict(value)
+
+    async def _serialize_dict(self, instance: Any) -> dict:
+        self._serialized = await self._serialize(instance, self._compiled_fields)
+        return self._serialized or {}
+
+    async def _serialize_list(self, instance: Any) -> list:
+        if isinstance(instance, AsyncIterable):
+            self._serialized_many = [
+                await self._serialize(o, self._compiled_fields) async for o in instance
+            ]
+        else:
+            self._serialized_many = [
+                await self._serialize(o, self._compiled_fields) for o in instance
+            ]
+        return self._serialized_many or []
+
+    @property
+    @deprecated("Use the .serialized and .serialized_many properties.")
+    async def data(self) -> list | dict:
+        """Get the serialized data from the :class:`Serializer`.
+
+        The data will be cached for future accesses.
+        """
+        # Cache the data for next time .data is called.
+        return await self.to_value(self.instance)
+
+    @property
+    async def serialized(self) -> dict:
+        if self._serialized is not None:
+            return self._serialized
+        return await self._serialize_dict(self.instance)
+
+    @property
+    async def serialized_many(self) -> list:
+        if self._serialized_many is not None:
+            return self._serialized_many
+        return await self._serialize_list(self.instance)
+
+
+class AsyncDictSerializer(AsyncSerializer):
+    default_getter: Any = operator.itemgetter

ypres-1.1.2.dist-info/METADATA

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: ypres
+Version: 1.1.2
+Summary: ypres is a simple object serialization framework built for speed.
+Project-URL: Homepage, https://github.com/rism-digital/ypres
+Project-URL: Source, https://github.com/rism-digital/ypres
+Project-URL: Issues, https://github.com/rism-digital/ypres/issues
+Author-email: Andrew Hankinson <andrew.hankinson@gmail.com>
+License: The MIT License (MIT)
+        
+        Copyright (c) 2015 Clark DuVall
+        Copyright (c) 2023 Andrew Hankinson, RISM Digital Center
+        
+        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.
+License-File: LICENSE
+Keywords: asyncio,json,serialization,serializer,typing
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.11
+Description-Content-Type: text/markdown
+
+# ypres: ridiculously fast object serialization
+
+This project started as a fork of the amazing [Serpy serializer](https://github.com/clarkduvall/serpy), which has been
+[marked as feature-complete](https://github.com/clarkduvall/serpy/issues/69) by the original author. This fork 
+adds some newer features, such as `asyncio` support so that asynchronous 
+methods may be called from within a serializer.
+
+It was renamed to "ypres" ("serpy" backwards, pronounced like the [Belgian town
+name](https://en.wikipedia.org/wiki/Ypres)) to avoid confusion with the original.
+
+Since forking it has undergone numerous changes and rewrites. The core of it
+is still somewhat recognizable, but there have also been many changes. 
+
+**ypres** is a simple object serialization framework built for
+speed. **ypres** serializes complex datatypes (Django Models, custom
+classes, ...) to simple native types (dicts, lists, strings, ...). The
+native types can easily be converted to JSON or any other format needed.
+
+The goal of **ypres** is to be able to do this *simply*, *reliably*, and
+*quickly*. Since serializers are class based, they can be combined,
+extended and customized with very little code duplication.
+
+## Changes from Serpy
+
+There are some notable changes from the original Serpy serializer in this fork.
+
+### New Serializer classes: AsyncSerializer and AsyncDictSerializer
+
+Serpy did not allow for `MethodField` implementations to use async / await methods.
+For those instances where you wish to embed an async / await coroutine in your serializer,
+two new serializer classes, `AsyncSerializer` and `AsyncDictSerializer`, will automatically 
+detect whether the method being called is a coroutine and handle it appropriately.
+
+### New StaticField class
+
+When combining many fields and manipulating output, it is sometimes desirable to have
+a fixed value for certain fields in the output. The new `StaticField` class allows
+you to specify a fixed value for the field, and this will always appear in the output.
+
+### Serializers allow a context object
+
+Additional context can be passed in to a serializer. This is helpful if you have some context
+that you wish to use when serializing the object. For example, you might pass in a user object
+that could customize the responses in the serializer with their name, or only perform certain
+serialization tasks if they are of a specific class (e.g., admin).
+
+### Date and DateTime Serializer Fields
+
+Date and DateTime fields can be serialized, based on the implementation from another fork,
+https://github.com/PKharlamov/drf-serpy/blob/master/drf_serpy/fields.py.
+
+### Deprecated the `.data` property.
+
+Since `.data` can return either a `list` (with `many=True`) or a `dict`, type checkers
+complained when you serialized a single object because the calling code does not handle
+the case of `data` being a list.
+
+Instead, two new properties, `serialized` and `serialized_many` are introduced that
+return a dict and a list directly. In the course of doing this work the class structure
+for the serializers was reworked to better implement common checks and data in the superclass.
+
+```python
+import ypres
+
+
+class MySerializer(ypres.Serializer):
+    foo = ypres.MethodField()
+    blah = ypres.MethodField()
+    
+    def get_foo(self, obj):
+        foo_data = obj.foo
+        ctx_data = self.context.get("additional", "")
+        return f"{foo_data}_{ctx_data}"
+    
+    def get_blah(self, obj):
+        blah_data = obj.blah
+        ctx_data = self.context.get("additional", "")
+        return f"{blah_data}_{ctx_data}"
+    
+    
+class Foo:
+    foo = "foo"
+    blah = "blah"
+
+my_data = MySerializer(Foo(), context={"additional": "bar"}).serialized
+
+# {"foo": "foo_bar", "blah": "blah_bar"}
+```
+
+### Changed behaviour of None
+
+By default, data that evaluates to a value of `None` will **not** be included
+in the output. To explicitly mark that a field should emit a `None` value, 
+it should be instantiated with an `emit_none=True` argument.
+
+Note that the combination of `emit_none` and `required` deserve special attention.
+
+ - If `emit_none` is `False` and `required` is `True` (default), then the object
+being serialized must have the matching attribute available, otherwise it will
+raise an error. The only exception is if the field is a `MethodField`, in which 
+case the attribute does not need to be present on the object. 
+This behaviour is not changed.
+ - If `emit_none` is `False` and `required` is `False` then the object being
+serialized will not appear in the output if its value is `None`
+ - If `emit_none` is `True` and `required` is `True`, then the object being
+serialized will attempt to return the value. However, it may fail if the `to_value`
+method being used does not accept `None`. An example of this is the `IntField`
+serializer, where the `to_value` method would effectively be calling `int(None)`.
+In this case, a `TypeError` will be raised. (This is the same as trying to serialize
+a string with an `IntField`, for example)
+ - If `emit_none` is `True` and `required` is `False`, then the object being
+serialized will actually skip the `to_value` step and simply return `None`. 
+
+Further to this, the behaviour of the `StrField` and `BoolField` were changed,
+where calling `StrField` on a value of `None` would actually return the string
+`"None"`. Similarly, calling `bool(None)` evaluates to `False`. In both of these
+cases the `to_value` handler has been modified to return `None` if the incoming
+value is `None`. 
+
+This prevents unexpected type values from appearing in the 
+output. For values that cannot be cast to `None` for `IntField` and `FloatField`,
+a `None` input will raise an exception.
+
+### Modern Python standards
+
+The project uses update Python packaging setups with `pyproject.toml`. It also
+adds configurations for `ruff`, works with `uv`, and fully supports type annotations. 
+
+## Source
+
+Source at: <https://github.com/rism-digital/ypres>
+
+If you want a feature, send a pull request!
+
+## Installation
+
+``` bash
+$ pip install git+https://github.com/rism-digital/ypres
+```
+
+## Examples
+
+### Simple Example
+
+```python
+import ypres
+
+class Foo(object):
+    """The object to be serialized."""
+    y = 'hello'
+    z = 9.5
+
+    def __init__(self, x):
+        self.x = x
+
+
+class FooSerializer(ypres.Serializer):
+    """The serializer schema definition."""
+    # Use a Field subclass like IntField if you need more validation.
+    x = ypres.IntField()
+    y = ypres.Field()
+    z = ypres.Field()
+
+f = Foo(1)
+FooSerializer(f).serialized
+# {'x': 1, 'y': 'hello', 'z': 9.5}
+
+fs = [Foo(i) for i in range(100)]
+FooSerializer(fs, many=True).serialized_many
+# [{'x': 0, 'y': 'hello', 'z': 9.5}, {'x': 1, 'y': 'hello', 'z': 9.5}, ...]
+```
+
+### Nested Example
+
+```python
+import ypres
+
+class Nestee(object):
+    """An object nested inside another object."""
+    n = 'hi'
+
+
+class Foo(object):
+    x = 1
+    nested = Nestee()
+
+
+class NesteeSerializer(ypres.Serializer):
+    n = ypres.Field()
+
+
+class FooSerializer(ypres.Serializer):
+    x = ypres.Field()
+    # Use another serializer as a field.
+    nested = NesteeSerializer()
+
+f = Foo()
+FooSerializer(f).serialized
+# {'x': 1, 'nested': {'n': 'hi'}}
+```
+
+### Complex Example
+
+```python
+import ypres
+
+class Foo(object):
+    y = 1
+    z = 2
+    super_long_thing = 10
+
+    def x(self):
+        return 5
+
+
+class FooSerializer(ypres.Serializer):
+    w = ypres.Field(attr='super_long_thing')
+    x = ypres.Field(call=True)
+    plus = ypres.MethodField()
+
+    def get_plus(self, obj):
+        return obj.y + obj.z
+
+f = Foo()
+FooSerializer(f).serialized
+# {'w': 10, 'x': 5, 'plus': 3}
+```
+
+### Inheritance Example
+
+```python
+import ypres
+
+class Foo(object):
+    a = 1
+    b = 2
+
+
+class ASerializer(ypres.Serializer):
+    a = ypres.Field()
+
+
+class ABSerializer(ASerializer):
+    """ABSerializer inherits the 'a' field from ASerializer.
+
+    This also works with multiple inheritance and mixins.
+    """
+    b = ypres.Field()
+
+f = Foo()
+ASerializer(f).serialized
+# {'a': 1}
+ABSerializer(f).serialized
+# {'a': 1, 'b': 2}
+```
+
+## License
+
+ypres is free software distributed under the terms of the MIT license.
+See the [LICENSE](https://github.com/clarkduvall/serpy/blob/master/LICENSE) file.

ypres-1.1.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+ypres/__init__.py,sha256=cfKxBKZQXXMnXDlrf2R7vCxqjlGvx3CiVYv8ipJiyMI,758
+ypres/fields.py,sha256=s22BqXNGSmM-Hk_vYTJsibFJ8GcsziSTzN6E5gwJKLs,7393
+ypres/serializer.py,sha256=eDwjplzjtiWjCClSLYPbleB5CI-0-ixDjn21nV0tNcE,18333
+ypres/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ypres-1.1.2.dist-info/METADATA,sha256=EBum3qgf1r4nUxiV2vIdjc913TkpVLQL4xJl1-JNP3U,10638
+ypres-1.1.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+ypres-1.1.2.dist-info/licenses/LICENSE,sha256=CEi0Gjqz-WIM4V9noRMkxZpHKugaYv_g2ri2oSiUBJc,1136
+ypres-1.1.2.dist-info/RECORD,,

ypres-1.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

ypres-1.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Clark DuVall
+Copyright (c) 2023 Andrew Hankinson, RISM Digital Center
+
+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.