sqlalchemy-declarative-filters 0.1.0__py3-none-any.whl

sqlalchemy_declarative_filters/__init__.py

@@ -0,0 +1,41 @@
+"""Declarative SQLAlchemy filters with auto-generated schemas.
+
+Import ``Filters`` and the decorators from this package for the dependency-free
+dataclass backend, or from ``.pydantic`` / ``.marshmallow`` for those. The names are
+the same in all three, so switching a project over is a one-line change::
+
+    from sqlalchemy_declarative_filters.pydantic import Filters, options, skip_null
+"""
+
+from __future__ import annotations
+
+from ._decorators import options, skip_null
+from ._exceptions import (
+    BackendNotAvailableError,
+    FilterDeclarationError,
+    FilterError,
+    JoinConflictWarning,
+    UnknownFilterError,
+)
+from ._joins import Statement
+from ._meta import Filters, FiltersMeta
+
+__version__ = "0.1.0"
+
+#: Explicit alias, for when more than one backend's base is in the same module.
+DataclassFilters = Filters
+
+__all__ = (
+    "BackendNotAvailableError",
+    "DataclassFilters",
+    "FilterDeclarationError",
+    "FilterError",
+    "Filters",
+    "FiltersMeta",
+    "JoinConflictWarning",
+    "Statement",
+    "UnknownFilterError",
+    "__version__",
+    "options",
+    "skip_null",
+)

sqlalchemy_declarative_filters/__init__.pyi

@@ -0,0 +1,112 @@
+"""Public typing surface for the dataclass namespace.
+
+The implementation modules stay plain, annotated Python and are type-checked as such;
+only the three namespace modules carry stubs, because their signatures are the part
+that differs per backend and reads badly inline.
+"""
+
+from collections.abc import Callable, Mapping
+from typing import Any, TypeVar
+
+from sqlalchemy.sql._typing import (
+    _ColumnExpressionArgument,
+    _JoinTargetArgument,
+    _OnClauseArgument,
+)
+from sqlalchemy.sql.selectable import Select
+
+from ._spec import FilterSpec as FilterSpec
+
+__version__: str
+
+_FuncT = TypeVar("_FuncT", bound=Callable[..., Any])
+_StatementT = TypeVar("_StatementT")
+
+class FilterError(Exception): ...
+class FilterDeclarationError(FilterError, TypeError): ...
+class UnknownFilterError(FilterError, KeyError): ...
+class BackendNotAvailableError(FilterError, ImportError): ...
+class JoinConflictWarning(UserWarning): ...
+
+class FiltersMeta(type):
+    #: The generated schema, in whichever backend ``__backend__`` names.
+    @property
+    def Schema(cls) -> type[Any]: ...
+    #: Alias of :attr:`Schema`.
+    @property
+    def Model(cls) -> type[Any]: ...
+    @property
+    def Dataclass(cls) -> type[Any]: ...
+    @property
+    def Pydantic(cls) -> type[Any]: ...
+    @property
+    def Marshmallow(cls) -> type[Any]: ...
+    @property
+    def __filters__(cls) -> tuple[FilterSpec, ...]: ...
+    def build_schema(cls, backend: str | None = ...) -> type[Any]: ...
+    def apply(
+        cls,
+        statement: _StatementT,
+        values: Mapping[str, Any] | Any | None = ...,
+    ) -> _StatementT: ...
+
+class Statement:
+    """The statement being built, as a filter body sees it.
+
+    ``self`` inside a filter is one of these, and so is what a filter returns.
+    Everything a SQLAlchemy ``Select`` offers is forwarded. Only the handful of methods
+    a filter body genuinely needs are spelled out, because every name declared here is
+    a name a filter cannot have; ``__getattr__`` covers ``order_by``, ``distinct`` and
+    the rest of the statement's surface.
+    """
+
+    def where(self, *whereclause: _ColumnExpressionArgument[bool]) -> Statement: ...
+    def having(self, *having: _ColumnExpressionArgument[bool]) -> Statement: ...
+    def join(
+        self,
+        target: _JoinTargetArgument,
+        onclause: _OnClauseArgument | None = ...,
+        *,
+        isouter: bool = ...,
+        full: bool = ...,
+    ) -> Statement:
+        """Join ``target`` unless it is already joined.
+
+        Deduplicated against the joins the other filters in the same ``apply`` asked
+        for and against the ones the incoming statement already carried.
+        """
+
+    def outerjoin(
+        self,
+        target: _JoinTargetArgument,
+        onclause: _OnClauseArgument | None = ...,
+        *,
+        full: bool = ...,
+    ) -> Statement: ...
+    #: The underlying SQLAlchemy statement.
+    def unwrap(self) -> Select[Any]: ...
+    def __getattr__(self, name: str) -> Any: ...
+
+class Filters(Statement, metaclass=FiltersMeta):
+    #: Which backend ``Schema`` uses; set by the base class you inherit from.
+    __backend__: str
+    #: Strings a query parameter may use to mean ``null`` on a ``@skip_null`` filter.
+    __null_strings__: frozenset[str]
+    #: Overrides the generated schema's class name.
+    __schema_name__: str
+
+DataclassFilters = Filters
+
+def options(
+    *,
+    default_factory: Callable[[], Any] = ...,
+    init: bool = ...,
+    repr: bool = ...,
+    hash: bool | None = ...,
+    compare: bool = ...,
+    metadata: Mapping[str, Any] = ...,
+    kw_only: bool = ...,
+) -> Callable[[_FuncT], _FuncT]:
+    """Keywords for :func:`dataclasses.field`, which is what backs this namespace."""
+
+def skip_null(func: _FuncT) -> _FuncT: ...

sqlalchemy_declarative_filters/_backends/__init__.py

@@ -0,0 +1,59 @@
+"""Schema backend registry.
+
+Backends are imported the first time they are asked for, so importing this package
+never pulls in Pydantic or Marshmallow.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, cast
+
+from .._exceptions import BackendNotAvailableError
+from .base import SchemaBackend, SchemaRequest
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+__all__ = ("SchemaBackend", "SchemaRequest", "backend_names", "get_backend")
+
+#: name -> (module, class, extra to install)
+_BACKENDS: dict[str, tuple[str, str, str | None]] = {
+    "dataclass": (".dataclass", "DataclassBackend", None),
+    "pydantic": (".pydantic", "PydanticBackend", "pydantic"),
+    "marshmallow": (".marshmallow", "MarshmallowBackend", "marshmallow"),
+}
+
+_LOADED: dict[str, SchemaBackend] = {}
+
+
+def backend_names() -> Iterator[str]:
+    """The names :func:`get_backend` accepts."""
+
+    return iter(_BACKENDS)
+
+
+def get_backend(name: str) -> SchemaBackend:
+    """Return the backend called ``name``, importing it on first use."""
+
+    if (backend := _LOADED.get(name)) is not None:
+        return backend
+
+    try:
+        module_name, class_name, extra = _BACKENDS[name]
+    except KeyError:
+        known = ", ".join(sorted(_BACKENDS))
+        raise ValueError(f"Unknown schema backend {name!r}; expected one of {known}.") from None
+
+    try:
+        module = import_module(module_name, __name__)
+    except ImportError as exc:
+        raise BackendNotAvailableError(
+            f"The {name!r} schema backend needs a dependency that is not installed: "
+            f"{exc}. Install it with "
+            f"`pip install sqlalchemy-declarative-filters[{extra}]`."
+        ) from exc
+
+    backend = _LOADED[name] = cast("SchemaBackend", getattr(module, class_name)())
+
+    return backend

sqlalchemy_declarative_filters/_backends/base.py

@@ -0,0 +1,56 @@
+"""The contract every schema backend implements."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, ClassVar
+
+if TYPE_CHECKING:
+    from .._spec import FilterSpec
+
+__all__ = ("SchemaBackend", "SchemaRequest")
+
+
+@dataclass(frozen=True)
+class SchemaRequest:
+    """Everything a backend needs to render one filter class as a schema."""
+
+    name: str
+    doc: str | None
+    module: str
+    specs: tuple[FilterSpec, ...]
+    null_strings: frozenset[str]
+
+    def is_null_string(self, value: Any) -> bool:
+        """Whether ``value`` is one of the strings that stand in for ``null``."""
+
+        return isinstance(value, str) and value.strip().lower() in self.null_strings
+
+    def coerce(self, value: Any) -> Any:
+        """Map a null-like string to ``None`` for filters that opted into it."""
+
+        return None if self.is_null_string(value) else value
+
+    @property
+    def nullable_names(self) -> tuple[str, ...]:
+        """Names of the filters whose null-like strings should become ``None``."""
+
+        return tuple(spec.name for spec in self.specs if spec.skip_null)
+
+
+class SchemaBackend(ABC):
+    """Renders :class:`~.._spec.FilterSpec` objects into a schema class."""
+
+    #: The name this backend is selected by.
+    name: ClassVar[str]
+
+    #: The extra to install to get it, or ``None`` when it needs no dependency.
+    extra: ClassVar[str | None] = None
+
+    @abstractmethod
+    def build(self, request: SchemaRequest) -> type[Any]:
+        """Build and return the schema class for ``request``."""
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} {self.name!r}>"

sqlalchemy_declarative_filters/_backends/dataclass.py

@@ -0,0 +1,81 @@
+"""The default backend: a plain :mod:`dataclasses` dataclass, no dependencies.
+
+It is a typed container, not a validator. Nothing checks that the values you put in
+match their annotations, and ``@options`` here takes ``dataclasses.field`` keywords
+rather than constraints. Use the Pydantic or Marshmallow backend when the values come
+from outside your own code and need validating.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import TYPE_CHECKING, Any
+
+from .base import SchemaBackend
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from .base import SchemaRequest
+
+__all__ = ("DataclassBackend",)
+
+
+class DataclassBackend(SchemaBackend):
+    """Renders filters as a keyword-only dataclass."""
+
+    name = "dataclass"
+
+    def build(self, request: SchemaRequest) -> type[Any]:
+        annotations: dict[str, Any] = {}
+        namespace: dict[str, Any] = {
+            "__annotations__": annotations,
+            "__doc__": request.doc,
+            "__module__": request.module,
+            "__filters_request__": request,
+            "from_mapping": classmethod(_from_mapping),
+        }
+
+        for spec in request.specs:
+            annotations[spec.name] = spec.schema_annotation
+            namespace[spec.name] = _field_for(spec)
+
+        # kw_only keeps declaration order regardless of which filters have defaults.
+        return dataclasses.dataclass(kw_only=True)(type(request.name, (), namespace))
+
+
+def _field_for(spec: Any) -> Any:
+    """Build the ``dataclasses.field`` for one filter."""
+
+    options = dict(spec.options)
+    metadata = {"description": spec.doc, **options.pop("metadata", {})}
+
+    if "default_factory" in options:
+        # A mutable default has to come from a factory; it replaces the plain default.
+        return dataclasses.field(metadata=metadata, **options)
+
+    return dataclasses.field(default=spec.schema_default, metadata=metadata, **options)
+
+
+def _from_mapping(cls: type[Any], data: Mapping[str, Any]) -> Any:
+    """Build an instance from a mapping, applying null-string coercion.
+
+    This is what the other backends get from their validation layer. It exists so a
+    dataclass schema can still be fed raw query parameters.
+    """
+
+    request: SchemaRequest = cls.__filters_request__
+    nullable = frozenset(request.nullable_names)
+    known = {field.name for field in dataclasses.fields(cls)}
+    unknown = set(data) - known
+
+    if unknown:
+        names = ", ".join(sorted(unknown))
+        raise TypeError(f"{cls.__name__} has no filter(s) named {names}.")
+
+    return cls(
+        **{
+            name: request.coerce(value) if name in nullable else value
+            for name, value in data.items()
+        }
+    )

sqlalchemy_declarative_filters/_backends/marshmallow.py

@@ -0,0 +1,128 @@
+"""The Marshmallow backend: a ``Schema`` subclass whose ``load()`` returns a dict.
+
+Marshmallow has no single field class, so annotations are mapped onto concrete field
+types here. ``@options`` keywords go to that field's constructor -- ``validate``,
+``data_key``, ``required`` and the rest -- and constraints are expressed the
+Marshmallow way, with validators::
+
+    @options(validate=validate.Length(min=3))
+    def name(self, value: str): ...
+"""
+
+from __future__ import annotations
+
+import datetime
+import decimal
+import enum
+import uuid
+from typing import TYPE_CHECKING, Any, Literal, get_args, get_origin
+
+from marshmallow import EXCLUDE, Schema, fields, pre_load, validate
+
+from .._spec import unwrap_optional
+from .base import SchemaBackend
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from .._spec import FilterSpec
+    from .base import SchemaRequest
+
+__all__ = ("MarshmallowBackend",)
+
+_SCALARS: dict[Any, type[fields.Field[Any]]] = {
+    str: fields.String,
+    int: fields.Integer,
+    float: fields.Float,
+    bool: fields.Boolean,
+    decimal.Decimal: fields.Decimal,
+    datetime.datetime: fields.DateTime,
+    datetime.date: fields.Date,
+    datetime.time: fields.Time,
+    datetime.timedelta: fields.TimeDelta,
+    uuid.UUID: fields.UUID,
+    dict: fields.Dict,
+}
+
+_SEQUENCES = (list, set, frozenset, tuple)
+
+
+class MarshmallowBackend(SchemaBackend):
+    """Renders filters as a Marshmallow schema."""
+
+    name = "marshmallow"
+    extra = "marshmallow"
+
+    def build(self, request: SchemaRequest) -> type[Schema]:
+        namespace: dict[str, Any] = {
+            "__doc__": request.doc,
+            "__module__": request.module,
+            # Filters are optional by nature; an unknown one is a caller mistake.
+            "Meta": type("Meta", (), {"unknown": EXCLUDE}),
+        }
+
+        for spec in request.specs:
+            namespace[spec.name] = _field_for(spec)
+
+        if request.nullable_names:
+            namespace["_coerce_null_strings"] = pre_load(_coercer(request))
+
+        return type(request.name, (Schema,), namespace)
+
+
+def _field_for(spec: FilterSpec) -> fields.Field[Any]:
+    """Build the Marshmallow field for one filter."""
+
+    options: dict[str, Any] = {
+        "allow_none": spec.optional,
+        "load_default": spec.schema_default,
+        "metadata": {"description": spec.doc},
+        **spec.options,
+    }
+
+    return _field_for_type(spec.schema_annotation, options)
+
+
+def _field_for_type(annotation: Any, options: dict[str, Any]) -> fields.Field[Any]:
+    """Map a Python annotation onto a concrete Marshmallow field."""
+
+    annotation, _ = unwrap_optional(annotation)
+
+    if (scalar := _SCALARS.get(annotation)) is not None:
+        return scalar(**options)
+
+    if isinstance(annotation, type) and issubclass(annotation, enum.Enum):
+        # Enums that carry a scalar value round-trip by value; the rest by name.
+        by_value = issubclass(annotation, (str, int))
+        return fields.Enum(annotation, by_value=by_value, **options)
+
+    origin = get_origin(annotation)
+
+    if origin in _SEQUENCES:
+        args = [arg for arg in get_args(annotation) if arg is not Ellipsis]
+        inner = _field_for_type(args[0], {}) if args else fields.Raw()
+        return fields.List(inner, **options)
+
+    if origin is Literal:
+        options.setdefault("validate", validate.OneOf(get_args(annotation)))
+        return fields.Raw(**options)
+
+    if origin is dict:
+        return fields.Dict(**options)
+
+    # Unknown annotation: pass the value through untouched rather than guessing.
+    return fields.Raw(**options)
+
+
+def _coercer(request: SchemaRequest) -> Any:
+    """A ``pre_load`` hook turning null-like strings into ``None``."""
+
+    nullable = frozenset(request.nullable_names)
+
+    def coerce_null_strings(_: Any, data: Mapping[str, Any], **__: Any) -> dict[str, Any]:
+        return {
+            key: None if key in nullable and request.is_null_string(value) else value
+            for key, value in data.items()
+        }
+
+    return coerce_null_strings

sqlalchemy_declarative_filters/_backends/pydantic.py

@@ -0,0 +1,64 @@
+"""The Pydantic backend: a ``BaseModel`` subclass, validation included.
+
+``@options`` keywords go straight to :func:`pydantic.Field`, so constraints such as
+``min_length`` and ``ge`` work as they would on a handwritten model.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Field, create_model, field_validator
+
+from .base import SchemaBackend
+
+if TYPE_CHECKING:
+    from .base import SchemaRequest
+
+__all__ = ("PydanticBackend",)
+
+
+class PydanticBackend(SchemaBackend):
+    """Renders filters as a Pydantic model."""
+
+    name = "pydantic"
+    extra = "pydantic"
+
+    def build(self, request: SchemaRequest) -> type[BaseModel]:
+        fields: dict[str, Any] = {}
+
+        for spec in request.specs:
+            options = dict(spec.options)
+            options.setdefault("description", spec.doc)
+            fields[spec.name] = (
+                spec.schema_annotation,
+                Field(default=spec.schema_default, **options),
+            )
+
+        validators: dict[str, Any] = {}
+
+        if names := request.nullable_names:
+            # `mode="before"` so the empty string is caught ahead of type coercion.
+            validators["_coerce_null_strings"] = field_validator(*names, mode="before")(
+                _coercer(request)
+            )
+
+        model: type[BaseModel] = create_model(
+            request.name,
+            __module__=request.module,
+            __validators__=validators,
+            **fields,
+        )
+        # Assigned rather than passed as `__doc__=`, which create_model only grew in 2.1.
+        model.__doc__ = request.doc
+
+        return model
+
+
+def _coercer(request: SchemaRequest) -> Any:
+    """A ``mode="before"`` validator turning null-like strings into ``None``."""
+
+    def coerce_null_strings(_: Any, value: Any) -> Any:
+        return None if request.is_null_string(value) else value
+
+    return classmethod(coerce_null_strings)

sqlalchemy_declarative_filters/_decorators.py

@@ -0,0 +1,55 @@
+"""Decorators applied to filter methods.
+
+Each decorator only records intent on the function object. Nothing is validated or
+built here; that happens once, lazily, when a schema is first requested.
+
+``options`` is deliberately untyped at runtime: the keywords it accepts depend on the
+schema backend in use, and each backend namespace ships a stub that pins them down.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from ._spec import OPTIONS_ATTR, SKIP_NULL_ATTR
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__all__ = ("options", "skip_null")
+
+_FuncT = TypeVar("_FuncT", bound="Callable[..., Any]")
+
+
+def options(**kwargs: Any) -> Callable[[_FuncT], _FuncT]:
+    """Attach schema field options to a filter.
+
+    The keywords are handed to the active backend verbatim, so they are whatever that
+    backend's field constructor takes. Import ``options`` from the same namespace as
+    ``Filters`` and your editor will hint the right ones.
+    """
+
+    def decorator(func: _FuncT) -> _FuncT:
+        existing = dict(getattr(func, OPTIONS_ATTR, {}))
+        existing.update(kwargs)
+        setattr(func, OPTIONS_ATTR, existing)
+
+        return func
+
+    return decorator
+
+
+def skip_null(func: _FuncT) -> _FuncT:
+    """Let an explicit ``null`` switch off a filter that has a default.
+
+    Without it, a filter declaring ``value: Status = Status.ACTIVE`` always applies.
+    With it, the schema field accepts ``None`` -- and the strings ``""``, ``"null"``
+    and ``"none"``, so a query string can say it too -- and the filter is skipped.
+
+    It does nothing on a filter without a default, which is already skipped when its
+    value is ``None``.
+    """
+
+    setattr(func, SKIP_NULL_ATTR, True)
+
+    return func

sqlalchemy_declarative_filters/_exceptions.py

@@ -0,0 +1,43 @@
+"""Exception and warning types raised by the library."""
+
+from __future__ import annotations
+
+__all__ = (
+    "BackendNotAvailableError",
+    "FilterDeclarationError",
+    "FilterError",
+    "JoinConflictWarning",
+    "UnknownFilterError",
+)
+
+
+class FilterError(Exception):
+    """Base class for every error raised by this library."""
+
+
+class FilterDeclarationError(FilterError, TypeError):
+    """A filter method is declared incorrectly.
+
+    Raised while the schema is being built, not while it is being applied.
+    """
+
+
+class UnknownFilterError(FilterError, KeyError):
+    """A value was supplied for a name that is not a filter on the class."""
+
+    def __str__(self) -> str:
+        # KeyError.__str__ wraps the message in quotes; undo that.
+        return str(self.args[0]) if self.args else ""
+
+
+class BackendNotAvailableError(FilterError, ImportError):
+    """A schema backend was requested but its optional dependency is missing."""
+
+
+class JoinConflictWarning(UserWarning):
+    """A join was requested onto a target that is already joined another way.
+
+    The join already in place wins, whether an earlier filter added it or the caller
+    did before handing the statement over. Make the ``self.join(...)`` calls agree, or
+    alias the target so the two joins address distinct selectables.
+    """