Developer Interface#

class generic_connection_pool.BaseConnectionPool(*, idle_timeout=60.0, max_lifetime=3600.0, min_idle=1, max_size=10, total_max_size=100)[source]#

Bases: Generic[EndpointT, ConnectionT]

Asynchronous connection pool.

Parameters:

idle_timeout (float) – inactivity time (in seconds) after which an extra connection will be disposed (a connection considered as extra if the number of endpoint connection exceeds min_idle).
max_lifetime (float) – number of seconds after which any connection will be disposed.
min_idle (int) – minimum number of connections the pool tries to hold for each endpoint. Connections that exceed that number will be considered as extra and will be disposed after idle_timeout of inactivity.
max_size (int) – maximum number of endpoint connections.
total_max_size (int) – maximum number of all connections in the pool.

exception generic_connection_pool.ConnectionPoolClosedError[source]#

Bases: BaseError

Connection pool already closed.

Threading#

Threading connection pool implementation.

class generic_connection_pool.threading.BaseConnectionManager[source]#

Bases: Generic[EndpointT, ConnectionT], ABC

Abstract synchronous connection factory.

abstract create(endpoint, timeout=None)[source]#

Creates a new connection.

Parameters:

endpoint (EndpointT) – endpoint to connect to
timeout (float | None) – operation timeout

Returns:

new connection

Return type:

ConnectionT

abstract dispose(endpoint, conn, timeout=None)[source]#

Disposes the connection.

Parameters:

endpoint (EndpointT) – endpoint to connect to
conn (ConnectionT) – connection to be disposed
timeout (float | None) – operation timeout

Return type:

None

check_aliveness(endpoint, conn, timeout=None)[source]#

Checks that the connection is alive.

Parameters:

endpoint (EndpointT) – endpoint to connect to
conn (ConnectionT) – connection to be checked
timeout (float | None) – operation timeout

Returns:

True if connection is alive otherwise False

Return type:

bool

on_acquire(endpoint, conn)[source]#

Callback invoked on connection acquire.

Parameters:

endpoint (EndpointT) – endpoint to connect to
conn (ConnectionT) – connection to be acquired

Return type:

None

on_release(endpoint, conn)[source]#

Callback invoked on connection on_release.

Parameters:

endpoint (EndpointT) – endpoint to connect to
conn (ConnectionT) – connection to be acquired

Return type:

None

on_connection_dead(endpoint, conn)[source]#

Callback invoked on when connection aliveness check failed.

Parameters:

endpoint (EndpointT) – endpoint to connect to
conn (ConnectionT) – dead connection

Return type:

None

class generic_connection_pool.threading.ConnectionPool(connection_manager, *, acquire_timeout=None, background_collector=False, dispose_batch_size=0, dispose_timeout=None, min_idle=1, max_size=10, **kwargs)[source]#

Bases: Generic[EndpointT, ConnectionT], BaseConnectionPool[EndpointT, ConnectionT]

Synchronous connection pool.

Parameters:

connection_manager (BaseConnectionManager[EndpointT, ConnectionT]) – connection manager instance. Used to create, dispose or check connection aliveness.
acquire_timeout (float | None) – connection acquiring default timeout.
background_collector (bool) – if True starts a background worker that disposes expired and idle connections maintaining requested pool state. If False the connections will be disposed on each connection release.
dispose_batch_size (int) – maximum number of expired and idle connections to be disposed on connection release (if background collector is started the parameter is ignored).
dispose_timeout (float | None) – connection disposal timeout.
min_idle (int) – minimum number of connections in each endpoint the pool tries to hold. Connections that exceed that number will be considered as extra and disposed after idle_timeout seconds of inactivity.
max_size (int) – maximum number of endpoint connections.
kwargs (Any) – see generic_connection_pool.common.BaseConnectionPool

get_endpoint_pool_size(endpoint, acquired=None)[source]#

Returns endpoint pool size.

Parameters:

endpoint (EndpointT) – pool endpoint
acquired (bool | None) – if True returns the number of acquired connections, if False returns the number of free connections otherwise returns total size

Return type:

int

connection(endpoint, timeout=None)[source]#

Acquires a connection from the pool.

Parameters:

endpoint (EndpointT) – connection endpoint
timeout (float | None) – number of seconds to wait. If timeout is reached TimeoutError is raised.

Returns:

acquired connection

Return type:

Generator[ConnectionT, None, None]

acquire(endpoint, timeout=None)[source]#

Acquires a connection from the pool.

Parameters:

endpoint (EndpointT) – connection endpoint
timeout (float | None) – number of seconds to wait. If timeout is reached TimeoutError is raised.

Returns:

acquired connection

Return type:

ConnectionT

release(conn, endpoint)[source]#

Releases a connection.

Parameters:

conn (ConnectionT) – connection to be released
endpoint (EndpointT) – connection endpoint

Return type:

None

close(timeout=None)[source]#

Closes the connection pool.

Parameters:: timeout (float | None) – timeout after which the pool closes all connection despite they are released or not
Return type:: None

Asyncio#

Asyncio connection pool implementation.

class generic_connection_pool.asyncio.BaseConnectionManager[source]#

Bases: Generic[EndpointT, ConnectionT], ABC

Abstract asynchronous connection factory.

abstract async create(endpoint)[source]#

Creates a new connection.

Parameters:: endpoint (EndpointT) – endpoint to connect to
Returns:: new connection
Return type:: ConnectionT

abstract async dispose(endpoint, conn)[source]#

Disposes the connection.

Parameters:

endpoint (EndpointT) – endpoint to connect to
conn (ConnectionT) – connection to be disposed

Return type:

None

async check_aliveness(endpoint, conn)[source]#

Checks that the connection is alive.

Parameters:

endpoint (EndpointT) – endpoint to connect to
conn (ConnectionT) – connection to be checked

Returns:

True if connection is alive otherwise False

Return type:

bool

async on_acquire(endpoint, conn)[source]#

Callback invoked on connection acquire.

Parameters:

endpoint (EndpointT) – endpoint to connect to
conn (ConnectionT) – connection to be acquired

Return type:

None

async on_release(endpoint, conn)[source]#

Callback invoked on connection on_release.

Parameters:

endpoint (EndpointT) – endpoint to connect to
conn (ConnectionT) – connection to be acquired

Return type:

None

async on_connection_dead(endpoint, conn)[source]#

Callback invoked on when connection aliveness check failed.

Parameters:

endpoint (EndpointT) – endpoint to connect to
conn (ConnectionT) – dead connection

Return type:

None

class generic_connection_pool.asyncio.ConnectionPool(connection_manager, *, acquire_timeout=None, background_collector=False, dispose_batch_size=0, dispose_timeout=None, min_idle=1, max_size=10, **kwargs)[source]#

Bases: Generic[EndpointT, ConnectionT], BaseConnectionPool[EndpointT, ConnectionT]

Synchronous connection pool.

Parameters:

connection_manager (BaseConnectionManager[EndpointT, ConnectionT]) – connection manager instance. Used to create, dispose or check connection aliveness.
acquire_timeout (float | None) – connection acquiring default timeout.
background_collector (bool) – if True starts a background worker that disposes expired and idle connections maintaining requested pool state. If False the connections will be disposed on each connection release.
dispose_batch_size (int) – maximum number of expired and idle connections to be disposed on connection release (if background collector is started the parameter is ignored).
dispose_timeout (float | None) – connection disposal timeout.
min_idle (int) – minimum number of connections in each endpoint the pool tries to hold. Connections that exceed that number will be considered as extra and disposed after idle_timeout seconds of inactivity.
max_size (int) – maximum number of endpoint connections.
kwargs (Any) – see generic_connection_pool.common.BaseConnectionPool

async get_endpoint_pool_size(endpoint, acquired=None)[source]#

Returns endpoint pool size.

Parameters:

endpoint (EndpointT) – pool endpoint
acquired (bool | None) – if True returns the number of acquired connections, if False returns the number of free connections otherwise returns total size

Return type:

int

connection(endpoint, timeout=None)[source]#

Acquires a connection from the pool.

Parameters:

endpoint (EndpointT) – connection endpoint
timeout (float | None) – number of seconds to wait. If timeout is reached TimeoutError is raised.

Returns:

acquired connection

Return type:

AsyncGenerator[ConnectionT, None]

async acquire(endpoint, timeout=None)[source]#

Acquires a connection from the pool.

Parameters:

endpoint (EndpointT) – connection endpoint
timeout (float | None) – number of seconds to wait. If timeout is reached TimeoutError is raised.

Returns:

acquired connection

Return type:

ConnectionT

async release(conn, endpoint)[source]#

Releases a connection.

Parameters:

conn (ConnectionT) – connection to be released
endpoint (EndpointT) – connection endpoint

Return type:

None

async close(timeout=None)[source]#

Closes the connection pool.

Parameters:: timeout (float | None) – timeout after which the pool closes all connection despite they are released or not
Return type:: None

Contrib#

Synchronous socket connection manager implementation.

class generic_connection_pool.contrib.socket.SocketAlivenessCheckingMixin[source]#

Bases: Generic[EndpointT]

Socket aliveness checking mix-in.

class generic_connection_pool.contrib.socket.TcpSocketConnectionManager[source]#

Bases: SocketAlivenessCheckingMixin[Tuple[Union[IPv4Address, IPv6Address], int]], BaseConnectionManager[Tuple[Union[IPv4Address, IPv6Address], int], socket]

TCP socket connection manager.

create(endpoint, timeout=None)[source]#

Creates a new connection.

Parameters:

endpoint (Tuple[IPv4Address | IPv6Address, int]) – endpoint to connect to
timeout (float | None) – operation timeout

Returns:

new connection

Return type:

socket

dispose(endpoint, conn, timeout=None)[source]#

Disposes the connection.

Parameters:

endpoint (Tuple[IPv4Address | IPv6Address, int]) – endpoint to connect to
conn (socket) – connection to be disposed
timeout (float | None) – operation timeout

Return type:

None

class generic_connection_pool.contrib.socket.SslSocketAlivenessCheckingMixin[source]#

Bases: Generic[EndpointT]

SSL socket aliveness checking mix-in.

class generic_connection_pool.contrib.socket.SslSocketConnectionManager(ssl)[source]#

Bases: SslSocketAlivenessCheckingMixin[Tuple[str, int]], BaseConnectionManager[Tuple[str, int], SSLSocket]

SSL socket connection manager.

Parameters:: ssl (SSLContext) –

create(endpoint, timeout=None)[source]#

Creates a new connection.

Parameters:

endpoint (Tuple[str, int]) – endpoint to connect to
timeout (float | None) – operation timeout

Returns:

new connection

Return type:

SSLSocket

dispose(endpoint, conn, timeout=None)[source]#

Disposes the connection.

Parameters:

endpoint (Tuple[str, int]) – endpoint to connect to
conn (SSLSocket) – connection to be disposed
timeout (float | None) – operation timeout

Return type:

None

Asynchronous socket connection manager implementation.

class generic_connection_pool.contrib.socket_async.SocketAlivenessCheckingMixin[source]#

Bases: Generic[EndpointT]

Nonblocking socket aliveness checking mix-in.

class generic_connection_pool.contrib.socket_async.TcpSocketConnectionManager[source]#

Bases: SocketAlivenessCheckingMixin[Tuple[Union[IPv4Address, IPv6Address], int]], BaseConnectionManager[Tuple[Union[IPv4Address, IPv6Address], int], socket]

TCP socket connection manager.

async create(endpoint)[source]#

Creates a new connection.

Parameters:: endpoint (Tuple[IPv4Address | IPv6Address, int]) – endpoint to connect to
Returns:: new connection
Return type:: socket

async dispose(endpoint, conn)[source]#

Disposes the connection.

Parameters:

endpoint (Tuple[IPv4Address | IPv6Address, int]) – endpoint to connect to
conn (socket) – connection to be disposed

Return type:

None

class generic_connection_pool.contrib.socket_async.StreamAlivenessCheckingMixin[source]#

Bases: Generic[EndpointT]

Asynchronous stream aliveness checking mix-in.

class generic_connection_pool.contrib.socket_async.TcpStreamConnectionManager(ssl=None)[source]#

Bases: StreamAlivenessCheckingMixin[Tuple[str, int]], BaseConnectionManager[Tuple[str, int], Tuple[StreamReader, StreamWriter]]

TCP stream connection manager.

Parameters:: ssl (None | bool | SSLContext) –

async create(endpoint)[source]#

Creates a new connection.

Parameters:: endpoint (Tuple[str, int]) – endpoint to connect to
Returns:: new connection
Return type:: Tuple[StreamReader, StreamWriter]

async dispose(endpoint, conn)[source]#

Disposes the connection.

Parameters:

endpoint (Tuple[str, int]) – endpoint to connect to
conn (Tuple[StreamReader, StreamWriter]) – connection to be disposed

Return type:

None

Unix specific functionality.

class generic_connection_pool.contrib.unix.CheckSocketAlivenessMixin[source]#

Bases: Generic[EndpointT]

Socket aliveness checking mixin.

class generic_connection_pool.contrib.unix.UnixSocketConnectionManager[source]#

Bases: CheckSocketAlivenessMixin[Path], BaseConnectionManager[Path, socket]

Unix socket connection manager.

create(endpoint, timeout=None)[source]#

Creates a new connection.

Parameters:

endpoint (Path) – endpoint to connect to
timeout (float | None) – operation timeout

Returns:

new connection

Return type:

socket

dispose(endpoint, conn, timeout=None)[source]#

Disposes the connection.

Parameters:

endpoint (Path) – endpoint to connect to
conn (socket) – connection to be disposed
timeout (float | None) – operation timeout

Return type:

None

Asynchronous unix specific functionality.

class generic_connection_pool.contrib.unix_async.UnixSocketConnectionManager[source]#

Bases: SocketAlivenessCheckingMixin[Path], BaseConnectionManager[Path, socket]

Asynchronous unix socket connection manager.

async create(endpoint)[source]#

Creates a new connection.

Parameters:: endpoint (Path) – endpoint to connect to
Returns:: new connection
Return type:: socket

async dispose(endpoint, conn)[source]#

Disposes the connection.

Parameters:

endpoint (Path) – endpoint to connect to
conn (socket) – connection to be disposed

Return type:

None

class generic_connection_pool.contrib.unix_async.UnixSocketStreamConnectionManager[source]#

Bases: StreamAlivenessCheckingMixin[Path], BaseConnectionManager[Path, Tuple[StreamReader, StreamWriter]]

Asynchronous unix socket stream connection manager.

async create(endpoint)[source]#

Creates a new connection.

Parameters:: endpoint (Path) – endpoint to connect to
Returns:: new connection
Return type:: Tuple[StreamReader, StreamWriter]

async dispose(endpoint, conn)[source]#

Disposes the connection.

Parameters:

endpoint (Path) – endpoint to connect to
conn (Tuple[StreamReader, StreamWriter]) – connection to be disposed

Return type:

None