tigrbl 0.0.1.dev1__py3-none-any.whl → 0.3.0.dev2__py3-none-any.whl

tigrbl/schema/builder/build_schema.py

@@ -0,0 +1,209 @@
+"""Core schema builder logic for Tigrbl v3."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Iterable, Set, Tuple, Type, Union
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, create_model
+
+from ..utils import namely_model
+from ...column.mro_collect import mro_collect_columns
+from .cache import _SchemaCache
+from .extras import _merge_request_extras, _merge_response_extras
+from .helpers import _add_field, _is_required, _python_type
+
+logger = logging.getLogger(__name__)
+
+
+def _build_schema(
+    orm_cls: type,
+    *,
+    name: str | None = None,
+    include: Set[str] | None = None,
+    exclude: Set[str] | None = None,
+    verb: str = "create",
+) -> Type[BaseModel]:
+    """Build (and cache) a verb-specific Pydantic schema for *orm_cls*."""
+    cache_key = (
+        orm_cls,
+        verb,
+        frozenset(include or ()),
+        frozenset(exclude or ()),
+        name,
+    )
+    cached = _SchemaCache.get(cache_key)
+    if cached is not None:
+        logger.debug("schema: cache hit %s verb=%s", orm_cls.__name__, verb)
+        return cached
+
+    logger.debug(
+        "schema: building %s verb=%s include=%s exclude=%s",
+        orm_cls.__name__,
+        verb,
+        include,
+        exclude,
+    )
+    fields: Dict[str, Tuple[type, Field]] = {}
+
+    # ── PASS 1: table-backed columns only (avoid mapper relationships)
+    table = getattr(orm_cls, "__table__", None)
+    table_cols: Iterable[Any] = tuple(table.columns) if table is not None else ()
+    specs: Dict[str, Any] = mro_collect_columns(orm_cls)
+
+    for col in table_cols:
+        attr_name = col.key or col.name
+
+        if include and attr_name not in include:
+            continue
+        if exclude and attr_name in exclude:
+            continue
+
+        spec = specs.get(attr_name)
+        io = getattr(spec, "io", None) if spec is not None else None
+        if verb in {"create", "update", "replace"}:
+            """Determine if the column participates in inbound verbs.
+
+            When a ColumnSpec is present it may explicitly restrict inbound
+            verbs via ``io.in_verbs``. Columns that only declare outbound verbs
+            are treated as read-only and omitted from request schemas. If no
+            ColumnSpec or ``in_verbs`` is provided we allow all verbs.
+            """
+
+            if getattr(col, "primary_key", False) and verb in {
+                "update",
+                "replace",
+                "delete",
+            }:
+                # Always expose the PK for mutating operations even when the
+                # ColumnSpec omits inbound verbs. The identifier is required so
+                # consumers can target the correct row.
+                pass
+            else:
+                if io is not None:
+                    in_verbs = set(getattr(io, "in_verbs", ()) or ())
+                    out_verbs = set(getattr(io, "out_verbs", ()) or ())
+                    if not in_verbs:
+                        if out_verbs:
+                            continue
+                    elif verb not in in_verbs:
+                        continue
+
+        logger.debug("schema: processing column %s (verb=%s)", attr_name, verb)
+
+        # Determine type and requiredness
+        py_t = _python_type(col)
+        required = _is_required(col, verb)
+
+        # Field construction (collect kwargs then create Field once)
+        fs = getattr(spec, "field", None)
+        field_kwargs: Dict[str, Any] = dict(getattr(fs, "constraints", {}) or {})
+
+        default_factory = getattr(spec, "default_factory", None)
+        if default_factory and verb in set(getattr(io, "in_verbs", []) or []):
+            field_kwargs["default_factory"] = default_factory
+            required = False
+        else:
+            field_kwargs["default"] = None if not required else ...
+
+        # IOSpec aliases → Pydantic validation/serialization aliases
+        alias_in = getattr(io, "alias_in", None) if io is not None else None
+        alias_out = getattr(io, "alias_out", None) if io is not None else None
+        if alias_in:
+            field_kwargs["validation_alias"] = AliasChoices(alias_in, attr_name)
+        if alias_out:
+            field_kwargs["serialization_alias"] = alias_out
+
+        fld = Field(**field_kwargs)
+
+        # Optional typing if nullable
+        is_nullable = bool(getattr(col, "nullable", True))
+        if is_nullable and py_t is not Any:
+            py_t = Union[py_t, None]
+
+        # Apply alias mappings for IO specs so that generated Pydantic models
+        # accept both the canonical field name and any configured alias. This
+        # ensures request payloads can use ``alias_in`` and response models use
+        # ``alias_out`` while still normalizing to the canonical attribute name
+        # internally.
+        if io is not None:
+            if verb in {"read", "list"}:
+                alias = getattr(io, "alias_out", None)
+            else:
+                alias = getattr(io, "alias_in", None)
+            if alias:
+                fld.alias = alias
+                fld.serialization_alias = alias
+                fld.validation_alias = AliasChoices(attr_name, alias)
+
+        _add_field(fields, name=attr_name, py_t=py_t, field=fld)
+        logger.debug(
+            "schema: added field %s required=%s type=%r", attr_name, required, py_t
+        )
+
+    # ── PASS 1b: virtual columns declared via ColumnSpec --------------------
+    for attr_name, spec in specs.items():
+        if getattr(spec, "storage", None) is not None:
+            continue  # real columns handled above
+        if include and attr_name not in include:
+            continue
+        if exclude and attr_name in exclude:
+            continue
+
+        io = getattr(spec, "io", None)
+        allowed_verbs = set(getattr(io, "in_verbs", ()) or ()) | set(
+            getattr(io, "out_verbs", ()) or ()
+        )
+        if allowed_verbs and verb not in allowed_verbs:
+            continue
+
+        fs = getattr(spec, "field", None)
+        py_t = getattr(fs, "py_type", Any) if fs is not None else Any
+        required = bool(fs and verb in getattr(fs, "required_in", ()))
+        allow_null = bool(fs and verb in getattr(fs, "allow_null_in", ()))
+        nullable = bool(getattr(spec, "nullable", True))
+        field_kwargs: Dict[str, Any] = dict(getattr(fs, "constraints", {}) or {})
+
+        default_factory = getattr(spec, "default_factory", None)
+        if default_factory and verb in set(getattr(spec.io, "in_verbs", []) or []):
+            field_kwargs["default_factory"] = default_factory
+            required = False
+        else:
+            field_kwargs["default"] = None if not required else ...
+
+        fld = Field(**field_kwargs)
+
+        if (allow_null or nullable) and py_t is not Any:
+            py_t = Union[py_t, None]
+
+        _add_field(fields, name=attr_name, py_t=py_t, field=fld)
+        logger.debug(
+            "schema: added virtual field %s required=%s type=%r",
+            attr_name,
+            required,
+            py_t,
+        )
+
+    # ── PASS 2: request/response extras
+    _merge_request_extras(orm_cls, verb, fields, include=include, exclude=exclude)
+    _merge_response_extras(orm_cls, verb, fields, include=include, exclude=exclude)
+
+    model_name = name or f"{orm_cls.__name__}{verb.capitalize()}"
+    cfg_kwargs = {"from_attributes": True}
+    if verb in {"create", "update", "replace"}:
+        cfg_kwargs["extra"] = "forbid"
+    cfg = ConfigDict(**cfg_kwargs)
+
+    schema_cls = create_model(model_name, __config__=cfg, **fields)  # type: ignore[arg-type]
+    schema_cls.model_rebuild(force=True)
+    schema_cls = namely_model(
+        schema_cls,
+        name=model_name,
+        doc=f"Tigrbl v3 {orm_cls.__name__} {verb} schema",
+    )
+    _SchemaCache[cache_key] = schema_cls
+    logger.debug("schema: created %s with %d fields", model_name, len(fields))
+    return schema_cls
+
+
+__all__ = ["_build_schema"]

tigrbl/schema/builder/cache.py

@@ -0,0 +1,24 @@
+"""Cache and type definitions for schema builder."""
+
+from __future__ import annotations
+
+from typing import Dict, Tuple, Type, Union, Literal
+
+from pydantic import BaseModel
+
+_SchemaVerb = Union[
+    Literal["create"],
+    Literal["read"],
+    Literal["update"],
+    Literal["replace"],
+    Literal["merge"],
+    Literal["delete"],
+    Literal["list"],
+    Literal["clear"],
+]
+
+_SchemaCache: Dict[
+    Tuple[type, str, frozenset, frozenset, str | None], Type[BaseModel]
+] = {}
+
+__all__ = ["_SchemaVerb", "_SchemaCache"]

tigrbl/schema/builder/compat.py

@@ -0,0 +1,16 @@
+"""Compatibility utilities for schema builder."""
+
+from __future__ import annotations
+
+try:
+    # Pydantic v2 sentinel for "no default"
+    from pydantic_core import PydanticUndefined  # type: ignore
+except Exception:  # pragma: no cover
+
+    class PydanticUndefinedClass:  # type: ignore
+        pass
+
+    PydanticUndefined = PydanticUndefinedClass()  # type: ignore
+
+
+__all__ = ["PydanticUndefined"]

tigrbl/schema/builder/extras.py

@@ -0,0 +1,85 @@
+"""Support for request/response extras in schema building."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Set, Tuple
+
+from pydantic import Field
+
+from ...config.constants import (
+    TIGRBL_REQUEST_EXTRAS_ATTR,
+    TIGRBL_RESPONSE_EXTRAS_ATTR,
+)
+from .helpers import _add_field
+
+logger = logging.getLogger(__name__)
+
+
+def _merge_request_extras(
+    orm_cls: type,
+    verb: str,
+    fields: Dict[str, Tuple[type, Field]],
+    *,
+    include: Set[str] | None,
+    exclude: Set[str] | None,
+) -> None:
+    """Merge request-only virtual fields into the schema."""
+    buckets = getattr(orm_cls, TIGRBL_REQUEST_EXTRAS_ATTR, None)
+    if not buckets:
+        return
+    if verb not in {"create", "update", "replace", "delete"}:
+        return
+
+    for bucket in (buckets.get("*", {}), buckets.get(verb, {})):
+        for name, spec in (bucket or {}).items():
+            if include and name not in include:
+                continue
+            if exclude and name in exclude:
+                continue
+            if isinstance(spec, tuple) and len(spec) == 2:
+                py_t, fld = spec
+            else:
+                py_t, fld = (spec or Any), Field(None)
+            _add_field(fields, name=name, py_t=py_t, field=fld)
+            logger.debug(
+                "schema: added request-extra field %s (verb=%s, type=%r)",
+                name,
+                verb,
+                py_t,
+            )
+
+
+def _merge_response_extras(
+    orm_cls: type,
+    verb: str,
+    fields: Dict[str, Tuple[type, Field]],
+    *,
+    include: Set[str] | None,
+    exclude: Set[str] | None,
+) -> None:
+    """Merge response-only virtual fields into the schema."""
+    buckets = getattr(orm_cls, TIGRBL_RESPONSE_EXTRAS_ATTR, None)
+    if not buckets:
+        return
+
+    for bucket in (buckets.get("*", {}), buckets.get(verb, {})):
+        for name, spec in (bucket or {}).items():
+            if include and name not in include:
+                continue
+            if exclude and name in exclude:
+                continue
+            if isinstance(spec, tuple) and len(spec) == 2:
+                py_t, fld = spec
+            else:
+                py_t, fld = (spec or Any), Field(None)
+            _add_field(fields, name=name, py_t=py_t, field=fld)
+            logger.debug(
+                "schema: added response-extra field %s (verb=%s, type=%r)",
+                name,
+                verb,
+                py_t,
+            )
+
+
+__all__ = ["_merge_request_extras", "_merge_response_extras"]

tigrbl/schema/builder/helpers.py

@@ -0,0 +1,51 @@
+"""Internal helper utilities for schema building."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Tuple
+
+from pydantic import Field
+
+
+def _bool(x: Any) -> bool:
+    try:
+        return bool(x)
+    except Exception:  # pragma: no cover
+        return False
+
+
+def _add_field(
+    sink: Dict[str, Tuple[type, Field]],
+    *,
+    name: str,
+    py_t: type | Any,
+    field: Field | None = None,
+) -> None:
+    sink[name] = (py_t, field if field is not None else Field(None))
+
+
+def _python_type(col: Any) -> type | Any:
+    try:
+        return col.type.python_type
+    except Exception:  # pragma: no cover
+        return Any
+
+
+def _is_required(col: Any, verb: str) -> bool:
+    """Decide if a column should be required for the given verb."""
+    if getattr(col, "primary_key", False):
+        if verb in {"update", "replace", "delete"}:
+            return True
+        auto = getattr(col, "autoincrement", False)
+        if auto not in (False, None) or getattr(col, "identity", None) is not None:
+            return False
+    if verb == "update":
+        return False
+    is_nullable = bool(getattr(col, "nullable", True))
+    has_default = (getattr(col, "default", None) is not None) or (
+        getattr(col, "server_default", None) is not None
+    )
+    return not is_nullable and not has_default
+
+
+__all__ = ["_bool", "_add_field", "_python_type", "_is_required"]

tigrbl/schema/builder/list_params.py

@@ -0,0 +1,117 @@
+"""Schema builders for list parameter models."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Any, Type
+
+from pydantic import BaseModel, ConfigDict, Field, create_model
+
+from ..utils import namely_model
+from ...column.mro_collect import mro_collect_columns
+
+logger = logging.getLogger(__name__)
+
+
+def _build_list_params(model: type) -> Type[BaseModel]:
+    """Create a list/filter schema for the given model."""
+    tab = model.__name__
+    logger.debug("schema: build_list_params for %s", tab)
+
+    base = dict(
+        skip=(int | None, Field(None, ge=0)),
+        limit=(int | None, Field(None, ge=10)),
+        sort=(str | list[str] | None, Field(None)),
+    )
+    _scalars = {str, int, float, bool, bytes, uuid.UUID}
+    cols: dict[str, tuple[type, Field]] = {}
+
+    table = getattr(model, "__table__", None)
+    if table is None or not getattr(table, "columns", None):
+        # No table info; return a minimal pager schema
+        schema = create_model(
+            f"{tab}ListParams", __config__=ConfigDict(extra="forbid"), **base
+        )  # type: ignore[arg-type]
+        schema = namely_model(
+            schema,
+            name=f"{tab}ListParams",
+            doc=f"List parameters for {tab}",
+        )
+        logger.debug(
+            "schema: build_list_params generated %s (no columns)", schema.__name__
+        )
+        return schema
+
+    pk_name = None
+    for c in table.columns:
+        if getattr(c, "primary_key", False):
+            pk_name = c.name
+            break
+
+    _canon = {
+        "eq": "eq",
+        "=": "eq",
+        "==": "eq",
+        "ne": "ne",
+        "!=": "ne",
+        "<>": "ne",
+        "lt": "lt",
+        "<": "lt",
+        "gt": "gt",
+        ">": "gt",
+        "lte": "lte",
+        "le": "lte",
+        "<=": "lte",
+        "gte": "gte",
+        "ge": "gte",
+        ">=": "gte",
+        "like": "like",
+        "not_like": "not_like",
+        "ilike": "ilike",
+        "not_ilike": "not_ilike",
+        "in": "in",
+        "not_in": "not_in",
+    }
+
+    for c in table.columns:
+        if pk_name and c.name == pk_name:
+            continue
+        py_t = getattr(c.type, "python_type", Any)
+        if py_t in _scalars:
+            spec_map = mro_collect_columns(model)
+            spec = spec_map.get(c.name)
+            io = getattr(spec, "io", None)
+            ops_raw = set(getattr(io, "filter_ops", ()) or [])
+            if not ops_raw:
+                # Allow basic equality filtering by default on scalar columns
+                ops_raw = {"eq"}
+            ops = {_canon.get(op, op) for op in ops_raw}
+            if "eq" in ops:
+                cols[c.name] = (py_t | None, Field(None))
+                logger.debug("schema: list filter add %s type=%r", c.name, py_t)
+            for op in ops:
+                if op == "eq":
+                    continue
+                fname = f"{c.name}__{op}"
+                cols[fname] = (py_t | None, Field(None))
+                logger.debug(
+                    "schema: list filter add %s op=%s type=%r", c.name, op, py_t
+                )
+
+    schema = create_model(
+        f"{tab}ListParams",
+        __config__=ConfigDict(extra="forbid"),
+        **base,  # type: ignore[arg-type]
+        **cols,  # type: ignore[arg-type]
+    )
+    schema = namely_model(
+        schema,
+        name=f"{tab}ListParams",
+        doc=f"List parameters for {tab}",
+    )
+    logger.debug("schema: build_list_params generated %s", schema.__name__)
+    return schema
+
+
+__all__ = ["_build_list_params"]

tigrbl/schema/builder/strip_parent_fields.py

@@ -0,0 +1,70 @@
+"""Utilities for removing fields from parent schemas."""
+
+from __future__ import annotations
+
+import inspect
+from typing import (
+    Any,
+    Dict,
+    List,
+    Set,
+    Tuple,
+    Type,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from pydantic import BaseModel, create_model
+
+from .compat import PydanticUndefined
+
+
+def _strip_parent_fields(base: Type[BaseModel], *, drop: Set[str]) -> Type[BaseModel]:
+    """Return a shallow clone of *base* with selected fields removed."""
+    assert issubclass(base, BaseModel), "base must be a Pydantic BaseModel subclass"
+
+    # RootModel[Union[Model, List[Model]]] – unwrap inner model so we can strip
+    # identifiers and return the cleaned schema directly.
+    if len(getattr(base, "model_fields", {})) == 1 and "root" in base.model_fields:
+        root_ann = base.model_fields["root"].annotation
+        if get_origin(root_ann) is Union:
+            item_type = None
+            for arg in get_args(root_ann):
+                origin = get_origin(arg)
+                if inspect.isclass(arg) and issubclass(arg, BaseModel):
+                    item_type = arg
+                    break
+                if origin in (list, List):
+                    sub = get_args(arg)[0]
+                    if inspect.isclass(sub) and issubclass(sub, BaseModel):
+                        item_type = sub
+                        break
+            if item_type is not None:
+                return _strip_parent_fields(item_type, drop=drop)
+
+    hints = get_type_hints(base, include_extras=True)
+    new_fields: Dict[str, Tuple[type, Any]] = {}
+
+    for name, finfo in base.model_fields.items():  # type: ignore[attr-defined]
+        if name in (drop or ()):  # pragma: no branch
+            continue
+        typ = hints.get(name, Any)
+        default = (
+            finfo.default
+            if getattr(finfo, "default", PydanticUndefined) is not PydanticUndefined
+            else ...
+        )
+        new_fields[name] = (typ, default)
+
+    clone = create_model(
+        f"{base.__name__}Pruned",
+        __config__=getattr(base, "model_config", None),
+        **new_fields,
+    )  # type: ignore[arg-type]
+    clone.model_rebuild(force=True)
+    return clone
+
+
+__all__ = ["_strip_parent_fields"]

tigrbl/schema/collect.py

@@ -0,0 +1,55 @@
+# tigrbl/v3/schema/collect.py
+from __future__ import annotations
+
+import inspect
+import logging
+from functools import lru_cache
+from typing import Dict
+
+from ..config.constants import TIGRBL_SCHEMA_DECLS_ATTR
+
+from .decorators import _SchemaDecl
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+
+
+@lru_cache(maxsize=None)
+def collect_decorated_schemas(model: type) -> Dict[str, Dict[str, type]]:
+    """Gather schema declarations for ``model`` across its MRO."""
+    logger.info("Collecting decorated schemas for %s", model.__name__)
+    out: Dict[str, Dict[str, type]] = {}
+
+    # Explicit registrations (MRO-merged)
+    for base in reversed(model.__mro__):
+        mapping: Dict[str, Dict[str, type]] = (
+            getattr(base, TIGRBL_SCHEMA_DECLS_ATTR, {}) or {}
+        )
+        if mapping:
+            logger.debug(
+                "Found explicit schema mapping on %s: %s", base.__name__, mapping
+            )
+        for alias, kinds in mapping.items():
+            bucket = out.setdefault(alias, {})
+            bucket.update(kinds or {})
+
+    # Nested classes with __tigrbl_schema_decl__
+    for base in reversed(model.__mro__):
+        for name, obj in base.__dict__.items():
+            if not inspect.isclass(obj):
+                logger.debug("Skipping non-class attribute %s.%s", base.__name__, name)
+                continue
+            decl: _SchemaDecl | None = getattr(obj, "__tigrbl_schema_decl__", None)
+            if not decl:
+                logger.debug(
+                    "Class %s.%s has no schema declaration", base.__name__, name
+                )
+                continue
+            bucket = out.setdefault(decl.alias, {})
+            bucket[decl.kind] = obj
+
+    logger.debug("Collected schema aliases: %s", list(out.keys()))
+    return out
+
+
+__all__ = ["collect_decorated_schemas"]