Skip to main content
Pooled clients + the generic client facade. Each client subclasses PooledClient (per-loop pooling, satisfies the contract BaseClient Protocol) and is reached by class through client_ctx. The driver each impl needs is declared by an extra (tai42-kit[curl] / [postgres]); import a driver submodule only when its driver is installed.

ClientDisconnectedError

tai42_contract.errors.ClientDisconnectedError
Raised when a client disconnects unexpectedly and is removed from the cache. This is not a permanent failure — retrying the operation will cause a fresh client to be created automatically.

ClientSettings

tai42_kit.clients.settings.ClientSettings
Base a client’s settings subclass extends to supply connection kwargs via client_kwargs(). Attributes

Members

client_kwargs

tai42_kit.clients.settings.ClientSettings.client_kwargs
Connection kwargs passed to the client’s _create / current.

PooledClient

tai42_kit.clients.base.PooledClient
A per-event-loop, per-epoch pool for a single driver client of type T. Subclasses implement _create and _close; callers lease the shared client through current, which rebuilds it after a classified disconnection.

Members

pool_key

tai42_kit.clients.base.PooledClient.pool_key
The pool this client leases for kwargs: two calls with equal keys share one pooled client. Parameters

current

tai42_kit.clients.base.PooledClient.current
Lease the pooled client for kwargs, creating it on first use. A disconnection inside the body evicts and closes the client and raises ClientDisconnectedError; retry to rebuild it. On a loop its end has marked closing (tai42_kit.loop_closing) a new lease raises RuntimeError; a lease held from before keeps its client. Parameters

close

tai42_kit.clients.base.PooledClient.close
Close and drop the pooled client for kwargs in the current epoch, if one is pooled. Parameters

PostgresConnectionOptions

tai42_kit.clients.settings.PostgresConnectionOptions
Postgres connection behaviour options, with no connection identity. The base of PostgresConnectionSettings, and of a door’s own namespace when the door brings its own DSN and takes only its behaviour from settings. Attributes

PostgresConnectionSettings

tai42_kit.clients.settings.PostgresConnectionSettings
Base Postgres connection settings loaded under a database’s TAI_DATABASE_<NAME>_ prefix. Attributes

Members

pg_dsn

tai42_kit.clients.settings.PostgresConnectionSettings.pg_dsn
Build the libpq DSN from the connection fields; a missing host or password raises a named error.

client_kwargs

tai42_kit.clients.settings.PostgresConnectionSettings.client_kwargs
Connection kwargs for the pooled client — JSON-serializable only. One pool per DSN per loop. min_size/max_size and retry_attempts are this database’s deployment build options, read when the pool is built; a second settings prefix resolving to the same DSN with different values raises rather than forking a second pool. env_prefix rides along (not identity) so the client can derive the owning component for the pool name.

RedisConnectionOptions

tai42_kit.clients.settings.RedisConnectionOptions
Redis connection behaviour options, with no connection identity. The base of RedisConnectionSettings, and of a door’s own namespace when the door brings its own connection string and takes only its behaviour from settings. Attributes

Members

connection_options

tai42_kit.clients.settings.RedisConnectionOptions.connection_options
The behaviour knobs that are set, in the kwarg form redis_connection_options takes.

RedisConnectionSettings

tai42_kit.clients.settings.RedisConnectionSettings
Base Redis connection settings with unprefixed field names for a store to subclass with its own prefix. The decode mode is a setting of the store (<PREFIX>DECODE_RESPONSES, default on). Attributes

Members

client_kwargs

tai42_kit.clients.settings.RedisConnectionSettings.client_kwargs
The base connection kwargs plus this store’s decode_responses.

RedisConnectionSettingsBase

tai42_kit.clients.settings.RedisConnectionSettingsBase
Redis connection identity and behaviour, with no decode mode. The base of RedisConnectionSettings, and of a component’s own connection when its code fixes the decode mode at each connection: client_kwargs then carries no decode_responses, and every caller adds the one its code reads. Attributes

Members

client_kwargs

tai42_kit.clients.settings.RedisConnectionSettingsBase.client_kwargs
Connection kwargs for the pooled client — JSON-serializable only. Every option in these kwargs is part of the pool identity: the URL, the decode mode, max_connections, the socket timeouts and the retry options together select one pooled client per loop. For redis-py the connection options are the client’s contract, so two components resolving to the same URL with different options get two clients by design — never a conflict. Every value must be JSON-serializable: retry_attempts travels as an int and the kit’s materialiser (redis_from_url_kwargs) turns it into a Retry object at construction time. env_prefix names this store’s component (so the client can name its own env var when redis_url is unset) and is a passenger, not identity — it never splits a pool. No decode mode is carried here; the caller adds it.

advance_client_epoch

tai42_kit.clients.base.advance_client_epoch
Advance the process-wide client epoch and return the epoch just retired. New current() leases pool under the new epoch; the retired epoch’s pools stay live until their last lease releases (or drain_epoch force-closes them at a deadline). The same counter stamps cached settings instances.

client_ctx

tai42_kit.clients.facade.client_ctx
Return an async context manager yielding a connected client for client_cls. Pass either settings (its client_kwargs() supplies the connection kwargs) or raw **kwargs, never both. fresh=True builds a one-shot client outside the pool and closes it on exit; otherwise the client is pooled and reused per event-loop + connection params. Parameters

current_client_epoch

tai42_kit.clients.base.current_client_epoch
The current client epoch — the value new leases and settings stamps carry.

drain_epoch

tai42_kit.clients.base.drain_epoch
Drain and close a retired epoch’s client pools for the running loop. Waits up to deadline seconds for every leased client of epoch to reach zero leases (each closes itself on its last release), then force-closes any that remain regardless of held leases, collecting failures into an ExceptionGroup so none is dropped. Must run on the loop that owns the pools; the current epoch cannot be drained. Parameters