exdrf-pd 0.1.17__tar.gz

exdrf_pd-0.1.17/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: exdrf-pd
+Version: 0.1.17
+Summary: Use Pydantic with Ex-DRF.
+Author-email: Nicu Tofan <nicu.tofan@gmail.com>
+License-Expression: MIT
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Development Status :: 3 - Alpha
+Classifier: Typing :: Typed
+Requires-Python: >=3.12.2
+Description-Content-Type: text/markdown
+Requires-Dist: exdrf>=0.1.17
+Requires-Dist: pydantic>=2.10.6
+Provides-Extra: dev
+Requires-Dist: autoflake; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pyproject-flake8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: click<9,>=8.2.1; extra == "dev"
+
+# Pydantic support for Ex-DRF
+
+**exdrf-pd** connects **Pydantic v2** models to the **exdrf** dataset tree. It
+is the usual path for HTTP APIs and validators that prefer **`BaseModel`** over
+SQLAlchemy declarative classes.
+
+## What it provides
+
+- **`ExModel`** subclasses and visitors that expose resources and fields in the
+  same shapes **exdrf** uses elsewhere, so codegen and tooling can treat ORM and
+  Pydantic sources uniformly where supported.
+- **`dataset_from_pydantic`** (and related imports under **`exdrf_pd`**) for
+  building an **`ExDataset`** from your model modules—used by plugins such as
+  **exdrf-gen-pd2dare**.
+
+## Dependencies
+
+**exdrf** and **pydantic** (see `pyproject.toml`). Python **3.12.2+** is
+required.
+
+## Related packages
+
+- **exdrf-gen-al2pd** — emits Pydantic `Xxx` / `XxxEx` / `XxxCreate` / `XxxEdit`
+  from SQLAlchemy metadata (often paired with **exdrf-gen-al2r**).
+- **exdrf-ts** — maps field types and Python annotations to TypeScript for DARE
+  and other TS emitters; depends on **exdrf-pd**.
+- **exdrf-gen-pd2dare** — generates DARE TypeScript from **`ExModel`** classes.
+
+Install **exdrf-gen** and the plugin you need; see **`exdrf-gen`** README for
+the plugin entry-point pattern.

exdrf_pd-0.1.17/README.md

@@ -0,0 +1,30 @@
+# Pydantic support for Ex-DRF
+
+**exdrf-pd** connects **Pydantic v2** models to the **exdrf** dataset tree. It
+is the usual path for HTTP APIs and validators that prefer **`BaseModel`** over
+SQLAlchemy declarative classes.
+
+## What it provides
+
+- **`ExModel`** subclasses and visitors that expose resources and fields in the
+  same shapes **exdrf** uses elsewhere, so codegen and tooling can treat ORM and
+  Pydantic sources uniformly where supported.
+- **`dataset_from_pydantic`** (and related imports under **`exdrf_pd`**) for
+  building an **`ExDataset`** from your model modules—used by plugins such as
+  **exdrf-gen-pd2dare**.
+
+## Dependencies
+
+**exdrf** and **pydantic** (see `pyproject.toml`). Python **3.12.2+** is
+required.
+
+## Related packages
+
+- **exdrf-gen-al2pd** — emits Pydantic `Xxx` / `XxxEx` / `XxxCreate` / `XxxEdit`
+  from SQLAlchemy metadata (often paired with **exdrf-gen-al2r**).
+- **exdrf-ts** — maps field types and Python annotations to TypeScript for DARE
+  and other TS emitters; depends on **exdrf-pd**.
+- **exdrf-gen-pd2dare** — generates DARE TypeScript from **`ExModel`** classes.
+
+Install **exdrf-gen** and the plugin you need; see **`exdrf-gen`** README for
+the plugin entry-point pattern.

exdrf_pd-0.1.17/exdrf_pd/__init__.py

@@ -0,0 +1,18 @@
+"""Pydantic helpers used alongside exdrf-generated APIs."""
+
+from exdrf_pd.base import ExModel
+from exdrf_pd.paged import PagedList, paged_list_empty_factory
+from exdrf_pd.schema_extra import (
+    EXDRF_JSON_SCHEMA_EXTRA_KEY,
+    wrap_exdrf_props,
+)
+from exdrf_pd.sort_item import SortItem
+
+__all__ = [
+    "EXDRF_JSON_SCHEMA_EXTRA_KEY",
+    "ExModel",
+    "PagedList",
+    "SortItem",
+    "paged_list_empty_factory",
+    "wrap_exdrf_props",
+]

exdrf_pd-0.1.17/exdrf_pd/__version__.py

@@ -0,0 +1,24 @@
+"""Package version from PEP 621 or installed metadata."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from exdrf.pep621_version import distribution_version, version_tuple_from_string
+
+_PYPROJECT = Path(__file__).resolve().parents[1] / "pyproject.toml"
+_DIST_NAME = "exdrf-pd"
+
+__version__ = version = distribution_version(_DIST_NAME, _PYPROJECT)
+__version_tuple__ = version_tuple = version_tuple_from_string(__version__)
+
+__commit_id__ = commit_id = None
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]

exdrf_pd-0.1.17/exdrf_pd/base.py

@@ -0,0 +1,58 @@
+from typing import TYPE_CHECKING, ClassVar, List, Type
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from exdrf_pd.visitor import ExModelVisitor
+
+
+class ExModel(BaseModel):
+    """A Pydantic BaseModel that automatically registers its subclasses."""
+
+    _registry: ClassVar[List[Type["ExModel"]]] = []
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        ExModel._registry.append(cls)
+
+    @classmethod
+    def get_subclasses(cls):
+        """Return all registered subclasses."""
+        return cls._registry
+
+    @classmethod
+    def visit(cls, visitor: "ExModelVisitor"):
+        """Visit all the models derived from this class."""
+        for model in cls._registry:
+            # Compute the categories (list of modules) of the model.
+            categories = visitor.category(model)
+
+            # Create the tree of categories.
+            m_map = visitor.categ_map
+            for c in categories:
+                # Get the category at this level.
+                c_map = m_map.get(c, None)
+                if c_map is None:
+                    # It does not exist, so create it.
+                    c_map = m_map[c] = {}
+
+                # Move to the next level.
+                m_map = c_map
+
+            # The leaf receives the model.
+            m_map[model.__name__] = model
+
+            # Visit the model itself.
+            visitor.visit_model(
+                model,
+                model.__name__,
+                categories,  # type: ignore
+            )
+
+            # Then visit all fields of the model.
+            for field_name, field_info in model.model_fields.items():
+                visitor.visit_field(
+                    model,
+                    field_name,
+                    field_info,  # type: ignore
+                )

exdrf_pd-0.1.17/exdrf_pd/filter_item.py

@@ -0,0 +1,41 @@
+from typing import Any, Optional
+
+from pydantic import BaseModel
+
+from exdrf.filter import FieldFilter
+
+
+class FilterItem(BaseModel):
+    """
+    An item in a filter list.
+
+    Valid examples:
+
+    - { "fld": "id", "op": "==", "vl": 1 }
+    - { "fld": "deleted", "op": true }
+    - { "fld": "age", "op": ">=", "vl": 18 }
+
+    Attributes:
+        fld: the column or other identifier that indicates
+            the subject of the filter;
+        op: the operation that is used to filter
+            (something like ``==``, ``!=``);
+        vl: the value to compare the field against;
+            for some operations this might be required,
+            for others may not be used at all;
+    """
+
+    fld: str
+    op: str
+    vl: Optional[Any] = None
+
+    class Config:
+        from_attributes = True
+        populate_by_name = True
+
+    @property
+    def as_op(self):
+        """
+        Create the filter operation from parsed object.
+        """
+        return FieldFilter(fld=self.fld, op=self.op, vl=self.vl)

exdrf_pd-0.1.17/exdrf_pd/loader.py

@@ -0,0 +1,426 @@
+import re
+from datetime import date, datetime
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ForwardRef,
+    Optional,
+    cast,
+    get_args,
+    get_origin,
+)
+
+from annotated_types import Ge, Gt, Le, Lt, MaxLen, MinLen
+from attrs import define
+
+try:
+    from pydantic.functional_validators import (
+        AfterValidator,
+        BeforeValidator,
+        PlainValidator,
+        WrapValidator,
+    )
+
+    _PYDANTIC_METADATA_SKIP_TYPES: tuple[type[Any], ...] = (
+        BeforeValidator,
+        AfterValidator,
+        PlainValidator,
+        WrapValidator,
+    )
+except ImportError:  # pragma: no cover - older pydantic
+    _PYDANTIC_METADATA_SKIP_TYPES = ()
+from exdrf.api import (
+    BoolField,
+    DateField,
+    DateTimeField,
+    EnumField,
+    FloatField,
+    FloatListField,
+    IntField,
+    IntListField,
+    RefOneToManyField,
+    RefOneToOneField,
+    StrField,
+    StrListField,
+)
+from exdrf.field import ExField
+from exdrf_pd.visitor import ExModelVisitor
+
+if TYPE_CHECKING:
+    from pydantic.fields import FieldInfo as PdFieldInfo  # noqa: F401
+
+    from exdrf.dataset import ExDataset
+    from exdrf.resource import ExResource
+
+
+def _optional_inner_type(annotation: Any) -> Any | None:
+    """Return ``T`` when ``annotation`` is ``Optional[T]`` or ``T | None``.
+
+    Args:
+        annotation: A typing annotation (e.g. from ``FieldInfo.annotation``).
+
+    Returns:
+        The non-``None`` member for a plain optional union; ``None`` if the
+        annotation is not exactly one non-``None`` type plus ``None``.
+    """
+
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+    if origin is None or not args:
+        return None
+    if type(None) not in args:
+        return None
+    non_none = [a for a in args if a is not type(None)]
+    if len(non_none) != 1:
+        return None
+    return non_none[0]
+
+
+def _exmodel_by_name() -> dict[str, type]:
+    """Map ``ExModel`` subclass simple names to their class objects.
+
+    Returns:
+        A dictionary keyed by :attr:`type.__name__` for every registered
+        :class:`exdrf_pd.base.ExModel` subclass.
+    """
+
+    from exdrf_pd.base import ExModel
+
+    return {cls.__name__: cls for cls in ExModel.get_subclasses()}
+
+
+def _is_exmodel_type(tp: Any) -> bool:
+    """Return whether ``tp`` is a concrete :class:`exdrf_pd.base.ExModel` type.
+
+    Args:
+        tp: Candidate type object.
+
+    Returns:
+        ``True`` when ``tp`` is a class derived from :class:`exdrf_pd.base.ExModel`.
+    """
+
+    from exdrf_pd.base import ExModel
+
+    try:
+        return isinstance(tp, type) and issubclass(tp, ExModel)
+    except TypeError:
+        return False
+
+
+def _paged_list_item_type(annotation: Any) -> Any | None:
+    """Return the item type for a concrete ``PagedList[T]`` annotation.
+
+    Args:
+        annotation: A specialized :class:`exdrf_pd.paged.PagedList` model class.
+
+    Returns:
+        ``T`` when ``annotation`` is ``PagedList[T]``; ``None`` otherwise.
+    """
+
+    meta = getattr(annotation, "__pydantic_generic_metadata__", None)
+    if not isinstance(meta, dict):
+        return None
+    from exdrf_pd.paged import PagedList
+
+    if meta.get("origin") is not PagedList:
+        return None
+    args_raw = meta.get("args") or ()
+    args_tuple = tuple(args_raw)
+    if len(args_tuple) != 1:
+        return None
+    return args_tuple[0]
+
+
+def _parse_forward_ref_arg(
+    expr: str,
+    models_by_name: dict[str, type],
+) -> Any | None:
+    """Turn a :class:`typing.ForwardRef` argument string into a live annotation.
+
+    Args:
+        expr: The forward reference's ``__forward_arg__`` text.
+        models_by_name: Map of :class:`exdrf_pd.base.ExModel` names to classes.
+
+    Returns:
+        A concrete annotation suitable for :func:`field_from_pydantic`, or
+        ``None`` when the expression is not supported.
+    """
+
+    from exdrf_pd.paged import PagedList
+
+    expr = expr.strip()
+    if expr.endswith(" | None"):
+        inner_expr = expr[: -len(" | None")].strip()
+        inner = _parse_forward_ref_arg(inner_expr, models_by_name)
+        if inner is None:
+            return None
+        return inner | type(None)
+
+    m = re.fullmatch(r"PagedList\[(\w+)\]", expr)
+    if m:
+        inner_cls = models_by_name.get(m.group(1))
+        if inner_cls is None:
+            return None
+        return cast(Any, PagedList)[inner_cls]
+
+    return models_by_name.get(expr)
+
+
+def _resolve_forward_ref_annotation(annotation: ForwardRef) -> Any | None:
+    """Resolve a :class:`typing.ForwardRef` using registered ``ExModel`` names.
+
+    Args:
+        annotation: Pydantic field annotation that is still a forward ref.
+
+    Returns:
+        Evaluated annotation, or ``None`` if it cannot be resolved here.
+    """
+
+    raw = getattr(annotation, "__forward_arg__", None)
+    if raw is None:
+        return None
+    return _parse_forward_ref_arg(str(raw), _exmodel_by_name())
+
+
+def field_from_pydantic(
+    resource: "ExResource",
+    field_name,
+    src_field: "PdFieldInfo",
+    annotation: Optional[type] = None,
+    **kwargs: Any,
+) -> "ExField":
+    """Create a Field object from a Pydantic field.
+
+    Args:
+        field_name: The name of the field.
+        src_field: The source field.
+        annotation: The type of the field; this is used when called
+            recursively to create a field from a list of fields. If
+            not provided the annotation of the source field is used.
+        **kwargs: Additional arguments to pass to the Field constructor.
+
+    Returns:
+        The internal representation of the field.
+    """
+    # ds = resource.dataset
+    extra = {
+        "resource": resource,
+        "src": src_field,
+        "name": field_name,
+        "title": src_field.title or field_name.replace("_", " ").title(),
+        "description": src_field.description,
+        **kwargs,
+    }
+    if annotation is None:
+        annotation = src_field.annotation
+
+    # Iterate field metadata keys and extract the information that we
+    # understand.
+    for md in src_field.metadata:
+        if isinstance(md, MinLen):
+            extra["min_length"] = md.min_length
+        elif isinstance(md, MaxLen):
+            extra["max_length"] = md.max_length
+        elif isinstance(md, Gt):
+            extra["min"] = md.gt
+        elif isinstance(md, Ge):
+            extra["min"] = md.ge
+        elif isinstance(md, Lt):
+            extra["max"] = md.lt
+        elif isinstance(md, Le):
+            extra["max"] = md.le
+        elif _PYDANTIC_METADATA_SKIP_TYPES and isinstance(
+            md,
+            _PYDANTIC_METADATA_SKIP_TYPES,
+        ):
+            continue
+        else:
+            raise ValueError(f"Unknown metadata type: {md}")
+
+    inner_opt = _optional_inner_type(annotation)
+    if inner_opt is not None:
+        return field_from_pydantic(
+            resource,
+            field_name,
+            src_field,
+            annotation=inner_opt,
+            nullable=True,
+            **kwargs,
+        )
+
+    result: ExField
+
+    paged_item = _paged_list_item_type(annotation)
+    if paged_item is not None and _is_exmodel_type(paged_item):
+        ds = resource.dataset
+        paged_ref = RefOneToManyField(
+            ref=ds[paged_item.__name__],
+            expect_lots=True,
+            **extra,
+        )
+        resource.add_field(paged_ref)
+        return paged_ref
+
+    if _is_exmodel_type(annotation):
+        ds = resource.dataset
+        model_cls = cast(type, annotation)
+        result = RefOneToOneField(
+            ref=ds[model_cls.__name__],
+            **extra,
+        )
+        resource.add_field(result)
+        return result
+
+    if annotation is bool:
+        result = BoolField(
+            **extra,
+        )
+    elif annotation is str:
+        result = StrField(
+            **extra,
+        )
+    elif annotation is int:
+        result = IntField(
+            **extra,
+        )
+    elif annotation is float:
+        result = FloatField(
+            **extra,
+        )
+    elif annotation is datetime:
+        result = DateTimeField(
+            **extra,
+        )
+    elif annotation is date:
+        result = DateField(
+            **extra,
+        )
+    elif annotation is Any:
+        result = StrField(
+            **extra,
+        )
+    elif str(annotation).startswith("typing.Literal["):
+        values = annotation.__args__  # type: ignore
+        result = EnumField(
+            enum_values=[(a, a.title()) for a in values],
+            **extra,
+        )
+    elif get_origin(annotation) is list:
+        # Homogeneous ``list[T]`` / ``List[T]`` (Pydantic v2 uses ``list[int]``).
+        args = get_args(annotation)
+        list_field: Optional[ExField] = None
+        if len(args) == 1:
+            referenced = args[0]
+            if isinstance(referenced, ForwardRef):
+                pass
+            elif referenced is str:
+                list_field = StrListField(
+                    **extra,
+                )
+            elif referenced is int:
+                list_field = IntListField(
+                    **extra,
+                )
+            elif referenced is float:
+                list_field = FloatListField(
+                    **extra,
+                )
+
+        if list_field is None:
+            # Composite lists (for example ``list[dict[str, Any]]`` relation key
+            # payloads): use a string scalar exdrf field for metadata, but keep
+            # the original pydantic ``FieldInfo`` as ``src`` so ``m2ts`` can read
+            # ``field.src.annotation`` when emitting TypeScript.
+            list_field = StrField(
+                **extra,
+            )
+        result = list_field
+    elif isinstance(annotation, ForwardRef):
+        resolved = _resolve_forward_ref_annotation(annotation)
+        if resolved is not None:
+            return field_from_pydantic(
+                resource,
+                field_name,
+                src_field,
+                annotation=resolved,
+                **kwargs,
+            )
+        raise NotImplementedError(
+            "Unsupported forward reference: %r" % (annotation.__forward_arg__,)
+        )
+    elif str(annotation).startswith("<class 'exdrf_models."):
+        c_path = str(annotation)[8:-2]
+        _, cls_name = c_path.rsplit(".", 1)
+        raise NotImplementedError
+        # result = RefManyField(
+        #     ref=ds[cls_name],
+        #     **extra,
+        # )
+    # elif field_name == "filter":
+    #     result = FilterField(
+    #         **extra,
+    #     )
+    else:
+        assert False, f"Unknown field type: {annotation}"
+
+    resource.add_field(result)
+    return result
+
+
+def dataset_from_pydantic(d_set: "ExDataset") -> "ExDataset":
+    """Create a dataset from a SQLAlchemy database.
+
+    Args:
+        d_set: The dataset to populate.
+
+    Returns:
+        The populated dataset.
+    """
+    ResClass = d_set.res_class
+
+    @define
+    class Visitor(ExModelVisitor):
+        """A visitor that simply creates one resource for each model."""
+
+        def visit_model(self, model, name, categories):
+            # Get the docstring and format it.
+            _, doc_lines = self.get_docs(model)
+
+            # Create a Resource object for the model.
+            rs = ResClass(
+                src=model,
+                dataset=d_set,
+                name=name,
+                categories=categories,
+                description="\n".join(doc_lines),
+            )
+
+            # Add the resource to the dataset.
+            d_set.resources.append(rs)
+
+    # Iterate all modes that inherit from ExModel and create a resource
+    # for each of them.
+    v = Visitor.run()
+
+    # The visitor also creates a map of categories to models.
+    d_set.category_map = v.categ_map
+
+    # Retrieve fields from the models and create a Field object for each
+    # field in the resource.
+    for resource in d_set.resources:
+        # TODO:
+        # if resource.name in ("ListResponse", "ListRequest"):
+        #     continue
+
+        # Get a list of fields sorted by name, but with the id
+        # field first.
+        fields = sorted(
+            ((a, b) for a, b in resource.src.model_fields.items()),
+            key=lambda x: x[0] if x[0] != "id" else "",
+        )
+
+        # Create a Field object for each field in the resource.
+        for field_name, src_field in fields:
+            field_from_pydantic(resource, field_name, src_field)
+
+    return d_set

exdrf_pd-0.1.17/exdrf_pd/model_import.py

@@ -0,0 +1,50 @@
+"""Import Pydantic model modules so ``dataset_from_pydantic`` can see subclasses."""
+
+from __future__ import annotations
+
+import importlib
+import os
+from typing import Iterable, List
+
+_ENV_PRIMARY = "EXDRF_PYDANTIC_MODELS_MODULES"
+_ENV_LEGACY = "RESI_PYDANTIC_MODELS_MODULES"
+
+
+def load_pydantic_modules(modules: Iterable[str]) -> List[str]:
+    """Import each module name so ExModel subclasses register before dataset build.
+
+    Args:
+        modules: Iterable of dotted Python module names.
+
+    Returns:
+        Module names that were imported successfully, in order.
+    """
+
+    imported: List[str] = []
+
+    # Import each module in order to register its Pydantic subclasses.
+    for module_name in modules:
+        clean_name = module_name.strip()
+        if not clean_name:
+            continue
+        importlib.import_module(clean_name)
+        imported.append(clean_name)
+
+    return imported
+
+
+def load_pydantic_modules_from_env() -> List[str]:
+    """Import modules listed in ``EXDRF_PYDANTIC_MODELS_MODULES``.
+
+    If ``EXDRF_PYDANTIC_MODELS_MODULES`` is unset or empty, falls back to
+    ``RESI_PYDANTIC_MODELS_MODULES`` for backward compatibility (deprecated).
+
+    Returns:
+        The list of imported module names.
+    """
+
+    raw_value = os.getenv(_ENV_PRIMARY, "")
+    if not raw_value.strip():
+        raw_value = os.getenv(_ENV_LEGACY, "")
+    modules = raw_value.split(",") if raw_value else []
+    return load_pydantic_modules(modules)

exdrf_pd-0.1.17/exdrf_pd/paged.py

@@ -0,0 +1,73 @@
+"""Paged collection shapes for API / Pydantic models."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+T = TypeVar("T")
+
+
+class PagedList(BaseModel, Generic[T]):
+    """A slice of a larger collection with stable paging fields.
+
+    Use this instead of a bare ``list[T]`` when the backing relation can be
+    large and clients should load data in pages (``offset`` / ``page_size`` /
+    ``total``).
+
+    Attributes:
+        total: Number of items available in the full collection.
+        offset: Zero-based index of the first entry in ``items`` within the
+            full collection.
+        page_size: Requested page capacity; ``len(items)`` may be smaller
+            (for example on the last page).
+        items: Entries returned for this page.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    total: int = Field(default=0, ge=0, description="Total items available")
+    offset: int = Field(default=0, ge=0, description="Start index of this page")
+    page_size: int = Field(
+        default=0,
+        ge=0,
+        description="Requested maximum items per page",
+    )
+    items: list[T] = Field(
+        default_factory=list,
+        description="Items loaded for this page",
+    )
+
+    @classmethod
+    def empty(cls) -> PagedList[T]:
+        """Return an empty page (all counters zero, no items).
+
+        Returns:
+            A validated empty :class:`PagedList` suitable for
+            ``Field(default_factory=...)``.
+        """
+        return cls.model_construct(
+            total=0,
+            offset=0,
+            page_size=0,
+            items=[],
+        )
+
+
+def paged_list_empty_factory() -> PagedList[Any]:
+    """Build an empty page without naming the item type (forward-ref safe).
+
+    Use as ``Field(default_factory=paged_list_empty_factory)`` on
+    ``PagedList[SomeModel]`` fields when ``SomeModel`` is only imported under
+    ``TYPE_CHECKING``.
+
+    Returns:
+        An empty :class:`PagedList` instance.
+    """
+    return PagedList.model_construct(
+        total=0,
+        offset=0,
+        page_size=0,
+        items=[],
+    )

exdrf_pd-0.1.17/exdrf_pd/schema_extra.py

@@ -0,0 +1,22 @@
+"""Constants for embedding exdrf metadata in Pydantic JSON schema extras."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+# Key used under ``Field(json_schema_extra=...)`` / ``model_config`` so
+# OpenAPI and clients can find exdrf field/resource metadata without
+# colliding with other extensions.
+EXDRF_JSON_SCHEMA_EXTRA_KEY = "exdrf"
+
+
+def wrap_exdrf_props(props: Mapping[str, Any]) -> dict[str, Any]:
+    """Nest exdrf properties under :data:`EXDRF_JSON_SCHEMA_EXTRA_KEY`.
+
+    Args:
+        props: Field or resource properties (JSON-serializable values).
+
+    Returns:
+        A single-key dict suitable for ``json_schema_extra``.
+    """
+    return {EXDRF_JSON_SCHEMA_EXTRA_KEY: dict(props)}

exdrf_pd-0.1.17/exdrf_pd/sort_item.py

@@ -0,0 +1,27 @@
+"""Sort keys for list queries (JSON alongside :class:`~exdrf_pd.filter_item.FilterItem`)."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SortItem(BaseModel):
+    """One attribute and direction in an ordered ``ORDER BY`` specification.
+
+    Sort keys are applied in list order (first key is primary, later keys
+    break ties). Serialize as JSON objects in a list, for example
+    ``[{"attr": "name", "order": "asc"}, {"attr": "id", "order": "desc"}]``.
+
+    Attributes:
+        attr: Column or ORM attribute name to sort by.
+        order: ``asc`` or ``desc``.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    attr: str = Field(description="Attribute or column name to sort by.")
+    order: Literal["asc", "desc"] = Field(
+        description="Sort direction for this key.",
+    )

exdrf_pd-0.1.17/exdrf_pd/visitor.py

@@ -0,0 +1,55 @@
+import textwrap
+from typing import List, Type
+
+from attrs import define, field
+from pydantic.fields import FieldInfo
+
+from exdrf_pd.base import ExModel
+
+
+@define
+class ExModelVisitor:
+    """A visitor that can be used to traverse a hierarchy of ExModels.
+
+    Attributes:
+        categ_map: Tree of categories, where each key is a category and the
+            value is a dictionary of subcategories or models. The tree is built
+            by the `visit` method, so it is not complete until that method
+            has been called.
+    """
+
+    categ_map: dict = field(factory=dict)
+
+    def visit_model(self, model: Type["ExModel"], name: str, categories: List[str]):
+        """Visit a model."""
+
+    def visit_field(self, model: Type["ExModel"], name: str, field: "FieldInfo"):
+        """Visit a field."""
+
+    @staticmethod
+    def category(model) -> List[str]:
+        """Get the category of a module.
+
+        This is the list of nested python modules in which the pydantic model
+        is defined, except for the first (package name) and the last (the file
+        name, which is usually the same as the resource name).
+        """
+        return model.__module__.split(".")[1:-1]
+
+    @staticmethod
+    def get_docs(thing):
+        """Retrieve the documentation of a pydantic model or field."""
+        doc = textwrap.dedent(thing.__doc__).strip() if thing.__doc__ else ""
+
+        doc_lines = doc.split("\n")
+        for i in range(1, len(doc_lines)):
+            if doc_lines[i].startswith("    "):
+                doc_lines[i] = doc_lines[i][4:]
+        return doc, doc_lines
+
+    @classmethod
+    def run(cls, *args, **kwargs):
+        """Run the visitor."""
+        v = cls(*args, **kwargs)
+        ExModel.visit(v)  # type: ignore[call-arg]
+        return v

exdrf_pd-0.1.17/exdrf_pd.egg-info/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: exdrf-pd
+Version: 0.1.17
+Summary: Use Pydantic with Ex-DRF.
+Author-email: Nicu Tofan <nicu.tofan@gmail.com>
+License-Expression: MIT
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Development Status :: 3 - Alpha
+Classifier: Typing :: Typed
+Requires-Python: >=3.12.2
+Description-Content-Type: text/markdown
+Requires-Dist: exdrf>=0.1.17
+Requires-Dist: pydantic>=2.10.6
+Provides-Extra: dev
+Requires-Dist: autoflake; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pyproject-flake8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: click<9,>=8.2.1; extra == "dev"
+
+# Pydantic support for Ex-DRF
+
+**exdrf-pd** connects **Pydantic v2** models to the **exdrf** dataset tree. It
+is the usual path for HTTP APIs and validators that prefer **`BaseModel`** over
+SQLAlchemy declarative classes.
+
+## What it provides
+
+- **`ExModel`** subclasses and visitors that expose resources and fields in the
+  same shapes **exdrf** uses elsewhere, so codegen and tooling can treat ORM and
+  Pydantic sources uniformly where supported.
+- **`dataset_from_pydantic`** (and related imports under **`exdrf_pd`**) for
+  building an **`ExDataset`** from your model modules—used by plugins such as
+  **exdrf-gen-pd2dare**.
+
+## Dependencies
+
+**exdrf** and **pydantic** (see `pyproject.toml`). Python **3.12.2+** is
+required.
+
+## Related packages
+
+- **exdrf-gen-al2pd** — emits Pydantic `Xxx` / `XxxEx` / `XxxCreate` / `XxxEdit`
+  from SQLAlchemy metadata (often paired with **exdrf-gen-al2r**).
+- **exdrf-ts** — maps field types and Python annotations to TypeScript for DARE
+  and other TS emitters; depends on **exdrf-pd**.
+- **exdrf-gen-pd2dare** — generates DARE TypeScript from **`ExModel`** classes.
+
+Install **exdrf-gen** and the plugin you need; see **`exdrf-gen`** README for
+the plugin entry-point pattern.

exdrf_pd-0.1.17/exdrf_pd.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+README.md
+pyproject.toml
+setup.py
+exdrf_pd/__init__.py
+exdrf_pd/__version__.py
+exdrf_pd/base.py
+exdrf_pd/filter_item.py
+exdrf_pd/loader.py
+exdrf_pd/model_import.py
+exdrf_pd/paged.py
+exdrf_pd/py.typed
+exdrf_pd/schema_extra.py
+exdrf_pd/sort_item.py
+exdrf_pd/visitor.py
+exdrf_pd.egg-info/PKG-INFO
+exdrf_pd.egg-info/SOURCES.txt
+exdrf_pd.egg-info/dependency_links.txt
+exdrf_pd.egg-info/requires.txt
+exdrf_pd.egg-info/top_level.txt
+exdrf_pd_tests/__init__.py
+tests/loader_optional_field_test.py
+tests/model_import_test.py
+tests/paged_schema_extra_test.py
+tests/sort_item_test.py

exdrf_pd-0.1.17/exdrf_pd.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

exdrf_pd-0.1.17/exdrf_pd.egg-info/requires.txt

@@ -0,0 +1,18 @@
+exdrf>=0.1.17
+pydantic>=2.10.6
+
+[dev]
+autoflake
+black
+build
+flake8
+isort
+mypy
+pre-commit
+pyproject-flake8
+pytest-cov
+pytest-mock
+pytest
+twine
+wheel
+click<9,>=8.2.1

exdrf_pd-0.1.17/exdrf_pd.egg-info/top_level.txt

@@ -0,0 +1,4 @@
+dist
+exdrf_pd
+exdrf_pd_tests
+tests

exdrf_pd-0.1.17/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+authors = [
+    { name = "Nicu Tofan", email = "nicu.tofan@gmail.com" },
+]
+license = "MIT"
+classifiers = [
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Development Status :: 3 - Alpha",
+  "Typing :: Typed",
+]
+description = "Use Pydantic with Ex-DRF."
+version = "0.1.17"
+name = "exdrf-pd"
+readme = "README.md"
+requires-python = ">=3.12.2"
+dependencies = [
+  "exdrf>=0.1.17",
+  "pydantic>=2.10.6",
+]
+
+[project.optional-dependencies]
+dev = [
+  "autoflake",
+  "black",
+  "build",
+  "flake8",
+  "isort",
+  "mypy",
+  "pre-commit",
+  "pyproject-flake8",
+  "pytest-cov",
+  "pytest-mock",
+  "pytest",
+  "twine",
+  "wheel",
+  "click>=8.2.1,<9",
+]
+
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = ["setuptools>=67.0"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+exdrf_pd = ["py.typed"]
+
+[tool.setuptools.packages.find]
+exclude = ["venv*", "playground*"]
+
+
+[tool.isort]
+profile = "black"
+
+[tool.black]
+line-length = 80
+target-version = ['py312']
+
+[tool.flake8]
+docstring-convention = "google"
+max-line-length = 80
+extend-ignore = ["E203", "E501", "W503"]

exdrf_pd-0.1.17/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

exdrf_pd-0.1.17/setup.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python
+
+import setuptools
+
+if __name__ == "__main__":
+    setuptools.setup(use_scm_version=True)

exdrf_pd-0.1.17/tests/loader_optional_field_test.py

@@ -0,0 +1,44 @@
+"""Tests for :mod:`exdrf_pd.loader` optional / PEP 604 union annotations."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+from exdrf.field_types.str_field import StrField
+from exdrf.resource import ExResource
+from exdrf_pd.loader import field_from_pydantic
+
+
+class TestFieldFromPydanticOptional:
+    """Covers ``str | None`` and ``Optional[str]`` field annotations."""
+
+    def test_pep604_str_or_none_produces_str_field(self) -> None:
+        """``str | None`` unwraps to :class:`StrField` instead of failing."""
+
+        class Sample(BaseModel):
+            """Minimal model with a PEP 604 optional string."""
+
+            label: str | None = None
+
+        resource = ExResource(name="Sample", src=Sample)
+        info = Sample.model_fields["label"]
+        field_from_pydantic(resource, "label", info)
+        assert len(resource.fields) == 1
+        assert isinstance(resource.fields[0], StrField)
+        assert resource.fields[0].name == "label"
+
+    def test_optional_str_produces_str_field(self) -> None:
+        """``Optional[str]`` is handled like ``str | None``."""
+
+        class Sample(BaseModel):
+            """Minimal model with ``typing.Optional``."""
+
+            label: Optional[str] = None
+
+        resource = ExResource(name="Sample", src=Sample)
+        info = Sample.model_fields["label"]
+        field_from_pydantic(resource, "label", info)
+        assert len(resource.fields) == 1
+        assert isinstance(resource.fields[0], StrField)

exdrf_pd-0.1.17/tests/model_import_test.py

@@ -0,0 +1,77 @@
+"""Tests for ``exdrf_pd.model_import``."""
+
+from __future__ import annotations
+
+import sys
+import types
+
+import pytest
+
+from exdrf_pd import model_import
+
+
+def test_load_pydantic_modules_skips_empty_and_imports(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Whitespace-only entries are skipped; valid modules are imported."""
+
+    created: list[str] = []
+
+    def fake_import_module(name: str) -> types.ModuleType:
+        created.append(name)
+        mod = types.ModuleType(name)
+        sys.modules[name] = mod
+        return mod
+
+    monkeypatch.setattr(model_import.importlib, "import_module", fake_import_module)
+    result = model_import.load_pydantic_modules(["  ", "a.b", "  c.d  ", ""])
+    assert result == ["a.b", "c.d"]
+    assert created == ["a.b", "c.d"]
+    for name in created:
+        sys.modules.pop(name, None)
+
+
+def test_load_pydantic_modules_from_env_prefers_exdrf_var(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """``EXDRF_PYDANTIC_MODELS_MODULES`` wins when set."""
+
+    monkeypatch.delenv("EXDRF_PYDANTIC_MODELS_MODULES", raising=False)
+    monkeypatch.delenv("RESI_PYDANTIC_MODELS_MODULES", raising=False)
+    monkeypatch.setenv("EXDRF_PYDANTIC_MODELS_MODULES", "mod_a")
+    monkeypatch.setenv("RESI_PYDANTIC_MODELS_MODULES", "mod_b")
+
+    imported: list[str] = []
+
+    def fake_import(name: str) -> types.ModuleType:
+        imported.append(name)
+        m = types.ModuleType(name)
+        sys.modules[name] = m
+        return m
+
+    monkeypatch.setattr(model_import.importlib, "import_module", fake_import)
+    model_import.load_pydantic_modules_from_env()
+    assert imported == ["mod_a"]
+    sys.modules.pop("mod_a", None)
+
+
+def test_load_pydantic_modules_from_env_resi_fallback(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """When ``EXDRF_*`` is empty, ``RESI_*`` is used."""
+
+    monkeypatch.delenv("EXDRF_PYDANTIC_MODELS_MODULES", raising=False)
+    monkeypatch.setenv("RESI_PYDANTIC_MODELS_MODULES", "legacy_mod")
+
+    imported: list[str] = []
+
+    def fake_import(name: str) -> types.ModuleType:
+        imported.append(name)
+        m = types.ModuleType(name)
+        sys.modules[name] = m
+        return m
+
+    monkeypatch.setattr(model_import.importlib, "import_module", fake_import)
+    model_import.load_pydantic_modules_from_env()
+    assert imported == ["legacy_mod"]
+    sys.modules.pop("legacy_mod", None)

exdrf_pd-0.1.17/tests/paged_schema_extra_test.py

@@ -0,0 +1,86 @@
+"""Tests for ``exdrf_pd.paged`` and ``exdrf_pd.schema_extra`` primitives."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import BaseModel, ValidationError
+
+from exdrf_pd.paged import PagedList, paged_list_empty_factory
+from exdrf_pd.schema_extra import (
+    EXDRF_JSON_SCHEMA_EXTRA_KEY,
+    wrap_exdrf_props,
+)
+
+
+class TestPagedList:
+    """Covers validation, defaults, and ``extra="forbid"`` for paging models."""
+
+    def test_round_trip_simple_items(self) -> None:
+        """A populated page validates and preserves counters."""
+
+        page = PagedList[int](
+            total=100,
+            offset=10,
+            page_size=20,
+            items=[1, 2],
+        )
+        assert page.total == 100
+        assert page.offset == 10
+        assert page.page_size == 20
+        assert page.items == [1, 2]
+
+    def test_empty_classmethod(self) -> None:
+        """``empty()`` yields a zeroed envelope with no items."""
+
+        page = PagedList[int].empty()
+        assert page.total == 0
+        assert page.offset == 0
+        assert page.page_size == 0
+        assert page.items == []
+
+    def test_paged_list_empty_factory_matches_empty(self) -> None:
+        """The forward-ref-safe factory matches ``PagedList[Any].empty()``."""
+
+        from_any = paged_list_empty_factory()
+        typed_empty = PagedList[int].empty()
+        assert from_any.model_dump() == typed_empty.model_dump()
+
+    def test_rejects_extra_keys(self) -> None:
+        """Unknown fields are rejected."""
+
+        with pytest.raises(ValidationError):
+            PagedList[int].model_validate(
+                {
+                    "total": 0,
+                    "offset": 0,
+                    "page_size": 0,
+                    "items": [],
+                    "unexpected": True,
+                }
+            )
+
+    def test_json_schema_includes_core_properties(self) -> None:
+        """OpenAPI-oriented schema lists the stable paging field names."""
+
+        class Item(BaseModel):
+            """Minimal nested item."""
+
+            id: int
+
+        schema = PagedList[Item].model_json_schema()
+        props = set(schema.get("properties", {}))
+        assert props == {"total", "offset", "page_size", "items"}
+
+
+class TestWrapExdrfProps:
+    """Tests for :func:`wrap_exdrf_props`."""
+
+    def test_nests_under_exdrf_key(self) -> None:
+        """Props are wrapped under :data:`EXDRF_JSON_SCHEMA_EXTRA_KEY`."""
+
+        wrapped = wrap_exdrf_props({"kind": "list", "resource": "towns"})
+        assert set(wrapped.keys()) == {EXDRF_JSON_SCHEMA_EXTRA_KEY}
+        assert wrapped[EXDRF_JSON_SCHEMA_EXTRA_KEY] == {
+            "kind": "list",
+            "resource": "towns",
+        }

exdrf_pd-0.1.17/tests/sort_item_test.py

@@ -0,0 +1,49 @@
+"""Tests for :class:`~exdrf_pd.sort_item.SortItem`."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from pydantic import TypeAdapter, ValidationError
+
+from exdrf_pd.sort_item import SortItem
+
+
+def test_package_exports_sort_item() -> None:
+    """``from exdrf_pd import SortItem`` re-exports the model."""
+
+    from exdrf_pd import SortItem as SortItemFromRoot
+
+    assert SortItemFromRoot is SortItem
+
+
+class TestSortItem:
+    """Validation and JSON round-trip for :class:`SortItem`."""
+
+    def test_accepts_asc_desc(self) -> None:
+        """Both literal orders validate."""
+
+        assert SortItem(attr="id", order="asc").order == "asc"
+        assert SortItem(attr="id", order="desc").order == "desc"
+
+    def test_rejects_invalid_order(self) -> None:
+        """Unknown direction raises validation error."""
+
+        with pytest.raises(ValidationError):
+            SortItem(attr="x", order="up")  # type: ignore[arg-type]
+
+    def test_json_roundtrip_list(self) -> None:
+        """``TypeAdapter`` parses the JSON list shape used in query strings."""
+
+        raw = json.dumps(
+            [
+                {"attr": "name", "order": "asc"},
+                {"attr": "id", "order": "desc"},
+            ],
+        )
+        adapter = TypeAdapter(list[SortItem])
+        items = adapter.validate_json(raw.encode("utf-8"))
+        assert len(items) == 2
+        assert items[0].attr == "name"
+        assert items[1].order == "desc"