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

tigrbl/bindings/handlers/builder.py

@@ -0,0 +1,119 @@
+# tigrbl/v3/bindings/handlers/builder.py
+from __future__ import annotations
+
+import logging
+from typing import Optional, Sequence, Tuple
+
+from ...op import OpSpec
+from ...op.types import StepFn
+from .namespaces import _ensure_alias_handlers_ns, _ensure_alias_hooks_ns
+from .steps import _wrap_core, _wrap_custom
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/handlers/builder")
+
+_Key = Tuple[str, str]
+
+
+def _attach_one(model: type, sp: OpSpec) -> None:
+    alias = sp.alias
+    handlers_ns = _ensure_alias_handlers_ns(model, alias)
+    hooks_ns = _ensure_alias_hooks_ns(model, alias)
+    chain: list[StepFn] = getattr(hooks_ns, "HANDLER")
+
+    custom_step = _wrap_custom(model, sp, sp.handler) if sp.handler else None
+    core_step: Optional[StepFn] = (
+        None if sp.target == "custom" else _wrap_core(model, sp.target)
+    )
+
+    placement = sp.persist
+    raw_step: Optional[StepFn] = None
+
+    logger.debug(
+        "Attaching handler for %s.%s target=%s placement=%s",
+        model.__name__,
+        alias,
+        sp.target,
+        placement,
+    )
+
+    if placement == "skip":
+        logger.debug("Placement 'skip' selected")
+        if custom_step is not None:
+            logger.debug("Appending custom step for alias %s", alias)
+            chain.append(custom_step)
+            raw_step = custom_step
+    elif sp.target == "custom":
+        logger.debug("Target 'custom' with alias %s", alias)
+        if custom_step is not None:
+            logger.debug("Appending custom step for alias %s", alias)
+            chain.append(custom_step)
+            raw_step = custom_step
+    elif custom_step is not None and core_step is not None:
+        logger.debug("Both custom and core steps present")
+        if placement == "append":
+            logger.debug("Appending core then custom step")
+            chain.extend([core_step, custom_step])
+            raw_step = core_step
+        elif placement == "override":
+            logger.debug("Overriding core step with custom step")
+            chain.append(custom_step)
+            raw_step = custom_step
+            core_step = None
+        else:
+            logger.debug("Prepending custom then core step")
+            chain.extend([custom_step, core_step])
+            raw_step = core_step
+    elif core_step is not None:
+        logger.debug("Only core step present; appending")
+        chain.append(core_step)
+        raw_step = core_step
+    elif custom_step is not None:
+        logger.debug("Only custom step present; appending")
+        chain.append(custom_step)
+        raw_step = custom_step
+
+    if raw_step is None:
+        logger.debug("No raw step produced; exiting")
+        return
+
+    setattr(handlers_ns, "raw", raw_step)
+    setattr(handlers_ns, "handler", raw_step)
+
+    if core_step is not None:
+        object.__setattr__(sp, "core", core_step)
+        object.__setattr__(sp, "core_raw", core_step)
+        setattr(handlers_ns, "core", core_step)
+        setattr(handlers_ns, "core_raw", core_step)
+        logger.debug("Core step registered for %s.%s", model.__name__, alias)
+    else:
+        object.__setattr__(sp, "core", raw_step)
+        object.__setattr__(sp, "core_raw", raw_step)
+        setattr(handlers_ns, "core", raw_step)
+        setattr(handlers_ns, "core_raw", raw_step)
+        logger.debug("Raw step registered as core for %s.%s", model.__name__, alias)
+
+    logger.debug(
+        "handlers: %s.%s → handler chain updated (persist=%s)",
+        model.__name__,
+        alias,
+        sp.persist,
+    )
+
+
+def build_and_attach(
+    model: type, specs: Sequence[OpSpec], *, only_keys: Optional[Sequence[_Key]] = None
+) -> None:
+    wanted = set(only_keys or ())
+    logger.debug("Building handlers for %s (only_keys=%s)", model.__name__, wanted)
+    for sp in specs:
+        key = (sp.alias, sp.target)
+        if wanted and key not in wanted:
+            logger.debug("Skipping spec %s due to only_keys filter", key)
+            continue
+        logger.debug("Processing spec %s", key)
+        _attach_one(model, sp)
+
+
+__all__ = ["build_and_attach"]

tigrbl/bindings/handlers/ctx.py

@@ -0,0 +1,74 @@
+# tigrbl/v3/bindings/handlers/ctx.py
+from __future__ import annotations
+import logging
+
+from typing import Any, Mapping, Sequence
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/handlers/ctx")
+
+
+def _ctx_get(ctx: Mapping[str, Any], key: str, default: Any = None) -> Any:
+    logger.debug("_ctx_get retrieving key '%s'", key)
+    try:
+        value = ctx[key]
+        logger.debug("Key '%s' found via mapping access", key)
+        return value
+    except Exception:
+        logger.debug("Key '%s' not found; using getattr fallback", key)
+        return getattr(ctx, key, default)
+
+
+def _ctx_payload(ctx: Mapping[str, Any]) -> Any:
+    temp = _ctx_get(ctx, "temp", None)
+    raw = _ctx_get(ctx, "payload", None)
+    if isinstance(temp, Mapping):
+        av = temp.get("assembled_values")
+        if isinstance(av, Mapping) and isinstance(raw, Mapping):
+            merged = dict(raw)
+            merged.update(av)
+            logger.debug("Payload from assembled values: %s", merged)
+            return merged
+
+    v = raw
+    if isinstance(v, Mapping):
+        logger.debug("Payload is a mapping")
+        logger.debug("Payload: %s", v)
+        return v
+    if isinstance(v, Sequence) and not isinstance(v, (str, bytes)):
+        logger.debug("Payload is a non-string sequence")
+        logger.debug("Payload: %s", v)
+        return v
+    logger.debug("Payload absent or unsupported; defaulting to empty dict")
+    v = {}
+    logger.debug("Payload: %s", v)
+    return v
+
+
+def _ctx_db(ctx: Mapping[str, Any]) -> Any:
+    logger.debug("Retrieving 'db' from context")
+    return _ctx_get(ctx, "db")
+
+
+def _ctx_request(ctx: Mapping[str, Any]) -> Any:
+    logger.debug("Retrieving 'request' from context")
+    return _ctx_get(ctx, "request")
+
+
+def _ctx_path_params(ctx: Mapping[str, Any]) -> Mapping[str, Any]:
+    v = _ctx_get(ctx, "path_params", None)
+    if isinstance(v, Mapping):
+        logger.debug("Path params found: %s", list(v.keys()))
+        return v
+    logger.debug("No path params found; returning empty mapping")
+    return {}
+
+
+__all__ = [
+    "_ctx_get",
+    "_ctx_payload",
+    "_ctx_db",
+    "_ctx_request",
+    "_ctx_path_params",
+]

tigrbl/bindings/handlers/identifiers.py

@@ -0,0 +1,228 @@
+# tigrbl/v3/bindings/handlers/identifiers.py
+from __future__ import annotations
+import logging
+
+import uuid
+from typing import Any, Mapping, Optional
+
+from .ctx import _ctx_payload, _ctx_path_params
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/handlers/identifiers")
+
+try:  # pragma: no cover
+    from sqlalchemy.inspection import inspect as _sa_inspect  # type: ignore
+except Exception:  # pragma: no cover
+    _sa_inspect = None  # type: ignore
+try:  # pragma: no cover
+    from sqlalchemy.sql import ClauseElement as SAClause  # type: ignore
+except Exception:  # pragma: no cover
+    SAClause = None  # type: ignore
+
+
+def _pk_name(model: type) -> str:
+    """Best-effort primary-key column name."""
+    logger.debug("Resolving PK name for %s", model.__name__)
+    if _sa_inspect is not None:
+        try:
+            mapper = _sa_inspect(model)
+            pk_cols = list(getattr(mapper, "primary_key", []) or [])
+            logger.debug("SQLAlchemy mapper found %d PK cols", len(pk_cols))
+            if len(pk_cols) == 1:
+                col = pk_cols[0]
+                name = getattr(col, "key", None) or getattr(col, "name", None)
+                logger.debug("PK name via mapper: %s", name)
+                if isinstance(name, str) and name:
+                    return name
+        except Exception as exc:
+            logger.debug("SQLAlchemy inspection failed: %s", exc)
+
+    table = getattr(model, "__table__", None)
+    if table is not None:
+        try:
+            pk = getattr(table, "primary_key", None)
+            cols_iter = getattr(pk, "columns", None)
+            cols = [c for c in cols_iter] if cols_iter is not None else []
+            logger.debug("Table inspection found %d PK cols", len(cols))
+            if len(cols) == 1:
+                col = cols[0]
+                name = getattr(col, "key", None) or getattr(col, "name", None)
+                logger.debug("PK name via table: %s", name)
+                if isinstance(name, str) and name:
+                    return name
+        except Exception as exc:
+            logger.debug("Table inspection failed: %s", exc)
+
+    logger.debug("Falling back to default PK name 'id'")
+    return "id"
+
+
+def _pk_type_info(model: type) -> tuple[Optional[type], Optional[Any]]:
+    """Return (python_type, sqlatype_instance) for the PK column if discoverable."""
+    logger.debug("Resolving PK type info for %s", model.__name__)
+    col = None
+    if _sa_inspect is not None:
+        try:
+            mapper = _sa_inspect(model)
+            pk_cols = list(getattr(mapper, "primary_key", []) or [])
+            logger.debug("Mapper returned %d PK cols", len(pk_cols))
+            if len(pk_cols) == 1:
+                col = pk_cols[0]
+        except Exception as exc:
+            logger.debug("Mapper inspection failed: %s", exc)
+            col = None
+
+    if col is None:
+        table = getattr(model, "__table__", None)
+        if table is not None:
+            try:
+                pk = getattr(table, "primary_key", None)
+                cols_iter = getattr(pk, "columns", None)
+                cols = [c for c in cols_iter] if cols_iter is not None else []
+                logger.debug("Table inspection yielded %d PK cols", len(cols))
+                if len(cols) == 1:
+                    col = cols[0]
+            except Exception as exc:
+                logger.debug("Table inspection failed: %s", exc)
+                col = None
+
+    if col is None:
+        logger.debug("PK column not found; returning (None, None)")
+        return (None, None)
+
+    try:
+        coltype = getattr(col, "type", None)
+    except Exception as exc:
+        logger.debug("Failed to get column type: %s", exc)
+        coltype = None
+
+    py_t = None
+    try:
+        py_t = getattr(coltype, "python_type", None)
+    except Exception as exc:
+        logger.debug("Failed to get python_type: %s", exc)
+        py_t = None
+
+    logger.debug("Resolved PK type info py_t=%s sa_type=%s", py_t, coltype)
+    return (py_t, coltype)
+
+
+def _looks_like_uuid_string(s: str) -> bool:
+    if not isinstance(s, str):
+        logger.debug("Value %r is not a string; cannot be UUID", s)
+        return False
+    try:
+        uuid.UUID(s)
+        logger.debug("Value %s looks like a UUID string", s)
+        return True
+    except Exception:
+        logger.debug("Value %s is not a valid UUID string", s)
+        return False
+
+
+def _is_uuid_type(py_t: Optional[type], sa_type: Optional[Any]) -> bool:
+    if py_t is uuid.UUID:
+        logger.debug("PK python type is UUID")
+        return True
+    try:
+        if getattr(sa_type, "as_uuid", False):
+            logger.debug("SQLAlchemy type %r uses as_uuid", sa_type)
+            return True
+    except Exception:
+        pass
+    try:
+        tname = type(sa_type).__name__.lower() if sa_type is not None else ""
+        if "uuid" in tname:
+            logger.debug("SQLAlchemy type name contains 'uuid': %s", tname)
+            return True
+    except Exception:
+        pass
+    return False
+
+
+def _coerce_ident_to_pk_type(model: type, value: Any) -> Any:
+    py_t, sa_t = _pk_type_info(model)
+    logger.debug("Coercing identifier %r to PK type %s", value, py_t)
+    if SAClause is not None and isinstance(value, SAClause):  # pragma: no cover
+        logger.debug("Value is SAClause; returning as-is")
+        return value
+    if _is_uuid_type(py_t, sa_t):
+        logger.debug("PK type identified as UUID")
+        if isinstance(value, uuid.UUID):
+            return value
+        if isinstance(value, str):
+            return uuid.UUID(value)
+        if isinstance(value, (bytes, bytearray)) and len(value) == 16:
+            return uuid.UUID(bytes=bytes(value))
+        if _looks_like_uuid_string(str(value)):
+            return uuid.UUID(str(value))
+        return value
+    if py_t is int:
+        logger.debug("PK type identified as int")
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str):
+            return int(value)
+        try:
+            return int(value)  # type: ignore[arg-type]
+        except Exception as exc:
+            logger.debug("Failed int coercion: %s", exc)
+            return value
+    return value
+
+
+def _is_clause(x: Any) -> bool:
+    return SAClause is not None and isinstance(x, SAClause)  # type: ignore[truthy-bool]
+
+
+def _resolve_ident(model: type, ctx: Mapping[str, Any]) -> Any:
+    payload = _ctx_payload(ctx)
+    path = _ctx_path_params(ctx)
+    pk = _pk_name(model)
+    logger.debug("Resolving identifier for %s using pk %s", model.__name__, pk)
+
+    candidates_keys = [
+        (path, pk),
+        (payload, pk),
+        (path, "id"),
+        (payload, "id"),
+        (path, "item_id"),
+        (payload, "item_id"),
+    ]
+    if pk != "id":
+        candidates_keys.extend(
+            [
+                (path, f"{pk}_id"),
+                (payload, f"{pk}_id"),
+            ]
+        )
+    candidates_keys.append((payload, "ident"))
+
+    for source, key in candidates_keys:
+        try:
+            v = source.get(key)  # type: ignore[call-arg]
+        except Exception:
+            v = None
+        logger.debug("Checking candidate key '%s' → %r", key, v)
+        if v is None:
+            continue
+        if _is_clause(v):
+            logger.debug("Value for key '%s' is a clause; skipping", key)
+            continue
+        try:
+            return _coerce_ident_to_pk_type(model, v)
+        except Exception:
+            logger.debug("Invalid identifier %r for pk %s", v, pk)
+            raise TypeError(f"Invalid identifier for '{pk}': {v!r}")
+
+    logger.debug("Identifier for pk %s not found", pk)
+    raise TypeError(f"Missing identifier '{pk}' in path or payload")
+
+
+__all__ = [
+    "_pk_name",
+    "_pk_type_info",
+    "_resolve_ident",
+    "_coerce_ident_to_pk_type",
+]

tigrbl/bindings/handlers/namespaces.py

@@ -0,0 +1,51 @@
+# tigrbl/v3/bindings/handlers/namespaces.py
+from __future__ import annotations
+import logging
+
+from types import SimpleNamespace
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/handlers/namespaces")
+
+
+def _ensure_alias_hooks_ns(model: type, alias: str) -> SimpleNamespace:
+    hooks_root = getattr(model, "hooks", None)
+    if hooks_root is None:
+        logger.debug("Creating hooks namespace for %s", model.__name__)
+        hooks_root = SimpleNamespace()
+        setattr(model, "hooks", hooks_root)
+
+    ns = getattr(hooks_root, alias, None)
+    if ns is None:
+        logger.debug("Creating hooks alias namespace '%s'", alias)
+        ns = SimpleNamespace()
+        setattr(hooks_root, alias, ns)
+
+    if not hasattr(ns, "HANDLER"):
+        logger.debug("Initializing HANDLER list for hooks '%s'", alias)
+        setattr(ns, "HANDLER", [])
+    return ns
+
+
+def _ensure_alias_handlers_ns(model: type, alias: str) -> SimpleNamespace:
+    handlers_root = getattr(model, "handlers", None)
+    if handlers_root is None:
+        logger.debug("Creating handlers namespace for %s", model.__name__)
+        handlers_root = SimpleNamespace()
+        setattr(model, "handlers", handlers_root)
+
+    ns = getattr(handlers_root, alias, None)
+    if ns is None:
+        logger.debug("Creating handlers alias namespace '%s'", alias)
+        ns = SimpleNamespace()
+        setattr(handlers_root, alias, ns)
+
+    hooks_ns = _ensure_alias_hooks_ns(model, alias)
+    if not hasattr(ns, "HANDLER"):
+        logger.debug("Linking HANDLER list from hooks namespace for '%s'", alias)
+        setattr(ns, "HANDLER", getattr(hooks_ns, "HANDLER"))
+    return ns
+
+
+__all__ = ["_ensure_alias_hooks_ns", "_ensure_alias_handlers_ns"]