API Documentation¶

Client¶

class Client(memcached_location: str | Path | TCPEndpoint | tuple[str, int] | Sequence[str | Path | TCPEndpoint | tuple[str, int]] | AWSAutoDiscoveryEndpoint | None = None, decode_responses: Literal[True, False] = False, encoding: str = ENCODING, min_connections: int = MIN_CONNECTIONS, max_connections: int = MAX_CONNECTIONS, blocking_timeout: float = BLOCKING_TIMEOUT, idle_connection_timeout: float = IDLE_CONNECTION_TIMEOUT, hashing_function: Callable[[str], int] | None = None, endpoint_healthcheck_config: EndpointHealthcheckConfig | None = None, connection_pool: Pool | None = None, connect_timeout: float | None = CONNECT_TIMEOUT, read_timeout: float | None = READ_TIMEOUT, socket_nodelay: bool | None = None, socket_keepalive: bool | None = None, socket_keepalive_options: dict[int, int | bytes] | None = None, max_inflight_requests_per_connection: int = MAX_INFLIGHT_REQUESTS_PER_CONNECTION, max_average_response_time_for_connection_reuse: float = MAX_AVERAGE_RESPONSE_TIME_FOR_CONNECTION_REUSE, ssl_context: SSLContext | None = None, username: str | None = None, password: str | None = None, authenticator: Authenticator | None = None)[source]¶

Initialize the Memcached client.

Either a memcached location or an existing connection pool must be provided.

Parameters:

memcached_location (MemcachedEndpoint | None) – The memcached server address(es) or endpoint configuration.
decode_responses (Literal[True, False]) – If True, decode responses using the specified encoding; otherwise, responses are returned as bytes.
encoding (str) – The character encoding used when decoding responses.
max_connections (int) – The maximum number of simultaneous connections to memcached.
min_connections (int) – The minimum number of connections to keep in the pool.
blocking_timeout (float) – The timeout (in seconds) to wait for a connection to become available.
idle_connection_timeout (float) – The maximum time to allow a connection to remain idle in the pool before being disconnected
hashing_function (Callable[[str], int] | None) –
A function to use for routing keys to endpoints for multi-key commands. If none is provided the default hashlib.md5() implementation from the standard library is used.

Important

This parameter is only relevant when connecting to multiple memcached servers
endpoint_healthcheck_config (EndpointHealthcheckConfig | None) –
Configuration to control whether endpoints are automatically removed/recovered based on health checks.

Important

This parameter is only relevant when connecting to multiple memcached servers
connection_pool (Pool) –
An optional pre-initialized connection pool. If provided, memcached_location must be None.

Caution

All connection/connection pool related arguments will be ignored when a connection_pool is provided as the arguments provided when creating the pool itself will be in effect.
connect_timeout (float | None) – Timeout (in seconds) for establishing a connection.
read_timeout (float | None) – Timeout (in seconds) for reading from a connection.
socket_nodelay (bool | None) – If True, disable Nagle’s algorithm on the socket.
socket_keepalive (bool | None) – If True, enable TCP keepalive on the socket.
socket_keepalive_options (dict[int, int | bytes] | None) – Additional options for configuring socket keepalive.
max_inflight_requests_per_connection (int) – Maximum number of requests allowed to be in-flight per connection.
max_average_response_time_for_connection_reuse (float) – Threshold for allowing the connection to be reused when there are requests pending.
ssl_context (SSLContext | None) – An SSL context to use for encrypted connections.
username (str | None) – Username for SASL authentication (if required).
password (str | None) – Password for SASL authentication (if required).
authenticator (Authenticator | None) – The authentication strategy to use when establishing new connections

Raises:

ValueError – If both or neither memcached_location and connection_pool are provided.

async get(*keys: KeyT) → dict[AnyStr, MemcachedItem][source]¶

Retrieve one or more items from memcached.

Parameters:: keys (KeyT) – One or more keys identifying the items to be retrieved.
Returns:: A dictionary mapping each found key to its corresponding memcached item.
Return type:: dict[AnyStr, MemcachedItem]

async gets(*keys: KeyT) → dict[AnyStr, MemcachedItem][source]¶

Retrieve items along with their CAS (Check And Set) identifiers from memcached.

Parameters:: keys (KeyT) – One or more keys identifying the items to be retrieved.
Returns:: A dictionary mapping each found key to its corresponding memcached item, including CAS value.
Return type:: dict[AnyStr, MemcachedItem]

async gat(*keys: KeyT, expiry: int) → dict[AnyStr, MemcachedItem][source]¶

Retrieve items from memcached and update their expiration time.

Parameters:

keys (KeyT) – One or more keys identifying the items to be retrieved.
expiry (int) – New expiration time (in seconds) to be applied to the items.

Returns:

A dictionary mapping each found key to its corresponding memcached item.

Return type:

dict[AnyStr, MemcachedItem]

async gats(*keys: KeyT, expiry: int) → dict[AnyStr, MemcachedItem][source]¶

Retrieve items with CAS identifiers and update their expiration time.

Parameters:

keys (KeyT) – One or more keys identifying the items to be retrieved.
expiry (int) – New expiration time (in seconds) to be applied to the items.

Returns:

A dictionary mapping each found key to its corresponding memcached item, including CAS value.

Return type:

dict[AnyStr, MemcachedItem]

async set(key: KeyT, value: ValueT, /, flags: int = 0, expiry: int = 0) → bool[source]¶

async set(key: KeyT, value: ValueT, /, flags: int = 0, expiry: int = 0, noreply: bool = False) → bool | None

Store a key-value pair in memcached.

Parameters:

key – The key under which the value should be stored.
value – The value to be stored.
flags – Arbitrary flags stored alongside the value (default: 0).
expiry – Expiration time in seconds (default: 0, meaning no expiration).
noreply – If True, the command will not wait for a reply from the server.

Returns:

True if the item was stored successfully, False otherwise; returns None if noreply is True.

async cas(key: KeyT, value: ValueT, cas: int, /, flags: int = 0, expiry: int = 0) → bool[source]¶

async cas(key: KeyT, value: ValueT, cas: int, /, flags: int = 0, expiry: int = 0, noreply: bool = False) → bool | None

Perform a CAS (Check-And-Set) operation on an item in memcached.

Parameters:

key – The key of the item to update.
value – The new value to store.
cas – The CAS identifier that must match the current CAS value of the item.
flags – Arbitrary flags stored alongside the value (default: 0).
expiry – Expiration time in seconds (default: 0, meaning no expiration).
noreply – If True, the command will not wait for a reply from the server.

Returns:

True if the item was updated successfully, False otherwise; returns None if noreply is True.

async add(key: KeyT, value: ValueT, /, flags: int = 0, expiry: int = 0) → bool[source]¶

async add(key: KeyT, value: ValueT, /, flags: int = 0, expiry: int = 0, noreply: bool = False) → bool | None

Add a key-value pair to memcached only if the key does not already exist.

Parameters:

key – The key under which the value should be added.
value – The value to be stored.
flags – Arbitrary flags stored alongside the value (default: 0).
expiry – Expiration time in seconds (default: 0, meaning no expiration).
noreply – If True, do not wait for a reply from the server.

Returns:

True if the item was added, False otherwise; returns None if noreply is True.

async append(key: KeyT, value: ValueT, /) → bool[source]¶

async append(key: KeyT, value: ValueT, /, noreply: bool = False) → bool | None

Append data to an existing item stored in memcached.

Parameters:

key – The key of the item to append data to.
value – The data to append.
noreply – If True, do not wait for a reply from the server.

Returns:

True if the append operation succeeded, False otherwise; returns None if noreply is True.

async prepend(key: KeyT, value: ValueT, /) → bool[source]¶

async prepend(key: KeyT, value: ValueT, /, noreply: bool = False) → bool | None

Prepend data to an existing item stored in memcached.

Parameters:

key – The key of the item to which data should be prepended.
value – The data to prepend.
noreply – If True, do not wait for a reply from the server.

Returns:

True if the prepend operation succeeded, False otherwise; returns None if noreply is True.

async replace(key: KeyT, value: ValueT, /, flags: int = 0, expiry: int = 0) → bool[source]¶

async replace(key: KeyT, value: ValueT, /, flags: int = 0, expiry: int = 0, noreply: bool = False) → bool | None

Replace the value for an existing key in memcached.

Parameters:

key – The key whose value is to be replaced.
value – The new value to store.
flags – Arbitrary flags stored alongside the value (default: 0).
expiry – Expiration time in seconds (default: 0, meaning no expiration).
noreply – If True, do not wait for a reply from the server.

Returns:

True if the replace operation succeeded, False otherwise; returns None if noreply is True.

async incr(key: KeyT, value: int, /) → int | None[source]¶

async incr(key: KeyT, value: int, /, noreply: bool = False) → int | None

Increment the numeric value of a key in memcached.

Parameters:

key – The key whose value should be incremented.
value – The amount by which to increment the current value.
noreply – If True, do not wait for a reply from the server.

Returns:

The new value after incrementing, or None if noreply is True.

async decr(key: KeyT, value: int, /) → int | None[source]¶

async decr(key: KeyT, value: int, /, noreply: bool = False) → int | None

Decrement the numeric value of a key in memcached.

Parameters:

key – The key whose value should be decremented.
value – The amount by which to decrement the current value.
noreply – If True, do not wait for a reply from the server.

Returns:

The new value after decrementing, or None if noreply is True.

async delete(key: KeyT, /) → bool[source]¶

async delete(key: KeyT, /, noreply: bool = False) → bool | None

Delete an item from memcached.

Parameters:

key – The key of the item to be deleted.
noreply – If True, do not wait for a reply from the server.

Returns:

True if the deletion was successful, False otherwise; returns None if noreply is True.

async touch(key: KeyT, expiry: int, /) → bool[source]¶

async touch(key: KeyT, expiry: int, /, noreply: bool = False) → bool | None

Update the expiration time for an existing key without modifying its value.

Parameters:

key – The key to update.
expiry – The new expiration time in seconds.
noreply – If True, do not wait for a reply from the server.

Returns:

True if the expiration time was updated successfully, False otherwise; returns None if noreply is True.

async flushall(expiry: int = 0, /) → bool[source]¶

Invalidate all existing items in memcached.

Parameters:: expiry (int) – Delay (in seconds) before flushing all items (default: 0).
Returns:: True if the flush operation succeeded, False otherwise.
Return type:: bool

Note

If the client is configured to use multiple memcached servers the result will be True only if all servers succeeded.

async stats(arg: str | None = None) → dict[str | Path | TCPEndpoint | tuple[str, int], dict[AnyStr, AnyStr]][source]¶

Retrieve server statistics from memcached.

Parameters:: arg (str | None) – An optional argument to specify a subset of statistics.
Returns:: A mapping of memcached servers to mappings of statistic keys and their corresponding values.
Return type:: dict[str | Path | TCPEndpoint | tuple[str, int], dict[AnyStr, AnyStr]]

async version() → dict[str | Path | TCPEndpoint | tuple[str, int], str][source]¶

Retrieve the memcached server version.

Returns:: A mapping of memcached servers to their versions
Return type:: dict[str | Path | TCPEndpoint | tuple[str, int], str]

Default values¶

MIN_CONNECTIONS = 1¶: Minimum number of connections to retain in the pool

MAX_CONNECTIONS = 2¶: Maximum connections to grow the pool to

IDLE_CONNECTION_TIMEOUT = 10.0¶: Maximum time to leave a connection idle before disconnecting

BLOCKING_TIMEOUT = 5.0¶: Maximum time to wait to retrieve a connection from the pool

CONNECT_TIMEOUT = 1.0¶: Maxiumum time to wait to establish a connection

READ_TIMEOUT = None¶: Maxiumum time to wait to read a response for a request

MAX_INFLIGHT_REQUESTS_PER_CONNECTION = 100¶: Maxiumum number of concurrent requests to pipeline on each connection

MAX_AVERAGE_RESPONSE_TIME_FOR_CONNECTION_REUSE = 0.05¶: Threshold for allowing the connection to be reused when there are requests pending.

REMOVE_UNHEALTHY_ENDPOINTS = False¶: Whether to remove unhealthy endpoints on connection errors. This is the default value for remove_unhealthy_endpoints

MAXIMUM_ERROR_COUNT_FOR_ENDPOINT_REMOVAL = 2¶: Maximum numbers of errors to tolerate before marking an endpoint as unhealthy

MONITOR_UNHEALTHY_ENDPOINTS = False¶: Whether to monitor unhealthy endpoints after they have been removed and attempt to restore them if they recover This is the default value for monitor_unhealthy_endpoints

MAXIMUM_RECOVERY_ATTEMPTS = 4¶: Maximum attempts to make to recover unhealthy endpoints This is the default value for maximum_recovery_attempts

RETRY_BACKOFF_POLICY: Literal['linear'] = 'linear'¶

Connection Pool¶

class Pool(endpoint: str | Path | TCPEndpoint | tuple[str, int] | Sequence[str | Path | TCPEndpoint | tuple[str, int]] | AWSAutoDiscoveryEndpoint, min_connections: int = MIN_CONNECTIONS, max_connections: int = MAX_CONNECTIONS, blocking_timeout: float = BLOCKING_TIMEOUT, idle_connection_timeout: float = IDLE_CONNECTION_TIMEOUT, **connection_args: Unpack[ConnectionParams])[source]¶

The abstract base class for a connection pool used by Client

Parameters:

endpoint (MemcachedEndpoint) – The memcached server address(es)
min_connections (int) – The minimum number of connections to keep in the pool.
max_connections (int) – The maximum number of simultaneous connections to memcached.
blocking_timeout (float) – The timeout (in seconds) to wait for a connection to become available.
idle_connection_timeout (float) – The maximum time to allow a connection to remain idle in the pool before being disconnected
connection_args (Unpack[ConnectionParams]) – Arguments to pass to the constructor of BaseConnection. refer to ConnectionParams

abstract property metrics: PoolMetrics¶: Pool health metrics

abstractmethod async initialize() → None[source]¶

Initialize the connection pool. The method can throw a connection error if the target server(s) can’t be connected to.

Return type:: None

abstractmethod async execute_command(command: Command[R]) → None[source]¶

Dispatches a command to memcached. To receive the response the future pointed to by command.response should be awaited as it will be updated when the response (or exception) is available on the transport.

Parameters:: command (Command[R])
Return type:: None

abstractmethod close() → None[source]¶

Closes the connection pool and disconnects all active connections

Return type:: None

class SingleServerPool(endpoint: str | Path | TCPEndpoint | tuple[str, int], min_connections: int = MIN_CONNECTIONS, max_connections: int = MAX_CONNECTIONS, blocking_timeout: float = BLOCKING_TIMEOUT, idle_connection_timeout: float = IDLE_CONNECTION_TIMEOUT, **connection_args: Unpack[ConnectionParams])[source]¶

Connection pool to manage connections to a single memcached server.

Parameters:

endpoint (SingleMemcachedInstanceEndpoint) – The memcached server address(es)
min_connections (int) – The minimum number of connections to keep in the pool.
max_connections (int) – The maximum number of simultaneous connections to memcached.
blocking_timeout (float) – The timeout (in seconds) to wait for a connection to become available.
idle_connection_timeout (float) – The maximum time to allow a connection to remain idle in the pool before being disconnected
connection_args (Unpack[ConnectionParams]) – Arguments to pass to the constructor of BaseConnection. refer to ConnectionParams

property metrics: PoolMetrics¶: Pool health metrics

async initialize() → None[source]¶

Initialize the connection pool. The method can throw a connection error if the target server(s) can’t be connected to.

Return type:: None

async execute_command(command: Command[R]) → None[source]¶

Parameters:: command (Command[R])
Return type:: None

close() → None[source]¶

Closes the connection pool and disconnects all active connections

Return type:: None

class ClusterPool(endpoint: Sequence[str | Path | TCPEndpoint | tuple[str, int]] | AWSAutoDiscoveryEndpoint, min_connections: int = MIN_CONNECTIONS, max_connections: int = MAX_CONNECTIONS, blocking_timeout: float = BLOCKING_TIMEOUT, idle_connection_timeout: float = IDLE_CONNECTION_TIMEOUT, hashing_function: Callable[[str], int] | None = None, endpoint_healthcheck_config: EndpointHealthcheckConfig | None = None, **connection_args: Unpack[ConnectionParams])[source]¶

Connection pool to manage connections to multiple memcached servers.

For multi-key commands, rendezvous hashing is used to distribute the command to the appropriate endpoints.

Parameters:

endpoint (Sequence[SingleMemcachedInstanceEndpoint] | AWSAutoDiscoveryEndpoint) – The memcached server address(es)
min_connections (int) – The minimum number of connections per endpoint to keep in the pool.
max_connections (int) – The maximum number of simultaneous connections per memcached endpoint.
blocking_timeout (float) – The timeout (in seconds) to wait for a connection to become available.
idle_connection_timeout (float) – The maximum time to allow a connection to remain idle in the pool before being disconnected
hashing_function (Callable[[str], int] | None) – A function to use for routing keys to endpoints for multi-key commands. If none is provided the default hashlib.md5() implementation from the standard library is used.
endpoint_healthcheck_config (EndpointHealthcheckConfig | None) – Configuration to control whether endpoints are automatically removed/recovered based on health checks.
connection_args (Unpack[ConnectionParams]) – Arguments to pass to the constructor of BaseConnection. refer to ConnectionParams

property metrics: PoolMetrics¶: Aggregate metrics obtained from the sub-pools for each endpoint that this cluster pool is configured against.

async initialize() → None[source]¶

Initialize the connection pool. The method can throw a connection error if the target server(s) can’t be connected to.

Return type:: None

async execute_command(command: Command[R]) → None[source]¶

Dispatches a command to the appropriate memcached endpoint(s). To receive the response the future pointed to by command.response should be awaited as it will be updated when the response(s) (or exception) are available on the transport and merged (if it is a command that spans multiple endpoints).

Parameters:: command (Command[R])
Return type:: None

close() → None[source]¶

Closes the connection pool and disconnects all active connections

Return type:: None

add_endpoint(endpoint: str | Path | TCPEndpoint | tuple[str, int]) → None[source]¶

Add a new endpoint to this pool

Parameters:: endpoint (str | Path | TCPEndpoint | tuple[str, int])
Return type:: None

remove_endpoint(endpoint: str | Path | TCPEndpoint | tuple[str, int]) → None[source]¶

Remove an endpoint from this pool. This will immediately also close all connections to that endpoint.

Parameters:: endpoint (str | Path | TCPEndpoint | tuple[str, int])
Return type:: None

update_endpoint_status(endpoint: str | Path | TCPEndpoint | tuple[str, int], status: EndpointStatus) → None[source]¶

Change the status of an endpoint in this pool. Marking an endpoint as EndpointStatus.DOWN will immediately stop routing requests to it, while marking it as EndpointStatus.UP will immediately start routing requests to it.

Parameters:

endpoint (str | Path | TCPEndpoint | tuple[str, int])
status (EndpointStatus)

Return type:

None

class EndpointHealthcheckConfig(remove_unhealthy_endpoints: 'bool' = False, maximum_error_count_for_removal: 'int' = 2, monitor_unhealthy_endpoints: 'bool' = False, maximum_recovery_attempts: 'int' = 4, retry_backoff_policy: "Literal['linear', 'exponential']" = 'linear')[source]¶

Parameters:

remove_unhealthy_endpoints (bool)
maximum_error_count_for_removal (int)
monitor_unhealthy_endpoints (bool)
maximum_recovery_attempts (int)
retry_backoff_policy (Literal['linear', 'exponential'])

remove_unhealthy_endpoints: bool = False¶: Whether to remove unhealthy endpoints on connection errors

maximum_error_count_for_removal: int = 2¶: Maximum numbers of errors to tolerate before marking an endpoint as unhealthy

monitor_unhealthy_endpoints: bool = False¶: Whether to monitor unhealthy endpoints after they have been removed and attempt to restore them if they recover

maximum_recovery_attempts: int = 4¶: Maximum attempts to make to recover unhealthy endpoints

retry_backoff_policy: Literal['linear', 'exponential'] = 'linear'¶: Retry backoff policy

enum EndpointStatus(value)[source]¶

Enumeration of endpoint statuses. Used by update_endpoint_status()

Member Type:: int

Valid values are as follows:

UP = <EndpointStatus.UP: 1>¶

DOWN = <EndpointStatus.DOWN: 2>¶

class PoolMetrics(created_at: float | None = None, requests_processed: int = 0, requests_failed: int = 0, last_connection_created: float = 0.0, last_request_processed: float = 0.0, average_response_time: float = 0.0, requests_pending: int = 0, current_connections: int = 0, maximum_connections: int = 0, connection_errors: int = 0, status: EndpointStatus | None = None, down_count: int = 0, recovery_count: int = 0)[source]¶

Tracks metrics for a connection pool.

Parameters:

created_at (float | None)
requests_processed (int)
requests_failed (int)
last_connection_created (float)
last_request_processed (float)
average_response_time (float)
requests_pending (int)
current_connections (int)
maximum_connections (int)
connection_errors (int)
status (EndpointStatus | None)
down_count (int)
recovery_count (int)

created_at: float | None = None¶: Timestamp when the pool was initialized.

requests_processed: int = 0¶: Total number of successfully processed requests.

requests_failed: int = 0¶: Total number of requests that failed.

last_connection_created: float = 0.0¶: Timestamp when the last connection was established

last_request_processed: float = 0.0¶: Timestamp when the last request completed processing.

average_response_time: float = 0.0¶: Average time taken to process requests.

requests_pending: int = 0¶: Number of requests currently pending.

current_connections: int = 0¶: Current connections

maximum_connections: int = 0¶: Maximum connections created

connection_errors: int = 0¶: Total number of connection errors

status: EndpointStatus | None = None¶: Current endpoint status

down_count: int = 0¶: Number of times the pool was marked down

recovery_count: int = 0¶: Number of times the node was switched from down to up

Connections¶

class BaseConnection(*, connect_timeout: float | None = CONNECT_TIMEOUT, read_timeout: float | None = READ_TIMEOUT, socket_keepalive: bool | None = True, socket_keepalive_options: dict[int, int | bytes] | None = None, socket_nodelay: bool | None = False, max_inflight_requests_per_connection: int = MAX_INFLIGHT_REQUESTS_PER_CONNECTION, max_average_response_time_for_connection_reuse: float = MAX_AVERAGE_RESPONSE_TIME_FOR_CONNECTION_REUSE, ssl_context: SSLContext | None = None, authenticator: Authenticator | None = None, username: str | None = None, password: str | None = None, on_connect_callbacks: list[Callable[[BaseConnection], None]] | None = None, on_disconnect_callbacks: list[Callable[[BaseConnection], None]] | None = None)[source]¶

Wraps an asyncio connection using a custom protocol. Provides methods for sending commands and reading lines.

Parameters:

connect_timeout (float | None) – Timeout for establishing a connection.
read_timeout (float | None) – Timeout for reading data from the connection.
socket_keepalive (bool | None) – Whether to enable SO_KEEPALIVE on the socket.
socket_keepalive_options (dict[int, int | bytes] | None) – Additional keepalive options.
socket_nodelay (bool | None) – Whether to enable TCP_NODELAY on the socket.
max_inflight_requests_per_connection (int) – Maximum concurrent requests allowed.
max_average_response_time_for_connection_reuse (float) – Threshold for allowing the connection to be reused when there are requests pending.
ssl_context (SSLContext | None) – SSL context for secure connections.
authenticator (Authenticator | None) – Authentication strategy to use after establishing a connection
username (str | None) – Username for SASL authentication.
password (str | None) – Password for SASL authentication.
on_connect_callbacks (list[Callable[[BaseConnection], None]] | None) – Callbacks to invoke upon successful connection.
on_disconnect_callbacks (list[Callable[[BaseConnection], None]] | None) – Callbacks to invoke upon disconnection.

metrics: ConnectionMetrics¶: Metrics related to this connection

abstractmethod async connect() → None[source]¶

Establish a connection to the target memcached server

Return type:: None

property connected: bool¶: Whether the connection is currently connected

property reusable: bool¶: Whether this connection is healthy enough to handle any more concurrent requests

close() → None[source]¶

Disconnect from the memcached server and clear internal state.

Return type:: None

create_request(command: Command[R]) → None[source]¶

Send a request to the memcached server and queue the response handling if this is not a noreply request.

Parameters:: command (Command[R])
Return type:: None

class TCPConnection(host_port: TCPEndpoint | tuple[str, int], **kwargs: Unpack[ConnectionParams])[source]¶

Parameters:

connect_timeout – Timeout for establishing a connection.
read_timeout – Timeout for reading data from the connection.
socket_keepalive – Whether to enable SO_KEEPALIVE on the socket.
socket_keepalive_options – Additional keepalive options.
socket_nodelay – Whether to enable TCP_NODELAY on the socket.
max_inflight_requests_per_connection – Maximum concurrent requests allowed.
max_average_response_time_for_connection_reuse – Threshold for allowing the connection to be reused when there are requests pending.
ssl_context – SSL context for secure connections.
authenticator – Authentication strategy to use after establishing a connection
username – Username for SASL authentication.
password – Password for SASL authentication.
on_connect_callbacks – Callbacks to invoke upon successful connection.
on_disconnect_callbacks – Callbacks to invoke upon disconnection.
host_port (TCPEndpoint | tuple[str, int])
kwargs (Unpack[ConnectionParams])

async connect() → None[source]¶

Establish a connection to the target memcached server listening on a tcp port

Return type:: None

close() → None¶

Disconnect from the memcached server and clear internal state.

Return type:: None

property connected: bool¶: Whether the connection is currently connected

create_request(command: Command[R]) → None¶

Send a request to the memcached server and queue the response handling if this is not a noreply request.

Parameters:: command (Command[R])
Return type:: None

property reusable: bool¶: Whether this connection is healthy enough to handle any more concurrent requests

metrics: ConnectionMetrics¶: Metrics related to this connection

class UnixSocketConnection(path: str | Path, **kwargs: Unpack[ConnectionParams])[source]¶

Parameters:

connect_timeout – Timeout for establishing a connection.
read_timeout – Timeout for reading data from the connection.
socket_keepalive – Whether to enable SO_KEEPALIVE on the socket.
socket_keepalive_options – Additional keepalive options.
socket_nodelay – Whether to enable TCP_NODELAY on the socket.
max_inflight_requests_per_connection – Maximum concurrent requests allowed.
max_average_response_time_for_connection_reuse – Threshold for allowing the connection to be reused when there are requests pending.
ssl_context – SSL context for secure connections.
authenticator – Authentication strategy to use after establishing a connection
username – Username for SASL authentication.
password – Password for SASL authentication.
on_connect_callbacks – Callbacks to invoke upon successful connection.
on_disconnect_callbacks – Callbacks to invoke upon disconnection.
path (UnixSocketEndpoint)
kwargs (Unpack[ConnectionParams])

close() → None¶

Disconnect from the memcached server and clear internal state.

Return type:: None

async connect() → None[source]¶

Establish a connection to the target memcached server listening on a unix domain socket

Return type:: None

property connected: bool¶: Whether the connection is currently connected

create_request(command: Command[R]) → None¶

Send a request to the memcached server and queue the response handling if this is not a noreply request.

Parameters:: command (Command[R])
Return type:: None

property reusable: bool¶: Whether this connection is healthy enough to handle any more concurrent requests

metrics: ConnectionMetrics¶: Metrics related to this connection

class ConnectionMetrics(created_at: float | None = None, requests_processed: int = 0, requests_failed: int = 0, last_written: float = 0.0, last_read: float = 0.0, last_request_processed: float = 0.0, average_response_time: float = 0.0, requests_pending: int = 0)[source]¶

Tracks metrics for a connection.

Parameters:

created_at (float | None)
requests_processed (int)
requests_failed (int)
last_written (float)
last_read (float)
last_request_processed (float)
average_response_time (float)
requests_pending (int)

created_at: float | None = None¶: Timestamp when the connection was established.

requests_processed: int = 0¶: Total number of successfully processed requests.

requests_failed: int = 0¶: Total number of requests that failed.

last_written: float = 0.0¶: Timestamp when data was last written.

last_read: float = 0.0¶: Timestamp when data was last read.

last_request_processed: float = 0.0¶: Timestamp when the last request completed processing.

average_response_time: float = 0.0¶: Average time taken to process requests.

requests_pending: int = 0¶: Number of requests currently pending.

Exception types¶

exception MemcachedError[source]¶: Base exception for any errors raised by the memcached servers

exception ClientError[source]¶: Raised when memcached responds with CLIENT_ERROR

exception ServerError[source]¶: Raised when memcached responds with SERVER_ERROR

exception MemcachioConnectionError(message: str, endpoint: str | Path | TCPEndpoint | tuple[str, int])[source]¶

Base exception for any connection errors encountered.

Parameters:

message (str)
endpoint (str | Path | TCPEndpoint | tuple[str, int])

endpoint: str | Path | TCPEndpoint | tuple[str, int]¶: The memcached server where the connection error originated from

exception ConnectionNotAvailable(endpoint: str | Path | TCPEndpoint | tuple[str, int], timeout: float)[source]¶

Raised when a connection couldn’t be acquired from the pool within the configured timeout

Parameters:

endpoint (str | Path | TCPEndpoint | tuple[str, int])
timeout (float)

exception NoAvailableNodes[source]¶: Raised when no nodes are available in the cluster

exception AutoDiscoveryError[source]¶: Raised when the response for autodiscovery is invalid

Types¶

KeyT = str | bytes¶: Acceptable types for a memcached key

ValueT = str | bytes | int¶: Acceptable types for values to store

class TCPEndpoint(host: str, port: int)[source]¶

Location of a memcached server listening on a tcp port

Parameters:

host (str)
port (int)

host: str¶: IPV4/6 host address

port: int¶: IPV4/6 port

UnixSocketEndpoint = str | pathlib._local.Path¶: Path to a memcached server listening on a UDS socket

class AWSAutoDiscoveryEndpoint(host: str, port: int, refresh_interval: float)[source]¶

Location of a memcached auto-discovery endpoint for use with AWS Elasticache

Parameters:

host (str)
port (int)
refresh_interval (float)

host: str¶: IPV4/6 host address

port: int¶: IPV4/6 port

refresh_interval: float¶: How often to trigger a refresh to check for updates

SingleMemcachedInstanceEndpoint = str | pathlib._local.Path | memcachio.types.TCPEndpoint | tuple[str, int]¶: The total description of a single memcached instance

MemcachedEndpoint = str | pathlib._local.Path | memcachio.types.TCPEndpoint | tuple[str, int] | collections.abc.Sequence[str | pathlib._local.Path | memcachio.types.TCPEndpoint | tuple[str, int]] | memcachio.types.AWSAutoDiscoveryEndpoint¶: The total description of either a single memcached instance or a memcached cluster

class MemcachedItem(key: AnyStr, flags: int, size: int, cas: int | None, value: AnyStr)[source]¶

Data class returned by retrieval commands such as get(), gets(), gat() and gats()

Parameters:

key (AnyStr)
flags (int)
size (int)
cas (int | None)
value (AnyStr)

key: AnyStr¶: The key of the item

flags: int¶: Any flags set on the item

size: int¶: The size (in bytes) of the data stored in the item

cas: int | None¶: The CAS value for the item if retrieved

value: AnyStr¶: The data value of the item

class ConnectionParams[source]¶

connect_timeout: float | None¶: Maximum time to wait when establishing a connection

read_timeout: float | None¶: Maximum time to wait for a response

socket_nodelay: NotRequired[bool | None]¶: Whether to set the socket.TCP_NODELAY flag on the socket

socket_keepalive: NotRequired[bool | None]¶: Whether to set the socket.SO_KEEPALIVE flag on the socket

socket_keepalive_options: NotRequired[dict[int, int | bytes] | None]¶: Additional options to set if socket_keepalive is True

max_inflight_requests_per_connection: NotRequired[int]¶: Maximum number of concurrent requests to allow on the connection

max_average_response_time_for_connection_reuse: NotRequired[float]¶: Threshold for allowing the connection to be reused when there are requests pending.

ssl_context: NotRequired[SSLContext | None]¶: SSL context to use if connecting to a memcached instance listening on a secure port

authenticator: NotRequired[Authenticator | None]¶: Authentication strategy to use after establishing a connection

username: NotRequired[str | None]¶: Username for SASL authentication

password: NotRequired[str | None]¶: Password for SASL authentication

Implementation Details¶

Command Types¶

class Command(*keys: KeyT, noreply: bool = False)[source]¶

The abstract generic command class used throughout the client -> connection pool -> connection lifecycle to manage dispatching a request, parsing the response (if not a noreply request) and resolving the future to receive the eventual parsed response.

This class is not meant for direct use, however it’s structure might be interesting if implementing a custom connection pool or using the connection classes directly.

As an example the following snippet demonstrates creating a set command that takes no flags or expiry and is dispatched directly to a connection without using Client or a Pool:

import asyncio
import weakref
from io import BytesIO

import memcachio
from memcachio.commands import Command, Request
from memcachio.constants import Commands


class MyCustomSetCommand(Command[bool]):
    name = Commands.SET

    def __init__(self, key: str, value: bytes, noreply: bool = False):
        self.value = value
        super().__init__(key, noreply=noreply)

    def build_request(self) -> memcachio.commands.Request[bool]:
        return Request(
            weakref.proxy(self),
            b"%b 0 0 %d" % (self.keys[0].encode(), len(self.value)),
            [self.value + b"\r\n"],
        )

    def parse(self, data: BytesIO, endpoint: SingleMemcachedInstanceEndpoint) -> bool:
        response = data.readline()
        return response.rstrip() == b"STORED"


async def example():
    command = MyCustomSetCommand("fubar", b"1234")
    connection = memcachio.TCPConnection(("localhost", 11211))
    await connection.connect()
    connection.create_request(command)
    assert await command.response


asyncio.run(example())

Parameters:

keys (KeyT) – The keys this command operates on
noreply (bool) – Whether the server should send a response to the command.

name: ClassVar[Commands]¶: The name of the command

response_time: float¶

request_sent: Future[bool]¶: A future that should be set when the request has been written to the socket

response: Future[R]¶: A future that should be set when the request has received a response and parsed

abstractmethod build_request() → Request[R][source]¶

Build the header and (optional) payload for the request to send to the memcached server

Return type:: Request[R]

abstractmethod parse(data: BytesIO, endpoint: str | Path | TCPEndpoint | tuple[str, int]) → R[source]¶

Parse the response from the buffer assuming the current position of the buffer contains the response for this command.

Parameters:

data (BytesIO)
endpoint (str | Path | TCPEndpoint | tuple[str, int])

Return type:

class Request(command: 'weakref.ProxyType[Command[R]]', header: 'bytes', body: 'list[bytes]' = <factory>)[source]¶

Parameters:

command (weakref.ProxyType[Command[R]])
header (bytes)
body (list[bytes])

Authentication¶

class Authenticator[source]¶

Abstract class for authentication strategy used by memcachio.BaseConnection.

abstractmethod async authenticate(connection: BaseConnection) → bool[source]¶

The method that will be called immediately after a connection is established to the server. This should perform any authentication handshake required by the server. See memcachio.SimpleAuthenticator for an example.

Parameters:: connection (BaseConnection) – The connection instance that was established
Return type:: bool

class SimpleAuthenticator(username: str, password: str)[source]¶

A username/password authentication strategy for the ASCII protocol as defined in the memcached protocol documentation.

Parameters:

username (str)
password (str)

async authenticate(connection: BaseConnection) → bool[source]¶

Authenticate the connection using a fake set command with the username and password as the payload.

Parameters:: connection (BaseConnection)
Return type:: bool

Routing¶

Rendezvous Hashing implementation to route keys to memcached nodes.

Parameters:

nodes (set[SingleMemcachedInstanceEndpoint] | None) – set of memcached nodes that are candidates
hasher (Callable[[str], int] | None) – function to use to hash a key to a node. If not provided, a default implementation using hashlib.md5() from the standard library will be used.

add_node(node: str | Path | TCPEndpoint | tuple[str, int]) → None[source]¶

Add a node to the set of candidate nodes

Parameters:: node (str | Path | TCPEndpoint | tuple[str, int])
Return type:: None

remove_node(node: str | Path | TCPEndpoint | tuple[str, int]) → None[source]¶

Remove a node from the set of candidate nodes

Parameters:: node (str | Path | TCPEndpoint | tuple[str, int])
Return type:: None

get_node(key: str) → str | Path | TCPEndpoint | tuple[str, int][source]¶

Get the node associated with key

Parameters:: key (str)
Return type:: str | Path | TCPEndpoint | tuple[str, int]