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)

BatchRetryExceededError

class BatchRetryExceededError(TheorydbPyError)

ConditionFailedError

class ConditionFailedError(TheorydbPyError)

EncryptionNotConfiguredError

class EncryptionNotConfiguredError(TheorydbPyError)

ImmutableModelMutationError

class ImmutableModelMutationError(TheorydbPyError)

LeaseHeldError

class LeaseHeldError(ConditionFailedError)

LeaseNotOwnedError

class LeaseNotOwnedError(ConditionFailedError)

NotFoundError

class NotFoundError(TheorydbPyError)

ProtectedFieldMutationError

class ProtectedFieldMutationError(TheorydbPyError)

RejectedDeployAuthorityEvidenceError

class RejectedDeployAuthorityEvidenceError(TheorydbPyError)

TheorydbPyError

class TheorydbPyError(Exception)

TransactionCanceledError

class TransactionCanceledError(TheorydbPyError)

ValidationError

class ValidationError(TheorydbPyError)

VersionConflictError

class VersionConflictError(ConditionFailedError)

tabletheory_py.fakedb

StatefulDynamoDBClient

class StatefulDynamoDBClient
def reset(self) -> 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.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, 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, 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