API Reference¶

class s2_sdk.S2(access_token: str, *, endpoints: Endpoints | None = None, timeout: Timeout | None = None, retry: Retry | None = None, compression: Compression = Compression.NONE)[source]¶

Client for S2, an API for unlimited, durable, real-time streams.

Works with both the cloud and open source, self-hosted versions.

Parameters:

access_token – Access token for authenticating with S2.
endpoints – S2 endpoints. If None, defaults to public cloud endpoints. See Endpoints.
timeout – Timeout configuration. If None, default values are used. See Timeout.
retry – Retry configuration. If None, default values are used. See Retry.
compression – Compression algorithm for requests and responses. Defaults to NONE. See Compression.

Tip

Use as an async context manager to ensure connections are closed:

async with S2(token) as s2:
    ...

Warning

If not using a context manager, call close() when done.

async close() → None[source]¶: Close all open connections to S2 service endpoints.

async create_basin(name: str, *, config: BasinConfig | None = None, location: str | None = None) → BasinInfo[source]¶

Create a basin.

Parameters:

name – Name of the basin.
config – Configuration for the basin.
location – Logical location for the basin. If None, the service uses the account’s default location. The location is fixed for the lifetime of the basin. Use list_locations() or get_default_location() to discover valid values.

Returns:

Information about the created basin.

Note

name must be globally unique, 8–48 characters, comprising lowercase letters, numbers, and hyphens. It cannot begin or end with a hyphen.

async ensure_basin(name: str, *, config: BasinConfig | None = None, location: str | None = None) → EnsuredBasinInfo[source]¶

Ensure a basin.

If the basin doesn’t exist, creates the basin with specified configuration.

If the basin already exists:

Its configuration is updated to the specified configuration, if different.
Its configuration is unchanged, if the specified configuration is same.

Parameters:

name – Name of the basin.
config – Configuration for the basin.
location – Logical location for the basin. If None when creating, the service uses the account’s default location. The location is fixed for the lifetime of the basin.

Returns:

Information about the ensured basin.

Note

name must be globally unique, 8–48 characters, comprising lowercase letters, numbers, and hyphens. It cannot begin or end with a hyphen.

basin(name: str) → S2Basin[source]¶

Get an S2Basin for performing basin-level operations.

Parameters:: name – Name of the basin.
Returns:: An S2Basin bound to the given basin name.

Tip

Also available via subscript: s2["my-basin"].

async list_basins(*, prefix: str = '', start_after: str = '', limit: int = 1000) → Page[BasinInfo][source]¶

List a page of basins.

Parameters:

prefix – Filter to basins whose name starts with this prefix.
start_after – List basins whose name is lexicographically after this value.
limit – Maximum number of basins to return per page. Capped at 1000.

Returns:

A page of BasinInfo.

Tip

See list_all_basins() for automatic pagination.

async list_all_basins(*, prefix: str = '', start_after: str = '', include_deleted: bool = False) → AsyncIterator[BasinInfo][source]¶

List all basins, paginating automatically.

Parameters:

prefix – Filter to basins whose name starts with this prefix.
start_after – List basins whose name is lexicographically after this value.
include_deleted – Include basins that are being deleted.

Yields:

BasinInfo for each basin.

async list_locations() → list[LocationInfo][source]¶

List locations available to the account.

Returns:: Locations available to the account.

async get_default_location() → LocationInfo[source]¶

Get the account’s default location.

Returns:: The account’s default location.

async set_default_location(location: str) → LocationInfo[source]¶

Set the account’s default location.

Parameters:: location – Location name.
Returns:: The account’s updated default location.

async delete_basin(name: str, *, ignore_not_found: bool = False) → None[source]¶

Delete a basin.

Parameters:

name – Name of the basin to delete.
ignore_not_found – If True, do not raise on 404.

Note

Basin deletion is asynchronous and may take several minutes to complete.

async get_basin_config(name: str) → BasinConfig[source]¶

Get basin configuration.

Parameters:: name – Name of the basin.
Returns:: Current configuration of the basin.

async reconfigure_basin(name: str, *, config: BasinConfig) → BasinConfig[source]¶

Reconfigure a basin.

Parameters:

name – Name of the basin.
config – New configuration. Only provided fields are updated.

Returns:

Updated basin configuration.

Note

Modifying default_stream_config only affects newly created streams.

async issue_access_token(id: str, *, scope: AccessTokenScope, expires_at: datetime | None = None, auto_prefix_streams: bool = False) → str[source]¶

Issue an access token.

Parameters:

id – Unique identifier for the token (1–96 bytes).
scope – Permissions scope for the token.
expires_at – Optional expiration time.
auto_prefix_streams – Automatically prefix stream names during creation and strip the prefix during listing.

Returns:

The access token string.

async list_access_tokens(*, prefix: str = '', start_after: str = '', limit: int = 1000) → Page[AccessTokenInfo][source]¶

List a page of access tokens.

Parameters:

prefix – Filter to tokens whose ID starts with this prefix.
start_after – List tokens whose ID is lexicographically after this value.
limit – Maximum number of tokens to return per page. Capped at 1000.

Returns:

A page of AccessTokenInfo.

Tip

See list_all_access_tokens() for automatic pagination.

async list_all_access_tokens(*, prefix: str = '', start_after: str = '') → AsyncIterator[AccessTokenInfo][source]¶

List all access tokens, paginating automatically.

Parameters:

prefix – Filter to tokens whose ID starts with this prefix.
start_after – List tokens whose ID is lexicographically after this value.

Yields:

AccessTokenInfo for each token.

async revoke_access_token(id: str) → None[source]¶

Revoke an access token.

Parameters:: id – Identifier of the token to revoke.

Get account metrics.

Parameters:

set – Metric set to query.
start – Start of the time range (epoch seconds).
end – End of the time range (epoch seconds).
interval – Accumulation interval for timeseries metrics.

Returns:

List of metric values.

Get basin metrics.

Parameters:

basin – Name of the basin.
set – Metric set to query.
start – Start of the time range (epoch seconds).
end – End of the time range (epoch seconds).
interval – Accumulation interval for timeseries metrics.

Returns:

List of metric values.

Get stream metrics.

Parameters:

basin – Name of the basin.
stream – Name of the stream.
set – Metric set to query.
start – Start of the time range (epoch seconds).
end – End of the time range (epoch seconds).
interval – Accumulation interval for timeseries metrics.

Returns:

List of metric values.

class s2_sdk.S2Basin[source]¶

Caution

Returned by S2.basin(). Do not instantiate directly.

property name: str¶: Basin name.

async create_stream(name: str, *, config: StreamConfig | None = None) → StreamInfo[source]¶

Create a stream.

Parameters:

name – Name of the stream.
config – Configuration for the stream.

Returns:

Information about the created stream.

Note

name must be unique within the basin. It can be an arbitrary string up to 512 characters. / is recommended as a delimiter for hierarchical naming.

async ensure_stream(name: str, *, config: StreamConfig | None = None) → EnsuredStreamInfo[source]¶

Ensure a stream.

If the stream doesn’t exist, creates the stream with specified configuration.

If the stream already exists:

Its configuration is updated to the specified configuration, if different.
Its configuration is unchanged, if the specified configuration is same.

Parameters:

name – Name of the stream.
config – Configuration for the stream.

Returns:

Information about the ensured stream.

Note

name must be unique within the basin. It can be an arbitrary string up to 512 characters. / is recommended as a delimiter for hierarchical naming.

stream(name: str, *, encryption_key: bytes | str | None = None) → S2Stream[source]¶

Get an S2Stream for performing stream-level operations.

Parameters:

name – Name of the stream.
encryption_key – Key for encrypting records on append and decrypting them on read. Required when encryption is enabled via BasinConfig.stream_cipher (see Encryption for supported algorithms). If bytes, it will get converted to a base64 encoded str. If str, it must be base64 encoded.

Returns:

An S2Stream bound to the given stream name.

Tip

Also available via subscript: s2["my-basin"]["my-stream"].

async list_streams(*, prefix: str = '', start_after: str = '', limit: int = 1000) → Page[StreamInfo][source]¶

List a page of streams.

Parameters:

prefix – Filter to streams whose name starts with this prefix.
start_after – List streams whose name is lexicographically after this value.
limit – Maximum number of streams to return per page. Capped at 1000.

Returns:

A page of StreamInfo.

Tip

See list_all_streams() for automatic pagination.

async list_all_streams(*, prefix: str = '', start_after: str = '', include_deleted: bool = False) → AsyncIterator[StreamInfo][source]¶

List all streams, paginating automatically.

Parameters:

prefix – Filter to streams whose name starts with this prefix.
start_after – List streams whose name is lexicographically after this value.
include_deleted – Include streams that are being deleted.

Yields:

StreamInfo for each stream.

async delete_stream(name: str, *, ignore_not_found: bool = False) → None[source]¶

Delete a stream.

Parameters:

name – Name of the stream to delete.
ignore_not_found – If True, do not raise on 404.

Note

Stream deletion is asynchronous and may take several minutes to complete.

async get_stream_config(name: str) → StreamConfig[source]¶

Get stream configuration.

Parameters:: name – Name of the stream.
Returns:: Current configuration of the stream.

async reconfigure_stream(name: str, *, config: StreamConfig) → StreamConfig[source]¶

Reconfigure a stream.

Parameters:

name – Name of the stream.
config – New configuration. Only provided fields are updated.

Returns:

Updated stream configuration.

class s2_sdk.S2Stream[source]¶

Caution

Returned by S2Basin.stream(). Do not instantiate directly.

property name: str¶: Stream name.

async check_tail() → StreamPosition[source]¶

Check the tail of a stream.

Returns:: The tail position — the next sequence number to be assigned and the timestamp of the last record on the stream.

async append(inp: AppendInput) → AppendAck[source]¶

Append a batch of records to a stream.

Parameters:: inp – Batch of records and optional conditions.
Returns:: Acknowledgement with assigned sequence numbers and tail position.

append_session(*, max_unacked_bytes: int = 5242880, max_unacked_batches: int | None = None) → AppendSession[source]¶

Open a session for appending batches of records continuously.

Pipelined inputs are guaranteed to be processed in order.

Parameters:

max_unacked_bytes – Maximum total metered bytes of unacknowledged batches before backpressure is applied. Default is 5 MiB.
max_unacked_batches – Maximum number of unacknowledged batches before backpressure is applied. If None, no limit is applied.

Returns:

An AppendSession to use as an async context manager.

Tip

Use as an async context manager:

async with stream.append_session() as session:
    ticket = await session.submit(AppendInput(records=[...]))
    ack = await ticket

Warning

If not using a context manager, call AppendSession.close() to ensure all submitted batches are appended.

producer(*, fencing_token: str | None = None, match_seq_num: int | None = None, batching: Batching | None = None, max_unacked_bytes: int = 5242880) → Producer[source]¶

Open a producer with per-record submit and auto-batching.

Parameters:

fencing_token – Fencing token applied to every batch.
match_seq_num – Expected sequence number for the first record. Automatically advanced after each acknowledgement.
batching – Auto-batching configuration. If None, default values are used. See Batching.
max_unacked_bytes – Maximum total metered bytes of unacknowledged batches before backpressure is applied. Default is 5 MiB.

Returns:

A Producer to use as an async context manager.

Tip

Use as an async context manager:

async with stream.producer() as p:
    ticket = await p.submit(Record(body=b"hello"))
    ack = await ticket

Warning

If not using a context manager, call Producer.close() to ensure all submitted records are appended.

Read a batch of records from a stream.

Parameters:

start – Inclusive start position.
limit – Maximum number of records or metered bytes to return.
until_timestamp – Exclusive upper-bound timestamp. All returned records are guaranteed to have timestamps less than this value.
clamp_to_tail – Clamp the start position to the tail when it exceeds the tail, instead of raising.
wait – Number of seconds to wait for records before returning.
ignore_command_records – Filter out command records from the batch.

Returns:

A ReadBatch containing sequenced records and an optional tail position. Records can be empty only if limit, until_timestamp, or wait were provided.

async read_session(*, start: SeqNum | Timestamp | TailOffset, limit: ReadLimit | None = None, until_timestamp: int | None = None, clamp_to_tail: bool = False, wait: int | None = None, ignore_command_records: bool = False) → AsyncIterable[ReadBatch][source]¶

Read batches of records from a stream continuously.

Parameters:

start – Inclusive start position.
limit – Maximum number of records or metered bytes to return across the entire session.
until_timestamp – Exclusive upper-bound timestamp. All returned records are guaranteed to have timestamps less than this value.
clamp_to_tail – Clamp the start position to the tail when it exceeds the tail, instead of raising.
wait – Number of seconds to wait for new records when the tail is reached.
ignore_command_records – Filter out command records from batches.

Yields:

ReadBatch — each containing a batch of records and an optional tail position.

Note

Sessions without bounds (no limit or until_timestamp) default to infinite wait, waiting for new records indefinitely. Sessions with bounds default to zero wait, ending when the bounds are met or the tail is reached. Setting a non-zero wait makes a bounded session wait up to that many seconds for new records before ending.

class s2_sdk.AppendSession[source]¶

Session for high-throughput appending with backpressure control.

Supports pipelining multiple AppendInputs while preserving submission order.

Caution

Returned by S2Stream.append_session(). Do not instantiate directly.

async submit(inp: AppendInput) → BatchSubmitTicket[source]¶

Submit a batch of records for appending.

Waits when backpressure limits are reached.

async close() → None[source]¶: Close the session and wait for all submitted batches to be appended.

class s2_sdk.BatchSubmitTicket[source]¶: Awaitable that resolves to an AppendAck once the batch is appended.

class s2_sdk.Producer[source]¶

High-level interface for submitting individual records.

Handles batching into AppendInput automatically and uses an append session internally.

Caution

Returned by S2Stream.producer(). Do not instantiate directly.

async submit(record: Record) → RecordSubmitTicket[source]¶

Submit a record for appending.

Waits when backpressure limits are reached.

async close() → None[source]¶: Close the producer and wait for all submitted records to be appended.

class s2_sdk.RecordSubmitTicket[source]¶: Awaitable that resolves to an IndexedAppendAck once the record is appended.

class s2_sdk.Endpoints(account: str, basin: str)[source]¶

S2 service endpoints. See endpoints.

classmethod default() → Endpoints[source]¶: Construct default S2 cloud endpoints.

classmethod from_env() → Endpoints[source]¶: Construct endpoints from S2_ACCOUNT_ENDPOINT and S2_BASIN_ENDPOINT environment variables.

class s2_sdk.Timeout(request: timedelta = timedelta(seconds=5), connection: timedelta = timedelta(seconds=3))[source]¶

Timeout configuration.

request: timedelta¶: Timeout for read, write, and pool operations. Default is 5 seconds.

connection: timedelta¶: Timeout for establishing connections. Default is 3 seconds.

class s2_sdk.Retry(max_attempts: int = 3, min_base_delay: timedelta = timedelta(milliseconds=100), max_base_delay: timedelta = timedelta(seconds=1), append_retry_policy: AppendRetryPolicy = AppendRetryPolicy.ALL)[source]¶

Retry configuration.

max_attempts: int¶: Maximum number of attempts, including the initial try. Must be at least 1. Default is 3.

min_base_delay: timedelta¶: Minimum base delay between retries, before jitter. Default is 100 ms.

max_base_delay: timedelta¶: Maximum base delay between retries, before jitter. Default is 1 second.

append_retry_policy: AppendRetryPolicy¶: Policy controlling when append operations are retried. Default is ALL.

class s2_sdk.Batching(max_records: int = 1000, max_bytes: int = 1048576, linger: timedelta = timedelta(milliseconds=5))[source]¶

Configuration for auto-batching records.

max_records: int¶: Maximum number of records per batch. Must be between 1 and 1000. Default is 1000.

max_bytes: int¶: Maximum metered bytes per batch. Must be between 8 and 1 MiB. Default is 1 MiB.

linger: timedelta¶: Maximum time to wait for more records before flushing a batch. Default is 5 ms.

Note

If set to 0, batches are flushed only when max_records or max_bytes is reached.

class s2_sdk.Record(body: bytes, headers: list[tuple[bytes, bytes]] = [], timestamp: int | None = None)[source]¶

A record to append.

body: bytes¶: Body of the record.

headers: list[tuple[bytes, bytes]]¶: Headers for the record.

timestamp: int | None¶: Timestamp for the record. Precise semantics depend on the stream’s timestamping configuration.

class s2_sdk.AppendInput(records: list[Record], match_seq_num: int | None = None, fencing_token: str | None = None)[source]¶

Input for append() and AppendSession.submit().

records: list[Record]¶: Batch of records to append atomically. Must contain 1–1000 records totalling at most 1 MiB in metered bytes.

match_seq_num: int | None¶: Expected sequence number for the first record in the batch. If unset, no matching is performed. If set and mismatched, the append fails.

fencing_token: str | None¶: Fencing token to match against the stream’s current fencing token. If unset, no matching is performed. If set and mismatched, the append fails.

class s2_sdk.AppendAck[source]¶

Acknowledgement for an AppendInput.

start: StreamPosition¶: Sequence number and timestamp of the first appended record.

end: StreamPosition¶: Sequence number of the last appended record + 1, and timestamp of the last appended record. end.seq_num - start.seq_num is the number of records appended.

tail: StreamPosition¶: Next sequence number to be assigned on the stream, and timestamp of the last record on the stream. Can be greater than end in case of concurrent appends.

class s2_sdk.IndexedAppendAck[source]¶

Acknowledgement for an appended record.

seq_num: int¶: Sequence number assigned to the record.

batch: AppendAck¶: Acknowledgement for the containing batch.

class s2_sdk.StreamPosition[source]¶

Position of a record in a stream.

seq_num: int¶: Sequence number of the record.

timestamp: int¶: Timestamp of the record.

class s2_sdk.ReadLimit(count: int | None = None, bytes: int | None = None)[source]¶

Limits for read operations.

count: int | None¶: Maximum number of records to return.

bytes: int | None¶: Maximum cumulative size of records calculated using metered_bytes().

class s2_sdk.ReadBatch[source]¶

Batch of records from a read session.

records: list[SequencedRecord]¶: Records that are durably sequenced on the stream.

tail: StreamPosition | None¶: Tail position of the stream, present when reading recent records.

class s2_sdk.SequencedRecord[source]¶

Record read from a stream.

seq_num: int¶: Sequence number assigned to this record.

body: bytes¶: Body of this record.

headers: list[tuple[bytes, bytes]]¶: Series of name-value pairs for this record.

timestamp: int¶: Timestamp for this record.

is_command_record() → bool[source]¶: Check if this is a command record.

class s2_sdk.SeqNum(value: int)[source]¶: Read starting from this sequence number.

class s2_sdk.Timestamp(value: int)[source]¶: Read starting from this timestamp.

class s2_sdk.TailOffset(value: int)[source]¶: Read starting from this many records before the tail.

class s2_sdk.Page[source]¶

A page of values.

items: list[T]¶: Items in this page.

has_more: bool¶: Whether there are more pages.

class s2_sdk.CommandRecord[source]¶

Factory class for creating command records.

static fence(token: str) → Record[source]¶

Create a fence command record.

The fencing token must not exceed 36 bytes when UTF-8 encoded.

static trim(desired_first_seq_num: int) → Record[source]¶

Create a trim command record.

Has no effect if the sequence number is smaller than the first existing record.

s2_sdk.metered_bytes(records: Iterable[Record | SequencedRecord]) → int[source]¶

Each record is metered using the following formula:

8 + 2 * len(headers)
+ sum((len(name) + len(value)) for (name, value) in headers)
+ len(body)

async s2_sdk.append_record_batches(records: AsyncIterable[Record], *, batching: Batching | None = None) → AsyncIterable[list[Record]][source]¶: Group records into batches based on count, bytes, and linger time.

async s2_sdk.append_inputs(records: AsyncIterable[Record], *, match_seq_num: int | None = None, fencing_token: str | None = None, batching: Batching | None = None) → AsyncIterable[AppendInput][source]¶

Group records into AppendInput batches based on count, bytes, and linger time.

If match_seq_num is set, it applies to the first input and is auto-incremented for subsequent ones.

enum s2_sdk.Compression(value)[source]¶

Compression algorithm for requests and responses.

Valid values are as follows:

NONE = Compression.NONE¶

ZSTD = Compression.ZSTD¶

GZIP = Compression.GZIP¶

enum s2_sdk.AppendRetryPolicy(value)[source]¶

Policy controlling when append operations are retried.

Valid values are as follows:

ALL = AppendRetryPolicy.ALL¶: Retry all retryable errors.

NO_SIDE_EFFECTS = AppendRetryPolicy.NO_SIDE_EFFECTS¶: Retry only when no server-side mutation could have occurred.

enum s2_sdk.Encryption(value)[source]¶

Encryption algorithm.

Valid values are as follows:

AEGIS_256 = Encryption.AEGIS_256¶: AEGIS-256.

AES_256_GCM = Encryption.AES_256_GCM¶: AES-256-GCM.

enum s2_sdk.StorageClass(value)[source]¶

Storage class for recent appends.

Valid values are as follows:

STANDARD = StorageClass.STANDARD¶: Offers end-to-end latencies under 500 ms.

EXPRESS = StorageClass.EXPRESS¶: Offers end-to-end latencies under 50 ms.

enum s2_sdk.TimestampingMode(value)[source]¶

Timestamping mode for appends. Timestamps are milliseconds since Unix epoch.

Valid values are as follows:

CLIENT_PREFER = TimestampingMode.CLIENT_PREFER¶: Prefer client-specified timestamp if present, otherwise use arrival time.

CLIENT_REQUIRE = TimestampingMode.CLIENT_REQUIRE¶: Require a client-specified timestamp and reject if absent.

ARRIVAL = TimestampingMode.ARRIVAL¶: Use the arrival time and ignore any client-specified timestamp.

class s2_sdk.Timestamping(mode: TimestampingMode | None = None, uncapped: bool | None = None)[source]¶

Timestamping behavior for appends.

mode: TimestampingMode | None¶: Timestamping mode. Defaults to CLIENT_PREFER.

uncapped: bool | None¶: Allow client-specified timestamps to exceed the arrival time.

Stream configuration.

storage_class: StorageClass | None¶: Storage class for recent appends. Defaults to EXPRESS.

retention_policy: int | Literal['infinite'] | None¶: Retention duration in seconds, or "infinite". Default is 7 days.

timestamping: Timestamping | None¶: Timestamping behavior for appends.

delete_on_empty_min_age: int | None¶: Minimum age in seconds before this stream can be automatically deleted if empty.

class s2_sdk.BasinConfig(default_stream_config: StreamConfig | None = None, stream_cipher: Encryption | None = None, create_stream_on_append: bool | None = None, create_stream_on_read: bool | None = None)[source]¶

Basin configuration.

default_stream_config: StreamConfig | None¶: Default configuration for streams in this basin.

stream_cipher: Encryption | None¶: Encryption algorithm to apply to newly created streams in the basin.

create_stream_on_append: bool | None¶: Create stream on append if it doesn’t exist.

create_stream_on_read: bool | None¶: Create stream on read if it doesn’t exist.

class s2_sdk.LocationInfo[source]¶

Logical location of a basin.

A basin’s location is fixed for the lifetime of the basin. Public locations represent multi-tenant S2 deployments within public cloud regions, for example "aws:us-east-1". Private locations represent single-tenant S2 deployments, restricted to accounts with access.

See basin locations for more.

name: str¶: Location name.

is_private: bool¶: Whether this location is an account-private placement.

class s2_sdk.BasinInfo[source]¶

Basin information.

name: str¶: Basin name.

location: str | None¶

Logical location of the basin, if returned by the service.

A basin’s location is fixed for the lifetime of the basin. See basin locations for more.

created_at: datetime¶: Creation time.

deleted_at: datetime | None¶: Deletion time if the basin is being deleted.

class s2_sdk.StreamInfo[source]¶

Stream information.

name: str¶: Stream name.

created_at: datetime¶: Creation time.

deleted_at: datetime | None¶: Deletion time if the stream is being deleted.

cipher: Encryption | None¶: Encryption algorithm for this stream, if encryption is enabled.

class s2_sdk.EnsuredBasinInfo[source]¶

Basin information with ensure operation outcome.

basin: BasinInfo¶: Basin information.

status: EnsureStatus¶: Outcome of the ensure operation.

class s2_sdk.EnsuredStreamInfo[source]¶

Stream information with ensure operation outcome.

stream: StreamInfo¶: Stream information.

status: EnsureStatus¶: Outcome of the ensure operation.

enum s2_sdk.EnsureStatus(value)[source]¶

Outcome of an ensure operation.

Valid values are as follows:

CREATED = EnsureStatus.CREATED¶: Resource created.

CONFIG_UPDATED = EnsureStatus.CONFIG_UPDATED¶: Resource already existed, and its config was updated.

CONFIG_UNCHANGED = EnsureStatus.CONFIG_UNCHANGED¶: Resource already existed, and its config is unchanged.

class s2_sdk.ExactMatch(value: str)[source]¶: Match only the resource with this exact name.

class s2_sdk.PrefixMatch(value: str)[source]¶: Match all resources that start with this prefix.

enum s2_sdk.Permission(value)[source]¶

Permission level for operation groups.

Valid values are as follows:

READ = Permission.READ¶

WRITE = Permission.WRITE¶

READ_WRITE = Permission.READ_WRITE¶

enum s2_sdk.Operation(value)[source]¶

Granular operation for access token scoping.

Valid values are as follows:

LIST_BASINS = Operation.LIST_BASINS¶

CREATE_BASIN = Operation.CREATE_BASIN¶

DELETE_BASIN = Operation.DELETE_BASIN¶

RECONFIGURE_BASIN = Operation.RECONFIGURE_BASIN¶

GET_BASIN_CONFIG = Operation.GET_BASIN_CONFIG¶

ISSUE_ACCESS_TOKEN = Operation.ISSUE_ACCESS_TOKEN¶

REVOKE_ACCESS_TOKEN = Operation.REVOKE_ACCESS_TOKEN¶

LIST_ACCESS_TOKENS = Operation.LIST_ACCESS_TOKENS¶

LIST_STREAMS = Operation.LIST_STREAMS¶

CREATE_STREAM = Operation.CREATE_STREAM¶

DELETE_STREAM = Operation.DELETE_STREAM¶

GET_STREAM_CONFIG = Operation.GET_STREAM_CONFIG¶

RECONFIGURE_STREAM = Operation.RECONFIGURE_STREAM¶

CHECK_TAIL = Operation.CHECK_TAIL¶

APPEND = Operation.APPEND¶

READ = Operation.READ¶

TRIM = Operation.TRIM¶

FENCE = Operation.FENCE¶

ACCOUNT_METRICS = Operation.ACCOUNT_METRICS¶

BASIN_METRICS = Operation.BASIN_METRICS¶

STREAM_METRICS = Operation.STREAM_METRICS¶

LIST_LOCATIONS = Operation.LIST_LOCATIONS¶

GET_DEFAULT_LOCATION = Operation.GET_DEFAULT_LOCATION¶

SET_DEFAULT_LOCATION = Operation.SET_DEFAULT_LOCATION¶

class s2_sdk.OperationGroupPermissions(account: Permission | None = None, basin: Permission | None = None, stream: Permission | None = None)[source]¶

Permissions at the operation group level.

account: Permission | None¶: Permission for account operations.

basin: Permission | None¶: Permission for basin operations.

stream: Permission | None¶: Permission for stream operations.

Scope of an access token.

basins: ExactMatch | PrefixMatch | None¶: Permitted basins.

streams: ExactMatch | PrefixMatch | None¶: Permitted streams.

access_tokens: ExactMatch | PrefixMatch | None¶: Permitted access tokens.

op_groups: OperationGroupPermissions | None¶: Permissions at operation group level.

ops: list[Operation]¶: Permitted operations.

class s2_sdk.AccessTokenInfo[source]¶

Access token information.

id: str¶: Access token ID.

scope: AccessTokenScope¶: Scope of the access token.

expires_at: datetime | None¶: Expiration time.

auto_prefix_streams: bool¶: Whether to automatically prefix stream names during creation and strip the prefix during listing.

enum s2_sdk.MetricUnit(value)[source]¶

Unit of a metric value.

Valid values are as follows:

BYTES = MetricUnit.BYTES¶

OPERATIONS = MetricUnit.OPERATIONS¶

enum s2_sdk.TimeseriesInterval(value)[source]¶

Bucket interval for timeseries metrics.

Valid values are as follows:

MINUTE = TimeseriesInterval.MINUTE¶

HOUR = TimeseriesInterval.HOUR¶

DAY = TimeseriesInterval.DAY¶

enum s2_sdk.AccountMetricSet(value)[source]¶

Available account-level metric sets.

Valid values are as follows:

ACTIVE_BASINS = AccountMetricSet.ACTIVE_BASINS¶

ACCOUNT_OPS = AccountMetricSet.ACCOUNT_OPS¶

enum s2_sdk.BasinMetricSet(value)[source]¶

Available basin-level metric sets.

Valid values are as follows:

STORAGE = BasinMetricSet.STORAGE¶

APPEND_OPS = BasinMetricSet.APPEND_OPS¶

READ_OPS = BasinMetricSet.READ_OPS¶

READ_THROUGHPUT = BasinMetricSet.READ_THROUGHPUT¶

APPEND_THROUGHPUT = BasinMetricSet.APPEND_THROUGHPUT¶

BASIN_OPS = BasinMetricSet.BASIN_OPS¶

enum s2_sdk.StreamMetricSet(value)[source]¶

Available stream-level metric sets.

Valid values are as follows:

STORAGE = StreamMetricSet.STORAGE¶

class s2_sdk.Scalar[source]¶: Single named metric value.

class s2_sdk.Accumulation[source]¶: Timeseries of accumulated values over buckets.

class s2_sdk.Gauge[source]¶: Timeseries of instantaneous values.

class s2_sdk.Label[source]¶: Set of string labels.

class s2_sdk.S2Error¶: Base class for all S2 related exceptions.

class s2_sdk.S2ClientError¶

Bases: S2Error

Error originating from the client.

class s2_sdk.S2ServerError¶

Bases: S2Error

Error originating from the server.

code¶: Error code from the server. See error codes for possible values.

message¶: Human-readable error message.

status_code¶: HTTP status code.

class s2_sdk.AppendConditionError¶

Bases: S2ServerError

Append condition was not met.

class s2_sdk.FencingTokenMismatchError¶

Bases: AppendConditionError

Fencing token did not match.

expected_fencing_token¶: The fencing token the server expected.

class s2_sdk.SeqNumMismatchError¶

Bases: AppendConditionError

Sequence number did not match.

expected_seq_num¶: The sequence number the server expected.

class s2_sdk.ReadUnwrittenError¶

Bases: S2ServerError

Read from an unwritten position.

tail¶: The tail position of the stream.