tigrbl-ops-oltp 0.1.0__tar.gz

tigrbl_ops_oltp-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: tigrbl-ops-oltp
+Version: 0.1.0
+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/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/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "tigrbl-ops-oltp"
+version = "0.1.0"
+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/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/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/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/tigrbl_ops_oltp/crud/helpers/__init__.py

@@ -0,0 +1,78 @@
+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_rollback,
+    _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_rollback",
+    "_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/tigrbl_ops_oltp/crud/helpers/db.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import inspect
+from functools import lru_cache
+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")
+
+
+@lru_cache(maxsize=512)
+def _is_async_db_type(db_type: type[Any]) -> bool:
+    return db_type.__name__ == "AsyncSession" or hasattr(db_type, "run_sync")
+
+
+def _is_async_db(db: Any) -> bool:
+    logger.debug("_is_async_db called with db=%s", db)
+    result = _is_async_db_type(type(db))
+    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)
+    result = db.get(model, pk_value)  # type: ignore[attr-defined]
+    if inspect.isawaitable(result):
+        result = await result
+    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)
+    result = db.execute(stmt)  # type: ignore[attr-defined]
+    if inspect.isawaitable(result):
+        result = await result
+    logger.debug("_maybe_execute returning %s", result)
+    return result
+
+
+async def _maybe_flush(db: Union[Session, AsyncSession]) -> None:
+    logger.debug("_maybe_flush called")
+    result = db.flush()  # type: ignore[attr-defined]
+    if inspect.isawaitable(result):
+        await result
+    logger.debug("_maybe_flush completed")
+
+
+async def _maybe_rollback(db: Union[Session, AsyncSession]) -> None:
+    logger.debug("_maybe_rollback called")
+    if not hasattr(db, "rollback"):
+        logger.debug("_maybe_rollback skipping rollback; no attribute")
+        return
+    result = db.rollback()  # type: ignore[attr-defined]
+    if inspect.isawaitable(result):
+        await result
+    logger.debug("_maybe_rollback 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
+    result = db.delete(obj)  # type: ignore[attr-defined]
+    if inspect.isawaitable(result):
+        await result
+    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/tigrbl_ops_oltp/crud/helpers/enum.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import enum as _enum
+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:
+            if 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")