Skip to main content
Pre-release

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

tigrbl-core

Tigrbl logo

Core Tigrbl framework specifications, decorators, schemas, hooks, operations, and primitives for schema-first APIs.

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

What is tigrbl-core?

Core Tigrbl framework specifications, decorators, schemas, hooks, operations, and primitives for schema-first APIs.

Why use tigrbl-core?

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

When should I install tigrbl-core?

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

Who is tigrbl-core for?

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

Where does tigrbl-core fit?

tigrbl-core lives at pkgs/10_core/tigrbl_core and serves a focused layer in the split Tigrbl framework.

How does tigrbl-core work?

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

Install

uv add tigrbl-core
pip install tigrbl-core

Surface Coverage

Surface Value
PyPI package tigrbl-core
Repository path pkgs/10_core/tigrbl_core
Python import root tigrbl_core
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-core 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_core: _spec/, canonical_json, config/, core/, op/, schema/

Package catalog:

  • tigrbl_core/_spec/: typed, serializable specifications for aliases, apps, bindings, columns, data types, docs, engines, fields, hooks, IO, middleware, operations, paths, requests, responses, routers, schemas, sessions, storage, tables, and table registries.
  • tigrbl_core/config/: constants, defaults, resolver logic, and engine traversal helpers used when app, router, table, column, op, and request layers are merged.
  • tigrbl_core/op/: canonical operation names, operation collection, and operation typing helpers.
  • tigrbl_core/schema/: dynamic schema construction, schema cache helpers, extras handling, list-parameter support, schema JSON helpers, and get_schema access.
  • tigrbl_core/canonical_json.py: deterministic JSON output used by docs, registry-like payloads, tests, and conformance artifacts.

Public API and Import Surface

  • Import roots: tigrbl_core.
  • Public symbols: public surface is module-oriented; import the package boundary and inspect submodules as needed.
  • Workspace dependencies: tigrbl-typing.
  • External runtime dependencies: pydantic>=2.10,<3, pyyaml, tomli-w, tomli>=2.0.1; python_version < '3.11'.

Specification Model

The core package is the contract layer. It defines the vocabulary consumed by base abstractions, concrete adapters, atoms, kernel planning, runtime routing, docs generation, and the public facade. Most application code should not construct these specs manually; application code should normally use facade decorators and shortcuts. Extension packages use the specs when they need deterministic, testable configuration objects.

Spec family What it describes
AppSpec, RouterSpec, TableSpec Container-level framework configuration and inheritance points.
ColumnSpec, FieldSpec, data type specs Field semantics, validation, storage, schema projection, and data-type lowering.
OpSpec and op utilities Operation name, alias, arity, binding, handler, schema, hook, response, and runtime intent.
HookSpec and hook types Hook targets, phases, predicates, ordering, and callable registration shape.
SchemaSpec, RequestSpec, ResponseSpec, IoSpec Input/output envelope behavior, request extraction, response shaping, and Pydantic model generation.
BindingSpec REST, JSON-RPC, stream, SSE, WebSocket, WSS, and WebTransport binding metadata.
EngineSpec, SessionSpec, StorageSpec Engine/provider/session/storage configuration without importing concrete engine implementations.
DocsSpec, PathSpec, MiddlewareSpec Documentation projection, route paths, and middleware configuration.

Operation Semantics

tigrbl_core.op.canonical.DEFAULT_CANON_VERBS is the default CRUD set:

create, read, update, replace, delete, list, clear

Tables can change canonical wiring through mode/include/exclude attributes or a should_wire_canonical(op) helper. Core only decides whether an operation is part of the desired specification. Concrete packages and operation packs supply the actual handlers and routing behavior.

Use this package when you need to inspect or build operation specs before runtime compilation. Use tigrbl when you simply want a working app surface.

Binding and Transport Semantics

BindingSpec keeps four concerns distinct:

  • protocol or binding kind, such as HTTP REST, HTTP JSON-RPC, HTTP stream, SSE, WebSocket, WSS, or WebTransport;
  • exchange shape, such as request/response, server stream, bidirectional stream, client stream, server stream, session, or datagram;
  • framing, such as JSON, JSON-RPC, SSE, WebSocket text, stream framing, or WebTransport lane-local framing;
  • runtime lane metadata, especially for WebTransport session, stream, and datagram behavior.

This separation is deliberate. Extension authors should not collapse protocol support into a single string or infer framing from the transport name. Invalid combinations should remain explicit validation failures so runtime behavior is fail-closed.

Configuration Precedence

Core resolvers use this precedence pattern:

request override > operation spec > column spec > table spec > router spec > app spec > defaults

The most specific layer wins. Keep default policy broad, then narrow behavior by table, column, and operation. Avoid hidden mutation of spec objects after a runtime plan has been compiled; build a fresh spec or invalidate the relevant cache when behavior truly changes.

Schema Construction

Schema helpers build operation-specific request and response models from table metadata, column specs, request/response extras, list-parameter rules, and op-level configuration. get_schema(...) is the stable way to retrieve the generated model for a table operation and direction. Prefer it over hand-writing duplicate Pydantic envelopes when data belongs to a Tigrbl operation.

Best practices for schema work:

  • Keep storage fields, wire fields, and virtual extras separate.
  • Put reusable schema behavior in table or column specs; reserve op specs for operation-specific differences.
  • Use canonical JSON helpers when writing deterministic docs or evidence artifacts.
  • Treat generated schemas as projections of the specs, not as the source of truth.

Extension Guidance

  • Depend on tigrbl-core when you need spec classes, op collection, schema generation, or config resolution without concrete app/router/runtime imports.
  • Keep specs serializable and deterministic. Do not attach live database sessions, request objects, or transport handles to core specs.
  • Validate protocol and binding assumptions in core or kernel-facing tests before adding runtime behavior.
  • Keep application-facing convenience APIs in tigrbl or tigrbl-concrete; keep cross-package contracts here.

Authoring BCP for this boundary:

  • Do treat ColumnSpec, FieldSpec, OpSpec, HookSpec, SchemaSpec, BindingSpec, EngineSpec, SessionSpec, and related specs as the contract vocabulary that other Tigrbl packages consume.
  • Do keep specs independent of FastAPI, Starlette, SQLAlchemy sessions, live request objects, and transport handles.
  • Do not move application route authoring, direct database calls, concrete engine creation, or runtime dispatch side effects into tigrbl-core.
  • Avoid duplicating spec fields in helper classes or generated schemas. Specs should remain the source that schema, docs, kernel, runtime, base, concrete, and facade layers project from.

Usage Examples

Verify the installed package

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

Import the package boundary

import importlib

module = importlib.import_module("tigrbl_core._spec")
print(module.__name__)

Inspect available modules

import importlib
import pkgutil

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

Use with the facade when building applications

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

How To Choose This Package

Choose tigrbl-core 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-core. 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-core 0.4.5.dev8

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-core 0.4.5.dev8
File Size Uploaded Provenance Actions
tigrbl_core-0.4.5.dev8.tar.gz 96.5 kB Without provenance Details for tigrbl_core-0.4.5.dev8.tar.gz

Built distribution (wheel)

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

Total release size: 214.7 kB

Release files / tigrbl_core-0.4.5.dev8.tar.gz

Download URL tigrbl_core-0.4.5.dev8.tar.gz
Size 96.5 kB
Tags Source
SHA-256 checksum
How to use checksums
924e16b4c3b1cf2ce5d922e5b413e4f04fb017453daca46d9f5b887476ee911d
BLAKE2b-256 checksum
How to use checksums
5628d64c4474354a6a311404c931f1e011fd368648aa92ac4830fbbbd0810511
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_core-0.4.5.dev8-py3-none-any.whl

Download URL tigrbl_core-0.4.5.dev8-py3-none-any.whl
Size 118.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bedb6b4ad6f3a5036762d61d4fbe16f569ea364bc52e52613706484a328d69ca
BLAKE2b-256 checksum
How to use checksums
0bd42bf8b20cdb57105bb570213e530fc8c55e3fd633ca7c8b2c9e5d94e2eaf8
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-core 0.4.5.dev8

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