# `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`](<https://sandloom.dev/docs/reference/sdk/authz/#authorize_resource>) | `sandloom.sdk.authz` | function | Load a resource by path id, authorize, and return it to the endpoint. |
| [`Base`](<https://sandloom.dev/docs/reference/sdk/data/#base>) | `sandloom.sdk.data` | class | Base class for all SQLAlchemy models. |
| [`command`](<https://sandloom.dev/docs/reference/sdk/contracts/#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`](<https://sandloom.dev/docs/reference/sdk/contracts/#contract>) | `sandloom.sdk.contracts` | function | The caller of contract `ref` (spec §5.3), declared at module level: |
| [`contract`](<https://sandloom.dev/docs/reference/sdk/contracts/#contract_1>) | `sandloom.sdk.contracts` | function | Declare a stateless provider class of contract `name`: |
| [`CreatedAt`](<https://sandloom.dev/docs/reference/sdk/data/#createdat>) | `sandloom.sdk.data` | annotated type |  |
| [`Credits`](<https://sandloom.dev/docs/reference/sdk/authz/#credits>) | `sandloom.sdk.authz` | class | Subject's live credit balance is at least `minimum`. |
| [`CurrentUser`](<https://sandloom.dev/docs/reference/sdk/web/#currentuser>) | `sandloom.sdk.web` | annotated type |  |
| [`db`](<https://sandloom.dev/docs/reference/sdk/data/#db>) | `sandloom.sdk.data` | function | The session of the innermost open unit of the current task (§4.3): |
| [`define_module`](<https://sandloom.dev/docs/reference/sdk/module/#define_module>) | `sandloom.sdk.module` | function | Build a module's `register(core)` from its declarations (spec §5.7). |
| [`Event`](<https://sandloom.dev/docs/reference/sdk/events/#event>) | `sandloom.sdk.events` | class | Base class of typed events: `class E(Event, channel=..., role="auto")`. |
| [`module_router`](<https://sandloom.dev/docs/reference/sdk/web/#module_router>) | `sandloom.sdk.web` | function | The module's router (spec §5.1), in `<module>/api.py`: |
| [`new_id`](<https://sandloom.dev/docs/reference/sdk/data/#new_id>) | `sandloom.sdk.data` | function | A new time-ordered id (UUIDv7, RFC 9562) for a primary key: |
| [`on`](<https://sandloom.dev/docs/reference/sdk/events/#on>) | `sandloom.sdk.events` | function | Register the decorated coroutine as a consumer of `event` (§5.4). |
| [`on_commit`](<https://sandloom.dev/docs/reference/sdk/effects/#on_commit>) | `sandloom.sdk.effects` | async function | Run `callback` only after the current Unit of Work COMMITS. |
| [`OrgRole`](<https://sandloom.dev/docs/reference/sdk/authz/#orgrole>) | `sandloom.sdk.authz` | class | Subject holds at least `minimum` role in the request's organization. |
| [`Owner`](<https://sandloom.dev/docs/reference/sdk/authz/#owner>) | `sandloom.sdk.authz` | class | Subject owns the request resource. |
| [`public`](<https://sandloom.dev/docs/reference/sdk/web/#public>) | `sandloom.sdk.web` | function | Declare a route unauthenticated, and why (ADR-0009 item 1). |
| [`record_audit`](<https://sandloom.dev/docs/reference/sdk/effects/#record_audit>) | `sandloom.sdk.effects` | function | Append an entry to the audit log within the current Unit of Work. |
| [`require`](<https://sandloom.dev/docs/reference/sdk/authz/#require>) | `sandloom.sdk.authz` | function | Return a dependency enforcing `policy` (no request resource). |
| [`Subscribed`](<https://sandloom.dev/docs/reference/sdk/authz/#subscribed>) | `sandloom.sdk.authz` | class | Subject's subscription grants access (coarse, claim-based). |
| [`SubscriptionActive`](<https://sandloom.dev/docs/reference/sdk/authz/#subscriptionactive>) | `sandloom.sdk.authz` | class | Subject's subscription is active right now (live, authoritative). |
| [`TenantScoped`](<https://sandloom.dev/docs/reference/sdk/data/#tenantscoped>) | `sandloom.sdk.data` | class | Mixin marking a model as tenant-owned (adds the indexed `tenant_id`). |
| [`as_user`](<https://sandloom.dev/docs/reference/sdk/testing/#as_user>) | `sandloom.sdk.testing` | function | `(user_id, headers)` with a freshly minted access token. |
| [`deliver`](<https://sandloom.dev/docs/reference/sdk/testing/#deliver>) | `sandloom.sdk.testing` | async function | Deliver one event to every consumer of its channel; returns how many. |
| [`fake_access_fact`](<https://sandloom.dev/docs/reference/sdk/testing/#fake_access_fact>) | `sandloom.sdk.testing` | function | Answer the access fact `name` with `value` inside the block. |
| [`fake_contract`](<https://sandloom.dev/docs/reference/sdk/testing/#fake_contract>) | `sandloom.sdk.testing` | function | Serve contract `ref` from `impl` for the block: |
| [`published`](<https://sandloom.dev/docs/reference/sdk/testing/#published>) | `sandloom.sdk.testing` | function | The events of `event`'s channel published by the code under test: |
| [`client`](<https://sandloom.dev/docs/reference/sdk/testing/plugin/#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`](<https://sandloom.dev/docs/reference/sdk/app/index.md>) | 0 | 2 |  |
| [`sandloom.sdk.authz`](<https://sandloom.dev/docs/reference/sdk/authz/index.md>) | 7 | 55 |  |
| [`sandloom.sdk.contracts`](<https://sandloom.dev/docs/reference/sdk/contracts/index.md>) | 3 | 30 |  |
| [`sandloom.sdk.data`](<https://sandloom.dev/docs/reference/sdk/data/index.md>) | 5 | 27 |  |
| [`sandloom.sdk.effects`](<https://sandloom.dev/docs/reference/sdk/effects/index.md>) | 2 | 8 |  |
| [`sandloom.sdk.errors`](<https://sandloom.dev/docs/reference/sdk/errors/index.md>) | 0 | 30 |  |
| [`sandloom.sdk.events`](<https://sandloom.dev/docs/reference/sdk/events/index.md>) | 2 | 7 |  |
| [`sandloom.sdk.infra`](<https://sandloom.dev/docs/reference/sdk/infra/index.md>) | 0 | 23 |  |
| [`sandloom.sdk.migrations`](<https://sandloom.dev/docs/reference/sdk/migrations/index.md>) | 0 | 2 |  |
| [`sandloom.sdk.module`](<https://sandloom.dev/docs/reference/sdk/module/index.md>) | 1 | 13 |  |
| [`sandloom.sdk.projections`](<https://sandloom.dev/docs/reference/sdk/projections/index.md>) | 0 | 26 |  |
| [`sandloom.sdk.sagas`](<https://sandloom.dev/docs/reference/sdk/sagas/index.md>) | 0 | 16 |  |
| [`sandloom.sdk.security`](<https://sandloom.dev/docs/reference/sdk/security/index.md>) | 0 | 24 |  |
| [`sandloom.sdk.tasks`](<https://sandloom.dev/docs/reference/sdk/tasks/index.md>) | 0 | 3 |  |
| [`sandloom.sdk.tenant`](<https://sandloom.dev/docs/reference/sdk/tenant/index.md>) | 0 | 8 |  |
| [`sandloom.sdk.testing`](<https://sandloom.dev/docs/reference/sdk/testing/index.md>) | 5 | 76 |  |
| [`sandloom.sdk.testing.fixtures`](<https://sandloom.dev/docs/reference/sdk/testing/fixtures/index.md>) | 0 | 28 |  |
| [`sandloom.sdk.testing.plugin`](<https://sandloom.dev/docs/reference/sdk/testing/plugin/index.md>) | 1 | 18 |  |
| [`sandloom.sdk.tooling`](<https://sandloom.dev/docs/reference/sdk/tooling/index.md>) | 0 | 2 |  |
| [`sandloom.sdk.web`](<https://sandloom.dev/docs/reference/sdk/web/index.md>) | 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](<https://sandloom.dev/docs/modules/guarantees/module-internals/index.md>).