Package-source copy · Generated into the site so runtime docs are searchable and linkable.

API Reference (Python)

This reference is generated from py/src/tabletheory_py source and the package __all__ export list. Do not hand-edit signatures here; run make generate-api-reference.

Drift check

make verify-api-reference

Public exports

tabletheory_py.aggregates

aggregate_field

def aggregate_field(items: Sequence[T], field: str | None=None) -> AggregateResult

AggregateResult

class AggregateResult
min: Any | None
max: Any | None
count: int
sum: float
average: float

average_field

def average_field(items: Sequence[T], field: str) -> float

count_distinct

def count_distinct(items: Sequence[T], field: str) -> int

group_by

def group_by(items: Sequence[T], field: str) -> GroupByQuery[T]

GroupByQuery

class GroupByQuery
def count(self, alias: str) -> GroupByQuery[T]
def sum(self, field: str, alias: str) -> GroupByQuery[T]
def avg(self, field: str, alias: str) -> GroupByQuery[T]
def min(self, field: str, alias: str) -> GroupByQuery[T]
def max(self, field: str, alias: str) -> GroupByQuery[T]
def having(self, aggregate: str, operator: str, value: Any) -> GroupByQuery[T]
def execute(self) -> list[GroupedResult[T]]

GroupedResult

class GroupedResult
key: Any
aggregates: dict[str, AggregateResult]
items: list[T]
count: int

max_field

def max_field(items: Sequence[T], field: str) -> Any

min_field

def min_field(items: Sequence[T], field: str) -> Any

sum_field

def sum_field(items: Sequence[T], field: str) -> float

tabletheory_py.dms

assert_model_definition_equivalent_to_dms

def assert_model_definition_equivalent_to_dms(model: ModelDefinition[Any], dms_model: Mapping[str, Any], *, ignore_table_name: bool) -> None

assert_models_equivalent

def assert_models_equivalent(got_model: ModelDefinition[Any] | Mapping[str, Any], want_model: Mapping[str, Any], *, ignore_table_name: bool=False) -> None

get_dms_model

def get_dms_model(doc: Mapping[str, Any], name: str) -> dict[str, Any]

model_definition_to_dms_model

def model_definition_to_dms_model(model: ModelDefinition[Any]) -> dict[str, Any]

parse_dms_document

def parse_dms_document(raw: str) -> dict[str, Any]

tabletheory_py.errors

AwsError

class AwsError(TheorydbPyError)
def safe_dict(self) -> dict[str, object]

BatchRetryExceededError

class BatchRetryExceededError(TheorydbPyError)
def safe_dict(self) -> dict[str, object]

CancellationReason

class CancellationReason
index: int
code: str
message: str

ConditionFailedError

class ConditionFailedError(TheorydbPyError)
def safe_dict(self) -> dict[str, object]

EncryptionNotConfiguredError

class EncryptionNotConfiguredError(TheorydbPyError)

ImmutableModelMutationError

class ImmutableModelMutationError(TheorydbPyError)

LeaseHeldError

class LeaseHeldError(ConditionFailedError)

LeaseNotOwnedError

class LeaseNotOwnedError(ConditionFailedError)

MigrationEncryptionError

class MigrationEncryptionError(TheorydbPyError)

NotFoundError

class NotFoundError(TheorydbPyError)

ProtectedFieldMutationError

class ProtectedFieldMutationError(TheorydbPyError)

RejectedDeployAuthorityEvidenceError

class RejectedDeployAuthorityEvidenceError(TheorydbPyError)

TheorydbPyError

class TheorydbPyError(Exception)
def safe_dict(self) -> dict[str, object]

ThrottledError

class ThrottledError(TransactionCanceledError)

TransactionCanceledError

class TransactionCanceledError(TheorydbPyError)
def safe_dict(self) -> dict[str, object]

TransactionConflictError

class TransactionConflictError(TransactionCanceledError)

ValidationError

class ValidationError(TheorydbPyError)

VersionConflictError

class VersionConflictError(ConditionFailedError)

tabletheory_py.fakedb

StatefulDynamoDBClient

class StatefulDynamoDBClient
def reset(self) -> None
def queue_transaction_cancellation(self, reasons: Sequence[dict[str, Any]] | None=None) -> None
def queue_transaction_error(self, err: Exception | None=None) -> None
def seed(self, table_name: str, *items: Item) -> None
def items(self, table_name: str) -> list[Item]
def create_table(self, **kwargs: Any) -> dict[str, Any]
def describe_table(self, **kwargs: Any) -> dict[str, Any]
def delete_table(self, **kwargs: Any) -> dict[str, Any]
def update_time_to_live(self, **kwargs: Any) -> dict[str, Any]
def put_item(self, **kwargs: Any) -> dict[str, Any]
def get_item(self, **kwargs: Any) -> dict[str, Any]
def update_item(self, **kwargs: Any) -> dict[str, Any]
def delete_item(self, **kwargs: Any) -> dict[str, Any]
def query(self, **kwargs: Any) -> dict[str, Any]
def scan(self, **kwargs: Any) -> dict[str, Any]
def batch_get_item(self, **kwargs: Any) -> dict[str, Any]
def batch_write_item(self, **kwargs: Any) -> dict[str, Any]
def transact_get_items(self, **kwargs: Any) -> dict[str, Any]
def transact_write_items(self, **kwargs: Any) -> dict[str, Any]

tabletheory_py.lease

Lease

class Lease
key: LeaseKey
token: str
expires_at: int

LeaseKey

class LeaseKey
pk: str
sk: str

LeaseManager

class LeaseManager
def lock_key(self, pk: str, sk: str='LOCK') -> LeaseKey
def acquire(self, key: LeaseKey, *, lease_seconds: int) -> Lease
def refresh(self, lease: Lease, *, lease_seconds: int) -> Lease
def release(self, lease: Lease) -> None

tabletheory_py.model

AttributeConverter

class AttributeConverter(Protocol)
def to_dynamodb(self, value: Any) -> Any
def from_dynamodb(self, value: Any) -> Any

gsi

def gsi(name: str, *, partition: str, sort: str | None=None, projection: Projection | None=None) -> IndexSpec

IndexDefinition

class IndexDefinition
name: str
type: str
partition: str
sort: str | None
projection: Projection

IndexSpec

class IndexSpec
name: str
type: str
partition: str
sort: str | None
projection: Projection

lsi

def lsi(name: str, *, sort: str, projection: Projection | None=None) -> IndexSpec

ModelDefinition

class ModelDefinition
model_type: type[T]
table_name: str | None
pk: AttributeDefinition
sk: AttributeDefinition | None
attributes: Mapping[str, AttributeDefinition]
indexes: tuple[IndexDefinition, ...]
write_policy: WritePolicy
def from_dataclass(cls, model_type: type[T], *, table_name: str | None=None, indexes: Sequence[IndexSpec]=(), write_policy: WritePolicy | None=None) -> ModelDefinition[T]

ModelDefinitionError

class ModelDefinitionError(ValueError)

Projection

class Projection
type: str
fields: tuple[str, ...]
def all() -> Projection
def keys_only() -> Projection
def include(*fields: str) -> Projection

Role

class Role(StrEnum)

theorydb_field

def theorydb_field(*, name: str | None=None, roles: Sequence[RoleLike] | None=None, omitempty: bool=False, set_: bool=False, json: bool=False, binary: bool=False, encrypted: bool=False, converter: AttributeConverter | None=None, ignore: bool=False, default: Any=MISSING, default_factory: Any=MISSING) -> Any

WritePolicy

class WritePolicy
mode: str
protected_attributes: Sequence[str]

tabletheory_py.multiaccount

AccountConfig

class AccountConfig
role_arn: str
external_id: str | None
region: str | None
session_duration_seconds: int
session_name: str | None
refresh_before_seconds: int

MultiAccountSessions

class MultiAccountSessions
def session(self, partner_id: str) -> Any
def client(self, partner_id: str, service: str, *, config: Any | None=None) -> Any

tabletheory_py.optimizer

QueryOptimizer

class QueryOptimizer
def explain(self, shape: QueryShape | ScanShape) -> QueryPlan

QueryPlan

class QueryPlan
id: str
operation: QueryOperation
index_name: str | None
projections: tuple[str, ...]
parallel_segments: int | None
optimization_hints: tuple[str, ...]

QueryShape

class QueryShape
kind: Literal['query']
model_name: str
table_name: str
index_name: str | None
index_type: IndexType
has_partition_key: bool
has_sort_key: bool
has_sort_condition: bool
has_filter: bool
projections: tuple[str, ...]
consistent_read: bool
scan_forward: bool

ScanShape

class ScanShape
kind: Literal['scan']
model_name: str
table_name: str
index_name: str | None
index_type: IndexType
has_filter: bool
projections: tuple[str, ...]
consistent_read: bool
parallel_scan_configured: bool
total_segments: int | None

tabletheory_py.preflight

ItemWriterPath

class ItemWriterPath(StrEnum)

marshal_item_for_writer_path

def marshal_item_for_writer_path(table: Table[T], item: T, path: ItemWriterPath) -> dict[str, Any]

tabletheory_py.protection

ConcurrencyLimiter

class ConcurrencyLimiter
def try_acquire(self) -> bool
def release(self) -> None
def acquire(self) -> Iterator[None]

SimpleLimiter

class SimpleLimiter
def allow(self) -> bool

tabletheory_py.protocols

DynamoDBClientProtocol

class DynamoDBClientProtocol(Protocol)
def query(self, **kwargs: Any) -> Mapping[str, Any]
def scan(self, **kwargs: Any) -> Mapping[str, Any]
def batch_get_item(self, **kwargs: Any) -> Mapping[str, Any]
def batch_write_item(self, **kwargs: Any) -> Mapping[str, Any]
def transact_get_items(self, **kwargs: Any) -> Mapping[str, Any]
def transact_write_items(self, **kwargs: Any) -> Mapping[str, Any]
def put_item(self, **kwargs: Any) -> Mapping[str, Any]
def get_item(self, **kwargs: Any) -> Mapping[str, Any]
def delete_item(self, **kwargs: Any) -> Mapping[str, Any]
def update_item(self, **kwargs: Any) -> Mapping[str, Any]

tabletheory_py.query

FilterCondition

class FilterCondition
field: str
op: str
values: tuple[Any, ...]
def eq(field: str, value: Any) -> FilterCondition
def ne(field: str, value: Any) -> FilterCondition
def lt(field: str, value: Any) -> FilterCondition
def lte(field: str, value: Any) -> FilterCondition
def gt(field: str, value: Any) -> FilterCondition
def gte(field: str, value: Any) -> FilterCondition
def between(field: str, low: Any, high: Any) -> FilterCondition
def begins_with(field: str, prefix: Any) -> FilterCondition
def contains(field: str, value: Any) -> FilterCondition
def in_(field: str, values: list[Any]) -> FilterCondition
def exists(field: str) -> FilterCondition
def not_exists(field: str) -> FilterCondition

FilterGroup

class FilterGroup
op: LogicalOp
filters: tuple[FilterExpression, ...]
def and_(*filters: FilterExpression) -> FilterGroup
def or_(*filters: FilterExpression) -> FilterGroup

Page

class Page
items: list[T]
next_cursor: str | None

SortKeyCondition

class SortKeyCondition
op: str
values: tuple[Any, ...]
def eq(value: Any) -> SortKeyCondition
def lt(value: Any) -> SortKeyCondition
def lte(value: Any) -> SortKeyCondition
def gt(value: Any) -> SortKeyCondition
def gte(value: Any) -> SortKeyCondition
def between(low: Any, high: Any) -> SortKeyCondition
def begins_with(prefix: Any) -> SortKeyCondition

tabletheory_py.release_state

transition_release_state

def transition_release_state(actual_table: Table[Any], event_table: Table[Any], *, actual_key: Mapping[str, Any], set_values: Mapping[str, Any], event_item: Any, outbox_item: Any | None=None, outbox_table: Table[Any] | None=None, expected_version: int | None=None, version_field: str='version') -> None

validate_deploy_authority_metadata

def validate_deploy_authority_metadata(item: Mapping[str, Any]) -> None

tabletheory_py.runtime

AwsCallMetric

class AwsCallMetric
service: str
operation: str
seconds: float
ok: bool

check_lambda_timeout

def check_lambda_timeout(context: Any, *, buffer_seconds: float=DEFAULT_LAMBDA_TIMEOUT_BUFFER_SECONDS) -> None

create_lambda_boto3_config

def create_lambda_boto3_config(*, connect_timeout: float=1.0, read_timeout: float=3.0, max_attempts: int=3) -> Config

get_lambda_boto3_client

def get_lambda_boto3_client(service: str, *, region: str | None=None, config: Config | None=None, session: Any | None=None, metrics: Callable[[AwsCallMetric], None] | None=None) -> Any

get_lambda_dynamodb_client

def get_lambda_dynamodb_client(*, region: str | None=None, config: Config | None=None, metrics: Callable[[AwsCallMetric], None] | None=None) -> Any

get_lambda_kms_client

def get_lambda_kms_client(*, region: str | None=None, config: Config | None=None, metrics: Callable[[AwsCallMetric], None] | None=None) -> Any

instrument_boto3_client

def instrument_boto3_client(client: Any, *, service: str, on_call: Callable[[AwsCallMetric], None]) -> Any

is_lambda_environment

def is_lambda_environment(environ: Mapping[str, str]=os.environ) -> bool

LambdaTimeoutConfig

class LambdaTimeoutConfig
buffer_seconds: float

with_lambda_timeout

def with_lambda_timeout(client: Any, context: Any, *, buffer_seconds: float=DEFAULT_LAMBDA_TIMEOUT_BUFFER_SECONDS) -> Any

tabletheory_py.schema

build_create_table_request

def build_create_table_request(model: ModelDefinition[Any], *, table_name: str | None=None, billing_mode: BillingMode='PAY_PER_REQUEST', provisioned_throughput: dict[str, int] | None=None) -> dict[str, Any]

create_table

def create_table(model: ModelDefinition[Any], *, client: Any | None=None, table_name: str | None=None, billing_mode: BillingMode='PAY_PER_REQUEST', provisioned_throughput: dict[str, int] | None=None, wait_for_active: bool=True, wait_timeout_seconds: float=300.0, poll_interval_seconds: float=0.25, sleep: Callable[[float], None]=time.sleep) -> None

delete_table

def delete_table(model: ModelDefinition[Any], *, client: Any | None=None, table_name: str | None=None, wait_for_delete: bool=True, wait_timeout_seconds: float=300.0, poll_interval_seconds: float=0.25, ignore_missing: bool=False, sleep: Callable[[float], None]=time.sleep) -> None

describe_table

def describe_table(model: ModelDefinition[Any], *, client: Any | None=None, table_name: str | None=None) -> dict[str, Any]

ensure_table

def ensure_table(model: ModelDefinition[Any], *, client: Any | None=None, table_name: str | None=None, billing_mode: BillingMode='PAY_PER_REQUEST', provisioned_throughput: dict[str, int] | None=None, wait_for_active: bool=True, wait_timeout_seconds: float=300.0, poll_interval_seconds: float=0.25, sleep: Callable[[float], None]=time.sleep) -> None

resolve_ttl_attribute

def resolve_ttl_attribute(model: ModelDefinition[Any]) -> str | None

update_time_to_live

def update_time_to_live(model: ModelDefinition[Any], *, client: Any | None=None, table_name: str | None=None, attribute_name: str | None=None, enabled: bool=True) -> None

tabletheory_py.schema_migration

add_field

def add_field(name: str, value: Any) -> MigrationTransform

auto_migrate

def auto_migrate(source_model: ModelDefinition[Any], *, client: Any | None=None, target_model: ModelDefinition[Any] | None=None, transform: MigrationTransform | None=None, backup_table: str | None=None, batch_size: int | None=None, data_copy: bool=False, kms_key_arn: str | None=None, kms_client: Any | None=None, rand_bytes: Callable[[int], bytes] | None=None, sleep: Callable[[float], None]=time.sleep) -> None

chain_transforms

def chain_transforms(*transforms: MigrationTransform) -> MigrationTransform

copy_all_fields

def copy_all_fields() -> MigrationTransform

remove_field

def remove_field(name: str) -> MigrationTransform

rename_field

def rename_field(old_name: str, new_name: str) -> MigrationTransform

tabletheory_py.streams

unmarshal_stream_image

def unmarshal_stream_image(model: ModelDefinition[T], stream_image: Any) -> T

unmarshal_stream_record

def unmarshal_stream_record(model: ModelDefinition[T], record: Any, *, image: str='NewImage') -> T | None

tabletheory_py.table

Table

class Table
def with_lambda_timeout(self, context: Any, *, buffer_seconds: float=DEFAULT_LAMBDA_TIMEOUT_BUFFER_SECONDS) -> Table[T]
def query(self, partition: Any, *, sort: SortKeyCondition | None=None, index_name: str | None=None, limit: int | None=None, cursor: str | None=None, scan_forward: bool=True, consistent_read: bool=False, projection: list[str] | None=None, filter: FilterExpression | None=None) -> Page[T]
def query_count(self, partition: Any, *, sort: SortKeyCondition | None=None, index_name: str | None=None, limit: int | None=None, cursor: str | None=None, scan_forward: bool=True, consistent_read: bool=False, projection: list[str] | None=None, filter: FilterExpression | None=None) -> int
def query_with_retry(self, partition: Any, *, sort: SortKeyCondition | None=None, index_name: str | None=None, limit: int | None=None, cursor: str | None=None, scan_forward: bool=True, consistent_read: bool=False, projection: list[str] | None=None, filter: FilterExpression | None=None, max_retries: int=5, initial_delay_seconds: float=0.1, max_delay_seconds: float=5.0, backoff_factor: float=2.0, retry_on_empty: bool=True, retry_on_error: bool=True, verify: Callable[[Page[T]], bool] | None=None, sleep: Callable[[float], None]=time.sleep) -> Page[T]
def query_all(self, partition: Any, *, sort: SortKeyCondition | None=None, index_name: str | None=None, limit: int | None=None, cursor: str | None=None, scan_forward: bool=True, consistent_read: bool=False, projection: list[str] | None=None, filter: FilterExpression | None=None) -> list[T]
def query_iter(self, partition: Any, *, sort: SortKeyCondition | None=None, index_name: str | None=None, limit: int | None=None, cursor: str | None=None, scan_forward: bool=True, consistent_read: bool=False, projection: list[str] | None=None, filter: FilterExpression | None=None) -> Iterator[Page[T]]
def describe_query(self, partition: Any | None=None, *, sort: SortKeyCondition | None=None, index_name: str | None=None, scan_forward: bool=True, consistent_read: bool=False, projection: list[str] | None=None, filter: FilterExpression | None=None) -> QueryShape
def scan(self, *, index_name: str | None=None, limit: int | None=None, cursor: str | None=None, consistent_read: bool=False, projection: list[str] | None=None, filter: FilterExpression | None=None, segment: int | None=None, total_segments: int | None=None) -> Page[T]
def scan_count(self, *, index_name: str | None=None, limit: int | None=None, cursor: str | None=None, consistent_read: bool=False, projection: list[str] | None=None, filter: FilterExpression | None=None, segment: int | None=None, total_segments: int | None=None) -> int
def scan_all(self, *, index_name: str | None=None, limit: int | None=None, cursor: str | None=None, consistent_read: bool=False, projection: list[str] | None=None, filter: FilterExpression | None=None, segment: int | None=None, total_segments: int | None=None) -> list[T]
def scan_iter(self, *, index_name: str | None=None, limit: int | None=None, cursor: str | None=None, consistent_read: bool=False, projection: list[str] | None=None, filter: FilterExpression | None=None, segment: int | None=None, total_segments: int | None=None) -> Iterator[Page[T]]
def describe_scan(self, *, index_name: str | None=None, consistent_read: bool=False, projection: list[str] | None=None, filter: FilterExpression | None=None, segment: int | None=None, total_segments: int | None=None) -> ScanShape
def scan_with_retry(self, *, index_name: str | None=None, limit: int | None=None, cursor: str | None=None, consistent_read: bool=False, projection: list[str] | None=None, filter: FilterExpression | None=None, max_retries: int=5, initial_delay_seconds: float=0.1, max_delay_seconds: float=5.0, backoff_factor: float=2.0, retry_on_empty: bool=True, retry_on_error: bool=True, verify: Callable[[Page[T]], bool] | None=None, sleep: Callable[[float], None]=time.sleep) -> Page[T]
def scan_all_segments(self, *, total_segments: int, index_name: str | None=None, limit: int | None=None, consistent_read: bool=False, projection: list[str] | None=None, filter: FilterExpression | None=None, max_workers: int | None=None) -> list[T]
def batch_get(self, keys: Sequence[Any], *, consistent_read: bool=False, projection: list[str] | None=None, max_retries: int=5, sleep: Callable[[float], None] | None=time.sleep) -> list[T]
def batch_write(self, *, puts: Sequence[T]=(), deletes: Sequence[Any]=(), max_retries: int=5, sleep: Callable[[float], None] | None=time.sleep) -> None
def transact_get(self, keys: Sequence[Any], *, projection: list[str] | None=None) -> list[T | None]
def transact_write(self, actions: Sequence[TransactWriteAction[T]]) -> None
def put(self, item: T, *, condition_expression: str | None=None, expression_attribute_names: Mapping[str, str] | None=None, expression_attribute_values: Mapping[str, Any] | None=None) -> None
def save(self, item: T, *, condition_expression: str | None=None, expression_attribute_names: Mapping[str, str] | None=None, expression_attribute_values: Mapping[str, Any] | None=None) -> None
def get(self, pk: Any, sk: Any | None=None, *, consistent_read: bool=False) -> T
def get_or_none(self, pk: Any, sk: Any | None=None, *, consistent_read: bool=False) -> T | None
def delete(self, pk: Any, sk: Any | None=None, *, condition_expression: str | None=None, expression_attribute_names: Mapping[str, str] | None=None, expression_attribute_values: Mapping[str, Any] | None=None) -> None
def update(self, pk: Any, sk: Any | None, updates: Mapping[str, Any], *, condition_expression: str | None=None, expression_attribute_names: Mapping[str, str] | None=None, expression_attribute_values: Mapping[str, Any] | None=None, protected_attributes: Sequence[str]=(), expected_version: int | None=None) -> T
def update_builder(self, pk: Any, sk: Any | None=None) -> UpdateBuilder[T]

tabletheory_py.transaction

TransactConditionCheck

class TransactConditionCheck
pk: Any
sk: Any | None
condition_expression: str
expression_attribute_names: Mapping[str, str] | None
expression_attribute_values: Mapping[str, Any] | None

TransactDelete

class TransactDelete
pk: Any
sk: Any | None
condition_expression: str | None
expression_attribute_names: Mapping[str, str] | None
expression_attribute_values: Mapping[str, Any] | None

TransactPut

class TransactPut
item: T
condition_expression: str | None
expression_attribute_names: Mapping[str, str] | None
expression_attribute_values: Mapping[str, Any] | None

TransactUpdate

class TransactUpdate
pk: Any
sk: Any | None
updates: Mapping[str, Any]
condition_expression: str | None
expression_attribute_names: Mapping[str, str] | None
expression_attribute_values: Mapping[str, Any] | None
protected_attributes: Sequence[str]

UpdateAdd

class UpdateAdd
value: Any

UpdateSetIfNotExists

class UpdateSetIfNotExists
default_value: Any

tabletheory_py.validation

SecurityValidationError

class SecurityValidationError(Exception)

validate_expression

def validate_expression(expression: str) -> None

validate_field_name

def validate_field_name(field: str) -> None

validate_index_name

def validate_index_name(name: str) -> None

validate_operator

def validate_operator(op: str) -> None

validate_table_name

def validate_table_name(name: str) -> None

validate_value

def validate_value(value: Any) -> None

Re-exported values without source signatures

These names are exported constants, aliases, or lazy imports that do not have a direct function/class signature:

DEFAULT_LAMBDA_TIMEOUT_BUFFER_SECONDS, MaxExpressionLength, MaxFieldNameLength, MaxNestedDepth, MaxOperatorLength, MaxValueStringLength, TransactWriteAction, evaluate_derived_key, evaluate_derived_key_definition, load_key_contract_file, parse_derived_key_contract, verify_derived_key_fixtures