Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

tigrbl-base

Tigrbl logo

Base contract package for Tigrbl apps, routers, tables, sessions, middleware, requests, responses, bindings, and engine interfaces.

PyPI version for tigrbl-base Downloads for tigrbl-base Discord community for tigrbl-base Repository hits for tigrbl-base README Apache 2.0 license Python versions 3.10 | 3.11 | 3.12 | 3.13 | 3.14 for tigrbl-base Workspace group for tigrbl-base

What is tigrbl-base?

Base contract package for Tigrbl apps, routers, tables, sessions, middleware, requests, responses, bindings, and engine interfaces.

Why use tigrbl-base?

Use it when you need this foundational Tigrbl layer directly as a small, focused dependency.

When should I install tigrbl-base?

Install it for extension packages, package-local tests, or internals that need this boundary without the whole facade.

Who is tigrbl-base for?

Framework maintainers, extension authors, and advanced users composing Tigrbl from split packages.

Where does tigrbl-base fit?

tigrbl-base lives at pkgs/20_base/tigrbl_base and serves a focused layer in the split Tigrbl framework.

How does tigrbl-base work?

It owns a narrow layer in the split workspace and is consumed by higher-level packages through explicit dependencies.

Install

uv add tigrbl-base
pip install tigrbl-base

Surface Coverage

Surface Value
PyPI package tigrbl-base
Repository path pkgs/20_base/tigrbl_base
Python import root tigrbl_base
Console scripts none declared
Entry points none declared
Optional extras none declared
Legal files LICENSE, NOTICE
Supported Python 3.10, 3.11, 3.12, 3.13, 3.14

What It Owns

tigrbl-base owns the foundational framework package boundary. It should be installed when you need this package's focused responsibility without assuming every other Tigrbl workspace package is present.

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.
  • Public symbols: public surface is module-oriented; import the package boundary and inspect submodules as needed.
  • Workspace dependencies: tigrbl-core, 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

python -m pip show tigrbl-base
python - <<'PY'
from importlib.metadata import version
print(version("tigrbl-base"))
PY

Import the package boundary

import importlib

module = importlib.import_module("tigrbl_base._base")
print(module.__name__)

Inspect available modules

import importlib
import pkgutil

module = importlib.import_module("tigrbl_base._base")
for info in pkgutil.iter_modules(getattr(module, "__path__", [])):
    print(info.name)

Use with the facade when building applications

uv add tigrbl tigrbl-base
python - <<'PY'
import tigrbl
print(tigrbl.__name__)
PY

How To Choose This Package

Choose tigrbl-base when the quick-answer table matches your use case. Choose tigrbl instead when you want the full public facade. Choose a lower-level package such as tigrbl-core, tigrbl-base, or tigrbl-runtime when you are building framework extensions or testing a specific internal boundary.

Support

Package-local Boundary

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.

Certification Status

  • Package status: governed package in the tigrbl/tigrbl workspace.
  • Governance source: SSOT registry.
  • Release evidence: publish workflow validates package builds, tests, GitHub release assets, and PyPI publication for managed packages.
  • Local certification guard: pkgs/97_tests/tigrbl_tests/tests/unit/test_package_badges_and_notices.py verifies every package README keeps the Discord badge, Apache 2.0 badge, explicit Python-version badge, LICENSE, and NOTICE.
  • Scope note: this README documents the package boundary. Runtime feature support remains governed by .ssot/ entities and the conformance docs linked below.

License

Licensed under the Apache License, Version 2.0. See LICENSE, NOTICE, and the official Apache 2.0 license text.

Metadata

Release files for tigrbl-base 0.4.5.dev6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tigrbl-base 0.4.5.dev6
File Size Uploaded Provenance Actions
tigrbl_base-0.4.5.dev6.tar.gz 42.5 kB Without provenance Details for tigrbl_base-0.4.5.dev6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tigrbl-base 0.4.5.dev6
File Interpreter ABI Platform Actions
tigrbl_base-0.4.5.dev6-py3-none-any.whl Python 3 none any Details for tigrbl_base-0.4.5.dev6-py3-none-any.whl

Total release size: 93.7 kB

Release files / tigrbl_base-0.4.5.dev6.tar.gz

Download URL tigrbl_base-0.4.5.dev6.tar.gz
Size 42.5 kB
Tags Source
SHA-256 checksum
How to use checksums
7f344e2dee522ee7587975526d8c8cdd65dd98ef894e1cd6f96a7666d0c8fded
BLAKE2b-256 checksum
How to use checksums
45a7bf5416bae1f8091bea18cb06f8c5df253237ccca589b205f059db9938392
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / tigrbl_base-0.4.5.dev6-py3-none-any.whl

Download URL tigrbl_base-0.4.5.dev6-py3-none-any.whl
Size 51.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
add3203852973c5b9a68270c2591692c9ab83babf2a2080c659bc10d6e23c8d7
BLAKE2b-256 checksum
How to use checksums
464e7725869c6988b0d8e6d32d843c999f1e5619e220fc844bd2eb480ea03129
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for tigrbl-base 0.4.5.dev6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page