tigrbl-ops-oltp 0.1.0.dev1__tar.gz

tigrbl_ops_oltp-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: tigrbl-ops-oltp
+Version: 0.1.0.dev1
+Summary: OLTP operation implementations for Tigrbl, including CRUD and bulk handlers.
+License-Expression: Apache-2.0
+Keywords: tigrbl,sdk,standards,framework,oltp,crud
+Author: Jacob Stewart
+Author-email: jacob@swarmauri.com
+Requires-Python: >=3.10,<3.13
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Development Status :: 1 - Planning
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Dist: tigrbl-base
+Requires-Dist: tigrbl-core
+Requires-Dist: tigrbl-orm
+Description-Content-Type: text/markdown
+
+![Tigrbl branding](https://github.com/swarmauri/swarmauri-sdk/blob/a170683ecda8ca1c4f912c966d4499649ffb8224/assets/tigrbl.brand.theme.svg)
+
+# tigrbl-ops-oltp
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/tigrbl-ops-oltp.svg) ![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg) ![Python Versions](https://img.shields.io/pypi/pyversions/tigrbl-ops-oltp.svg) ![License](https://img.shields.io/pypi/l/tigrbl-ops-oltp.svg) ![Version](https://img.shields.io/pypi/v/tigrbl-ops-oltp.svg)
+
+## Features
+
+- Transactional OLTP operation implementations for Tigrbl.
+- Includes canonical CRUD and bulk operation executors.
+- Supports Python 3.10 through 3.12.
+
+## Installation
+
+### uv
+
+```bash
+uv add tigrbl-ops-oltp
+```
+
+### pip
+
+```bash
+pip install tigrbl-ops-oltp
+```
+
+## Usage
+
+Import operation callables or parameter markers from `tigrbl_ops_oltp.crud`.
+

tigrbl_ops_oltp-0.1.0.dev1/README.md

@@ -0,0 +1,29 @@
+![Tigrbl branding](https://github.com/swarmauri/swarmauri-sdk/blob/a170683ecda8ca1c4f912c966d4499649ffb8224/assets/tigrbl.brand.theme.svg)
+
+# tigrbl-ops-oltp
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/tigrbl-ops-oltp.svg) ![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg) ![Python Versions](https://img.shields.io/pypi/pyversions/tigrbl-ops-oltp.svg) ![License](https://img.shields.io/pypi/l/tigrbl-ops-oltp.svg) ![Version](https://img.shields.io/pypi/v/tigrbl-ops-oltp.svg)
+
+## Features
+
+- Transactional OLTP operation implementations for Tigrbl.
+- Includes canonical CRUD and bulk operation executors.
+- Supports Python 3.10 through 3.12.
+
+## Installation
+
+### uv
+
+```bash
+uv add tigrbl-ops-oltp
+```
+
+### pip
+
+```bash
+pip install tigrbl-ops-oltp
+```
+
+## Usage
+
+Import operation callables or parameter markers from `tigrbl_ops_oltp.crud`.

tigrbl_ops_oltp-0.1.0.dev1/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "tigrbl-ops-oltp"
+version = "0.1.0.dev1"
+description = "OLTP operation implementations for Tigrbl, including CRUD and bulk handlers."
+license = "Apache-2.0"
+readme = "README.md"
+repository = "http://github.com/swarmauri/swarmauri-sdk"
+requires-python = ">=3.10,<3.13"
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Development Status :: 1 - Planning",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
+dependencies = [
+    "tigrbl-orm",
+    "tigrbl-base",
+    "tigrbl-core",
+]
+keywords = ["tigrbl", "sdk", "standards", "framework", "oltp", "crud"]
+
+[tool.uv.sources]
+"tigrbl-orm" = { workspace = true }
+"tigrbl-base" = { workspace = true }
+"tigrbl-core" = { workspace = true }
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.poetry]
+packages = [
+    { include = "tigrbl_ops_oltp" },
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.9",
+]

tigrbl_ops_oltp-0.1.0.dev1/tigrbl_ops_oltp/__init__.py

@@ -0,0 +1,22 @@
+"""OLTP operation implementations for Tigrbl."""
+
+from .crud import (  # noqa: F401
+    Body,
+    Header,
+    Param,
+    Path,
+    Query,
+    bulk_create,
+    bulk_delete,
+    bulk_merge,
+    bulk_replace,
+    bulk_update,
+    clear,
+    create,
+    delete,
+    list,
+    merge,
+    read,
+    replace,
+    update,
+)

tigrbl_ops_oltp-0.1.0.dev1/tigrbl_ops_oltp/crud/__init__.py

@@ -0,0 +1,43 @@
+from .ops import (
+    create,
+    read,
+    update,
+    replace,
+    merge,
+    delete,
+    list as _list,
+    clear,
+)
+from .bulk import (
+    bulk_create,
+    bulk_update,
+    bulk_replace,
+    bulk_merge,
+    bulk_delete,
+)
+
+from .params import Body, Header, Param, Path, Query
+
+# Public alias named exactly `list` to preserve API surface
+list = _list  # noqa: A001 - intentional shadow of built-in for public API
+
+__all__ = [
+    "Header",
+    "Path",
+    "Query",
+    "Body",
+    "Param",
+    "create",
+    "read",
+    "update",
+    "replace",
+    "merge",
+    "delete",
+    "list",
+    "clear",
+    "bulk_create",
+    "bulk_update",
+    "bulk_replace",
+    "bulk_merge",
+    "bulk_delete",
+]

tigrbl_ops_oltp-0.1.0.dev1/tigrbl_ops_oltp/crud/bulk.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Mapping, Union
+
+import builtins as _builtins
+import logging
+
+from .helpers import (
+    AsyncSession,
+    Session,
+    sa_delete,
+    _coerce_pk_value,
+    _immutable_columns,
+    _maybe_delete,
+    _maybe_execute,
+    _maybe_flush,
+    _maybe_get,
+    _set_attrs,
+    _single_pk_name,
+    _validate_enum_values,
+)
+from .ops import merge, read
+
+logger = logging.getLogger("uvicorn")
+
+
+async def bulk_create(
+    model: type, rows: Iterable[Mapping[str, Any]], db: Union[Session, AsyncSession]
+) -> List[Any]:
+    """
+    Insert many rows. Returns the list of persisted instances.
+    Flush-only.
+    """
+    logger.debug("bulk_create called with model=%s rows=%s", model, rows)
+    items_data = [dict(r) for r in (rows or ())]
+    for r in items_data:
+        _validate_enum_values(model, r)
+    items = [model(**r) for r in items_data]
+    if not items:
+        logger.debug("bulk_create no items to create")
+        return []
+    if hasattr(db, "add_all"):
+        db.add_all(items)  # type: ignore[attr-defined]
+    else:
+        for it in items:
+            db.add(it)  # type: ignore[attr-defined]
+    await _maybe_flush(db)
+    logger.debug("bulk_create persisted %d items", len(items))
+    return items
+
+
+async def bulk_update(
+    model: type, rows: Iterable[Mapping[str, Any]], db: Union[Session, AsyncSession]
+) -> List[Any]:
+    """
+    Update many rows by PK. Each row must include the PK field.
+    Returns the list of updated instances. Flush-only.
+    """
+    logger.debug("bulk_update called with model=%s rows=%s", model, rows)
+    pk = _single_pk_name(model)
+    skip = _immutable_columns(model, "update")
+    updated: List[Any] = []
+    for r in rows or ():
+        r = dict(r)
+        _validate_enum_values(model, r)
+        ident = r.get(pk)
+        if ident is None:
+            raise ValueError(f"bulk_update requires '{pk}' in each row")
+        obj = await read(model, ident, db)
+        data = {k: v for k, v in r.items() if k != pk}
+        _set_attrs(obj, data, allow_missing=True, skip=skip)
+        updated.append(obj)
+    if updated:
+        await _maybe_flush(db)
+    logger.debug("bulk_update updated %d items", len(updated))
+    return updated
+
+
+async def bulk_replace(
+    model: type, rows: Iterable[Mapping[str, Any]], db: Union[Session, AsyncSession]
+) -> List[Any]:
+    """
+    Replace many rows by PK. Each row must include the PK field.
+    Missing attributes are nulled (except PK). Flush-only.
+    """
+    logger.debug("bulk_replace called with model=%s rows=%s", model, rows)
+    pk = _single_pk_name(model)
+    skip = _immutable_columns(model, "replace")
+    replaced: List[Any] = []
+    for r in rows or ():
+        r = dict(r)
+        _validate_enum_values(model, r)
+        ident = r.get(pk)
+        if ident is None:
+            raise ValueError(f"bulk_replace requires '{pk}' in each row")
+        obj = await read(model, ident, db)
+        data = {k: v for k, v in r.items() if k != pk}
+        _set_attrs(obj, data, allow_missing=False, skip=skip)
+        replaced.append(obj)
+    if replaced:
+        await _maybe_flush(db)
+    logger.debug("bulk_replace replaced %d items", len(replaced))
+    return replaced
+
+
+async def bulk_merge(
+    model: type, rows: Iterable[Mapping[str, Any]], db: Union[Session, AsyncSession]
+) -> List[Any]:
+    """Merge many rows by primary key with upsert semantics."""
+    logger.debug("bulk_merge called with model=%s rows=%s", model, rows)
+    pk = _single_pk_name(model)
+    results: List[Any] = []
+    to_create: List[Mapping[str, Any]] = []
+    for r in rows or ():
+        r = dict(r)
+        ident = _coerce_pk_value(model, r.get(pk))
+        if ident is not None:
+            existing = await _maybe_get(db, model, ident)
+            if existing is not None:
+                data = {k: v for k, v in r.items() if k != pk}
+                merged = await merge(model, ident, data, db=db)
+                results.append(merged)
+                continue
+            r[pk] = ident
+        to_create.append(r)
+    if to_create:
+        created = await bulk_create(model, to_create, db)
+        results.extend(created)
+    logger.debug(
+        "bulk_merge returning %d results (%d created)",
+        len(results),
+        len(to_create),
+    )
+    return results
+
+
+async def bulk_delete(
+    model: type, idents: Iterable[Any], db: Union[Session, AsyncSession]
+) -> Dict[str, int]:
+    """
+    Delete many rows by a sequence of PK values. Returns {"deleted": N}.
+    Flush-only.
+    """
+    logger.debug("bulk_delete called with model=%s idents=%s", model, idents)
+    pk_name = _single_pk_name(model)
+    id_seq = _builtins.list(idents or ())
+    if not id_seq:
+        logger.debug("bulk_delete no ids supplied")
+        return {"deleted": 0}
+
+    if sa_delete is not None:
+        col = getattr(model, pk_name)
+        stmt = sa_delete(model).where(col.in_(id_seq))  # type: ignore[attr-defined]
+        res = await _maybe_execute(db, stmt)
+        await _maybe_flush(db)
+        n = int(getattr(res, "rowcount", 0) or 0)
+        logger.debug("bulk_delete removed %d rows via stmt", n)
+        return {"deleted": n}
+
+    n = 0
+    for ident in id_seq:
+        obj = await read(model, ident, db)
+        await _maybe_delete(db, obj)
+        n += 1
+    await _maybe_flush(db)
+    logger.debug("bulk_delete removed %d rows individually", n)
+    return {"deleted": n}

tigrbl_ops_oltp-0.1.0.dev1/tigrbl_ops_oltp/crud/helpers/__init__.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+try:
+    from sqlalchemy import select, delete as sa_delete, and_, asc, desc, Enum as SAEnum
+    from sqlalchemy.orm import Session
+    from sqlalchemy.ext.asyncio import AsyncSession
+    from sqlalchemy.orm.exc import NoResultFound  # type: ignore
+except Exception:  # pragma: no cover
+    select = sa_delete = and_ = asc = desc = None  # type: ignore
+    SAEnum = None  # type: ignore
+    Session = object  # type: ignore
+    AsyncSession = object  # type: ignore
+
+    class NoResultFound(LookupError):  # type: ignore
+        pass
+
+
+from .model import (
+    _pk_columns,
+    _single_pk_name,
+    _coerce_pk_value,
+    _model_columns,
+    _colspecs,
+    _filter_in_values,
+    _immutable_columns,
+)
+from .filters import _CANON_OPS, _coerce_filters, _apply_filters, _apply_sort
+from .db import (
+    _is_async_db,
+    _maybe_get,
+    _maybe_execute,
+    _maybe_flush,
+    _maybe_delete,
+    _set_attrs,
+)
+from .enum import _validate_enum_values
+from .normalize import (
+    _normalize_list_call,
+    _pop_bound_self,
+    _extract_db,
+    _as_pos_int,
+)
+
+__all__ = [
+    "AsyncSession",
+    "Session",
+    "NoResultFound",
+    "select",
+    "sa_delete",
+    "_apply_filters",
+    "_apply_sort",
+    "_CANON_OPS",
+    "_coerce_filters",
+    "_coerce_pk_value",
+    "_colspecs",
+    "_filter_in_values",
+    "_immutable_columns",
+    "_is_async_db",
+    "_maybe_delete",
+    "_maybe_execute",
+    "_maybe_flush",
+    "_maybe_get",
+    "_model_columns",
+    "_normalize_list_call",
+    "_pop_bound_self",
+    "_extract_db",
+    "_as_pos_int",
+    "_pk_columns",
+    "_set_attrs",
+    "_single_pk_name",
+    "_validate_enum_values",
+    "SAEnum",
+    "asc",
+    "desc",
+    "and_",
+]

tigrbl_ops_oltp-0.1.0.dev1/tigrbl_ops_oltp/crud/helpers/db.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence, Union
+
+import logging
+
+from . import AsyncSession, Session
+from .model import _model_columns, _single_pk_name
+
+logger = logging.getLogger("uvicorn")
+
+
+def _is_async_db(db: Any) -> bool:
+    logger.debug("_is_async_db called with db=%s", db)
+    result = isinstance(db, AsyncSession) or hasattr(db, "run_sync")
+    logger.debug("_is_async_db returning %s", result)
+    return result
+
+
+async def _maybe_get(db: Union[Session, AsyncSession], model: type, pk_value: Any):
+    logger.debug("_maybe_get model=%s pk_value=%s", model, pk_value)
+    if _is_async_db(db):
+        result = await db.get(model, pk_value)  # type: ignore[attr-defined]
+    else:
+        result = db.get(model, pk_value)  # type: ignore[attr-defined]
+    logger.debug("_maybe_get returning %s", result)
+    return result
+
+
+async def _maybe_execute(db: Union[Session, AsyncSession], stmt: Any):
+    logger.debug("_maybe_execute stmt=%s", stmt)
+    if _is_async_db(db):
+        result = await db.execute(stmt)  # type: ignore[attr-defined]
+    else:
+        result = db.execute(stmt)  # type: ignore[attr-defined]
+    logger.debug("_maybe_execute returning %s", result)
+    return result
+
+
+async def _maybe_flush(db: Union[Session, AsyncSession]) -> None:
+    logger.debug("_maybe_flush called")
+    if _is_async_db(db):
+        await db.flush()  # type: ignore[attr-defined]
+    else:
+        db.flush()  # type: ignore[attr-defined]
+    logger.debug("_maybe_flush completed")
+
+
+async def _maybe_delete(db: Union[Session, AsyncSession], obj: Any) -> None:
+    logger.debug("_maybe_delete called with obj=%s", obj)
+    if not hasattr(db, "delete"):
+        logger.debug("_maybe_delete skipping delete; no attribute")
+        return
+    if _is_async_db(db):
+        await db.delete(obj)  # type: ignore[attr-defined]
+    else:
+        db.delete(obj)  # type: ignore[attr-defined]
+    logger.debug("_maybe_delete completed for obj=%s", obj)
+
+
+def _set_attrs(
+    obj: Any,
+    values: Mapping[str, Any],
+    *,
+    allow_missing: bool = True,
+    skip: Sequence[str] = (),
+) -> None:
+    logger.debug(
+        "_set_attrs called on obj=%s values=%s allow_missing=%s skip=%s",
+        obj,
+        values,
+        allow_missing,
+        skip,
+    )
+    cols = set(_model_columns(type(obj)))
+    pk = _single_pk_name(type(obj))
+    skip_set = set(skip) | {pk}
+
+    if allow_missing:
+        for k, v in values.items():
+            if k in cols and k not in skip_set:
+                setattr(obj, k, v)
+    else:
+        for c in cols:
+            if c in skip_set:
+                continue
+            if c in values:
+                setattr(obj, c, values[c])
+            else:
+                setattr(obj, c, None)
+    logger.debug("_set_attrs completed for obj=%s", obj)

tigrbl_ops_oltp-0.1.0.dev1/tigrbl_ops_oltp/crud/helpers/enum.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+import builtins as _builtins
+import logging
+
+from . import SAEnum
+
+logger = logging.getLogger("uvicorn")
+
+
+def _validate_enum_values(model: type, values: Mapping[str, Any]) -> None:
+    logger.debug("_validate_enum_values called with model=%s values=%s", model, values)
+    if not values or SAEnum is None:
+        logger.debug("_validate_enum_values no validation needed")
+        return
+
+    table = getattr(model, "__table__", None)
+    if table is None:
+        return
+
+    get = getattr(table.c, "get", None)
+
+    for key, v in values.items():
+        col = get(key) if get else None
+        if col is None:
+            try:
+                col = table.c[key]  # type: ignore[index]
+            except Exception:
+                col = None
+        if col is None:
+            continue
+
+        col_type = getattr(col, "type", None)
+        if col_type is None or not isinstance(col_type, SAEnum):
+            continue
+
+        if v is None:
+            continue
+
+        enum_cls = getattr(col_type, "enum_class", None)
+        if enum_cls is not None:
+            try:
+                import enum as _enum
+            except Exception:  # pragma: no cover
+                _enum = None
+
+            if _enum is not None and isinstance(v, _enum.Enum):
+                if isinstance(v, enum_cls):
+                    continue
+                logger.debug(
+                    "_validate_enum_values invalid value %s for enum %s", v, enum_cls
+                )
+                raise LookupError(
+                    f"{v!r} is not among the defined enum values. "
+                    f"Enum name: {enum_cls.__name__}. "
+                    f"Possible values: {', '.join([e.value for e in enum_cls])}"
+                )
+
+            allowed_values = [e.value for e in enum_cls]
+            allowed_names = [e.name for e in enum_cls]
+            if isinstance(v, str) and (v in allowed_values or v in allowed_names):
+                continue
+
+            logger.debug(
+                "_validate_enum_values invalid value %s for enum %s", v, enum_cls
+            )
+            raise LookupError(
+                f"{v!r} is not among the defined enum values. "
+                f"Enum name: {enum_cls.__name__}. "
+                f"Possible values: {', '.join(allowed_values)}"
+            )
+        else:
+            allowed = _builtins.list(getattr(col_type, "enums", []) or [])
+            if isinstance(v, str) and v in allowed:
+                continue
+            logger.debug(
+                "_validate_enum_values invalid value %s for enum %s", v, col_type
+            )
+            raise LookupError(
+                f"{v!r} is not among the defined enum values. "
+                f"Enum name: {getattr(col_type, 'name', 'Enum')}. "
+                f"Possible values: {', '.join(allowed) if allowed else '(none)'}"
+            )
+    logger.debug("_validate_enum_values completed")

tigrbl_ops_oltp-0.1.0.dev1/tigrbl_ops_oltp/crud/helpers/filters.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, Mapping, Optional, Sequence
+
+import logging
+
+from . import select, and_, asc, desc
+from .model import _model_columns, _colspecs
+
+logger = logging.getLogger("uvicorn")
+
+_CANON_OPS = {
+    "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",
+    "nin": "not_in",
+}
+
+
+def _coerce_filters(
+    model: type, filters: Optional[Mapping[str, Any]]
+) -> Dict[str, Any]:
+    logger.debug("_coerce_filters called with filters=%s", filters)
+    cols = set(_model_columns(model))
+    specs = _colspecs(model)
+    raw = dict(filters or {})
+    out: Dict[str, Any] = {}
+    for k, v in raw.items():
+        name, op = k.split("__", 1) if "__" in k else (k, "eq")
+        if name not in cols:
+            continue
+        canon = _CANON_OPS.get(op, op)
+        sp = specs.get(name)
+        if sp is not None:
+            io = getattr(sp, "io", None)
+            ops = set(getattr(io, "filter_ops", ()) or [])
+            ops = {_CANON_OPS.get(o, o) for o in ops}
+            if not ops or canon not in ops:
+                continue
+        key = name if canon == "eq" else f"{name}__{canon}"
+        out[key] = v
+    logger.debug("_coerce_filters returning %s", out)
+    return out
+
+
+def _apply_filters(model: type, filters: Mapping[str, Any]) -> Any:
+    logger.debug("_apply_filters called with filters=%s", filters)
+    if select is None:  # pragma: no cover
+        return None
+    clauses = []
+    for k, v in filters.items():
+        name, op = k.split("__", 1) if "__" in k else (k, "eq")
+        canon = _CANON_OPS.get(op, op)
+        col = getattr(model, name, None)
+        if col is None:
+            continue
+        if canon == "eq":
+            clauses.append(col == v)
+        elif canon == "ne":
+            clauses.append(col != v)
+        elif canon == "lt":
+            clauses.append(col < v)
+        elif canon == "gt":
+            clauses.append(col > v)
+        elif canon == "lte":
+            clauses.append(col <= v)
+        elif canon == "gte":
+            clauses.append(col >= v)
+        elif canon == "like":
+            clauses.append(col.like(v))
+        elif canon == "not_like":
+            clauses.append(~col.like(v))
+        elif canon == "ilike":
+            clauses.append(col.ilike(v))
+        elif canon == "not_ilike":
+            clauses.append(~col.ilike(v))
+        elif canon == "in":
+            seq = list(v) if isinstance(v, (list, tuple, set)) else [v]
+            clauses.append(col.in_(seq))
+        elif canon == "not_in":
+            seq = list(v) if isinstance(v, (list, tuple, set)) else [v]
+            clauses.append(~col.in_(seq))
+    if not clauses:
+        logger.debug("_apply_filters produced no clauses")
+        return None
+    result = clauses[0] if len(clauses) == 1 else and_(*clauses)
+    logger.debug("_apply_filters returning %s", result)
+    return result
+
+
+def _apply_sort(model: type, sort: Any) -> Sequence[Any] | None:
+    logger.debug("_apply_sort called with sort=%s", sort)
+    if select is None or sort is None:  # pragma: no cover
+        return None
+
+    def _tokenize(s: str) -> list[str]:
+        return [t.strip() for t in s.split(",") if t.strip()]
+
+    tokens: list[str] = []
+    if isinstance(sort, str):
+        tokens = _tokenize(sort)
+    elif isinstance(sort, Iterable):
+        for t in sort:
+            if isinstance(t, str):
+                tokens.extend(_tokenize(t))
+
+    if not tokens:
+        logger.debug("_apply_sort no tokens derived")
+        return None
+
+    specs = _colspecs(model)
+    order_by_exprs: list[Any] = []
+    for tok in tokens:
+        direction = "asc"
+        name = tok
+
+        if ":" in tok:
+            name, dirpart = tok.split(":", 1)
+            name = name.strip()
+            dirpart = dirpart.strip().lower()
+            if dirpart in ("desc", "descending"):
+                direction = "desc"
+        elif tok.startswith("-"):
+            name = tok[1:]
+            direction = "desc"
+
+        col = getattr(model, name, None)
+        if col is None:
+            continue
+        sp = specs.get(name)
+        if sp is not None:
+            io = getattr(sp, "io", None)
+            if io is not None and not getattr(io, "sortable", False):
+                continue
+        if direction == "desc":
+            order_by_exprs.append(desc(col))
+        else:
+            order_by_exprs.append(asc(col))
+
+    result = order_by_exprs or None
+    logger.debug("_apply_sort returning %s", result)
+    return result

tigrbl_ops_oltp-0.1.0.dev1/tigrbl_ops_oltp/crud/helpers/model.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import datetime as dt
+from typing import Any, Dict, Mapping, Tuple
+
+import logging
+
+try:
+    from tigrbl_canon.mapping.column_mro_collect import mro_collect_columns
+except Exception:  # pragma: no cover
+
+    def mro_collect_columns(_model: type, _cache_bust: int | None = None):
+        return {}
+
+
+logger = logging.getLogger("uvicorn")
+
+
+def _pk_columns(model: type) -> Tuple[Any, ...]:
+    logger.debug("_pk_columns called with model=%s", model)
+    table = getattr(model, "__table__", None)
+    if table is None:
+        raise ValueError(f"{model.__name__} has no __table__")
+    pks = tuple(table.primary_key.columns)  # type: ignore[attr-defined]
+    if not pks:
+        raise ValueError(f"{model.__name__} has no primary key")
+    logger.debug("_pk_columns returning %s", pks)
+    return pks
+
+
+def _single_pk_name(model: type) -> str:
+    logger.debug("_single_pk_name called with model=%s", model)
+    pks = _pk_columns(model)
+    if len(pks) != 1:
+        raise NotImplementedError(
+            f"{model.__name__} has composite PK; not supported by default core"
+        )
+    name = pks[0].name
+    logger.debug("_single_pk_name returning %s", name)
+    return name
+
+
+def _coerce_pk_value(model: type, value: Any) -> Any:
+    logger.debug("_coerce_pk_value called with model=%s value=%s", model, value)
+    if value is None:
+        return None
+    try:
+        col = _pk_columns(model)[0]
+        py_type = col.type.python_type  # type: ignore[attr-defined]
+    except Exception:  # pragma: no cover - best effort
+        logger.debug("_coerce_pk_value returning original value %s", value)
+        return value
+    if isinstance(value, py_type):
+        return value
+    try:
+        coerced = py_type(value)
+        logger.debug("_coerce_pk_value coerced %s to %s", value, coerced)
+        return coerced
+    except Exception:  # pragma: no cover - fallback to original
+        logger.debug("_coerce_pk_value failed to coerce %s", value)
+        return value
+
+
+def _model_columns(model: type) -> Tuple[str, ...]:
+    logger.debug("_model_columns called with model=%s", model)
+    table = getattr(model, "__table__", None)
+    if table is None:
+        return ()
+    cols = tuple(c.name for c in table.columns)
+    logger.debug("_model_columns returning %s", cols)
+    return cols
+
+
+def _colspecs(model: type) -> Mapping[str, Any]:
+    logger.info("_colspecs called with model=%s", model)
+    cache_bust = hash(
+        (
+            id(getattr(model, "__tigrbl_colspecs__", None)),
+            id(getattr(model, "__tigrbl_cols__", None)),
+        )
+    )
+    specs = mro_collect_columns(model, _cache_bust=cache_bust)
+    logger.info("_colspecs returning %s", specs)
+    return specs
+
+
+def _filter_in_values(
+    model: type, data: Mapping[str, Any], verb: str
+) -> Dict[str, Any]:
+    logger.info("_filter_in_values called with data=%s verb=%s", data, verb)
+    specs = _colspecs(model)
+    if not specs:
+        result = dict(data)
+        logger.debug("_filter_in_values returning %s", result)
+        return result
+    out: Dict[str, Any] = {}
+    for k, v in data.items():
+        sp = specs.get(k)
+        if sp is None:
+            out[k] = v
+            continue
+        io = getattr(sp, "io", None)
+        allowed = True
+        if io is not None:
+            in_verbs = getattr(io, "in_verbs", ())
+            mutable = getattr(io, "mutable_verbs", ())
+            if in_verbs and verb not in in_verbs:
+                allowed = False
+            if mutable and verb not in mutable:
+                allowed = False
+        if allowed:
+            try:
+                col = getattr(getattr(model, "__table__", None), "columns", {}).get(k)
+                py_t = getattr(getattr(col, "type", None), "python_type", None)
+                if py_t is not None and v is not None and not isinstance(v, py_t):
+                    if py_t in (dt.datetime, dt.date) and isinstance(v, str):
+                        parsed = py_t.fromisoformat(v)
+                        out[k] = parsed
+                    else:
+                        out[k] = py_t(v)
+                else:
+                    out[k] = v
+            except Exception:
+                # Best effort coercion only; preserve original value on failure.
+                out[k] = v
+    logger.info("_filter_in_values returning %s", out)
+    return out
+
+
+def _immutable_columns(model: type, verb: str) -> set[str]:
+    logger.info("_immutable_columns called with model=%s verb=%s", model, verb)
+    specs = _colspecs(model)
+    if not specs:
+        return set()
+    imm: set[str] = set()
+    for name, sp in specs.items():
+        io = getattr(sp, "io", None)
+        mutable = getattr(io, "mutable_verbs", ()) if io else ()
+        if mutable and verb not in mutable:
+            imm.add(name)
+    logger.info("_immutable_columns returning %s", imm)
+    return imm

tigrbl_ops_oltp-0.1.0.dev1/tigrbl_ops_oltp/crud/helpers/normalize.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional, Union
+import builtins as _builtins
+import logging
+
+from . import AsyncSession, Session
+
+logger = logging.getLogger("uvicorn")
+
+
+def _pop_bound_self(args: list[Any]) -> None:
+    logger.debug("_pop_bound_self called with args=%s", args)
+    if args and not isinstance(args[0], type):
+        args.pop(0)
+    logger.debug("_pop_bound_self result args=%s", args)
+
+
+def _extract_db(
+    args: list[Any], kwargs: dict[str, Any]
+) -> Union[Session, AsyncSession]:
+    logger.debug("_extract_db called with args=%s kwargs=%s", args, kwargs)
+    db = kwargs.pop("db", None)
+    if db is not None:
+        logger.debug("_extract_db found db in kwargs=%s", db)
+        return db
+    for i, a in enumerate(args):
+        if isinstance(a, (Session, AsyncSession)) or hasattr(a, "execute"):
+            args.pop(i)
+            logger.debug("_extract_db using positional db=%s", a)
+            return a  # type: ignore[return-value]
+    logger.debug("_extract_db failed to find db")
+    raise TypeError("db session is required")
+
+
+def _as_pos_int(x: Any) -> Optional[int]:
+    logger.debug("_as_pos_int called with x=%s", x)
+    if x is None:
+        return None
+    try:
+        v = int(x)
+        result = v if v >= 0 else 0
+        logger.debug("_as_pos_int returning %s", result)
+        return result
+    except Exception:
+        logger.debug("_as_pos_int returning None for x=%s", x)
+        return None
+
+
+def _normalize_list_call(
+    _args: tuple[Any, ...], _kwargs: dict[str, Any]
+) -> tuple[type, Dict[str, Any]]:
+    logger.debug("_normalize_list_call called with _args=%s _kwargs=%s", _args, _kwargs)
+    args = _builtins.list(_args)
+    kwargs = dict(_kwargs)
+
+    _pop_bound_self(args)
+
+    if args and isinstance(args[0], type):
+        model = args.pop(0)
+    else:
+        model = kwargs.pop("model", None)
+        if not isinstance(model, type):
+            raise TypeError("list(model, ...) requires a model class")
+
+    filters = kwargs.pop("filters", None)
+    if filters is None and args:
+        maybe = args[0]
+        if isinstance(maybe, Mapping):
+            filters = args.pop(0)
+
+    skip = _as_pos_int(kwargs.pop("skip", None))
+    limit = _as_pos_int(kwargs.pop("limit", None))
+    sort = kwargs.pop("sort", None)
+
+    if skip is None and args:
+        skip = _as_pos_int(args[0])
+        if skip is not None:
+            args.pop(0)
+    if limit is None and args:
+        limit = _as_pos_int(args[0])
+        if limit is not None:
+            args.pop(0)
+
+    db = _extract_db(args, kwargs)
+
+    if filters is None:
+        filters = {}
+
+    result = {
+        "filters": filters,
+        "skip": skip,
+        "limit": limit,
+        "db": db,
+        "sort": sort,
+    }
+    logger.debug("_normalize_list_call returning model=%s params=%s", model, result)
+    return model, result

tigrbl_ops_oltp-0.1.0.dev1/tigrbl_ops_oltp/crud/ops.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional, Union
+
+import builtins as _builtins
+import logging
+
+from sqlalchemy.orm.exc import UnmappedInstanceError
+from sqlalchemy import inspect as _sa_inspect
+from sqlalchemy.exc import NoInspectionAvailable, OperationalError
+
+from .helpers import (
+    AsyncSession,
+    Session,
+    NoResultFound,
+    select,
+    sa_delete,
+    _apply_filters,
+    _apply_sort,
+    _coerce_filters,
+    _coerce_pk_value,
+    _filter_in_values,
+    _immutable_columns,
+    _maybe_delete,
+    _maybe_execute,
+    _maybe_flush,
+    _maybe_get,
+    _normalize_list_call,
+    _set_attrs,
+    _single_pk_name,
+    _validate_enum_values,
+)
+
+logger = logging.getLogger("uvicorn")
+
+
+def _ensure_model_mapped(model: type) -> None:
+    try:
+        _sa_inspect(model)
+        return
+    except NoInspectionAvailable:
+        pass
+
+    from tigrbl_orm.orm.tables import TableBase
+    from tigrbl_base._base._table_base import _materialize_colspecs_to_sqla
+
+    _materialize_colspecs_to_sqla(model)
+    TableBase.registry.map_declaratively(model)
+
+
+def _ensure_model_table(model: type, db: Union[Session, AsyncSession]) -> None:
+    """Best-effort table creation for in-memory sqlite race conditions."""
+    table = getattr(model, "__table__", None)
+    if table is None:
+        return
+    bind = getattr(db, "bind", None)
+    if bind is None and hasattr(db, "get_bind"):
+        try:
+            bind = db.get_bind()
+        except Exception:
+            bind = None
+    if bind is None:
+        return
+    try:
+        table.create(bind=bind, checkfirst=True)
+    except Exception:
+        return
+
+
+async def create(
+    model: type, data: Mapping[str, Any], db: Union[Session, AsyncSession]
+) -> Any:
+    """
+    Insert a single row. Returns the persisted model instance.
+    Flush-only (commit happens later in END_TX).
+    """
+    logger.debug("create called with model=%s data=%s", model, data)
+    _ensure_model_mapped(model)
+    data = _filter_in_values(model, data or {}, "create")
+    _validate_enum_values(model, data)
+    obj = model(**data)
+    if hasattr(db, "add"):
+        try:
+            db.add(obj)
+        except UnmappedInstanceError:
+            # Test suites may dispose the declarative registry between app
+            # instances. Re-materialize and re-map before retrying create.
+            from tigrbl_orm.orm.tables import TableBase
+            from tigrbl_base._base._table_base import _materialize_colspecs_to_sqla
+
+            _materialize_colspecs_to_sqla(model)
+            TableBase.registry.map_declaratively(model)
+            obj = model(**data)
+            db.add(obj)
+    try:
+        await _maybe_flush(db)
+    except OperationalError as exc:
+        if "no such table" not in str(exc).lower():
+            raise
+        _ensure_model_table(model, db)
+        obj = model(**data)
+        db.add(obj)
+        await _maybe_flush(db)
+    logger.debug("create persisted obj=%s", obj)
+    return obj
+
+
+async def read(model: type, ident: Any, db: Union[Session, AsyncSession]) -> Any:
+    """
+    Load a single row by primary key. Raises NoResultFound if not found.
+    """
+    logger.debug("read called with model=%s ident=%s", model, ident)
+    _ensure_model_mapped(model)
+    obj = await _maybe_get(db, model, ident)
+    if obj is None:
+        logger.debug("read did not find model=%s ident=%s", model, ident)
+        raise NoResultFound(f"{model.__name__}({ident!r}) not found")
+    logger.debug("read returning obj=%s", obj)
+    return obj
+
+
+async def update(
+    model: type, ident: Any, data: Mapping[str, Any], db: Union[Session, AsyncSession]
+) -> Any:
+    """
+    Partial update by primary key. Missing keys are left unchanged.
+    Returns the updated model instance. Flush-only.
+    """
+    logger.debug("update called with model=%s ident=%s data=%s", model, ident, data)
+    _ensure_model_mapped(model)
+    data = _filter_in_values(model, data or {}, "update")
+    _validate_enum_values(model, data)
+    obj = await read(model, ident, db)
+    skip = _immutable_columns(model, "update")
+    _set_attrs(obj, data, allow_missing=True, skip=skip)
+    await _maybe_flush(db)
+    logger.debug("update returning obj=%s", obj)
+    return obj
+
+
+async def replace(
+    model: type, ident: Any, data: Mapping[str, Any], db: Union[Session, AsyncSession]
+) -> Any:
+    """
+    PUT semantics with upsert behaviour.
+
+    If the row exists it is replaced entirely (missing attributes are nulled).
+    If the row does not exist it is created with the provided identifier.
+    Flush-only.
+    """
+    logger.debug("replace called with model=%s ident=%s data=%s", model, ident, data)
+    _ensure_model_mapped(model)
+    data = _filter_in_values(model, data or {}, "replace")
+    _validate_enum_values(model, data)
+    pk = _single_pk_name(model)
+    obj = await _maybe_get(db, model, ident)
+    if obj is None:
+        payload = {pk: ident, **data}
+        result = await create(model, payload, db=db)
+        logger.debug("replace created obj=%s", result)
+        return result
+    skip = _immutable_columns(model, "replace")
+    _set_attrs(obj, data, allow_missing=False, skip=skip)
+    await _maybe_flush(db)
+    logger.debug("replace updated obj=%s", obj)
+    return obj
+
+
+async def merge(
+    model: type, ident: Any, data: Mapping[str, Any], db: Union[Session, AsyncSession]
+) -> Any:
+    """PATCH semantics with upsert behaviour."""
+    logger.debug("merge called with model=%s ident=%s data=%s", model, ident, data)
+    _ensure_model_mapped(model)
+    pk = _single_pk_name(model)
+    ident = _coerce_pk_value(model, ident)
+    obj = await _maybe_get(db, model, ident)
+
+    verb = "update" if obj is not None else "create"
+    data = _filter_in_values(model, data or {}, verb)
+    _validate_enum_values(model, data)
+    data_no_pk = {k: v for k, v in data.items() if k != pk}
+    if obj is None:
+        payload = {pk: ident, **data_no_pk}
+        result = await create(model, payload, db=db)
+        logger.debug("merge created obj=%s", result)
+        return result
+    skip = _immutable_columns(model, "update")
+    _set_attrs(obj, data_no_pk, allow_missing=True, skip=skip)
+    await _maybe_flush(db)
+    logger.debug("merge updated obj=%s", obj)
+    return obj
+
+
+async def delete(
+    model: type, ident: Any, db: Union[Session, AsyncSession]
+) -> Dict[str, int]:
+    """
+    Delete by primary key. Returns {"deleted": 1} if removed, else raises NoResultFound.
+    Flush-only.
+    """
+    logger.debug("delete called with model=%s ident=%s", model, ident)
+    _ensure_model_mapped(model)
+    obj = await read(model, ident, db)
+    await _maybe_delete(db, obj)
+    await _maybe_flush(db)
+    logger.debug("delete removed obj=%s", obj)
+    return {"deleted": 1}
+
+
+# NOTE: tolerant signature: accepts positional/keyword and ignores stray args
+async def list(*_args: Any, **_kwargs: Any) -> List[Any]:  # noqa: A001  (shadow built-in)
+    """
+    Simple list with equality filters + skip/limit (+ optional sort).
+    Tolerant to:
+      - missing filters (defaults to {})
+      - accidental bound-method 'self' (first positional arg)
+      - positional or keyword args
+      - stray extras (e.g., request) which are ignored
+    """
+    logger.debug("list called with args=%s kwargs=%s", _args, _kwargs)
+    model, params = _normalize_list_call(_args, _kwargs)
+    _ensure_model_mapped(model)
+
+    filters: Mapping[str, Any] = _coerce_filters(model, params["filters"])
+    skip: Optional[int] = params["skip"]
+    limit: Optional[int] = params["limit"]
+    db: Union[Session, AsyncSession] = params["db"]
+    sort = params["sort"]
+
+    if select is None:  # pragma: no cover
+        # Fallback: legacy query API
+        q = db.query(model)  # type: ignore[attr-defined]
+        if filters:
+            q = q.filter_by(**filters)  # type: ignore[attr-defined]
+        if isinstance(skip, int):
+            q = q.offset(max(skip, 0))  # type: ignore[attr-defined]
+        if isinstance(limit, int) and limit is not None:
+            q = q.limit(max(limit, 0))  # type: ignore[attr-defined]
+        return _builtins.list(q.all())  # type: ignore[attr-defined]
+
+    where = _apply_filters(model, filters)
+    stmt = select(model)
+    if where is not None:
+        stmt = stmt.where(where)
+
+    order_exprs = _apply_sort(model, sort)
+    if order_exprs:
+        for ob in order_exprs:
+            stmt = stmt.order_by(ob)
+
+    if isinstance(skip, int):
+        stmt = stmt.offset(max(skip, 0))
+    if isinstance(limit, int) and limit is not None:
+        stmt = stmt.limit(max(limit, 0))
+
+    result = await _maybe_execute(db, stmt)
+    items = _builtins.list(result.scalars().all())  # type: ignore[attr-defined]
+    logger.debug("list returning %d items", len(items))
+    return items
+
+
+async def clear(
+    *args: Any,
+    **kwargs: Any,
+) -> Dict[str, int]:
+    """
+    Delete many rows matching equality filters. Returns {"deleted": N}.
+    Flush-only. Tolerant to the same calling variations as `list`.
+    """
+    # Reuse normalizer to accept the same shapes
+    logger.debug("clear called with args=%s kwargs=%s", args, kwargs)
+    model, params = _normalize_list_call(args, kwargs)
+    _ensure_model_mapped(model)
+    raw_filters: Mapping[str, Any] = params["filters"]
+    db: Union[Session, AsyncSession] = params["db"]
+
+    if sa_delete is None:  # pragma: no cover
+        # Fallback path: manual iteration
+        items = await list(model, raw_filters, db=db)
+        n = 0
+        for obj in items:
+            await _maybe_delete(db, obj)
+            n += 1
+        await _maybe_flush(db)
+        return {"deleted": n}
+
+    filt = _coerce_filters(model, raw_filters)
+    where = _apply_filters(model, filt)
+    stmt = sa_delete(model)
+    if where is not None:
+        stmt = stmt.where(where)
+
+    res = await _maybe_execute(db, stmt)
+    await _maybe_flush(db)
+    n = int(getattr(res, "rowcount", 0) or 0)
+    logger.debug("clear removed %d rows", n)
+    return {"deleted": n}

tigrbl_ops_oltp-0.1.0.dev1/tigrbl_ops_oltp/crud/params.py

@@ -0,0 +1,50 @@
+"""Parameter marker helpers for std dependency resolution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class Param:
+    default: Any = None
+    alias: str | None = None
+    required: bool = False
+    location: str = "query"
+
+
+def Body(default: Any = None, **kwargs: Any) -> Param:
+    return Param(
+        default=default,
+        alias=kwargs.get("alias"),
+        required=default is ...,
+        location="body",
+    )
+
+
+def Query(default: Any = None, **kwargs: Any) -> Param:
+    return Param(
+        default=default,
+        alias=kwargs.get("alias"),
+        required=default is ...,
+        location="query",
+    )
+
+
+def Path(default: Any = None, **kwargs: Any) -> Param:
+    return Param(
+        default=default,
+        alias=kwargs.get("alias"),
+        required=default is ...,
+        location="path",
+    )
+
+
+def Header(default: Any = None, **kwargs: Any) -> Param:
+    return Param(
+        default=default,
+        alias=kwargs.get("alias"),
+        required=default is ...,
+        location="header",
+    )