drf-fastserializers 0.2.0__py3-none-any.whl

drf_fastserializers/__init__.py

@@ -0,0 +1,79 @@
+"""drf-fastserializers: faster DRF serializers, one line at a time.
+
+Quick start (existing DRF serializers):
+
+    from drf_fastserializers import FastSerializerMixin, FastJSONRenderer
+    from rest_framework import serializers
+
+    class TxnSerializer(FastSerializerMixin, serializers.ModelSerializer):
+        class Meta:
+            model = Txn
+            fields = ["id", "name", "amount"]
+
+    class TxnListView(ListAPIView):
+        serializer_class = TxnSerializer       # unchanged
+        renderer_classes = [FastJSONRenderer]  # add this
+        queryset = Txn.objects.all()
+
+The mixin auto-translates the serializer at first .data access (cached
+per-class) and switches the read path to pydantic-core's Rust JSON
+encoder. Falls back to standard DRF .data with a warning if any field
+can't be mechanically translated (typically SerializerMethodField).
+
+New code (define schemas natively in pydantic):
+
+    from drf_fastserializers import FastSerializer
+
+    class TxnOut(FastSerializer):
+        id: int
+        name: str
+        amount: Decimal | None = None
+
+    class TxnListView(ListAPIView):
+        serializer_class = TxnOut.drf
+        renderer_classes = [FastJSONRenderer]
+
+Public surface:
+
+- `FastSerializerMixin`: mix into an existing DRF Serializer.
+- `FastJSONRenderer`: Rust-encoded output path; add to `renderer_classes`.
+- `FastJSONParser`: Rust-encoded input path; add to `parser_classes`.
+- `FastSerializer`: pydantic-backed schema base for new code.
+- `from_drf(SerializerCls)`: explicit DRF to FastSerializer translation.
+- `from_model(DjangoModel)`: derive a FastSerializer from a Django model.
+- `drf_serializer(SchemaCls)`: functional alternative to `.drf`.
+"""
+
+from ._compat import PYD_V3
+from ._payload import FastPayload, RawJSONBytes
+from .accelerator import FastListSerializer, FastSerializerMixin
+from .migrate import MigrationError, from_drf
+from .models import ModelMappingError, from_model
+from .parser import FastJSONParser
+from .renderer import FastJSONRenderer
+from .serializer import DRFAdapter, FastSerializer, drf_serializer
+
+# Ordered to match README narrative: migration story first, native second.
+__all__ = [
+    # Entry path: drop into existing DRF serializers.
+    "FastSerializerMixin",
+    "FastJSONRenderer",
+    "FastJSONParser",
+    "FastListSerializer",
+    # Migration helpers.
+    "from_drf",
+    "from_model",
+    "MigrationError",
+    "ModelMappingError",
+    # Native pydantic-first path for new code.
+    "FastSerializer",
+    "DRFAdapter",
+    "drf_serializer",
+    # Marker payloads (mostly internal but useful for type hints).
+    "FastPayload",
+    "RawJSONBytes",
+    # Version compatibility flag.
+    "PYD_V3",
+]
+
+__version__ = "0.2.0.dev0"

drf_fastserializers/_compat.py

@@ -0,0 +1,21 @@
+"""Pydantic version compatibility gate.
+
+Supports pydantic v2.7+ and v3.x. Both share the surface this library uses
+(BaseModel, TypeAdapter, ConfigDict, ValidationError, model_dump_json).
+"""
+
+from typing import Final
+
+import pydantic
+
+_parts = pydantic.VERSION.split(".")
+PYD_MAJOR: Final[int] = int(_parts[0])
+PYD_MINOR: Final[int] = int(_parts[1])
+
+if PYD_MAJOR < 2 or (PYD_MAJOR == 2 and PYD_MINOR < 7):
+    raise RuntimeError(
+        f"drf-fastserializers requires pydantic>=2.7, got {pydantic.VERSION}. "
+        f"Upgrade with: pip install -U 'pydantic>=2.7'"
+    )
+
+PYD_V3: Final[bool] = PYD_MAJOR >= 3

drf_fastserializers/_errors.py

@@ -0,0 +1,17 @@
+"""Coerce pydantic ValidationError into DRF's `{field: [msg, ...]}` shape."""
+
+from pydantic import ValidationError
+
+
+def pydantic_errors_to_drf(exc: ValidationError) -> dict[str, list[str]]:
+    """Flatten pydantic loc paths to dotted keys. Aggregate messages per key.
+
+    Pydantic loc is a tuple like ('user', 'addresses', 0, 'zip'); DRF expects
+    a flat dotted field name. Empty loc maps to 'non_field_errors' to match
+    DRF's idiom for object-level validation failures.
+    """
+    out: dict[str, list[str]] = {}
+    for err in exc.errors():
+        loc = ".".join(str(part) for part in err["loc"]) or "non_field_errors"
+        out.setdefault(loc, []).append(err["msg"])
+    return out

drf_fastserializers/_payload.py

@@ -0,0 +1,109 @@
+"""Marker payloads exchanged between subsystems.
+
+`FastPayload` (output side) carries validated pydantic instances + the
+TypeAdapter needed to encode them. The renderer recognizes the type and
+routes encoding to `dump_json` (Rust). Anything that treats it as a
+dict/list lazy-materializes via `dump_python`.
+
+`RawJSONBytes` (input side) wraps raw request body bytes so that the
+matching `DRFAdapter.is_valid` can hand them straight to `validate_json`
+(Rust). Anything else reading `request.data` sees a dict-like proxy
+that decodes on demand.
+"""
+
+import json
+from typing import Any
+
+from pydantic import TypeAdapter
+
+
+class FastPayload:
+    """Lazily-materialized JSON payload.
+
+    Renderers detect this type and emit Rust-encoded bytes via
+    `adapter.dump_json`. Anything that subscripts or iterates falls back
+    to a one-time Python materialization for compatibility.
+    """
+
+    __slots__ = ("adapter", "instances", "many", "_materialized")
+
+    def __init__(self, adapter: TypeAdapter, instances: Any, many: bool) -> None:
+        self.adapter = adapter
+        self.instances = instances
+        self.many = many
+        self._materialized: Any = None
+
+    def _materialize(self) -> Any:
+        if self._materialized is None:
+            self._materialized = self.adapter.dump_python(self.instances, mode="json")
+        return self._materialized
+
+    def __getitem__(self, key: Any) -> Any:
+        return self._materialize()[key]
+
+    def __iter__(self):
+        return iter(self._materialize())
+
+    def __len__(self) -> int:
+        return len(self._materialize())
+
+    def __contains__(self, item: Any) -> bool:
+        return item in self._materialize()
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, FastPayload):
+            return self._materialize() == other._materialize()
+        return self._materialize() == other
+
+    def __repr__(self) -> str:
+        return f"FastPayload(many={self.many})"
+
+
+class RawJSONBytes:
+    """Lazy-decoded JSON payload from a `FastJSONParser`.
+
+    Holds the raw request body for the fast input path (validate_json
+    runs in Rust over bytes). Falls back to a one-time `json.loads`
+    when something else accesses the payload as a Python container.
+    """
+
+    __slots__ = ("raw", "_parsed")
+
+    def __init__(self, raw: bytes) -> None:
+        self.raw = raw
+        self._parsed: Any = None
+
+    def _decode(self) -> Any:
+        if self._parsed is None:
+            self._parsed = json.loads(self.raw or b"null")
+        return self._parsed
+
+    def __getitem__(self, key: Any) -> Any:
+        return self._decode()[key]
+
+    def __iter__(self):
+        return iter(self._decode())
+
+    def __len__(self) -> int:
+        return len(self._decode())
+
+    def __contains__(self, item: Any) -> bool:
+        return item in self._decode()
+
+    def get(self, key: Any, default: Any = None) -> Any:
+        decoded = self._decode()
+        if isinstance(decoded, dict):
+            return decoded.get(key, default)
+        return default
+
+    def keys(self):
+        return self._decode().keys()
+
+    def values(self):
+        return self._decode().values()
+
+    def items(self):
+        return self._decode().items()
+
+    def __repr__(self) -> str:
+        return f"RawJSONBytes({len(self.raw)} bytes)"

drf_fastserializers/accelerator.py

@@ -0,0 +1,127 @@
+"""In-place acceleration of existing DRF Serializer subclasses.
+
+Add `FastSerializerMixin` to the inheritance list of an existing
+serializer and `.data` switches to the pydantic-core Rust path:
+
+    from drf_fastserializers import FastSerializerMixin, FastJSONRenderer
+    from rest_framework import serializers
+
+    class TxnSerializer(FastSerializerMixin, serializers.ModelSerializer):
+        class Meta:
+            model = Txn
+            fields = ["id", "name", "amount"]
+
+    class TxnListView(ListAPIView):
+        serializer_class = TxnSerializer
+        renderer_classes = [FastJSONRenderer]
+        queryset = Txn.objects.all()
+
+The mixin translates the serializer's fields to a `FastSerializer`
+schema at first `.data` access (cached per class). If translation fails
+(most commonly because of `SerializerMethodField`), it emits a one-time
+warning and falls back to DRF's standard `.data`. The mixin is safe to
+leave on; it never breaks the response.
+
+Set `Meta.fast = False` to disable the fast path explicitly. Useful for
+opt-out per serializer without removing the mixin.
+"""
+
+import warnings
+from typing import Any, ClassVar
+
+from rest_framework import serializers as drf
+
+from .migrate import MigrationError, from_drf
+from .serializer import FastSerializer
+
+
+class FastListSerializer(drf.ListSerializer):
+    """ListSerializer with a Rust-encoded `.data` property.
+
+    Constructed automatically by `FastSerializerMixin.many_init`. Defers
+    to the child's translated `FastSerializer` schema; falls back to
+    `ListSerializer.data` if translation is unavailable.
+    """
+
+    @property
+    def data(self) -> Any:
+        child_cls = type(self.child)
+        schema = _resolve_schema(child_cls)
+        if schema is None or self.instance is None:
+            return super().data
+        return schema.drf(instance=self.instance, many=True).data
+
+
+class FastSerializerMixin:
+    """Mix into an existing DRF Serializer to accelerate `.data`.
+
+    Override order matters: place `FastSerializerMixin` **first** in the
+    MRO so its `data` property wins:
+
+        class TxnSerializer(FastSerializerMixin, serializers.ModelSerializer):
+            ...
+    """
+
+    _fast_schema_cache: ClassVar[type[FastSerializer] | None] = None
+    _fast_schema_resolved: ClassVar[bool] = False
+
+    @classmethod
+    def many_init(cls, *args: Any, **kwargs: Any) -> drf.ListSerializer:
+        # Mirror DRF's many_init logic, swapping ListSerializer → FastListSerializer
+        # unless the user explicitly set Meta.list_serializer_class.
+        meta = getattr(cls, "Meta", None)
+        user_list_cls = getattr(meta, "list_serializer_class", None)
+        if user_list_cls is not None and user_list_cls is not drf.ListSerializer:
+            return super().many_init(*args, **kwargs)  # type: ignore[misc]
+
+        allow_empty = kwargs.pop("allow_empty", None)
+        max_length = kwargs.pop("max_length", None)
+        min_length = kwargs.pop("min_length", None)
+        child_kwargs = {k: v for k, v in kwargs.items() if k not in drf.LIST_SERIALIZER_KWARGS}
+        list_kwargs: dict[str, Any] = {"child": cls(**child_kwargs)}
+        if allow_empty is not None:
+            list_kwargs["allow_empty"] = allow_empty
+        if max_length is not None:
+            list_kwargs["max_length"] = max_length
+        if min_length is not None:
+            list_kwargs["min_length"] = min_length
+        list_kwargs.update({k: v for k, v in kwargs.items() if k in drf.LIST_SERIALIZER_KWARGS})
+        return FastListSerializer(*args, **list_kwargs)
+
+    @property
+    def data(self) -> Any:
+        schema = _resolve_schema(type(self))
+        if schema is None or self.instance is None:
+            return super().data  # type: ignore[misc]
+        return schema.drf(instance=self.instance, many=False).data
+
+
+def _resolve_schema(cls: type) -> type[FastSerializer] | None:
+    """Memoized translation of a DRF Serializer class into a FastSerializer.
+
+    Honors `Meta.fast = False` as an explicit opt-out. Caches the result
+    (success or failure) on the serializer class itself to keep subsequent
+    lookups O(1).
+    """
+    if not cls.__dict__.get("_fast_schema_resolved"):
+        meta = getattr(cls, "Meta", None)
+        if meta is not None and getattr(meta, "fast", True) is False:
+            cls._fast_schema_cache = None
+        else:
+            cls._fast_schema_cache = _try_translate(cls)
+        cls._fast_schema_resolved = True
+    return cls._fast_schema_cache
+
+
+def _try_translate(cls: type) -> type[FastSerializer] | None:
+    try:
+        return from_drf(cls)
+    except MigrationError as exc:
+        warnings.warn(
+            f"{cls.__name__}: cannot auto-translate to FastSerializer ({exc}). "
+            f"Falling back to standard DRF `.data` (no Rust speedup). "
+            f"Pass `exclude=(...)` via from_drf manually, or set `Meta.fast = False` "
+            f"to silence this warning.",
+            stacklevel=3,
+        )
+        return None

drf_fastserializers/migrate.py

@@ -0,0 +1,218 @@
+"""Translate `rest_framework.serializers.Serializer` classes into `FastSerializer`.
+
+`from_drf(MyExistingSerializer)` walks `serializer.fields` and builds an
+equivalent pydantic-backed schema at runtime. Use the result as you would
+any other `FastSerializer`:
+
+    FastTxnOut = from_drf(TxnSerializer)
+
+    class MyView(ListAPIView):
+        serializer_class = FastTxnOut.drf
+        renderer_classes = [FastJSONRenderer]
+
+Limits: `SerializerMethodField` and DRF fields with overridden
+`to_representation` have no mechanical equivalent. The helper raises
+`MigrationError` naming the offending field; convert those manually
+using pydantic's `@computed_field`, then exclude them from `from_drf`.
+"""
+
+from collections.abc import Callable
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from typing import Any
+from uuid import UUID
+
+from pydantic import AliasPath, Field, computed_field, create_model
+from rest_framework import serializers as drf
+
+from .serializer import FastSerializer
+
+# Exact-type DRF field → pydantic type mapping. Subclasses are handled by
+# walking MRO below. ListSerializer / Serializer / ListField / SerializerMethodField
+# are special-cased before this table is consulted.
+_SCALAR_MAP: dict[type[drf.Field], type] = {
+    drf.CharField: str,
+    drf.EmailField: str,
+    drf.URLField: str,
+    drf.SlugField: str,
+    drf.RegexField: str,
+    drf.IntegerField: int,
+    drf.FloatField: float,
+    drf.DecimalField: Decimal,
+    drf.BooleanField: bool,
+    drf.DateField: date,
+    drf.DateTimeField: datetime,
+    drf.TimeField: time,
+    drf.DurationField: timedelta,
+    drf.UUIDField: UUID,
+    drf.IPAddressField: str,
+    drf.FileField: str,
+    drf.ImageField: str,
+    drf.ChoiceField: str,
+    drf.JSONField: Any,  # type: ignore[dict-item]
+    drf.DictField: dict,
+    drf.HStoreField: dict,
+    drf.PrimaryKeyRelatedField: int,
+    drf.StringRelatedField: str,
+    drf.HyperlinkedIdentityField: str,
+    drf.HyperlinkedRelatedField: str,
+    drf.SlugRelatedField: str,
+}
+
+
+class MigrationError(NotImplementedError):
+    """Raised when a DRF field cannot be mechanically translated."""
+
+
+def from_drf(
+    serializer_cls: type[drf.Serializer],
+    *,
+    name: str | None = None,
+    exclude: tuple[str, ...] = (),
+    computed: dict[str, tuple[Callable[[Any], Any], type]] | None = None,
+) -> type[FastSerializer]:
+    """Build a `FastSerializer` subclass equivalent to `serializer_cls`.
+
+    Args:
+        serializer_cls: An existing DRF `Serializer` or `ModelSerializer` class.
+        name: Override the generated class name; defaults to `"<Cls>Fast"`.
+        exclude: Field names to skip (use for fields you intend to drop or
+            redeclare manually).
+        computed: Replace `SerializerMethodField`s with inline
+            `@computed_field`s. Map of ``field_name -> (callable, return_type)``;
+            the callable receives the pydantic instance as its sole arg.
+            Fields named here are skipped during DRF translation, then
+            attached as computed properties on the result.
+
+    Returns:
+        A `FastSerializer` subclass ready for `.drf` + `FastJSONRenderer`.
+
+    Raises:
+        MigrationError: if any non-excluded, non-computed field has no
+            clean mapping. The exception names the field and its DRF type.
+    """
+    computed = computed or {}
+    skip = set(exclude) | set(computed)
+
+    instance = serializer_cls()
+    fields: dict[str, tuple[Any, Any]] = {}
+    for field_name, field in instance.fields.items():
+        if field_name in skip:
+            continue
+        py_type, py_field = _map_field(field_name, field)
+        fields[field_name] = (py_type, py_field)
+
+    cls_name = name or f"{serializer_cls.__name__}Fast"
+    base = create_model(cls_name, __base__=FastSerializer, **fields)
+    if not computed:
+        return base
+    return _attach_computed(base, computed, cls_name)
+
+
+def _attach_computed(
+    base: type[FastSerializer],
+    computed: dict[str, tuple[Callable[[Any], Any], type]],
+    cls_name: str,
+) -> type[FastSerializer]:
+    """Subclass `base` with `@computed_field` properties attached.
+
+    Each entry's callable becomes a property getter; the second element of
+    the tuple is the return annotation pydantic uses to type the field in
+    the JSON schema and for output coercion.
+    """
+    namespace: dict[str, Any] = {}
+    for cname, (fn, return_type) in computed.items():
+        # Build a typed wrapper so pydantic can read the return annotation.
+        def _make_getter(_fn: Callable[[Any], Any], _ret: type) -> Callable[[Any], Any]:
+            def getter(self: Any) -> Any:
+                return _fn(self)
+
+            getter.__annotations__ = {"self": Any, "return": _ret}
+            return getter
+
+        namespace[cname] = computed_field(property(_make_getter(fn, return_type)))
+    return type(cls_name, (base,), namespace)
+
+
+def _map_field(field_name: str, field: drf.Field) -> tuple[Any, Any]:
+    """Map one DRF field to (python_type, pydantic Field info)."""
+    if isinstance(field, drf.SerializerMethodField):
+        raise MigrationError(
+            f"Field {field_name!r} is a SerializerMethodField; cannot be "
+            f"auto-translated. Pass exclude=({field_name!r},) to from_drf() "
+            f"and redeclare it on the result with @computed_field."
+        )
+
+    if isinstance(field, drf.ListSerializer):
+        child_type = from_drf(type(field.child))
+        return _wrap_optional(list[child_type], field), _field_info(field, field_name)
+
+    if isinstance(field, drf.Serializer):
+        child_type = from_drf(type(field))
+        return _wrap_optional(child_type, field), _field_info(field, field_name)
+
+    if isinstance(field, drf.ListField):
+        child_type, _ = _map_field(f"{field_name}[]", field.child)
+        return _wrap_optional(list[child_type], field), _field_info(
+            field, field_name, empty_default=list
+        )
+
+    py_type = _resolve_scalar(field)
+    if py_type is None:
+        raise MigrationError(
+            f"Field {field_name!r} of type {type(field).__name__!r} has no "
+            f"mapping in from_drf. Add it to exclude=(...) and declare it "
+            f"manually on the resulting FastSerializer."
+        )
+    return _wrap_optional(py_type, field), _field_info(field, field_name)
+
+
+def _resolve_scalar(field: drf.Field) -> type | None:
+    """Walk MRO to find the closest mapped DRF field type."""
+    for cls in type(field).__mro__:
+        if cls in _SCALAR_MAP:
+            return _SCALAR_MAP[cls]
+    return None
+
+
+def _wrap_optional(py_type: Any, field: drf.Field) -> Any:
+    """Wrap as `T | None` when the DRF field is nullable or not required."""
+    if field.allow_null or not field.required:
+        return py_type | None
+    return py_type
+
+
+def _field_info(
+    field: drf.Field,
+    field_name: str,
+    *,
+    empty_default: Any = None,
+) -> Any:
+    """Build the pydantic Field() carrying default + validation_alias.
+
+    `empty_default` is the factory (e.g. `list`, `dict`) used when the DRF
+    field is `required=False` with no explicit default; mirrors DRF's
+    behavior of treating those as empty containers rather than null.
+    """
+    kwargs: dict[str, Any] = {}
+
+    # source="a.b.c" → AliasPath(a, b, c). source=="*" means "the whole object";
+    # leave it alone, pydantic's from_attributes handles it.
+    source = getattr(field, "source", None)
+    if source and source != field_name and source != "*":
+        parts = source.split(".")
+        kwargs["validation_alias"] = parts[0] if len(parts) == 1 else AliasPath(*parts)
+
+    default = getattr(field, "default", drf.empty)
+    if field.required:
+        if not kwargs:
+            return ...  # plain required field
+        return Field(..., **kwargs)
+    if default is drf.empty:
+        if empty_default is not None:
+            kwargs["default_factory"] = empty_default
+        else:
+            kwargs["default"] = None
+    else:
+        kwargs["default"] = default
+    return Field(**kwargs)