Python API Reference

These pages document the authored Python API that provider authors use to build Gestalt integrations, authentication providers, caches, and S3 backends.

Public authoring surface for Gestalt Python providers.

The package is published as gestalt-sdk and imported as gestalt. Provider authors typically build integrations around the re-exported symbols documented in the Sphinx reference:

from gestalt import Model, Plugin, operation

class SearchInput(Model):
    query: str

plugin = Plugin("search")

@plugin.operation(title="Search")
def search(params: SearchInput):
    return {"query": params.query}

Generated protobuf bindings remain available under gestalt.gen, but the authored reference documentation focuses on the handwritten SDK surface.

The supported import surface is the top-level gestalt package:

from gestalt import Model, Plugin, Cache, IndexedDB, S3

Generated protobuf bindings remain available through gestalt.gen, but the authored reference below focuses on the handwritten SDK API that provider authors use directly.

Core authoring types

Model	Base class for operation input and output models.
field	Declare a model field with catalog metadata.
Subject	Identity information attached to an incoming provider request.
Credential	Credential metadata resolved by the Gestalt host for the request.
Access	Authorization context resolved for the request.
Request	Host-provided request context for an operation invocation.
Response	Structured operation response with an explicit HTTP status.
OK	Wrap body in a success response with status 200 OK.
Error	Application error raised by a provider operation.

class Model

Base class for operation input and output models.

Subclasses are automatically converted into dataclasses, so provider authors can declare request and response types with normal annotations:

class SearchInput(Model):
    query: str = field(description="Search term")

field(*, description='', default=MISSING, default_factory=MISSING, required=None)

Declare a model field with catalog metadata.

Parameters:

• description (str) – Human-readable parameter description exported to the generated catalog.

• default (Any) – Explicit default value for the field.

• default_factory (Any) – Callable used to create the default value.

• required (bool | None) – Override the inferred required flag in the generated catalog.

Return type:

Any

class Subject(id='', kind='', display_name='', auth_source='')

Identity information attached to an incoming provider request.

Parameters:

• id (str)

• kind (str)

• display_name (str)

• auth_source (str)

class Credential(mode='', subject_id='', connection='', instance='')

Credential metadata resolved by the Gestalt host for the request.

Parameters:

• mode (str)

• subject_id (str)

• connection (str)

• instance (str)

class Access(policy='', role='')

Authorization context resolved for the request.

Parameters:

• policy (str)

• role (str)

class Request(token='', connection_params=<factory>, subject=<factory>, credential=<factory>, access=<factory>, invocation_token='', workflow=<factory>)

Host-provided request context for an operation invocation.

Parameters:

• token (str)

• connection_params (dict[str, str])

• subject (Subject)

• credential (Credential)

• access (Access)

• invocation_token (str)

• workflow (dict[str, Any])

class Response(status, body)

Structured operation response with an explicit HTTP status.

Parameters:

• status (int | None)

• body (T)

OK(body)

Wrap body in a success response with status 200 OK.

Parameters:

body (T)

Return type:

Response[T]

exception Error(status, message='')

Application error raised by a provider operation.

Parameters:

• status (int | HTTPStatus)

• message (str)

Return type:

None

Plugin authoring

Plugin	Integration plugin definition and operation registry.
operation	Register an operation on the calling module's implicit plugin.
session_catalog	Register a per-request catalog hook on the implicit module plugin.
SessionCatalogProvider	Protocol for plugins that return a per-request catalog.
Catalog
CatalogOperation
CatalogParameter
OperationAnnotations

class Plugin(name, *, module_name=None)

Integration plugin definition and operation registry.

Plugin collects operation handlers, optional configuration hooks, and optional session catalog hooks before handing control to the runtime:

from gestalt import Model, Plugin

class SearchInput(Model):
    query: str

plugin = Plugin("search")

@plugin.operation(title="Search")
def search(params: SearchInput):
    return {"query": params.query}

Parameters:

• name (str)

• module_name (str | None)

classmethod from_manifest(path, *, base_dir=None)

Build a plugin name from a manifest path.

Parameters:

• path (str | Path)

• base_dir (Path | None)

Return type:

Plugin

configure(func)

Register a configuration hook for provider name and config data.

Parameters:

func (Any)

Return type:

Any

session_catalog(func)

Register a per-request catalog hook.

Parameters:

func (Any)

Return type:

Any

post_connect(func)

Register a connect-time metadata hook.

Parameters:

func (Any)

Return type:

Any

http_subject(func)

Register a hosted HTTP subject-resolution hook.

Parameters:

func (Any)

Return type:

Any

operation(func=None, /, *, id=None, method=DEFAULT_OPERATION_METHOD, title='', description='', allowed_roles=None, tags=None, read_only=False, visible=None)

Register an operation handler on this plugin.

Parameters:

• func (Any | None)

• id (str | None)

• method (str)

• title (str)

• description (str)

• allowed_roles (list[str] | None)

• tags (list[str] | None)

• read_only (bool)

• visible (bool | None)

Return type:

Any

configure_provider(name, config)

Invoke the registered configuration hook if one exists.

Parameters:

• name (str)

• config (dict[str, Any])

Return type:

None

execute(operation, params, request)

Execute a registered operation against request parameters.

Parameters:

• operation (str)

• params (dict[str, Any])

• request (Request)

Return type:

OperationResult

catalog_dict()

Return the static plugin catalog as a plain dictionary.

Return type:

dict[str, Any]

write_catalog(path)

Write the static plugin catalog to disk.

Parameters:

path (str | Path)

Return type:

None

supports_session_catalog()

Report whether the plugin exposes a session catalog hook.

Return type:

bool

supports_post_connect()

Report whether the plugin exposes a post-connect metadata hook.

Return type:

bool

supports_http_subject()

Report whether the plugin exposes a hosted HTTP subject hook.

Return type:

bool

catalog_for_request(request)

Return a per-request catalog if the plugin defines one.

Parameters:

request (Request)

Return type:

Catalog | dict[str, Any] | None

post_connect_metadata(token)

Return additional stored metadata after a connection is established.

Parameters:

token (ConnectedToken)

Return type:

dict[str, str] | None

resolve_http_subject(request, context)

Resolve an incoming hosted HTTP request to a Gestalt subject.

Parameters:

• request (HTTPSubjectRequest)

• context (Request)

Return type:

Subject | None

serve()

Start the integration runtime for this plugin.

Return type:

None

operation(func=None, /, *, id=None, method=DEFAULT_OPERATION_METHOD, title='', description='', allowed_roles=None, tags=None, read_only=False, visible=None)

Register an operation on the calling module’s implicit plugin.

This decorator is useful when a module-level plugin object would be redundant:

from gestalt import Model, operation

class SearchInput(Model):
    query: str

@operation(title="Search")
def search(params: SearchInput):
    return {"query": params.query}

Parameters:

• func (Any | None)

• id (str | None)

• method (str)

• title (str)

• description (str)

• allowed_roles (list[str] | None)

• tags (list[str] | None)

• read_only (bool)

• visible (bool | None)

Return type:

Any

session_catalog(func=None, /)

Register a per-request catalog hook on the implicit module plugin.

Parameters:

func (Any | None)

Return type:

Any

class SessionCatalogProvider(*args, **kwargs)

Protocol for plugins that return a per-request catalog.

Catalog protocol types

These top-level exports are generated protocol message types that the SDK re-exports for lower-level catalog integration work.

Catalog
CatalogOperation
CatalogParameter
OperationAnnotations

class Catalog

class CatalogOperation

class CatalogParameter

class OperationAnnotations

Provider interfaces

ProviderKind	Runtime kinds supported by the Python SDK.
ProviderMetadata	Descriptive metadata returned by MetadataProvider.
PluginProvider	Base interface shared by provider-style runtimes.
MetadataProvider	Optional mixin for providers that expose descriptive metadata.
HealthChecker	Optional mixin for providers that support health checks.
WarningsProvider	Optional mixin for providers that emit startup warnings.
Closer	Optional mixin for providers with explicit shutdown work.
PluginProviderAdapter	Wrap a provider and registration callback for integration runtimes.
AuthenticationProvider	Base class for authentication providers.
ExternalTokenValidator	Optional mixin for providers that validate external bearer tokens.
SessionTTLProvider	Optional mixin for providers that control session lifetimes.
SecretsProvider	Base class for secret-provider runtimes.
CacheProvider	Base class for cache-provider runtimes.
S3Provider	Base class for S3-compatible object store runtimes.
AuthenticatedUser
BeginLoginRequest
BeginLoginResponse
CompleteLoginRequest

class ProviderKind(value)

Runtime kinds supported by the Python SDK.

class ProviderMetadata(kind, name='', display_name='', description='', version='')

Descriptive metadata returned by MetadataProvider.

Parameters:

• kind (ProviderKind | str)

• name (str)

• display_name (str)

• description (str)

• version (str)

class PluginProvider

Base interface shared by provider-style runtimes.

configure(name, config)

Apply the host-provided provider name and parsed configuration.

Parameters:

• name (str)

• config (dict[str, Any])

Return type:

None

class MetadataProvider

Optional mixin for providers that expose descriptive metadata.

metadata()

Return metadata for the running provider instance.

Return type:

ProviderMetadata

class HealthChecker

Optional mixin for providers that support health checks.

health_check()

Raise if the provider is unhealthy.

Return type:

None

class WarningsProvider

Optional mixin for providers that emit startup warnings.

warnings()

Return human-readable warnings for the host to surface.

Return type:

list[str]

class Closer

Optional mixin for providers with explicit shutdown work.

close()

Release any provider resources before the process exits.

Return type:

None

class PluginProviderAdapter(kind, provider, register_services)

Wrap a provider and registration callback for integration runtimes.

Parameters:

• kind (ProviderKind | str)

• provider (PluginProvider)

• register_services (RegisterServices)

serve()

Start the provider’s gRPC runtime.

Return type:

None

class AuthenticationProvider

Base class for authentication providers.

begin_login(request)

Begin an interactive login flow.

Parameters:

request (Any)

Return type:

Any

complete_login(request)

Complete an interactive login flow.

Parameters:

request (Any)

Return type:

Any

serve()

Start the authentication runtime.

Return type:

None

class ExternalTokenValidator

Optional mixin for providers that validate external bearer tokens.

validate_external_token(token)

Validate a bearer token and return the authenticated subject.

Parameters:

token (str)

Return type:

Any

class SessionTTLProvider

Optional mixin for providers that control session lifetimes.

session_ttl()

Return the requested session time-to-live.

Return type:

timedelta

class SecretsProvider

Base class for secret-provider runtimes.

get_secret(name)

Return a secret value by name.

Parameters:

name (str)

Return type:

str

serve()

Start the secrets runtime.

Return type:

None

class CacheProvider

Base class for cache-provider runtimes.

get(key)

Return a cached value or None if the key is missing.

Parameters:

key (str)

Return type:

bytes | None

get_many(keys)

Return the subset of keys that currently exist.

Parameters:

keys (list[str])

Return type:

dict[str, bytes]

set(key, value, ttl=None)

Store value for key with an optional time-to-live.

Parameters:

• key (str)

• value (bytes)

• ttl (timedelta | None)

Return type:

None

set_many(entries, ttl=None)

Store multiple cache entries using repeated set() calls.

Parameters:

• entries (list[CacheEntry])

• ttl (dt.timedelta | None)

Return type:

None

delete(key)

Delete a cache entry and report whether it existed.

Parameters:

key (str)

Return type:

bool

delete_many(keys)

Delete a batch of cache keys and return the number removed.

Parameters:

keys (list[str])

Return type:

int

touch(key, ttl)

Refresh the TTL for an existing key.

Parameters:

• key (str)

• ttl (timedelta)

Return type:

bool

serve()

Start the cache runtime.

Return type:

None

class S3Provider

Base class for S3-compatible object store runtimes.

serve()

Start the S3 runtime.

Return type:

None

Auth protocol types

These generated authentication message types are also re-exported from gestalt so provider code can type or construct lower-level protocol payloads without reaching into private modules.

AuthenticatedUser
BeginLoginRequest
BeginLoginResponse
CompleteLoginRequest

class AuthenticatedUser

class BeginLoginRequest

class BeginLoginResponse

class CompleteLoginRequest

Cache client

CacheEntry	Cache key and value pair used by batch operations.
Cache	Client for a host-provided Gestalt cache provider.
cache_socket_env	Return the environment variable name for a cache socket binding.

class CacheEntry(key, value)

Cache key and value pair used by batch operations.

Parameters:

• key (str)

• value (bytes)

class Cache(name=None)

Client for a host-provided Gestalt cache provider.

Parameters:

name (str | None)

close()

Close the underlying gRPC channel.

Return type:

None

get(key)

Return the cached value for key if it exists.

Parameters:

key (str)

Return type:

bytes | None

get_many(keys)

Return the subset of keys that currently exist.

Parameters:

keys (list[str])

Return type:

dict[str, bytes]

set(key, value, ttl=None)

Store value for key with an optional TTL.

Parameters:

• key (str)

• value (bytes)

• ttl (timedelta | None)

Return type:

None

set_many(entries, ttl=None)

Store multiple cache entries with one RPC.

Parameters:

• entries (Iterable[CacheEntry])

• ttl (timedelta | None)

Return type:

None

delete(key)

Delete key and return whether an entry existed.

Parameters:

key (str)

Return type:

bool

delete_many(keys)

Delete multiple keys and return the number removed.

Parameters:

keys (list[str])

Return type:

int

touch(key, ttl)

Refresh the TTL for key if the entry exists.

Parameters:

• key (str)

• ttl (timedelta)

Return type:

bool

__enter__()

Return the cache client for with statements.

Return type:

Cache

__exit__(*args)

Close the cache client at the end of a context manager block.

Parameters:

args (Any)

Return type:

None

cache_socket_env(name=None)

Return the environment variable name for a cache socket binding.

Parameters:

name (str | None)

Return type:

str

IndexedDB client

CURSOR_NEXT	int([x]) -> integer int(x, base=10) -> integer
CURSOR_NEXT_UNIQUE	int([x]) -> integer int(x, base=10) -> integer
CURSOR_PREV	int([x]) -> integer int(x, base=10) -> integer
CURSOR_PREV_UNIQUE	int([x]) -> integer int(x, base=10) -> integer
indexeddb_socket_env	Return the environment variable name for an IndexedDB socket binding.
NotFoundError	Raised when an IndexedDB record, store, or cursor target is missing.
AlreadyExistsError	Raised when an IndexedDB object already exists.
KeyRange	Lower and upper bounds for a cursor or range query.
IndexSchema	Definition for an index within an object store.
ObjectStoreSchema	Schema definition for an object store.
IndexedDB	Client for a host-provided IndexedDB-compatible store.
ObjectStore	Client bound to a single IndexedDB object store.
Index	Client bound to a secondary index on an object store.
Cursor	Stateful cursor over object store or index results.

CURSOR_NEXT = 0

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

CURSOR_NEXT_UNIQUE = 1

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

CURSOR_PREV = 2

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

CURSOR_PREV_UNIQUE = 3

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

indexeddb_socket_env(name=None)

Return the environment variable name for an IndexedDB socket binding.

Parameters:

name (str | None)

Return type:

str

exception NotFoundError

Raised when an IndexedDB record, store, or cursor target is missing.

exception AlreadyExistsError

Raised when an IndexedDB object already exists.

class KeyRange(lower=None, upper=None, lower_open=False, upper_open=False)

Lower and upper bounds for a cursor or range query.

Parameters:

• lower (Any)

• upper (Any)

• lower_open (bool)

• upper_open (bool)

class IndexSchema(name, key_path=<factory>, unique=False)

Definition for an index within an object store.

Parameters:

• name (str)

• key_path (list[str])

• unique (bool)

class ObjectStoreSchema(indexes=<factory>)

Schema definition for an object store.

Parameters:

indexes (list[IndexSchema])

class IndexedDB(name=None)

Client for a host-provided IndexedDB-compatible store.

Parameters:

name (str | None)

close()

Close the underlying gRPC channel.

Return type:

None

create_object_store(name, schema=None)

Create an object store with an optional schema.

Parameters:

• name (str)

• schema (ObjectStoreSchema | None)

Return type:

None

delete_object_store(name)

Delete an object store by name.

Parameters:

name (str)

Return type:

None

object_store(name)

Return a client bound to an object store.

Parameters:

name (str)

Return type:

ObjectStore

transaction(stores, mode='readonly', *, durability_hint='default')

Start an explicit IndexedDB transaction.

Parameters:

• stores (list[str])

• mode (str)

• durability_hint (str)

Return type:

Transaction

__enter__()

Return the client for with statements.

Return type:

IndexedDB

__exit__(*args)

Close the client at the end of a context manager block.

Parameters:

args (Any)

Return type:

None

class ObjectStore(stub, store)

Client bound to a single IndexedDB object store.

Parameters:

• stub (Any)

• store (str)

get(id)

Fetch a record by primary key.

Parameters:

id (str)

Return type:

dict[str, Any]

get_key(id)

Return the canonical key for a primary key lookup.

Parameters:

id (str)

Return type:

str

add(record)

Insert a new record.

Parameters:

record (dict[str, Any])

Return type:

None

put(record)

Insert or replace a record.

Parameters:

record (dict[str, Any])

Return type:

None

delete(id)

Delete a record by primary key.

Parameters:

id (str)

Return type:

None

clear()

Delete every record in the store.

Return type:

None

get_all(key_range=None)

Return all records that fall within key_range.

Parameters:

key_range (KeyRange | None)

Return type:

list[dict[str, Any]]

get_all_keys(key_range=None)

Return all primary keys that fall within key_range.

Parameters:

key_range (KeyRange | None)

Return type:

list[str]

count(key_range=None)

Return the number of matching records.

Parameters:

key_range (KeyRange | None)

Return type:

int

delete_range(key_range)

Delete all records within key_range.

Parameters:

key_range (KeyRange)

Return type:

int

open_cursor(key_range=None, direction=CURSOR_NEXT)

Open a record cursor over the store.

Parameters:

• key_range (KeyRange | None)

• direction (int)

Return type:

Cursor

open_key_cursor(key_range=None, direction=CURSOR_NEXT)

Open a key-only cursor over the store.

Parameters:

• key_range (KeyRange | None)

• direction (int)

Return type:

Cursor

index(name)

Return a client for a named index on this store.

Parameters:

name (str)

Return type:

Index

class Index(stub, store, index)

Client bound to a secondary index on an object store.

Parameters:

• stub (Any)

• store (str)

• index (str)

get(*values)

Fetch the first matching record for the indexed values.

Parameters:

values (Any)

Return type:

dict[str, Any]

get_key(*values)

Fetch the first matching primary key for the indexed values.

Parameters:

values (Any)

Return type:

str

get_all(*values, key_range=None)

Return all records matching the indexed values and key range.

Parameters:

• values (Any)

• key_range (KeyRange | None)

Return type:

list[dict[str, Any]]

get_all_keys(*values, key_range=None)

Return all primary keys matching the indexed values and key range.

Parameters:

• values (Any)

• key_range (KeyRange | None)

Return type:

list[str]

count(*values, key_range=None)

Return the number of records matching the indexed values.

Parameters:

• values (Any)

• key_range (KeyRange | None)

Return type:

int

delete(*values)

Delete records matching the indexed values.

Parameters:

values (Any)

Return type:

int

open_cursor(*values, key_range=None, direction=CURSOR_NEXT)

Open a record cursor over the indexed results.

Parameters:

• values (Any)

• key_range (KeyRange | None)

• direction (int)

Return type:

Cursor

open_key_cursor(*values, key_range=None, direction=CURSOR_NEXT)

Open a key-only cursor over the indexed results.

Parameters:

• values (Any)

• key_range (KeyRange | None)

• direction (int)

Return type:

Cursor

class Cursor(stub, store, *, key_range=None, direction=CURSOR_NEXT, keys_only=False, index='', values=())

Stateful cursor over object store or index results.

Parameters:

• stub (Any)

• store (str)

• key_range (KeyRange | None)

• direction (int)

• keys_only (bool)

• index (str)

• values (tuple[Any, ...])

continue_()

Advance to the next matching cursor entry.

Return type:

bool

continue_to_key(key)

Advance the cursor to key or the next greater entry.

Parameters:

key (Any)

Return type:

bool

advance(count)

Skip forward by count entries.

Parameters:

count (int)

Return type:

bool

property key: Any

Current key for the cursor entry.

property primary_key: str | None

Current primary key for the cursor entry.

property value: dict[str, Any]

Current record value for the cursor entry.

delete()

Delete the current cursor entry.

Return type:

None

update(value)

Replace the current cursor entry with value.

Parameters:

value (dict[str, Any])

Return type:

None

close()

Close the cursor stream.

Return type:

None

__enter__()

Return the cursor for with statements.

Return type:

Cursor

__exit__(*args)

Close the cursor at the end of a context manager block.

Parameters:

args (Any)

Return type:

None

S3 client

ENV_S3_SOCKET	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
s3_socket_env	Return the environment variable name for an S3 socket binding.
S3NotFoundError	Raised when the requested object does not exist.
S3PreconditionFailedError	Raised when conditional request headers fail.
S3InvalidRangeError	Raised when a requested byte range is invalid.
ObjectRef	Reference to an S3 object, optionally pinned to a version.
ObjectMeta	Object metadata returned by S3 operations.
ByteRange	Inclusive byte range used for object reads.
ReadOptions	Conditional and ranged read options for an object request.
WriteOptions	Metadata and precondition options for object writes.
ListOptions	Query options for listing objects within a bucket.
ListPage	One page of object-listing results.
CopyOptions	Conditional headers for copy operations.
PresignMethod	HTTP methods supported by presigned object URLs.
PresignOptions	Options for generating a presigned object URL.
PresignResult	Presigned URL response returned by the provider.
S3ReadStream	Streaming object body reader returned by S3.read_object().
S3	Client for a host-provided Gestalt S3 runtime.
S3Object	Convenience wrapper for a single S3 object reference.

ENV_S3_SOCKET = 'GESTALT_S3_SOCKET'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

s3_socket_env(name=None)

Return the environment variable name for an S3 socket binding.

Parameters:

name (str | None)

Return type:

str

exception S3NotFoundError

Raised when the requested object does not exist.

exception S3PreconditionFailedError

Raised when conditional request headers fail.

exception S3InvalidRangeError

Raised when a requested byte range is invalid.

class ObjectRef(bucket, key, version_id='')

Reference to an S3 object, optionally pinned to a version.

Parameters:

• bucket (str)

• key (str)

• version_id (str)

class ObjectMeta(ref, etag='', size=0, content_type='', last_modified=None, metadata=<factory>, storage_class='')

Object metadata returned by S3 operations.

Parameters:

• ref (ObjectRef)

• etag (str)

• size (int)

• content_type (str)

• last_modified (datetime | None)

• metadata (dict[str, str])

• storage_class (str)

class ByteRange(start=None, end=None)

Inclusive byte range used for object reads.

Parameters:

• start (int | None)

• end (int | None)

class ReadOptions(range=None, if_match='', if_none_match='', if_modified_since=None, if_unmodified_since=None)

Conditional and ranged read options for an object request.

Parameters:

• range (ByteRange | None)

• if_match (str)

• if_none_match (str)

• if_modified_since (datetime | None)

• if_unmodified_since (datetime | None)

class WriteOptions(content_type='', cache_control='', content_disposition='', content_encoding='', content_language='', metadata=<factory>, if_match='', if_none_match='')

Metadata and precondition options for object writes.

Parameters:

• content_type (str)

• cache_control (str)

• content_disposition (str)

• content_encoding (str)

• content_language (str)

• metadata (dict[str, str])

• if_match (str)

• if_none_match (str)

class ListOptions(bucket, prefix='', delimiter='', continuation_token='', start_after='', max_keys=0)

Query options for listing objects within a bucket.

Parameters:

• bucket (str)

• prefix (str)

• delimiter (str)

• continuation_token (str)

• start_after (str)

• max_keys (int)

class ListPage(objects=<factory>, common_prefixes=<factory>, next_continuation_token='', has_more=False)

One page of object-listing results.

Parameters:

• objects (list[ObjectMeta])

• common_prefixes (list[str])

• next_continuation_token (str)

• has_more (bool)

class CopyOptions(if_match='', if_none_match='')

Conditional headers for copy operations.

Parameters:

• if_match (str)

• if_none_match (str)

class PresignMethod(value)

HTTP methods supported by presigned object URLs.

class PresignOptions(method=None, expires=None, content_type='', content_disposition='', headers=<factory>)

Options for generating a presigned object URL.

Parameters:

• method (PresignMethod | str | None)

• expires (timedelta | None)

• content_type (str)

• content_disposition (str)

• headers (dict[str, str])

class PresignResult(url, method=None, expires_at=None, headers=<factory>)

Presigned URL response returned by the provider.

Parameters:

• url (str)

• method (PresignMethod | str | None)

• expires_at (datetime | None)

• headers (dict[str, str])

class S3ReadStream(stream)

Streaming object body reader returned by S3.read_object().

Parameters:

stream (Any)

__enter__()

Return the stream for with statements.

Return type:

S3ReadStream

__exit__(*args)

Close the stream at the end of a context manager block.

Parameters:

args (Any)

Return type:

None

iter_chunks()

Yield the remaining object body chunks.

Return type:

Iterator[bytes]

read(size=-1)

Read up to size bytes from the stream.

Parameters:

size (int)

Return type:

bytes

close()

Cancel the underlying RPC stream and discard buffered bytes.

Return type:

None

class S3(name=None)

Client for a host-provided Gestalt S3 runtime.

Parameters:

name (str | None)

close()

Close the underlying gRPC channel.

Return type:

None

object(bucket, key)

Return an object helper for the latest version.

Parameters:

• bucket (str)

• key (str)

Return type:

S3Object

object_version(bucket, key, version_id)

Return an object helper pinned to a specific version.

Parameters:

• bucket (str)

• key (str)

• version_id (str)

Return type:

S3Object

head_object(ref)

Fetch metadata for an object without reading its body.

Parameters:

ref (ObjectRef)

Return type:

ObjectMeta

read_object(ref, opts=None)

Open a streaming read for an object.

Parameters:

• ref (ObjectRef)

• opts (ReadOptions | None)

Return type:

tuple[ObjectMeta, S3ReadStream]

write_object(ref, body=None, opts=None)

Write an object body and return the resulting metadata.

Parameters:

• ref (ObjectRef)

• body (bytes | bytearray | memoryview | BinaryIO | Iterable[bytes] | None)

• opts (WriteOptions | None)

Return type:

ObjectMeta

delete_object(ref)

Delete an object.

Parameters:

ref (ObjectRef)

Return type:

None

list_objects(opts)

List objects within a bucket.

Parameters:

opts (ListOptions)

Return type:

ListPage

copy_object(source, destination, opts=None)

Copy an object and return metadata for the destination.

Parameters:

• source (ObjectRef)

• destination (ObjectRef)

• opts (CopyOptions | None)

Return type:

ObjectMeta

presign_object(ref, opts=None)

Generate a presigned URL for an object operation.

Parameters:

• ref (ObjectRef)

• opts (PresignOptions | None)

Return type:

PresignResult

create_object_access_url(ref, opts=None)

Create a host-mediated object access URL.

Parameters:

• ref (ObjectRef)

• opts (PresignOptions | None)

Return type:

PresignResult

create_access_url(ref, opts=None)

Create a host-mediated object access URL.

Parameters:

• ref (ObjectRef)

• opts (PresignOptions | None)

Return type:

PresignResult

__enter__()

Return the client for with statements.

Return type:

S3

__exit__(*args)

Close the client at the end of a context manager block.

Parameters:

args (Any)

Return type:

None

class S3Object(client, ref)

Convenience wrapper for a single S3 object reference.

Parameters:

• client (S3)

• ref (ObjectRef)

stat()

Fetch object metadata.

Return type:

ObjectMeta

exists()

Return whether the object exists.

Return type:

bool

stream(opts=None)

Open a streaming read for the object.

Parameters:

opts (ReadOptions | None)

Return type:

tuple[ObjectMeta, S3ReadStream]

bytes(opts=None)

Read the full object body as bytes.

Parameters:

opts (ReadOptions | None)

Return type:

bytes

text(opts=None, *, encoding='utf-8')

Read the full object body as text.

Parameters:

• opts (ReadOptions | None)

• encoding (str)

Return type:

str

json(opts=None)

Read and decode the full object body as JSON.

Parameters:

opts (ReadOptions | None)

Return type:

Any

write(body=None, opts=None)

Write an object body.

Parameters:

• body (bytes | bytearray | memoryview | BinaryIO | Iterable[bytes] | None)

• opts (WriteOptions | None)

Return type:

ObjectMeta

write_bytes(body, opts=None)

Write bytes to the object.

Parameters:

• body (bytes | bytearray | memoryview)

• opts (WriteOptions | None)

Return type:

ObjectMeta

write_text(body, opts=None, *, encoding='utf-8')

Encode and write text to the object.

Parameters:

• body (str)

• opts (WriteOptions | None)

• encoding (str)

Return type:

ObjectMeta

write_json(value, opts=None)

Encode and write JSON to the object.

Parameters:

• value (Any)

• opts (WriteOptions | None)

Return type:

ObjectMeta

delete()

Delete the object.

Return type:

None

presign(opts=None)

Generate a presigned URL for this object.

Parameters:

opts (PresignOptions | None)

Return type:

PresignResult

create_access_url(opts=None)

Create a host-mediated object access URL for this object.

Parameters:

opts (PresignOptions | None)

Return type:

PresignResult