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

tigrbl/column/infer/planning.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .types import DataKind, PyTypeInfo, SATypePlan, InferenceError
+
+
+def _plan_sa_type(
+    kind: DataKind,
+    py: PyTypeInfo,
+    *,
+    prefer_dialect: Optional[str],
+    max_length: Optional[int],
+    decimal_precision: Optional[int],
+    decimal_scale: Optional[int],
+) -> SATypePlan:
+    d = prefer_dialect
+
+    if kind is DataKind.STRING:
+        if max_length and max_length > 0:
+            return SATypePlan(
+                name="String", args=(max_length,), kwargs={}, dialect=None
+            )
+        return SATypePlan(name="String", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.TEXT:
+        return SATypePlan(name="Text", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.BYTES:
+        return SATypePlan(name="LargeBinary", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.BOOL:
+        return SATypePlan(name="Boolean", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.INT:
+        return SATypePlan(name="Integer", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.BIGINT:
+        return SATypePlan(name="BigInteger", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.FLOAT:
+        return SATypePlan(name="Float", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.DECIMAL:
+        kwargs: Dict[str, Any] = {}
+        if decimal_precision is not None:
+            kwargs["precision"] = decimal_precision
+        if decimal_scale is not None:
+            kwargs["scale"] = decimal_scale
+        return SATypePlan(name="Numeric", args=(), kwargs=kwargs, dialect=None)
+
+    if kind is DataKind.DATE:
+        return SATypePlan(name="Date", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.TIME:
+        return SATypePlan(name="Time", args=(), kwargs={"timezone": True}, dialect=None)
+
+    if kind is DataKind.DATETIME:
+        return SATypePlan(
+            name="DateTime", args=(), kwargs={"timezone": True}, dialect=None
+        )
+
+    if kind is DataKind.UUID:
+        if d == "postgresql":
+            return SATypePlan(
+                name="UUID", args=(), kwargs={"as_uuid": True}, dialect="postgresql"
+            )
+        return SATypePlan(name="String", args=(36,), kwargs={}, dialect=None)
+
+    if kind is DataKind.JSON:
+        if d == "postgresql":
+            return SATypePlan(name="JSONB", args=(), kwargs={}, dialect="postgresql")
+        return SATypePlan(name="JSON", args=(), kwargs={}, dialect=None)
+
+    if kind is DataKind.ENUM:
+        if not py.enum_cls:
+            raise InferenceError("ENUM kind requires enum_cls in PyTypeInfo")
+        return SATypePlan(
+            name="Enum", args=(py.enum_cls,), kwargs={"native_enum": True}, dialect=None
+        )
+
+    if kind is DataKind.ARRAY:
+        if not py.array_item:
+            raise InferenceError("ARRAY kind requires array_item in PyTypeInfo")
+        elem_plan = _plan_sa_type(
+            _nested_kind_from_py(py.array_item),
+            py.array_item,
+            prefer_dialect=prefer_dialect,
+            max_length=None,
+            decimal_precision=None,
+            decimal_scale=None,
+        )
+        if prefer_dialect == "postgresql":
+            return SATypePlan(
+                name="ARRAY",
+                args=(elem_plan.name,),
+                kwargs={},
+                dialect="postgresql",
+            )
+        return SATypePlan(name="JSON", args=(), kwargs={}, dialect=None)
+
+    raise InferenceError(f"Cannot plan SA type for kind={kind!r}")
+
+
+def _nested_kind_from_py(nested_py: PyTypeInfo) -> DataKind:
+    if nested_py.enum_cls is not None:
+        return DataKind.ENUM
+    b = nested_py.base
+    import datetime as _dt
+    import decimal as _dc
+    import uuid as _uuid
+
+    if b is str:
+        return DataKind.STRING
+    if b in (bytes, bytearray, memoryview):
+        return DataKind.BYTES
+    if b is bool:
+        return DataKind.BOOL
+    if b is int:
+        return DataKind.INT
+    if b is float:
+        return DataKind.FLOAT
+    if b is _dc.Decimal:
+        return DataKind.DECIMAL
+    if b is _dt.datetime:
+        return DataKind.DATETIME
+    if b is _dt.date:
+        return DataKind.DATE
+    if b is _dt.time:
+        return DataKind.TIME
+    if b is _uuid.UUID:
+        return DataKind.UUID
+    return DataKind.JSON

tigrbl/column/infer/types.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple, Type
+
+
+# ---------------------------------------------------------------------------
+# Public markers (wire/adapters provide validation/normalization at runtime)
+# ---------------------------------------------------------------------------
+
+
+class Email:
+    """Marker indicating email string semantics."""
+
+
+class Phone:
+    """Marker indicating E.164 phone string semantics."""
+
+
+# ---------------------------------------------------------------------------
+# Portable data-kind (DB- and adapter-agnostic)
+# ---------------------------------------------------------------------------
+
+
+class DataKind(str, Enum):
+    STRING = "string"
+    TEXT = "text"
+    BYTES = "bytes"
+    BOOL = "bool"
+    INT = "int"
+    BIGINT = "bigint"
+    FLOAT = "float"
+    DECIMAL = "decimal"
+    DATE = "date"
+    TIME = "time"
+    DATETIME = "datetime"
+    UUID = "uuid"
+    JSON = "json"
+    ENUM = "enum"
+    ARRAY = "array"
+
+
+# ---------------------------------------------------------------------------
+# Structured outputs
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PyTypeInfo:
+    """Normalized info about the Python-side type annotation."""
+
+    base: Any
+    is_optional: bool = False
+    enum_cls: Optional[Type[Enum]] = None
+    array_item: Optional["PyTypeInfo"] = None
+    annotated: Tuple[Any, ...] = ()
+
+
+@dataclass(frozen=True)
+class SATypePlan:
+    """Declarative plan for constructing an SA column type downstream."""
+
+    name: str  # e.g., "UUID", "String", "JSONB", "Enum", "ARRAY"
+    args: Tuple[Any, ...]  # positional args (e.g., (enum_cls,))
+    kwargs: Dict[str, Any]  # keyword args (e.g., {"as_uuid": True})
+    dialect: Optional[str] = None  # e.g., "postgresql" for JSONB/UUID/ARRAY
+
+
+@dataclass(frozen=True)
+class JsonHint:
+    """Minimal JSON Schema-ish hints for docs."""
+
+    type: str
+    format: Optional[str] = None
+    maxLength: Optional[int] = None
+    enum: Optional[List[str]] = None
+    items: Optional["JsonHint"] = None
+
+
+@dataclass(frozen=True)
+class Inferred:
+    """Primary product of inference."""
+
+    kind: DataKind
+    py: PyTypeInfo
+    sa: SATypePlan
+    json: JsonHint
+    nullable: bool
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class InferenceError(ValueError):
+    """Base class for inference-related errors."""
+
+
+class UnsupportedType(InferenceError):
+    """Raised when a type cannot be inferred."""

tigrbl/column/infer/utils.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import (
+    Any,
+    List,
+    Optional,
+    Tuple,
+    Type,
+    Union,
+    get_args,
+    get_origin,
+    Annotated,
+)
+
+
+def _strip_optional(tp: Any) -> Tuple[Any, bool]:
+    """Return (inner_type, is_optional) for Optional[T] / Union[T, None]."""
+    origin = get_origin(tp)
+    if origin is Union:
+        args = tuple(a for a in get_args(tp))
+        if len(args) == 2 and type(None) in args:
+            inner = args[0] if args[1] is type(None) else args[1]
+            return inner, True
+    return tp, False
+
+
+def _strip_annotated(tp: Any) -> Tuple[Any, Tuple[Any, ...]]:
+    """Return (base, metadata) for Annotated[base, *meta]; otherwise (tp, ())."""
+    origin = get_origin(tp)
+    if origin is Annotated:
+        args = get_args(tp)
+        if len(args) >= 1:
+            base, meta = args[0], tuple(args[1:])
+            return base, meta
+    return tp, ()
+
+
+def _array_item(tp: Any) -> Optional[Any]:
+    origin = get_origin(tp)
+    if origin in (list, List, tuple, Tuple, set, frozenset):
+        args = get_args(tp)
+        if not args:
+            return Any
+        if origin in (tuple, Tuple) and len(args) == 2 and args[1] is Ellipsis:
+            return args[0]
+        if len(args) == 1:
+            return args[0]
+        return Any
+    return None
+
+
+def _is_enum(tp: Any) -> Optional[Type[Enum]]:
+    try:
+        if isinstance(tp, type) and issubclass(tp, Enum):
+            return tp
+    except Exception:
+        pass
+    return None

tigrbl/column/io_spec.py

@@ -0,0 +1,133 @@
+# --- io_spec.py --------------------------------------------------------------
+from dataclasses import dataclass, replace
+from typing import Callable, Tuple, Literal
+from .field_spec import FieldSpec as F
+
+
+@dataclass(frozen=True)
+class _PairedCfg:
+    gen: Callable[[dict], object]  # ctx -> raw
+    store: Callable[[object, dict], object]  # (raw, ctx) -> stored
+    alias: str
+    verbs: Tuple[str, ...]
+    emit: str  # "pre_flush" | "post_refresh" | "readtime"
+    alias_field: F
+    mask_last: int | None
+
+
+@dataclass(frozen=True)
+class _AssembleCfg:
+    sources: Tuple[str, ...]
+    fn: Callable[[dict, dict], object]  # (payload, ctx) -> stored
+
+
+@dataclass(frozen=True)
+class _ReadtimeAlias:
+    name: str
+    fn: Callable[[object, dict], object]  # (obj, ctx) -> alias value
+    verbs: Tuple[str, ...]
+    alias_field: F
+    mask_last: int | None
+
+
+EmitPoint = Literal["pre_flush", "post_refresh", "pre_response", "readtime"]
+
+
+@dataclass(frozen=True)
+class Pair:
+    raw: object
+    stored: object
+
+
+@dataclass(frozen=True)
+class IOSpec:
+    """Control how a column participates in API input and output.
+
+    ``in_verbs`` and ``out_verbs`` enumerate which operations may accept or
+    emit the field. ``alias_in``/``alias_out`` allow different payload keys,
+    ``sensitive`` and ``redact_last`` mark values for masking, and
+    ``filter_ops``/``sortable`` flag whether the field can be used in query
+    filters or ordering. Advanced helpers like :meth:`assemble`,
+    :meth:`paired`, and :meth:`alias_readtime` derive values or expose extra
+    read-time aliases.
+    """
+
+    in_verbs: Tuple[str, ...] = ()
+    out_verbs: Tuple[str, ...] = ()
+    mutable_verbs: Tuple[str, ...] = ()
+    alias_in: str | None = None
+    alias_out: str | None = None
+    sensitive: bool = False
+    redact_last: int | None = None
+    filter_ops: Tuple[str, ...] = ()
+    sortable: bool = False
+    allow_in: Callable[[str, dict], bool] | None = None
+    allow_out: Callable[[str, dict], bool] | None = None
+    _paired: _PairedCfg | None = None
+    _assemble: _AssembleCfg | None = None
+    _readtime_aliases: Tuple[_ReadtimeAlias, ...] = ()
+
+    def assemble(self, sources, fn):
+        """Return a new spec that derives a value from ``sources`` using ``fn``."""
+        cfg = _AssembleCfg(sources=tuple(sources), fn=fn)
+        return replace(self, _assemble=cfg)
+
+    def paired(
+        self,
+        make,
+        *,
+        alias,
+        verbs=("create",),
+        emit: EmitPoint = "pre_flush",
+        alias_field: F = F(py_type=str),
+        mask_last: int | None = None,
+    ):
+        """Return a new spec with a paired field configuration."""
+
+        def gen(ctx):
+            pair = make(ctx)
+            temp = (
+                ctx.get("temp") if isinstance(ctx, dict) else getattr(ctx, "temp", None)
+            )
+            if isinstance(temp, dict):
+                temp.setdefault("_paired_cache", {})[alias] = pair.stored
+            return pair.raw
+
+        def store(raw, ctx):
+            temp = getattr(ctx, "temp", None)
+            if isinstance(temp, dict):
+                cached = temp.get("_paired_cache", {}).pop(alias, None)
+                if cached is not None:
+                    return cached
+            return make(ctx).stored
+
+        cfg = _PairedCfg(
+            gen=gen,
+            store=store,
+            alias=alias,
+            verbs=tuple(verbs),
+            emit=emit,
+            alias_field=alias_field,
+            mask_last=mask_last,
+        )
+        return replace(self, _paired=cfg)
+
+    def alias_readtime(
+        self,
+        name,
+        fn,
+        *,
+        verbs=("read", "list"),
+        alias_field: F = F(py_type=str),
+        mask_last: int | None = None,
+    ):
+        """Return a new spec with an additional read-time alias."""
+
+        alias_cfg = _ReadtimeAlias(
+            name=name,
+            fn=fn,
+            verbs=tuple(verbs),
+            alias_field=alias_field,
+            mask_last=mask_last,
+        )
+        return replace(self, _readtime_aliases=self._readtime_aliases + (alias_cfg,))

tigrbl/column/mro_collect.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from typing import Dict
+
+from .column_spec import ColumnSpec
+from .io_spec import IOSpec as IO
+from .storage_spec import StorageSpec as S
+
+logger = logging.getLogger("uvicorn")
+
+
+# Default inbound/outbound verbs for columns lacking an explicit ColumnSpec.
+#
+# Without this, plain SQLAlchemy ``Column`` definitions are omitted from the
+# collected spec map, causing downstream components to treat their values as
+# unknown.  By seeding such columns with a permissive IO spec we ensure they
+# participate in canonical CRUD operations just like columns defined via
+# ``acol``.
+_DEFAULT_IO = IO(
+    in_verbs=("create", "update", "replace"),
+    out_verbs=("read", "list"),
+    mutable_verbs=("create", "update", "replace"),
+)
+
+
+@lru_cache(maxsize=None)
+def mro_collect_columns(
+    model: type, *, _cache_bust: int | None = None
+) -> Dict[str, ColumnSpec]:
+    """Collect ColumnSpecs declared on *model* and all mixins.
+
+    Iterates across the model's MRO so that mixin-defined columns are included
+    in the resulting mapping. Later definitions take precedence over earlier
+    ones in the MRO.  Any table-backed columns lacking a spec are populated with
+    a default ColumnSpec so they participate in opviews and schema generation.
+    """
+    logger.info("Collecting columns for %s", model.__name__)
+    out: Dict[str, ColumnSpec] = {}
+    for base in reversed(model.__mro__):
+        mapping = getattr(base, "__tigrbl_colspecs__", None)
+        if isinstance(mapping, dict):
+            out.update(mapping)
+        mapping = getattr(base, "__tigrbl_cols__", None)
+        if isinstance(mapping, dict):
+            out.update(mapping)
+
+    table = getattr(model, "__table__", None)
+    if table is not None:
+        for col in table.columns:
+            name = getattr(col, "key", None) or col.name
+            out.setdefault(name, ColumnSpec(storage=S(), io=_DEFAULT_IO))
+
+    logger.info("Collected %d columns for %s", len(out), model.__name__)
+    return out
+
+
+__all__ = ["mro_collect_columns"]

tigrbl/column/shortcuts.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from ._column import Column
+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
+
+__all__ = [
+    "makeColumn",
+    "makeVirtualColumn",
+    "acol",
+    "vcol",
+    "F",
+    "IO",
+    "S",
+    "ColumnSpec",
+    "Column",
+]
+
+
+def makeColumn(
+    *,
+    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,
+    spec: ColumnSpec | None = None,
+    **kw: Any,
+) -> Column:
+    """Return a :class:`Column` descriptor for declarative models."""
+    if spec is not None:
+        if 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:
+        if read_producer is not None and storage is not None:
+            raise ValueError(
+                "read_producer is only valid for virtual (storage=None) columns."
+            )
+        spec = ColumnSpec(
+            storage=storage,
+            field=field,
+            io=io,
+            default_factory=default_factory,
+            read_producer=read_producer,
+        )
+    return Column(spec=spec, **kw)
+
+
+def makeVirtualColumn(
+    *,
+    field: F | None = None,
+    io: IO | None = None,
+    default_factory: Optional[Callable[[dict], Any]] = None,
+    producer: Optional[Callable[[object, dict], Any]] = None,
+    read_producer: Optional[Callable[[object, dict], Any]] = None,
+    spec: ColumnSpec | None = None,
+    **kw: Any,
+) -> Column:
+    """Convenience for wire-only virtual columns."""
+    if spec is not None:
+        if any(
+            x is not None for x in (field, io, default_factory, producer, read_producer)
+        ):
+            raise ValueError("Provide either spec or individual components, not both.")
+        return Column(spec=spec, **kw)
+    if producer is not None and read_producer is not None:
+        raise ValueError("Provide only one of producer= or read_producer=, not both.")
+    rp = read_producer or producer
+    return Column(
+        spec=ColumnSpec(
+            storage=None,
+            field=field,
+            io=io,
+            default_factory=default_factory,
+            read_producer=rp,
+        ),
+        **kw,
+    )
+
+
+# Convenience aliases retained for backward compatibility
+acol = makeColumn
+vcol = makeVirtualColumn

tigrbl/column/storage_spec.py

@@ -0,0 +1,65 @@
+# ---------------------------------------
+# storage_spec.py (S)
+# ---------------------------------------
+from dataclasses import KW_ONLY, dataclass
+from typing import Any, Literal, Union
+
+
+@dataclass(frozen=True)
+class StorageTransform:
+    """Functions used to transform values on the way to and from the database."""
+
+    to_stored: Union[callable, None] = (
+        None  # (python, ctx) -> python persisted (e.g., hash/encrypt/normalize)
+    )
+    from_stored: Union[callable, None] = (
+        None  # (python, ctx) -> python exposed (rare; only if you ever expose stored)
+    )
+
+
+@dataclass(frozen=True)
+class ForeignKeySpec:
+    """Lightweight description of a foreign key relationship."""
+
+    target: str  # "tenant(id)" or fully-qualified
+    on_delete: Literal["CASCADE", "RESTRICT", "SET NULL", "SET DEFAULT"] = "RESTRICT"
+    on_update: Literal["CASCADE", "RESTRICT", "SET NULL", "SET DEFAULT"] = "RESTRICT"
+    deferrable: bool = False
+    initially_deferred: bool = False
+    match: Literal["FULL", "PARTIAL", "SIMPLE"] = "SIMPLE"
+
+
+@dataclass(frozen=True)
+class StorageSpec:
+    """Describe the database-level shape and behaviour of a column.
+
+    The spec maps closely to SQLAlchemy's :class:`~sqlalchemy.Column` keyword
+    arguments: ``type_`` and flags such as ``nullable`` or ``primary_key``
+    define the table schema while ``default`` and ``onupdate`` represent ORM
+    side defaults. ``server_default`` and ``refresh_on_return`` support
+    database-generated values. Optional helpers provide value transforms,
+    foreign keys, check constraints and comments.
+    """
+
+    # SQLAlchemy column shape (DDL/runtime)
+    type_: Any | None = None
+    _: KW_ONLY
+    nullable: bool | None = None
+    unique: bool = False
+    index: bool = False
+    primary_key: bool = False
+    autoincrement: bool | None = None
+
+    # ORM-side defaults (run in SQLAlchemy) – optional if you use API defaults/paired
+    default: Any | None = None  # scalar or callable()
+    onupdate: Any | None = None
+
+    # DB-side defaults/generation (run in the database)
+    server_default: Any | None = None  # e.g., func.now(), text("...")
+    refresh_on_return: bool = False  # force refresh after flush when DB generated
+
+    # Optional storage helpers
+    transform: StorageTransform | None = None
+    fk: ForeignKeySpec | None = None
+    check: str | None = None
+    comment: str | None = None

tigrbl/config/__init__.py

@@ -0,0 +1,19 @@
+# tigrbl/v3/config/__init__.py
+"""Tigrbl v3 – configuration surface.
+
+Exports:
+    - DEFAULTS: canonical configuration defaults
+    - CfgView:  read-only config view (attr + dict access)
+    - resolve_cfg(...): precedence-based merger across apps/api/tab/cols/op/overrides
+"""
+
+from __future__ import annotations
+
+from .defaults import DEFAULTS
+from .resolver import CfgView, resolve_cfg
+
+__all__ = [
+    "DEFAULTS",
+    "CfgView",
+    "resolve_cfg",
+]