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

tigrbl/bindings/schemas/utils.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+import logging
+
+# tigrbl/v3/bindings/schemas/utils.py
+
+from types import SimpleNamespace
+from typing import Any, Optional, Tuple, Type
+
+from pydantic import BaseModel, create_model
+
+from ...schema.types import SchemaArg, SchemaRef
+from ...schema import namely_model
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/schemas/utils")
+
+_Key = Tuple[str, str]  # (alias, target)
+
+
+def _camel(s: str) -> str:
+    return "".join(p.capitalize() or "_" for p in s.split("_"))
+
+
+def _alias_schema(
+    schema: Type[BaseModel], *, model: type, alias: str, kind: str
+) -> Type[BaseModel]:
+    logger.debug(
+        "Aliasing schema %s for %s as %s %s",
+        schema.__name__,
+        model.__name__,
+        alias,
+        kind,
+    )
+    name = f"{model.__name__}{_camel(alias)}{kind}"
+    if getattr(schema, "__name__", None) == name:
+        logger.debug("Schema already aliased as %s", name)
+        return schema
+    try:
+        clone = create_model(name, __base__=schema)  # type: ignore[arg-type]
+    except Exception as e:  # pragma: no cover - best effort
+        logger.debug("Failed to clone schema %s: %s", schema.__name__, e)
+        return schema
+    logger.debug("Created alias schema %s", name)
+    return namely_model(
+        clone,
+        name=name,
+        doc=f"{alias} {kind.lower()} schema for {model.__name__}",
+    )
+
+
+def _ensure_alias_namespace(model: type, alias: str) -> SimpleNamespace:
+    ns = getattr(model.schemas, alias, None)
+    if ns is None:
+        ns = SimpleNamespace()
+        setattr(model.schemas, alias, ns)
+        logger.debug("Created namespace for %s.%s", model.__name__, alias)
+    else:
+        logger.debug("Using existing namespace for %s.%s", model.__name__, alias)
+    return ns
+
+
+def _pk_info(model: type) -> Tuple[str, type | Any]:
+    """
+    Return (pk_name, python_type) for single-PK tables. If composite, returns (pk, Any).
+    """
+    table = getattr(model, "__table__", None)
+    if table is None or not getattr(table, "primary_key", None):
+        logger.debug("Model %s has no table or primary key", model.__name__)
+        return ("id", Any)
+    cols = list(table.primary_key.columns)  # type: ignore[attr-defined]
+    if not cols:
+        logger.debug("Model %s primary key columns empty", model.__name__)
+        return ("id", Any)
+    if len(cols) > 1:
+        logger.debug("Model %s has composite primary key", model.__name__)
+        # Composite keys: schema builder uses verb='delete' to require what's needed.
+        # For bulk_delete we fall back to Any.
+        return ("id", Any)
+    col = cols[0]
+    py_t = getattr(getattr(col, "type", None), "python_type", Any)
+    logger.debug(
+        "Model %s primary key %s of type %s",
+        model.__name__,
+        getattr(col, "name", "id"),
+        py_t,
+    )
+    return (getattr(col, "name", "id"), py_t or Any)
+
+
+def _parse_str_ref(s: str) -> Tuple[str, str]:
+    """
+    Parse dotted schema ref "alias.in" | "alias.out".
+    """
+    s = s.strip()
+    logger.debug("Parsing schema ref '%s'", s)
+    if "." not in s:
+        logger.debug("Schema ref '%s' missing '.'", s)
+        raise ValueError(
+            f"Invalid schema path '{s}', expected 'alias.in' or 'alias.out'"
+        )
+    alias, kind = s.split(".", 1)
+    kind = kind.strip()
+    if kind not in {"in", "out"}:
+        logger.debug("Schema ref '%s' has invalid kind '%s'", s, kind)
+        raise ValueError(f"Invalid schema kind '{kind}', expected 'in' or 'out'")
+    logger.debug("Parsed schema ref alias=%s kind=%s", alias, kind)
+    return alias.strip(), kind
+
+
+def _resolve_schema_arg(model: type, arg: SchemaArg) -> Optional[Type[BaseModel]]:
+    """
+    Resolve an override to a concrete Pydantic model or raw:
+      • SchemaRef("alias","in"|"out") → that model
+      • "alias.in" | "alias.out"      → that model
+      • "raw"                         → None (raw passthrough)
+      • None                          → caller should keep defaults for canonical ops;
+                                        for custom ops no defaults exist → raw
+    Unsupported (will raise):
+      • direct Pydantic model classes
+      • callables/thunks
+      • any other strings
+    """
+    logger.debug("Resolving schema arg %s for %s", arg, model.__name__)
+    if arg is None:
+        logger.debug("Schema arg is None; returning None")
+        return None
+
+    # explicit raw
+    if isinstance(arg, str) and arg.strip().lower() == "raw":
+        logger.debug("Schema arg is explicit raw")
+        return None
+
+    # direct Pydantic model
+    if isinstance(arg, type) and issubclass(arg, BaseModel):
+        logger.debug("Schema arg is direct model %s", arg.__name__)
+        return arg
+
+    # SchemaRef
+    if isinstance(arg, SchemaRef):
+        logger.debug("Schema arg is SchemaRef(alias=%s, kind=%s)", arg.alias, arg.kind)
+        if arg.kind not in ("in", "out"):
+            logger.debug("Unsupported SchemaRef kind '%s'", arg.kind)
+            raise ValueError(
+                f"Unsupported SchemaRef kind '{arg.kind}'. Use 'in' or 'out'.",
+            )
+        ns = getattr(model, "schemas", None)
+        if ns is None or getattr(ns, arg.alias, None) is None:
+            logger.debug("Unknown schema alias '%s' on %s", arg.alias, model.__name__)
+            raise KeyError(f"Unknown schema alias '{arg.alias}' on {model.__name__}")
+        alias_ns = getattr(ns, arg.alias)
+        attr = "in_" if arg.kind == "in" else "out"
+        res = getattr(alias_ns, attr, None)
+        if res is None:
+            logger.debug(
+                "Schema '%s.%s' not found on %s", arg.alias, attr, model.__name__
+            )
+            raise KeyError(f"Schema '{arg.alias}.{attr}' not found on {model.__name__}")
+        logger.debug(
+            "Resolved SchemaRef %s.%s to %s",
+            arg.alias,
+            attr,
+            getattr(res, "__name__", None),
+        )
+        return res  # type: ignore[return-value]
+
+    # dotted string
+    if isinstance(arg, str):
+        alias, kind = _parse_str_ref(arg)
+        ns = getattr(model, "schemas", None)
+        if ns is None or getattr(ns, alias, None) is None:
+            logger.debug("Unknown schema alias '%s' on %s", alias, model.__name__)
+            raise KeyError(f"Unknown schema alias '{alias}' on {model.__name__}")
+        alias_ns = getattr(ns, alias)
+        attr = "in_" if kind == "in" else "out"
+        res = getattr(alias_ns, attr, None)
+        if res is None:
+            logger.debug("Schema '%s.%s' not found on %s", alias, attr, model.__name__)
+            raise KeyError(f"Schema '{alias}.{attr}' not found on {model.__name__}")
+        logger.debug(
+            "Resolved schema path %s.%s to %s",
+            alias,
+            attr,
+            getattr(res, "__name__", None),
+        )
+        return res  # type: ignore[return-value]
+
+    logger.debug("Unsupported SchemaArg type: %s", type(arg))
+    # Everything else is unsupported now
+    raise TypeError(
+        f"Unsupported SchemaArg type: {type(arg)}. "
+        "Use SchemaRef(...,'in'|'out'), 'alias.in'/'alias.out', 'raw', or None.",
+    )

tigrbl/column/README.md

@@ -0,0 +1,62 @@
+# Column Specs
+
+Tigrbl columns are declared with helper functions like `acol` and `vcol`.
+Each column is driven by three smaller specs that describe how the value is
+stored, validated, and exposed. These specs keep column behaviour
+consistent across the ORM, schema generation, and the runtime API.
+
+## StorageSpec (`S`)
+Describes the database shape and storage behaviour.
+
+- `type_` – SQLAlchemy column type.
+- `nullable`, `unique`, `index`, `primary_key`, `autoincrement`.
+- Defaults and generation: `default`, `onupdate`, `server_default`,
+  `refresh_on_return`.
+- Optional helpers: `transform`, `fk`, `check`, `comment`.
+
+## FieldSpec (`F`)
+Captures Pydantic metadata and request policy.
+
+- `py_type` – Python type, inferred when omitted.
+- `constraints` – passed to `pydantic.Field` for validation.
+- `required_in` / `allow_null_in` – control required and nullable verbs.
+
+## IOSpec (`IO`)
+Controls API exposure and advanced value handling.
+
+- `in_verbs` / `out_verbs` – verbs that accept or emit the value.
+- `mutable_verbs` – verbs allowed to change the value.
+- `alias_in` / `alias_out` – alternative field names.
+- `sensitive`, `redact_last` – masking and redaction options.
+- `filter_ops`, `sortable` – enable filtering and sorting.
+- Helpers: `assemble`, `paired`, `alias_readtime` for computed aliases.
+
+## ColumnSpec
+`ColumnSpec` ties the three specs together and adds runtime helpers such as
+`default_factory` and `read_producer`.
+
+```python
+from tigrbl.column import acol, vcol, F, IO, S
+
+class Widget(Base):
+    __tablename__ = "widgets"
+
+    id: Mapped[int] = acol(storage=S(primary_key=True))
+    name: Mapped[str] = acol(
+        field=F(constraints={"max_length": 50}),
+        storage=S(nullable=False, index=True),
+        io=IO(
+            in_verbs=("create", "update"),
+            out_verbs=("read", "list"),
+            sortable=True,
+        ),
+    )
+    checksum: Mapped[str] = vcol(
+        field=F(),
+        io=IO(out_verbs=("read",)),
+        read_producer=lambda obj, ctx: f"{obj.name}:{obj.id}",
+    )
+```
+
+For additional background see the "Column-Level Configuration" section in the
+parent [README](../README.md).

tigrbl/column/__init__.py

@@ -0,0 +1,72 @@
+# tigrbl/v3/column/__init__.py
+"""Tigrbl v3 – column specs public API.
+
+Unifies StorageSpec (DB-facing), FieldSpec (python/wire semantics), and IOSpec (in/out exposure)
+into a :class:`ColumnSpec` with a :class:`Column` descriptor. Provides ergonomic constructors
+``makeColumn`` and ``makeVirtualColumn`` (with ``acol``/``vcol`` convenience aliases) and re-exports the
+bind-time type inference utilities and markers.
+
+Public surface:
+    Column, ColumnSpec, FieldSpec as F, StorageSpec as S, IOSpec as IO
+    makeColumn, makeVirtualColumn, acol, vcol
+    infer, Inferred, DataKind, SATypePlan, JsonHint
+    markers: Email, Phone
+    exceptions: InferenceError, UnsupportedType
+    helper: is_virtual(ColumnSpec) -> bool
+"""
+
+from __future__ import annotations
+
+# Core spec types
+from .column_spec import ColumnSpec
+from ._column import Column
+from .field_spec import FieldSpec as F
+from .storage_spec import StorageSpec as S
+from .io_spec import IOSpec as IO
+
+# Ergonomic constructors
+from .shortcuts import makeColumn, makeVirtualColumn, acol, vcol
+
+# Bind-time inference (DB/vendor-agnostic)
+from .infer import (
+    infer,
+    Inferred,
+    DataKind,
+    SATypePlan,
+    JsonHint,
+    Email,
+    Phone,
+    InferenceError,
+    UnsupportedType,
+)
+
+__all__ = [
+    "ColumnSpec",
+    "Column",
+    "F",
+    "S",
+    "IO",
+    "makeColumn",
+    "makeVirtualColumn",
+    "acol",
+    "vcol",
+    "infer",
+    "Inferred",
+    "DataKind",
+    "SATypePlan",
+    "JsonHint",
+    "Email",
+    "Phone",
+    "InferenceError",
+    "UnsupportedType",
+    "is_virtual",
+]
+
+
+def is_virtual(col: ColumnSpec) -> bool:
+    """Return True if the column is wire-only (never persisted)."""
+    return getattr(col, "storage", None) is None
+
+
+def __dir__():
+    return sorted(__all__)

tigrbl/column/_column.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import MappedColumn
+
+from .column_spec import ColumnSpec
+from .field_spec import FieldSpec as F
+from .io_spec import IOSpec as IO
+from .storage_spec import StorageSpec as S
+
+
+class Column(ColumnSpec, MappedColumn):
+    """SQLAlchemy column implementing a :class:`ColumnSpec`."""
+
+    __slots__ = ()
+
+    def __init__(
+        self,
+        *,
+        spec: ColumnSpec | None = None,
+        storage: S | None = None,
+        field: F | None = None,
+        io: IO | None = None,
+        default_factory: Optional[Callable[[dict], Any]] = None,
+        read_producer: Optional[Callable[[object, dict], Any]] = None,
+        **kw: Any,
+    ) -> None:
+        if spec is not None and any(
+            x is not None for x in (storage, field, io, default_factory, read_producer)
+        ):
+            raise ValueError("Provide either spec or individual components, not both.")
+        if spec is None:
+            spec = ColumnSpec(
+                storage=storage,
+                field=field,
+                io=io,
+                default_factory=default_factory,
+                read_producer=read_producer,
+            )
+        else:
+            storage = spec.storage
+            field = spec.field
+            io = spec.io
+            default_factory = spec.default_factory
+            read_producer = spec.read_producer
+
+        s = storage
+        if s is not None:
+            args: list[Any] = [s.type_]
+            fk = getattr(s, "fk", None)
+            if fk is not None:
+                args.append(
+                    ForeignKey(
+                        fk.target,
+                        ondelete=fk.on_delete,
+                        onupdate=fk.on_update,
+                        deferrable=fk.deferrable,
+                        initially="DEFERRED" if fk.initially_deferred else "IMMEDIATE",
+                        match=fk.match,
+                    )
+                )
+            MappedColumn.__init__(
+                self,
+                *args,
+                primary_key=s.primary_key,
+                nullable=s.nullable,
+                unique=s.unique,
+                index=s.index,
+                default=s.default,
+                autoincrement=s.autoincrement,
+                server_default=s.server_default,
+                onupdate=s.onupdate,
+                comment=s.comment,
+                **kw,
+            )
+        else:
+            MappedColumn.__init__(self, **kw)
+
+        self.storage = s
+        self.field = field if field is not None else F()
+        self.io = io if io is not None else IO()
+        self.default_factory = default_factory
+        self.read_producer = read_producer
+
+    def __set_name__(self, owner, name: str) -> None:
+        parent = getattr(super(), "__set_name__", None)
+        if parent:
+            parent(owner, name)
+        colspecs = owner.__dict__.get("__tigrbl_colspecs__")
+        if colspecs is None:
+            base_specs = getattr(owner, "__tigrbl_colspecs__", {})
+            colspecs = dict(base_specs)
+            setattr(owner, "__tigrbl_colspecs__", colspecs)
+        colspecs[name] = self

tigrbl/column/column_spec.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from .field_spec import FieldSpec as F
+from .io_spec import IOSpec as IO
+from .storage_spec import StorageSpec as S
+
+
+class ColumnSpec:
+    """Aggregate configuration for a model attribute.
+
+    A :class:`ColumnSpec` brings together the three lower-level specs used by
+    Tigrbl's declarative column system:
+
+    - ``storage`` (:class:`~tigrbl.column.storage_spec.StorageSpec`) controls
+      how the value is persisted in the database.
+    - ``field`` (:class:`~tigrbl.column.field_spec.FieldSpec`) describes the
+      Python type and any schema metadata.
+    - ``io`` (:class:`~tigrbl.column.io_spec.IOSpec`) governs inbound and
+      outbound API exposure.
+
+    Optional ``default_factory`` and ``read_producer`` callables allow for
+    programmatic defaults and virtual read-time values respectively.
+    """
+
+    def __init__(
+        self,
+        *,
+        storage: S | None,
+        field: F | None = None,
+        io: IO | None = None,
+        default_factory: Optional[Callable[[dict], Any]] = None,
+        read_producer: Optional[Callable[[object, dict], Any]] = None,
+    ) -> None:
+        self.storage = storage
+        self.field = field if field is not None else F()
+        self.io = io if io is not None else IO()
+        self.default_factory = default_factory
+        self.read_producer = read_producer

tigrbl/column/field_spec.py

@@ -0,0 +1,31 @@
+# field_spec.py
+from __future__ import annotations
+from dataclasses import dataclass, field as dc_field
+from typing import Any, Dict, Tuple, Callable
+from pydantic import ValidationInfo  # v2
+
+PreFn = Callable[[Any, ValidationInfo], Any]  # BeforeValidator
+PostFn = Callable[[Any, ValidationInfo], Any]  # AfterValidator
+
+
+@dataclass(frozen=True)
+class FieldSpec:
+    """Describe Python-side metadata for a column or virtual field.
+
+    ``py_type`` denotes the expected Python type and may be omitted when the
+    model attribute is annotated; the type will then be inferred. ``constraints``
+    mirrors arguments accepted by :func:`pydantic.Field` and participates in
+    schema generation. ``required_in`` and ``allow_null_in`` govern which API
+    verbs must supply the value or may explicitly send ``null`` in requests.
+    Responses rely on Pydantic's built-in encoders based solely on the
+    declared type.
+    """
+
+    py_type: Any = Any
+
+    # For request/response schema generation (+ pydantic.Field)
+    constraints: Dict[str, Any] = dc_field(default_factory=dict)
+
+    # Request policy (DB nullability lives in StorageSpec.nullable)
+    required_in: Tuple[str, ...] = ()
+    allow_null_in: Tuple[str, ...] = ()

tigrbl/column/infer/__init__.py

@@ -0,0 +1,25 @@
+from .core import infer
+from .types import (
+    Email,
+    Phone,
+    DataKind,
+    PyTypeInfo,
+    SATypePlan,
+    JsonHint,
+    Inferred,
+    InferenceError,
+    UnsupportedType,
+)
+
+__all__ = [
+    "infer",
+    "Email",
+    "Phone",
+    "DataKind",
+    "PyTypeInfo",
+    "SATypePlan",
+    "JsonHint",
+    "Inferred",
+    "InferenceError",
+    "UnsupportedType",
+]

tigrbl/column/infer/core.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, get_origin
+
+from .types import DataKind, PyTypeInfo, Inferred
+from .utils import _strip_optional, _strip_annotated, _array_item, _is_enum
+from .planning import _plan_sa_type
+from .jsonhints import _json_hint
+
+
+def infer(
+    annotation: Any,
+    *,
+    prefer_dialect: Optional[str] = "postgresql",
+    max_length: Optional[int] = None,
+    decimal_precision: Optional[int] = None,
+    decimal_scale: Optional[int] = None,
+) -> Inferred:
+    """Bind-time inference from Python annotation to DataKind and hints."""
+    base, is_opt = _strip_optional(annotation)
+    base, meta = _strip_annotated(base)
+
+    enum_cls = _is_enum(base)
+    item_tp = _array_item(base)
+
+    array_item_info: Optional[PyTypeInfo] = None
+    if item_tp is not None:
+        nested = infer(
+            item_tp,
+            prefer_dialect=prefer_dialect,
+            max_length=max_length,
+            decimal_precision=decimal_precision,
+            decimal_scale=decimal_scale,
+        )
+        array_item_info = nested.py
+
+    py_info = PyTypeInfo(
+        base=base,
+        is_optional=is_opt,
+        enum_cls=enum_cls,
+        array_item=array_item_info,
+        annotated=meta,
+    )
+
+    import datetime as _dt
+    import decimal as _dc
+    import uuid as _uuid
+
+    origin = get_origin(base)
+
+    if enum_cls is not None:
+        kind = DataKind.ENUM
+    elif item_tp is not None:
+        kind = DataKind.ARRAY
+    elif base in (str,):
+        kind = DataKind.STRING
+    elif base in (bytes, bytearray, memoryview):
+        kind = DataKind.BYTES
+    elif base in (bool,):
+        kind = DataKind.BOOL
+    elif base in (int,):
+        kind = DataKind.INT
+    elif base in (float,):
+        kind = DataKind.FLOAT
+    elif base in (_dc.Decimal,):
+        kind = DataKind.DECIMAL
+    elif base in (_dt.datetime,):
+        kind = DataKind.DATETIME
+    elif base in (_dt.date,):
+        kind = DataKind.DATE
+    elif base in (_dt.time,):
+        kind = DataKind.TIME
+    elif base in (_uuid.UUID,):
+        kind = DataKind.UUID
+    else:
+        if origin in (dict, Dict):
+            kind = DataKind.JSON
+        else:
+            kind = DataKind.JSON
+
+    sa = _plan_sa_type(
+        kind,
+        py_info,
+        prefer_dialect=prefer_dialect,
+        max_length=max_length,
+        decimal_precision=decimal_precision,
+        decimal_scale=decimal_scale,
+    )
+
+    jh = _json_hint(kind, py_info, max_length=max_length)
+
+    return Inferred(kind=kind, py=py_info, sa=sa, json=jh, nullable=is_opt)

tigrbl/column/infer/jsonhints.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .types import DataKind, PyTypeInfo, JsonHint, Email, Phone
+from .planning import _nested_kind_from_py
+
+
+def _json_hint(
+    kind: DataKind, py: PyTypeInfo, *, max_length: Optional[int]
+) -> JsonHint:
+    if kind is DataKind.STRING:
+        fmt = None
+        if Email in py.annotated:
+            fmt = "email"
+        if Phone in py.annotated:
+            fmt = "phone"
+        return JsonHint(type="string", format=fmt, maxLength=max_length)
+    if kind is DataKind.BYTES:
+        return JsonHint(type="string", format="byte")
+    if kind is DataKind.BOOL:
+        return JsonHint(type="boolean")
+    if kind is DataKind.INT or kind is DataKind.BIGINT:
+        return JsonHint(type="integer")
+    if kind is DataKind.FLOAT or kind is DataKind.DECIMAL:
+        return JsonHint(type="number")
+    if kind is DataKind.DATE:
+        return JsonHint(type="string", format="date")
+    if kind is DataKind.TIME:
+        return JsonHint(type="string", format="time")
+    if kind is DataKind.DATETIME:
+        return JsonHint(type="string", format="date-time")
+    if kind is DataKind.UUID:
+        return JsonHint(type="string", format="uuid")
+    if kind is DataKind.JSON:
+        return JsonHint(type="object")
+    if kind is DataKind.ENUM and py.enum_cls:
+        return JsonHint(type="string", enum=[e.name for e in py.enum_cls])
+    if kind is DataKind.ARRAY and py.array_item:
+        elem_kind = _nested_kind_from_py(py.array_item)
+        return JsonHint(
+            type="array", items=_json_hint(elem_kind, py.array_item, max_length=None)
+        )
+    return JsonHint(type="string")