tigrbl-base 0.4.2.dev4__tar.gz → 0.4.3.dev4__tar.gz

{tigrbl_base-0.4.2.dev4 → tigrbl_base-0.4.3.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tigrbl-base
-Version: 0.4.2.dev4
+Version: 0.4.3.dev4
 Summary: Base contract package for Tigrbl apps, routers, tables, sessions, middleware, requests, responses, bindings, and engine interfaces.
 License: Apache License
                                     Version 2.0, January 2004
@@ -250,7 +250,7 @@ Description-Content-Type: text/markdown
 <a href="https://discord.gg/K4YTAPapjR"><img src="https://img.shields.io/badge/Discord-Join%20chat-5865F2?logo=discord&logoColor=white" alt="Discord community for tigrbl-base"/></a>
 <a href="https://github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_base/README.md"><img src="https://hits.sh/github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_base/README.md.svg?label=hits" alt="Repository hits for tigrbl-base README"/></a>
 <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-525252" alt="Apache 2.0 license"/></a>
-<a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776ab" alt="Python versions 3.10 | 3.11 | 3.12 | 3.13 | 3.14 for tigrbl-base"/></a>
+<a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%2C%203.11%2C%203.12%2C%203.13%2C%203.14-3776ab" alt="Python versions 3.10 | 3.11 | 3.12 | 3.13 | 3.14 for tigrbl-base"/></a>
 <a href="https://github.com/tigrbl/tigrbl/blob/master/docs/README.md"><img src="https://img.shields.io/badge/workspace-core-1f6feb" alt="Workspace group for tigrbl-base"/></a>
 </div>
 
@@ -307,7 +307,7 @@ pip install tigrbl-base
 | Entry points | none declared |
 | Optional extras | none declared |
 | Legal files | `LICENSE`, `NOTICE` |
-| Supported Python | `3.10 | 3.11 | 3.12 | 3.13 | 3.14` |
+| Supported Python | `3.10, 3.11, 3.12, 3.13, 3.14` |
 
 ## What It Owns
 
@@ -316,6 +316,15 @@ pip install tigrbl-base
 Implementation orientation:
 - `tigrbl_base`: _base/, column/
 
+Package catalog:
+- `_base/_app_base.py`, `_router_base.py`, and `_table_base.py`: abstract app, router, and table behavior used by concrete framework classes.
+- `_base/_op_base.py`, `_binding_base.py`, `_rest_map.py`, and `_rpc_map.py`: operation, binding, REST mapping, and JSON-RPC mapping contracts.
+- `_base/_schema_base.py`, `_request_base.py`, `_response_base.py`, `_headers_base.py`, and `_middleware_base.py`: request/response/schema/header/middleware abstractions.
+- `_base/_engine_base.py`, `_engine_provider_base.py`, `_session_abc.py`, `_session_base.py`, and `_storage.py`: engine, provider, session, and storage interfaces.
+- `_base/_column_base.py`, `_table_registry_base.py`, `_alias_base.py`, `_hook_base.py`, `_security_base.py`, and `_datatype_lowering.py`: table metadata, aliasing, hook/security contracts, and data-type lowering hooks.
+- `_base/_assembly.py` and `_mapping_access.py`: assembly and mapping helpers for concrete implementations.
+- `column/infer`: column inference planning, JSON hint handling, type interpretation, and utility helpers.
+
 ## Public API and Import Surface
 
 - Import roots: `tigrbl_base`.
@@ -323,6 +332,55 @@ Implementation orientation:
 - Workspace dependencies: [`tigrbl-core`](https://pypi.org/project/tigrbl-core/), [`tigrbl-atoms`](https://pypi.org/project/tigrbl-atoms/).
 - External runtime dependencies: `sqlalchemy>=2.0`, `pydantic>=2.0`.
 
+## Abstraction Semantics
+
+`tigrbl-base` is the abstract contract layer between core specs and concrete implementations. It is useful when you need interface behavior without importing the facade or concrete ASGI/application classes.
+
+The package answers questions such as:
+
+- What must an app/router/table expose for assembly?
+- How do REST and JSON-RPC maps represent operation bindings?
+- What does a request, response, middleware, hook, session, engine provider, or storage adapter need to provide?
+- How should column metadata be inferred before a concrete table class lowers it into ORM/schema/runtime behavior?
+
+It should not own route registration side effects, transport IO, database engine construction, or runtime execution. Those belong in `tigrbl-concrete`, engine packages, kernel/runtime packages, or the facade.
+
+## Base Contracts by Area
+
+| Area | Base responsibility |
+|---|---|
+| App/router/table | Provide shared assembly, inclusion, registration, and metadata contracts. |
+| Operations and bindings | Represent operation maps, REST maps, RPC maps, alias behavior, and binding access. |
+| Schema and IO | Provide base shape for request/response/schema objects without deciding concrete rendering. |
+| Engine/session/storage | Define provider/session/storage contracts so concrete engines can plug in consistently. |
+| Hooks/security/middleware | Provide registration and interface surfaces for lifecycle customization and request policy. |
+| Columns | Infer and lower type information while keeping spec-level intent separate from concrete ORM wiring. |
+
+## Column Inference
+
+`tigrbl_base.column.infer` supports the framework's schema-first and table-first workflows. It helps interpret Python typing, JSON hints, planning metadata, and column options before concrete packages lower them into SQLAlchemy/Pydantic/runtime representations.
+
+Best practices for column inference:
+- Keep inference deterministic; the same type hints and config should produce the same plan.
+- Keep storage intent separate from wire-schema intent.
+- Preserve explicit user configuration over inferred defaults.
+- Add tests for ambiguous type handling instead of silently guessing.
+
+## Extension Guidance
+
+- Depend on `tigrbl-base` when you are writing concrete adapters, engine adapters, or framework tests that need abstract contracts.
+- Do not import `tigrbl` facade classes here; base should remain lower than the public facade.
+- Keep methods small and contract-oriented. Put operational side effects in concrete implementations or atoms.
+- Treat base classes as compatibility surfaces. Renaming or tightening a method affects all concrete packages.
+- Prefer composition with `tigrbl-core` specs rather than duplicating spec fields in base classes.
+
+Authoring BCP for this boundary:
+- Do use `tigrbl-base` for abstract app/router/table/session/request/response/binding/security/middleware/storage contracts and column inference behavior.
+- Do keep column inference deterministic and spec-driven before concrete packages lower intent into ORM, schema, runtime, or docs behavior.
+- Do not make `tigrbl-base` the public application import path for normal service code.
+- Do not put route registration side effects, direct database transaction calls, concrete engine construction, FastAPI/Starlette route objects, or runtime execution into this package.
+- Avoid treating SQLAlchemy materialization as the source of truth here. Base may prepare and validate metadata, but reusable field behavior should remain represented by Tigrbl specs.
+
 ## Usage Examples
 
 ### Verify the installed package
@@ -383,6 +441,8 @@ Choose `tigrbl-base` when the quick-answer table matches your use case. Choose [
 - [Package layout](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/PACKAGE_LAYOUT.md)
 - [Current target](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/CURRENT_TARGET.md)
 - [Current state](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/CURRENT_STATE.md)
+- [Next steps](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/NEXT_STEPS.md)
+- [Documentation pointers](https://github.com/tigrbl/tigrbl/blob/master/docs/governance/DOC_POINTERS.md)
 - [SSOT registry](https://github.com/tigrbl/tigrbl/blob/master/.ssot/registry.json)
 - [Release workflow](https://github.com/tigrbl/tigrbl/actions/workflows/publish.yml)
 
@@ -394,7 +454,7 @@ Choose `tigrbl-base` when the quick-answer table matches your use case. Choose [
 
 ## Package-local Boundary
 
-This README is the package-local distribution entry point for `tigrbl-base`. It answers install, usage, API, ownership, and certification-orientation questions for this package. Broader architectural decisions, release status, and cross-package proof chains remain in the repository-level docs and SSOT registry.
+This file is a package-local distribution entry point. This README is the package-local distribution entry point for `tigrbl-base`. It answers install, usage, API, ownership, and certification-orientation questions for this package. Broader architectural decisions, release status, and cross-package proof chains remain in the repository-level docs and SSOT registry.
 
 ## License
 

{tigrbl_base-0.4.2.dev4 → tigrbl_base-0.4.3.dev4}/README.md

@@ -7,7 +7,7 @@
 <a href="https://discord.gg/K4YTAPapjR"><img src="https://img.shields.io/badge/Discord-Join%20chat-5865F2?logo=discord&logoColor=white" alt="Discord community for tigrbl-base"/></a>
 <a href="https://github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_base/README.md"><img src="https://hits.sh/github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_base/README.md.svg?label=hits" alt="Repository hits for tigrbl-base README"/></a>
 <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-525252" alt="Apache 2.0 license"/></a>
-<a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776ab" alt="Python versions 3.10 | 3.11 | 3.12 | 3.13 | 3.14 for tigrbl-base"/></a>
+<a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%2C%203.11%2C%203.12%2C%203.13%2C%203.14-3776ab" alt="Python versions 3.10 | 3.11 | 3.12 | 3.13 | 3.14 for tigrbl-base"/></a>
 <a href="https://github.com/tigrbl/tigrbl/blob/master/docs/README.md"><img src="https://img.shields.io/badge/workspace-core-1f6feb" alt="Workspace group for tigrbl-base"/></a>
 </div>
 
@@ -64,7 +64,7 @@ pip install tigrbl-base
 | Entry points | none declared |
 | Optional extras | none declared |
 | Legal files | `LICENSE`, `NOTICE` |
-| Supported Python | `3.10 | 3.11 | 3.12 | 3.13 | 3.14` |
+| Supported Python | `3.10, 3.11, 3.12, 3.13, 3.14` |
 
 ## What It Owns
 
@@ -73,6 +73,15 @@ pip install tigrbl-base
 Implementation orientation:
 - `tigrbl_base`: _base/, column/
 
+Package catalog:
+- `_base/_app_base.py`, `_router_base.py`, and `_table_base.py`: abstract app, router, and table behavior used by concrete framework classes.
+- `_base/_op_base.py`, `_binding_base.py`, `_rest_map.py`, and `_rpc_map.py`: operation, binding, REST mapping, and JSON-RPC mapping contracts.
+- `_base/_schema_base.py`, `_request_base.py`, `_response_base.py`, `_headers_base.py`, and `_middleware_base.py`: request/response/schema/header/middleware abstractions.
+- `_base/_engine_base.py`, `_engine_provider_base.py`, `_session_abc.py`, `_session_base.py`, and `_storage.py`: engine, provider, session, and storage interfaces.
+- `_base/_column_base.py`, `_table_registry_base.py`, `_alias_base.py`, `_hook_base.py`, `_security_base.py`, and `_datatype_lowering.py`: table metadata, aliasing, hook/security contracts, and data-type lowering hooks.
+- `_base/_assembly.py` and `_mapping_access.py`: assembly and mapping helpers for concrete implementations.
+- `column/infer`: column inference planning, JSON hint handling, type interpretation, and utility helpers.
+
 ## Public API and Import Surface
 
 - Import roots: `tigrbl_base`.
@@ -80,6 +89,55 @@ Implementation orientation:
 - Workspace dependencies: [`tigrbl-core`](https://pypi.org/project/tigrbl-core/), [`tigrbl-atoms`](https://pypi.org/project/tigrbl-atoms/).
 - External runtime dependencies: `sqlalchemy>=2.0`, `pydantic>=2.0`.
 
+## Abstraction Semantics
+
+`tigrbl-base` is the abstract contract layer between core specs and concrete implementations. It is useful when you need interface behavior without importing the facade or concrete ASGI/application classes.
+
+The package answers questions such as:
+
+- What must an app/router/table expose for assembly?
+- How do REST and JSON-RPC maps represent operation bindings?
+- What does a request, response, middleware, hook, session, engine provider, or storage adapter need to provide?
+- How should column metadata be inferred before a concrete table class lowers it into ORM/schema/runtime behavior?
+
+It should not own route registration side effects, transport IO, database engine construction, or runtime execution. Those belong in `tigrbl-concrete`, engine packages, kernel/runtime packages, or the facade.
+
+## Base Contracts by Area
+
+| Area | Base responsibility |
+|---|---|
+| App/router/table | Provide shared assembly, inclusion, registration, and metadata contracts. |
+| Operations and bindings | Represent operation maps, REST maps, RPC maps, alias behavior, and binding access. |
+| Schema and IO | Provide base shape for request/response/schema objects without deciding concrete rendering. |
+| Engine/session/storage | Define provider/session/storage contracts so concrete engines can plug in consistently. |
+| Hooks/security/middleware | Provide registration and interface surfaces for lifecycle customization and request policy. |
+| Columns | Infer and lower type information while keeping spec-level intent separate from concrete ORM wiring. |
+
+## Column Inference
+
+`tigrbl_base.column.infer` supports the framework's schema-first and table-first workflows. It helps interpret Python typing, JSON hints, planning metadata, and column options before concrete packages lower them into SQLAlchemy/Pydantic/runtime representations.
+
+Best practices for column inference:
+- Keep inference deterministic; the same type hints and config should produce the same plan.
+- Keep storage intent separate from wire-schema intent.
+- Preserve explicit user configuration over inferred defaults.
+- Add tests for ambiguous type handling instead of silently guessing.
+
+## Extension Guidance
+
+- Depend on `tigrbl-base` when you are writing concrete adapters, engine adapters, or framework tests that need abstract contracts.
+- Do not import `tigrbl` facade classes here; base should remain lower than the public facade.
+- Keep methods small and contract-oriented. Put operational side effects in concrete implementations or atoms.
+- Treat base classes as compatibility surfaces. Renaming or tightening a method affects all concrete packages.
+- Prefer composition with `tigrbl-core` specs rather than duplicating spec fields in base classes.
+
+Authoring BCP for this boundary:
+- Do use `tigrbl-base` for abstract app/router/table/session/request/response/binding/security/middleware/storage contracts and column inference behavior.
+- Do keep column inference deterministic and spec-driven before concrete packages lower intent into ORM, schema, runtime, or docs behavior.
+- Do not make `tigrbl-base` the public application import path for normal service code.
+- Do not put route registration side effects, direct database transaction calls, concrete engine construction, FastAPI/Starlette route objects, or runtime execution into this package.
+- Avoid treating SQLAlchemy materialization as the source of truth here. Base may prepare and validate metadata, but reusable field behavior should remain represented by Tigrbl specs.
+
 ## Usage Examples
 
 ### Verify the installed package
@@ -140,6 +198,8 @@ Choose `tigrbl-base` when the quick-answer table matches your use case. Choose [
 - [Package layout](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/PACKAGE_LAYOUT.md)
 - [Current target](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/CURRENT_TARGET.md)
 - [Current state](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/CURRENT_STATE.md)
+- [Next steps](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/NEXT_STEPS.md)
+- [Documentation pointers](https://github.com/tigrbl/tigrbl/blob/master/docs/governance/DOC_POINTERS.md)
 - [SSOT registry](https://github.com/tigrbl/tigrbl/blob/master/.ssot/registry.json)
 - [Release workflow](https://github.com/tigrbl/tigrbl/actions/workflows/publish.yml)
 
@@ -151,7 +211,7 @@ Choose `tigrbl-base` when the quick-answer table matches your use case. Choose [
 
 ## Package-local Boundary
 
-This README is the package-local distribution entry point for `tigrbl-base`. It answers install, usage, API, ownership, and certification-orientation questions for this package. Broader architectural decisions, release status, and cross-package proof chains remain in the repository-level docs and SSOT registry.
+This file is a package-local distribution entry point. This README is the package-local distribution entry point for `tigrbl-base`. It answers install, usage, API, ownership, and certification-orientation questions for this package. Broader architectural decisions, release status, and cross-package proof chains remain in the repository-level docs and SSOT registry.
 
 ## License
 

{tigrbl_base-0.4.2.dev4 → tigrbl_base-0.4.3.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tigrbl-base"
-version = "0.4.2.dev4"
+version = "0.4.3.dev4"
 description = "Base contract package for Tigrbl apps, routers, tables, sessions, middleware, requests, responses, bindings, and engine interfaces."
 readme = "README.md"
 license = { file = "LICENSE" }

{tigrbl_base-0.4.2.dev4 → tigrbl_base-0.4.3.dev4}/tigrbl_base/_base/__init__.py

@@ -22,6 +22,8 @@ _EXPORTS = {
     "SchemaBase": "_schema_base",
     "SessionABC": "_session_abc",
     "TigrblSessionBase": "_session_base",
+    "CrudTableBase": "_table_base",
+    "RealtimeTableBase": "_table_base",
     "TableBase": "_table_base",
     "TableRegistryBase": "_table_registry_base",
     "AttrDict": "_mapping_access",
@@ -29,6 +31,9 @@ _EXPORTS = {
 
 __all__ = list(_EXPORTS)
 
+for _symbol in __all__:
+    globals().pop(_symbol, None)
+
 
 def __getattr__(name: str) -> Any:
     module_name = _EXPORTS.get(name)

{tigrbl_base-0.4.2.dev4 → tigrbl_base-0.4.3.dev4}/tigrbl_base/_base/_app_base.py

@@ -5,7 +5,7 @@ import inspect
 from typing import Any
 from typing import Callable, Optional, Sequence
 
-from tigrbl_core._spec.app_spec import AppSpec
+from tigrbl_core._spec.app_spec import AppSpec, normalize_execution_backend
 from tigrbl_core._spec.engine_spec import EngineCfg
 from tigrbl_core._spec.response_spec import ResponseSpec
 
@@ -100,7 +100,7 @@ class AppBase(AppSpec):
             title=spec.title,
             description=spec.description,
             version=spec.version,
-            execution_backend=spec.execution_backend,
+            execution_backend=normalize_execution_backend(spec.execution_backend),
             engine=spec.engine,
             routers=routers,
             ops=tuple(spec.ops or ()),
@@ -133,7 +133,7 @@ class AppBase(AppSpec):
             title=str(spec.title or "Tigrbl"),
             description=spec.description,
             version=str(spec.version or "0.1.0"),
-            execution_backend=str(spec.execution_backend or "auto"),
+            execution_backend=normalize_execution_backend(spec.execution_backend),
             engine=spec.engine,
             routers=cls._bind_mapped_children(spec.routers, parent=parent),
             ops=cls._bind_mapped_children(spec.ops, parent=parent),

{tigrbl_base-0.4.2.dev4 → tigrbl_base-0.4.3.dev4}/tigrbl_base/_base/_mapping_access.py

@@ -15,5 +15,11 @@ class AttrDict(dict):
     def __setattr__(self, key: str, value: Any) -> None:  # pragma: no cover - trivial
         self[key] = value
 
+    def __delattr__(self, item: str) -> None:
+        try:
+            del self[item]
+        except KeyError as exc:
+            raise AttributeError(item) from exc
+
 
 __all__ = ["AttrDict"]

{tigrbl_base-0.4.2.dev4 → tigrbl_base-0.4.3.dev4}/tigrbl_base/_base/_table_base.py

@@ -11,6 +11,13 @@ from sqlalchemy import CheckConstraint, ForeignKey, MetaData
 from sqlalchemy.types import Enum as SAEnum, String
 
 from ._datatype_lowering import lower_datatype_to_sqla_type
+from tigrbl_core._spec.table_profile_spec import (
+    CRUD_TABLE_PROFILE,
+    PLAIN_TABLE_PROFILE,
+    REALTIME_TABLE_PROFILE,
+    TableProfileError,
+    coerce_table_profile,
+)
 
 # ──────────────────────────────────────────────────────────────────────────────
 # Helpers – type inference & SA type instantiation
@@ -342,6 +349,39 @@ def _attach_model_ops_namespace(model: type) -> None:
     model.opspecs = ops_ns
 
 
+def _normalize_table_profile_declaration(cls: type) -> None:
+    profile_attr = "TABLE_PROFILE"
+    explicit_profile = profile_attr in cls.__dict__
+
+    legacy_attrs = {
+        "DEFAULT_CANON_VERBS",
+        "should_wire_canonical",
+        "__tigrbl_defaults_mode__",
+        "__tigrbl_defaults_include__",
+        "__tigrbl_defaults_exclude__",
+        "__tigrbl_ops__",
+        "OPS",
+    }
+    present_legacy = sorted(name for name in legacy_attrs if name in cls.__dict__)
+    cfg = cls.__dict__.get("table_config")
+    if isinstance(cfg, dict) and (
+        "binding_profiles" in cfg
+        or "default_bindings" in cfg
+        or "default_binding_profiles" in cfg
+    ):
+        present_legacy.append("table_config.binding_profiles")
+
+    if explicit_profile and present_legacy:
+        raise TableProfileError(
+            f"{cls.__name__} declares TABLE_PROFILE and legacy table default "
+            f"authority {', '.join(present_legacy)}"
+        )
+
+    value = cls.__dict__.get(profile_attr, getattr(cls, profile_attr, PLAIN_TABLE_PROFILE))
+    normalized = coerce_table_profile(value)
+    setattr(cls, profile_attr, normalized)
+
+
 # ──────────────────────────────────────────────────────────────────────────────
 # Declarative Base
 # ──────────────────────────────────────────────────────────────────────────────
@@ -349,8 +389,11 @@ def _attach_model_ops_namespace(model: type) -> None:
 
 class TableBase(DeclarativeBase):
     __allow_unmapped__ = True
+    TABLE_PROFILE = PLAIN_TABLE_PROFILE
 
     def __init_subclass__(cls, **kw):
+        _normalize_table_profile_declaration(cls)
+
         # 0) Remove any previously registered class with the same module path.
         try:
             reg = TableBase.registry._class_registry
@@ -540,4 +583,14 @@ class TableBase(DeclarativeBase):
         return getattr(self, key)
 
 
-__all__ = ["TableBase"]
+class CrudTableBase(TableBase):
+    __abstract__ = True
+    TABLE_PROFILE = CRUD_TABLE_PROFILE
+
+
+class RealtimeTableBase(TableBase):
+    __abstract__ = True
+    TABLE_PROFILE = REALTIME_TABLE_PROFILE
+
+
+__all__ = ["CrudTableBase", "RealtimeTableBase", "TableBase"]