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

tigrbl/config/constants.py

@@ -0,0 +1,224 @@
+# tigrbl/v3/config/constants.py
+"""
+Tigrbl v3 – Configuration constants
+
+Centralizes “well-known” names and defaults used across v3. These are
+pure-Python constants; there is no runtime coupling to any web framework.
+
+Highlights
+----------
+• Verbs/targets are *derived* from the v3 OpSpec canon so they always stay in sync.
+• Default HTTP method mapping for REST bindings lives here (used by bindings.rest).
+• Model config keys document the names we look for on SQLAlchemy classes.
+
+Nothing in this module performs I/O.
+"""
+
+from __future__ import annotations
+
+from typing import Mapping, Tuple
+import re
+
+# NOTE: importing CANON from ``ops.types`` introduces a circular dependency
+# because that module transitively imports this one via ``hook``. To keep the
+# constant values in sync without triggering the circular import at import time,
+# we inline the canonical verb tuple here. This tuple **must** match
+# ``tigrbl.op.types.CANON``.
+CANON: Tuple[str, ...] = (
+    "create",
+    "read",
+    "update",
+    "replace",
+    "merge",
+    "delete",
+    "list",
+    "clear",
+    "bulk_create",
+    "bulk_update",
+    "bulk_replace",
+    "bulk_merge",
+    "bulk_delete",
+    "custom",
+)
+
+
+# ───────────────────────────────────────────────────────────────────────────────
+# Verbs / targets
+# ───────────────────────────────────────────────────────────────────────────────
+
+# Source of truth: `CANON` keys (strings like "create", "read", "bulk_update", ...)
+ALL_VERBS: frozenset[str] = frozenset(
+    str(k) for k in (CANON.keys() if hasattr(CANON, "keys") else CANON)
+)  # type: ignore[arg-type]
+
+# Bulk targets are those prefixed with "bulk_"
+BULK_VERBS: frozenset[str] = frozenset(v for v in ALL_VERBS if v.startswith("bulk_"))
+
+# Routable canonical (non-bulk) verbs; excludes the synthetic "custom"
+ROUTING_VERBS: frozenset[str] = frozenset(
+    v for v in ALL_VERBS if not v.startswith("bulk_") and v != "custom"
+)
+
+
+# ───────────────────────────────────────────────────────────────────────────────
+# Default HTTP methods per target (bindings.rest uses this unless overridden)
+# ───────────────────────────────────────────────────────────────────────────────
+
+DEFAULT_HTTP_METHODS: Mapping[str, Tuple[str, ...]] = {
+    "create": ("POST",),
+    "read": ("GET",),
+    "update": ("PATCH",),
+    "replace": ("PUT",),
+    "merge": ("PATCH",),
+    "delete": ("DELETE",),
+    "list": ("GET",),
+    "clear": ("DELETE",),
+    "bulk_create": ("POST",),
+    "bulk_update": ("PATCH",),
+    "bulk_replace": ("PUT",),
+    "bulk_merge": ("PATCH",),
+    "bulk_delete": ("DELETE",),
+    "custom": ("POST",),
+}
+
+
+# ───────────────────────────────────────────────────────────────────────────────
+# Model-level configuration attributes (looked up on the SQLAlchemy class)
+# ───────────────────────────────────────────────────────────────────────────────
+
+# Well-known attribute names injected or inspected on ORM models
+TIGRBL_REQUEST_EXTRAS_ATTR = (
+    "__tigrbl_request_extras__"  # request-only virtual fields per verb
+)
+TIGRBL_RESPONSE_EXTRAS_ATTR = (
+    "__tigrbl_response_extras__"  # response-only virtual fields per verb
+)
+TIGRBL_OPS_ATTR = "__tigrbl_ops__"  # declarative OpSpec list from decorators
+TIGRBL_VERB_ALIASES_ATTR = "__tigrbl_verb_aliases__"  # optional verb alias map
+TIGRBL_VERB_ALIAS_POLICY_ATTR = "__tigrbl_verb_alias_policy__"  # alias policy override
+TIGRBL_NESTED_PATHS_ATTR = "__tigrbl_nested_paths__"  # nested path callback (optional)
+TIGRBL_API_HOOKS_ATTR = "__tigrbl_api_hooks__"  # API-level hooks map
+TIGRBL_HOOKS_ATTR = "__tigrbl_hooks__"  # model-level hooks map
+TIGRBL_REGISTRY_LISTENER_ATTR = "__tigrbl_registry_listener__"  # ops registry listener
+TIGRBL_GET_DB_ATTR = "__tigrbl_get_db__"  # DB dependency
+TIGRBL_AUTH_DEP_ATTR = "__tigrbl_auth_dep__"  # auth dependency
+TIGRBL_AUTHORIZE_ATTR = "__tigrbl_authorize__"  # authorization callable
+TIGRBL_REST_DEPENDENCIES_ATTR = "__tigrbl_rest_dependencies__"  # extra REST deps
+TIGRBL_RPC_DEPENDENCIES_ATTR = "__tigrbl_rpc_dependencies__"  # extra RPC deps
+TIGRBL_OWNER_POLICY_ATTR = "__tigrbl_owner_policy__"  # ownership policy override
+TIGRBL_TENANT_POLICY_ATTR = "__tigrbl_tenant_policy__"  # tenancy policy override
+TIGRBL_ALLOW_ANON_ATTR = "__tigrbl_allow_anon__"  # verbs callable without auth
+TIGRBL_DEFAULTS_MODE_ATTR = "__tigrbl_defaults_mode__"  # canonical verb wiring policy
+TIGRBL_DEFAULTS_INCLUDE_ATTR = "__tigrbl_defaults_include__"  # verbs to force include
+TIGRBL_DEFAULTS_EXCLUDE_ATTR = "__tigrbl_defaults_exclude__"  # verbs to force exclude
+TIGRBL_SCHEMA_DECLS_ATTR = "__tigrbl_schema_decls__"  # declared schemas map
+
+# Aggregate of recognized model-level config attributes
+MODEL_LEVEL_CFGS: frozenset[str] = frozenset(
+    {
+        TIGRBL_REQUEST_EXTRAS_ATTR,
+        TIGRBL_RESPONSE_EXTRAS_ATTR,
+        TIGRBL_OPS_ATTR,
+        TIGRBL_VERB_ALIASES_ATTR,
+        TIGRBL_VERB_ALIAS_POLICY_ATTR,
+        TIGRBL_NESTED_PATHS_ATTR,
+        TIGRBL_API_HOOKS_ATTR,
+        TIGRBL_HOOKS_ATTR,
+        TIGRBL_REGISTRY_LISTENER_ATTR,
+        TIGRBL_GET_DB_ATTR,
+        TIGRBL_AUTH_DEP_ATTR,
+        TIGRBL_AUTHORIZE_ATTR,
+        TIGRBL_REST_DEPENDENCIES_ATTR,
+        TIGRBL_RPC_DEPENDENCIES_ATTR,
+        TIGRBL_OWNER_POLICY_ATTR,
+        TIGRBL_TENANT_POLICY_ATTR,
+        TIGRBL_ALLOW_ANON_ATTR,
+        TIGRBL_DEFAULTS_MODE_ATTR,
+        TIGRBL_DEFAULTS_INCLUDE_ATTR,
+        TIGRBL_DEFAULTS_EXCLUDE_ATTR,
+        TIGRBL_SCHEMA_DECLS_ATTR,
+        "__resource__",  # resource name override for REST
+    }
+)
+
+# Other internal attribute names
+TIGRBL_CUSTOM_OP_ATTR = "__tigrbl_custom_op__"  # marker for custom op
+HOOK_DECLS_ATTR = "__tigrbl_hook_decls__"  # per-function hook declarations
+
+# ───────────────────────────────────────────────────────────────────────────────
+# ‼ Everything is natively transactional now
+# ‼ We will not support transactionals as a custom type or obj moving forward.
+# ‼ Support is not guaranteed.
+# ───────────────────────────────────────────────────────────────────────────────
+TIGRBL_TX_MODELS_ATTR = "__tigrbl_tx_models__"  # transactional model cache
+
+
+# ───────────────────────────────────────────────────────────────────────────────
+# Common context keys used throughout runtime/bindings (non-normative)
+# ───────────────────────────────────────────────────────────────────────────────
+
+# These string constants are *conventional* keys you may put into ctx, not
+# enforced by Tigrbl. They’re listed here for discoverability.
+CTX_REQUEST_KEY = "request"
+CTX_DB_KEY = "db"
+CTX_PAYLOAD_KEY = "payload"
+CTX_PATH_PARAMS_KEY = "path_params"
+CTX_ENV_KEY = "env"
+CTX_RPC_ID_KEY = "rpc_id"  # used by the JSON-RPC dispatcher
+CTX_SKIP_PERSIST_FLAG = "__tigrbl_skip_persist__"  # set by ephemeral ops
+
+# Optional auth/multitenancy keys that middlewares may populate for hooks to read
+CTX_USER_ID_KEY = "user_id"
+CTX_TENANT_ID_KEY = "tenant_id"
+CTX_AUTH_KEY = "auth"
+
+# Request.state attribute that carries auth context (tenant/user ids)
+TIGRBL_AUTH_CONTEXT_ATTR = "__tigrbl_auth_context__"
+
+
+# Regex for safe SQL identifiers
+__SAFE_IDENT__ = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+__all__ = [
+    "ALL_VERBS",
+    "BULK_VERBS",
+    "ROUTING_VERBS",
+    "DEFAULT_HTTP_METHODS",
+    "MODEL_LEVEL_CFGS",
+    "TIGRBL_REQUEST_EXTRAS_ATTR",
+    "TIGRBL_RESPONSE_EXTRAS_ATTR",
+    "TIGRBL_OPS_ATTR",
+    "TIGRBL_VERB_ALIASES_ATTR",
+    "TIGRBL_VERB_ALIAS_POLICY_ATTR",
+    "TIGRBL_NESTED_PATHS_ATTR",
+    "TIGRBL_API_HOOKS_ATTR",
+    "TIGRBL_HOOKS_ATTR",
+    "TIGRBL_REGISTRY_LISTENER_ATTR",
+    "TIGRBL_GET_DB_ATTR",
+    "TIGRBL_AUTH_DEP_ATTR",
+    "TIGRBL_AUTHORIZE_ATTR",
+    "TIGRBL_REST_DEPENDENCIES_ATTR",
+    "TIGRBL_RPC_DEPENDENCIES_ATTR",
+    "TIGRBL_OWNER_POLICY_ATTR",
+    "TIGRBL_TENANT_POLICY_ATTR",
+    "TIGRBL_ALLOW_ANON_ATTR",
+    "TIGRBL_DEFAULTS_MODE_ATTR",
+    "TIGRBL_DEFAULTS_INCLUDE_ATTR",
+    "TIGRBL_DEFAULTS_EXCLUDE_ATTR",
+    "TIGRBL_SCHEMA_DECLS_ATTR",
+    "TIGRBL_CUSTOM_OP_ATTR",
+    "HOOK_DECLS_ATTR",
+    "TIGRBL_TX_MODELS_ATTR",
+    "CTX_REQUEST_KEY",
+    "CTX_DB_KEY",
+    "CTX_PAYLOAD_KEY",
+    "CTX_PATH_PARAMS_KEY",
+    "CTX_ENV_KEY",
+    "CTX_RPC_ID_KEY",
+    "CTX_SKIP_PERSIST_FLAG",
+    "CTX_USER_ID_KEY",
+    "CTX_TENANT_ID_KEY",
+    "CTX_AUTH_KEY",
+    "TIGRBL_AUTH_CONTEXT_ATTR",
+    "__SAFE_IDENT__",
+]

tigrbl/config/defaults.py

@@ -0,0 +1,29 @@
+# tigrbl/v3/config/defaults.py
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+# Canonical defaults used by config.resolver and runtime atoms.
+# Keep these conservative; adapters/apps can override at any scope.
+DEFAULTS: Mapping[str, Any] = {
+    # ── wire/out (response shaping) ────────────────────────────────────────────
+    "exclude_none": False,  # drop null-valued keys in wire:dump
+    "omit_nulls": False,  # alias; resolver normalizes both ways
+    "response_extras_overwrite": False,  # allow extras to replace existing keys
+    "extras_overwrite": False,  # alias; resolver normalizes both ways
+    # ── wire/in (request validation) ───────────────────────────────────────────
+    "reject_unknown_fields": False,  # if True, unknown input keys cause 422
+    # ── refresh / hydration policy ────────────────────────────────────────────
+    "refresh_policy": "auto",  # 'auto' | 'always' | 'never'
+    "refresh_after_write": None,  # Optional[bool]; resolver maps → policy
+    # ── validation/docs policy buckets (deep-merged) ──────────────────────────
+    # Shape: dict[op][field] = bool (true means "required for inbound")
+    "required_policy": {},
+    # ── docs/openapi knobs (deep-merged) ──────────────────────────────────────
+    "openapi": {},
+    "docs": {},
+    # ── tracing (deep-merged) ─────────────────────────────────────────────────
+    "trace": {
+        "enabled": True,
+    },
+}

tigrbl/config/resolver.py

@@ -0,0 +1,295 @@
+# tigrbl/v3/config/resolver.py
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from types import MappingProxyType
+from typing import Any, Dict, Iterable, Mapping, Optional
+
+# Optional defaults module (kept tolerant if not present yet)
+try:
+    from .defaults import DEFAULTS  # expected: Mapping[str, Any]
+except Exception:  # pragma: no cover
+    DEFAULTS = {
+        # wire/out
+        "exclude_none": False,
+        "omit_nulls": False,  # alias; normalized below
+        "response_extras_overwrite": False,
+        "extras_overwrite": False,  # alias
+        # wire/in
+        "reject_unknown_fields": False,
+        # refresh
+        "refresh_policy": "auto",  # 'auto' | 'always' | 'never'
+        "refresh_after_write": None,  # Optional[bool] → normalized into refresh_policy
+        # validation/docs
+        "required_policy": {},  # dict[op][field] = bool
+        # misc buckets developers may use
+        "openapi": {},
+        "docs": {},
+        "trace": {"enabled": True},
+    }
+
+
+# Keys that should be deep-merged (dict ← dict) instead of overridden.
+_DEEP_KEYS = {
+    "required_policy",
+    "openapi",
+    "docs",
+    "trace",
+    "policies",
+}
+
+
+class CfgView:
+    """
+    Read-only attribute/dict view over a plain dict.
+    Unknown attributes return None (to play nicely with getattr(cfg, 'x', None)).
+    """
+
+    __slots__ = ("_data",)
+
+    def __init__(self, data: Mapping[str, Any]):
+        # freeze top-level mapping
+        self._data = MappingProxyType(dict(data))
+
+    def __getattr__(self, name: str) -> Any:
+        return self._data.get(name, None)
+
+    def __getitem__(self, key: str) -> Any:
+        return self._data[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._data.get(key, default)
+
+    def as_dict(self) -> Dict[str, Any]:
+        """Copy out a mutable dict (for diagnostics/serialization)."""
+        return dict(self._data)
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"CfgView({dict(self._data)!r})"
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Public API
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def resolve_cfg(
+    *,
+    model: Any = None,
+    specs: Optional[Mapping[str, Any]] = None,
+    op: Optional[str] = None,
+    opspec: Any = None,
+    tabspec: Any = None,
+    apispec: Any = None,
+    appspec: Any = None,
+    overrides: Optional[Mapping[str, Any]] = None,
+) -> CfgView:
+    """
+    Merge configuration from multiple scopes with precedence:
+
+      opspec > colspecs > tabspec > apispec > appspec > defaults
+
+    The result is normalized and returned as a read-only CfgView suitable for ctx.cfg.
+
+    Notes:
+      - 'specs' is the {field -> ColumnSpec} map; any col-level '.cfg' dicts are merged.
+      - Non-dict or None layers are ignored.
+      - For a few known keys we support aliases and light normalization (see _normalize()).
+    """
+    layers: list[Mapping[str, Any]] = []
+
+    # 1) Base defaults (lowest precedence)
+    layers.append(_coerce_map(DEFAULTS))
+
+    # 2) App / API / Tab scopes
+    if appspec is not None:
+        layers.append(_extract_cfg(appspec))
+    if apispec is not None:
+        layers.append(_extract_cfg(apispec))
+    if tabspec is not None:
+        layers.append(_extract_cfg(tabspec))
+
+    # 3) Column-level aggregation (merged across all columns in stable order)
+    if specs:
+        col_cfg = _collect_col_cfg(specs)
+        if col_cfg:
+            layers.append(col_cfg)
+
+    # 4) Op-spec (highest declared spec layer)
+    if opspec is not None:
+        layers.append(_extract_cfg(opspec))
+
+    # 5) Per-request overrides (absolute highest precedence)
+    if overrides:
+        layers.append(_coerce_map(overrides))
+
+    # Merge with precedence (later wins), then normalize and freeze
+    merged = _merge_layers(layers)
+    merged = _normalize(merged, op=op)
+
+    return CfgView(merged)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _coerce_map(obj: Any) -> Mapping[str, Any]:
+    """Best-effort conversion of common config carriers to a plain mapping."""
+    if obj is None:
+        return {}
+    if isinstance(obj, Mapping):
+        return obj
+    # dataclass?
+    if is_dataclass(obj):
+        try:
+            # Drop keys with ``None`` values so they don't override defaults.
+            return {k: v for k, v in asdict(obj).items() if v is not None}
+        except Exception:
+            pass
+    # namespace-like with __dict__
+    d = getattr(obj, "__dict__", None)
+    if isinstance(d, dict):
+        return d
+    # pydantic v2 config-like
+    if hasattr(obj, "model_dump") and callable(getattr(obj, "model_dump")):
+        try:
+            return dict(obj.model_dump())
+        except Exception:
+            pass
+    # last resort: single 'cfg' attr if it's a mapping
+    cfg = getattr(obj, "cfg", None)
+    if isinstance(cfg, Mapping):
+        return cfg
+    return {}
+
+
+def _extract_cfg(spec: Any) -> Mapping[str, Any]:
+    """
+    Pull a config mapping from a spec-like object.
+    Accepts: spec.cfg, spec.config, or the object itself if it's a mapping.
+    """
+    if isinstance(spec, Mapping):
+        return spec
+    for name in ("cfg", "config"):
+        val = getattr(spec, name, None)
+        if isinstance(val, Mapping):
+            return val
+    # dataclass or namespace
+    return _coerce_map(spec)
+
+
+def _collect_col_cfg(specs: Mapping[str, Any]) -> Mapping[str, Any]:
+    """
+    Merge .cfg from ColumnSpec and its sub-specs (io/field/storage) across all columns.
+    Deep-merge dict values for keys in _DEEP_KEYS; override for scalars/others.
+    Later fields (lexicographic) win on conflicts to keep determinism.
+    """
+    acc: Dict[str, Any] = {}
+    for field in sorted(specs.keys()):
+        col = specs[field]
+        # Collect potential cfg dictionaries from multiple places on ColumnSpec
+        for obj in (
+            col,
+            getattr(col, "io", None),
+            getattr(col, "field", None),
+            getattr(col, "storage", None),
+        ):
+            mapping = _extract_cfg(obj)
+            if mapping:
+                acc = _merge_layers([acc, mapping])
+    return acc
+
+
+def _merge_layers(layers: Iterable[Mapping[str, Any]]) -> Dict[str, Any]:
+    """
+    Precedence-aware merge: later layers override earlier ones.
+    Dict values are shallow-merged except for keys in _DEEP_KEYS (deep merge).
+    """
+    result: Dict[str, Any] = {}
+    for layer in layers:
+        if not isinstance(layer, Mapping):
+            continue
+        for k, v in layer.items():
+            if (
+                k in _DEEP_KEYS
+                and isinstance(result.get(k), Mapping)
+                and isinstance(v, Mapping)
+            ):
+                result[k] = _deep_merge_dicts(result[k], v)
+            else:
+                result[k] = v
+    return result
+
+
+def _deep_merge_dicts(a: Mapping[str, Any], b: Mapping[str, Any]) -> Dict[str, Any]:
+    """
+    Deep merge two dicts; values in 'b' override 'a'. Only recurses on dicts.
+    Lists/sets/tuples are overridden (not concatenated) to remain predictable.
+    """
+    out: Dict[str, Any] = dict(a)
+    for k, v in b.items():
+        av = out.get(k)
+        if isinstance(av, Mapping) and isinstance(v, Mapping):
+            out[k] = _deep_merge_dicts(av, v)
+        else:
+            out[k] = v
+    return out
+
+
+def _normalize(cfg: Mapping[str, Any], *, op: Optional[str]) -> Dict[str, Any]:
+    """
+    Produce a normalized config dict with aliases resolved and policy rules applied.
+    """
+    d = dict(cfg)  # copy
+
+    # 1) Refresh policy normalization
+    #    - If refresh_after_write is explicitly True/False, that wins.
+    #    - Otherwise ensure refresh_policy has a sane default.
+    raw_after = d.get("refresh_after_write", None)
+    if isinstance(raw_after, bool):
+        d["refresh_policy"] = "always" if raw_after else "never"
+    else:
+        pol = d.get("refresh_policy", None)
+        if pol not in {"auto", "always", "never"}:
+            d["refresh_policy"] = "auto"
+
+    # 2) Alias handling for omit nulls and extras overwrite
+    if "exclude_none" not in d and isinstance(d.get("omit_nulls"), bool):
+        d["exclude_none"] = bool(d["omit_nulls"])
+    if "omit_nulls" not in d and isinstance(d.get("exclude_none"), bool):
+        d["omit_nulls"] = bool(d["exclude_none"])
+
+    if "response_extras_overwrite" not in d and isinstance(
+        d.get("extras_overwrite"), bool
+    ):
+        d["response_extras_overwrite"] = bool(d["extras_overwrite"])
+    if "extras_overwrite" not in d and isinstance(
+        d.get("response_extras_overwrite"), bool
+    ):
+        d["extras_overwrite"] = bool(d["response_extras_overwrite"])
+
+    # 3) required_policy structure sanity: dict[op][field] = bool
+    rp = d.get("required_policy")
+    if not isinstance(rp, Mapping):
+        d["required_policy"] = {}
+    else:
+        # ensure nested dicts & booleans; ignore malformed entries
+        fixed: Dict[str, Dict[str, bool]] = {}
+        for op_name, per_field in rp.items():
+            if not isinstance(per_field, Mapping):
+                continue
+            fixed[str(op_name)] = {
+                str(f): bool(v)
+                for f, v in per_field.items()
+                if isinstance(v, (bool, int))
+            }
+        d["required_policy"] = fixed
+
+    # 4) Optional op-specific view (pre-resolved convenience)
+    if op:
+        per_op = d["required_policy"].get(op, {})
+        d.setdefault("_required_for_op", per_op)
+
+    return d

tigrbl/core/__init__.py

@@ -0,0 +1,47 @@
+# tigrbl/v3/core/__init__.py
+"""
+Tigrbl v3 – Core operations.
+
+Re-exports the canonical CRUD bodies implemented in `.crud`.
+
+Notes:
+- These functions are **flush-only**. They never call `db.commit()`.
+- Final commits are driven by the runtime executor's `END_TX` phase.
+"""
+
+from __future__ import annotations
+
+from .crud import (
+    create,
+    read,
+    update,
+    replace,
+    merge,
+    delete,
+    list as _list,  # avoid shadowing built-in, then re-export as `list`
+    clear,
+    bulk_create,
+    bulk_update,
+    bulk_replace,
+    bulk_merge,
+    bulk_delete,
+)
+
+# Public alias named exactly `list` to preserve API surface
+list = _list  # noqa: A001 - intentional shadow of built-in for public API
+
+__all__ = [
+    "create",
+    "read",
+    "update",
+    "replace",
+    "merge",
+    "delete",
+    "list",
+    "clear",
+    "bulk_create",
+    "bulk_update",
+    "bulk_replace",
+    "bulk_merge",
+    "bulk_delete",
+]

tigrbl/core/crud/__init__.py

@@ -0,0 +1,36 @@
+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,
+)
+
+# Public alias named exactly `list` to preserve API surface
+list = _list  # noqa: A001 - intentional shadow of built-in for public API
+
+__all__ = [
+    "create",
+    "read",
+    "update",
+    "replace",
+    "merge",
+    "delete",
+    "list",
+    "clear",
+    "bulk_create",
+    "bulk_update",
+    "bulk_replace",
+    "bulk_merge",
+    "bulk_delete",
+]