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.

Note

If iteration over records raises, or batching is cancelled or stopped before completion, records already consumed but not yet yielded as a batch may be discarded.

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.