sandloom.sdk: the Python API¶
Sandloom Public API 1.0: the one namespace business modules import (spec §2).
A business module and its tests import only public sandloom.sdk modules (no
leading underscore), generated contract stubs and contract DTOs, and their
own package. This root re-exports the beginner code names; every other
public name lives in its themed module:
sandloom.sdk.module, .app, .migrations, .tooling, .web,
.data, .tenant, .events, .effects, .tasks, .contracts,
.authz, .sagas, .projections, .infra, .security,
.errors, .testing (and .testing.fixtures).
Importing sandloom.sdk reads no environment and performs no I/O (spec §2.4,
test_sdk_import_is_side_effect_free). Layers (spec §3): the public
modules > sandloom.sdk._decl (L1, declarative) > sandloom.sdk._prim (L2
primitives); the kernel never imports sandloom.sdk (.importlinter).
Start with the beginner names below. The themed modules also expose
advanced primitives for explicit transaction, event and deployment needs.
Run sandloom docs <name> for a name's signature and usage.
The beginner names¶
These 21 code names are importable from sandloom.sdk directly; the six testing names (client, as_user, published, deliver, fake_contract, fake_access_fact) come from sandloom.sdk.testing and its pytest plugin. Each links to its entry on its home page.
| Name | Home | Kind | Summary |
|---|---|---|---|
authorize_resource |
sandloom.sdk.authz |
function | Load a resource by path id, authorize, and return it to the endpoint. |
Base |
sandloom.sdk.data |
class | Base class for all SQLAlchemy models. |
command |
sandloom.sdk.contracts |
function | Mark a provider method as a command: deduplicated by its idempotency_key argument, committed in the provider's own unit, not atomic wit... |
Contract |
sandloom.sdk.contracts |
function | The caller of contract ref (spec §5.3), declared at module level: |
contract |
sandloom.sdk.contracts |
function | Declare a stateless provider class of contract name: |
CreatedAt |
sandloom.sdk.data |
annotated type | |
Credits |
sandloom.sdk.authz |
class | Subject's live credit balance is at least minimum. |
CurrentUser |
sandloom.sdk.web |
annotated type | |
db |
sandloom.sdk.data |
function | The session of the innermost open unit of the current task (§4.3): |
define_module |
sandloom.sdk.module |
function | Build a module's register(core) from its declarations (spec §5.7). |
Event |
sandloom.sdk.events |
class | Base class of typed events: class E(Event, channel=..., role="auto"). |
module_router |
sandloom.sdk.web |
function | The module's router (spec §5.1), in <module>/api.py: |
new_id |
sandloom.sdk.data |
function | A new time-ordered id (UUIDv7, RFC 9562) for a primary key: |
on |
sandloom.sdk.events |
function | Register the decorated coroutine as a consumer of event (§5.4). |
on_commit |
sandloom.sdk.effects |
async function | Run callback only after the current Unit of Work COMMITS. |
OrgRole |
sandloom.sdk.authz |
class | Subject holds at least minimum role in the request's organization. |
Owner |
sandloom.sdk.authz |
class | Subject owns the request resource. |
public |
sandloom.sdk.web |
function | Declare a route unauthenticated, and why (ADR-0009 item 1). |
record_audit |
sandloom.sdk.effects |
function | Append an entry to the audit log within the current Unit of Work. |
require |
sandloom.sdk.authz |
function | Return a dependency enforcing policy (no request resource). |
Subscribed |
sandloom.sdk.authz |
class | Subject's subscription grants access (coarse, claim-based). |
SubscriptionActive |
sandloom.sdk.authz |
class | Subject's subscription is active right now (live, authoritative). |
TenantScoped |
sandloom.sdk.data |
class | Mixin marking a model as tenant-owned (adds the indexed tenant_id). |
as_user |
sandloom.sdk.testing |
function | (user_id, headers) with a freshly minted access token. |
deliver |
sandloom.sdk.testing |
async function | Deliver one event to every consumer of its channel; returns how many. |
fake_access_fact |
sandloom.sdk.testing |
function | Answer the access fact name with value inside the block. |
fake_contract |
sandloom.sdk.testing |
function | Serve contract ref from impl for the block: |
published |
sandloom.sdk.testing |
function | The events of event's channel published by the code under test: |
client |
sandloom.sdk.testing.plugin |
fixture | HTTP client on the app; every request runs on the test's db. |
Modules¶
| Module | Beginner names | Names | Summary |
|---|---|---|---|
sandloom.sdk.app |
0 | 2 | |
sandloom.sdk.authz |
7 | 55 | |
sandloom.sdk.contracts |
3 | 30 | |
sandloom.sdk.data |
5 | 27 | |
sandloom.sdk.effects |
2 | 8 | |
sandloom.sdk.errors |
0 | 30 | |
sandloom.sdk.events |
2 | 7 | |
sandloom.sdk.infra |
0 | 23 | |
sandloom.sdk.migrations |
0 | 2 | |
sandloom.sdk.module |
1 | 13 | |
sandloom.sdk.projections |
0 | 26 | |
sandloom.sdk.sagas |
0 | 16 | |
sandloom.sdk.security |
0 | 24 | |
sandloom.sdk.tasks |
0 | 3 | |
sandloom.sdk.tenant |
0 | 8 | |
sandloom.sdk.testing |
5 | 76 | |
sandloom.sdk.testing.fixtures |
0 | 28 | |
sandloom.sdk.testing.plugin |
1 | 18 | |
sandloom.sdk.tooling |
0 | 2 | |
sandloom.sdk.web |
3 | 30 |
Levels¶
Level 1 (declarative: define_module discovery, module_router, Event, on, contract, command, Contract, typed saga steps, Projection) is built only from level 2 (the primitives these pages list as advanced). The kernel (level 3) is never imported by a module. See Module internals.