pymemcache.client.base module

class pymemcache.client.base.Client(server: ~typing.Union[~typing.Tuple[str, int], str], serde=None, serializer=None, deserializer=None, connect_timeout: ~typing.Optional[float] = None, timeout: ~typing.Optional[float] = None, no_delay: bool = False, ignore_exc: bool = False, socket_module: module = <module 'socket' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/socket.py'>, socket_keepalive: ~typing.Optional[~pymemcache.client.base.KeepaliveOpts] = None, key_prefix: bytes = b'', default_noreply: bool = True, allow_unicode_keys: bool = False, encoding: str = 'ascii', tls_context: ~typing.Optional[~ssl.SSLContext] = None)

Bases: object

A client for a single memcached server.

Server Connection

The server parameter controls how the client connects to the memcached server. You can either use a (host, port) tuple for a TCP connection or a string containing the path to a UNIX domain socket.

The connect_timeout and timeout parameters can be used to set socket timeout values. By default, timeouts are disabled.

When the no_delay flag is set, the TCP_NODELAY socket option will also be set. This only applies to TCP-based connections.

Lastly, the socket_module allows you to specify an alternate socket implementation (such as gevent.socket).

Keys and Values

Keys must have a __str__() method which should return a str with no more than 250 ASCII characters and no whitespace or control characters. Unicode strings must be encoded (as UTF-8, for example) unless they consist only of ASCII characters that are neither whitespace nor control characters.

Values must have a __str__() method to convert themselves to a byte string. Unicode objects can be a problem since str() on a Unicode object will attempt to encode it as ASCII (which will fail if the value contains code points larger than U+127). You can fix this with a serializer or by just calling encode on the string (using UTF-8, for instance).

If you intend to use anything but str as a value, it is a good idea to use a serializer. The pymemcache.serde library has an already implemented serializer which pickles and unpickles data.

Serialization and Deserialization

The constructor takes an optional object, the “serializer/deserializer” (“serde”), which is responsible for both serialization and deserialization of objects. That object must satisfy the serializer interface by providing two methods: serialize and deserialize. serialize takes two arguments, a key and a value, and returns a tuple of two elements, the serialized value, and an integer in the range 0-65535 (the “flags”). deserialize takes three parameters, a key, value, and flags, and returns the deserialized value.

Here is an example using JSON for non-str values:

class JSONSerde(object):
    def serialize(self, key, value):
        if isinstance(value, str):
            return value, 1
        return json.dumps(value), 2

    def deserialize(self, key, value, flags):
        if flags == 1:
            return value

        if flags == 2:
            return json.loads(value)

        raise Exception("Unknown flags for value: {1}".format(flags))

Note

Most write operations allow the caller to provide a flags value to support advanced interaction with the server. This will override the “flags” value returned by the serializer and should therefore only be used when you have a complete understanding of how the value should be serialized, stored, and deserialized.

Error Handling

All of the methods in this class that talk to memcached can throw one of the following exceptions:

Instances of this class maintain a persistent connection to memcached which is terminated when any of these exceptions are raised. The next call to a method on the object will result in a new connection being made to memcached.

__init__(server: ~typing.Union[~typing.Tuple[str, int], str], serde=None, serializer=None, deserializer=None, connect_timeout: ~typing.Optional[float] = None, timeout: ~typing.Optional[float] = None, no_delay: bool = False, ignore_exc: bool = False, socket_module: module = <module 'socket' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/socket.py'>, socket_keepalive: ~typing.Optional[~pymemcache.client.base.KeepaliveOpts] = None, key_prefix: bytes = b'', default_noreply: bool = True, allow_unicode_keys: bool = False, encoding: str = 'ascii', tls_context: ~typing.Optional[~ssl.SSLContext] = None)

Constructor.

Parameters
  • server – tuple(hostname, port) or string containing a UNIX socket path.

  • serde – optional serializer object, see notes in the class docs.

  • serializer – deprecated serialization function

  • deserializer – deprecated deserialization function

  • connect_timeout – optional float, seconds to wait for a connection to the memcached server. Defaults to “forever” (uses the underlying default socket timeout, which can be very long).

  • timeout – optional float, seconds to wait for send or recv calls on the socket connected to memcached. Defaults to “forever” (uses the underlying default socket timeout, which can be very long).

  • no_delay – optional bool, set the TCP_NODELAY flag, which may help with performance in some cases. Defaults to False.

  • ignore_exc – optional bool, True to cause the “get”, “gets”, “get_many” and “gets_many” calls to treat any errors as cache misses. Defaults to False.

  • socket_module – socket module to use, e.g. gevent.socket. Defaults to the standard library’s socket module.

  • socket_keepalive – Activate the socket keepalive feature by passing a KeepaliveOpts structure in this parameter. Disabled by default (None). This feature is only supported on Linux platforms.

  • key_prefix – Prefix of key. You can use this as namespace. Defaults to b’’.

  • default_noreply – bool, the default value for ‘noreply’ as passed to store commands (except from cas, incr, and decr, which default to False).

  • allow_unicode_keys – bool, support unicode (utf8) keys

  • encoding – optional str, controls data encoding (defaults to ‘ascii’).

Notes

The constructor does not make a connection to memcached. The first call to a method on the object will do that.

add(key: Union[bytes, str], value: Any, expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None) bool

The memcached “add” command.

Parameters
  • key – str, see class docs for details.

  • value – str, see class docs for details.

  • expire – optional int, number of seconds until the item is expired from the cache, or zero for no expiry (the default).

  • noreply – optional bool, True to not wait for the reply (defaults to self.default_noreply).

  • flags – optional int, arbitrary bit field used for server-specific flags

Returns

If noreply is True (or if it is unset and self.default_noreply is True), the return value is always True. Otherwise the return value is True if the value was stored, and False if it was not (because the key already existed).

append(key: Union[bytes, str], value, expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None) bool

The memcached “append” command.

Parameters
  • key – str, see class docs for details.

  • value – str, see class docs for details.

  • expire – optional int, number of seconds until the item is expired from the cache, or zero for no expiry (the default).

  • noreply – optional bool, True to not wait for the reply (defaults to self.default_noreply).

  • flags – optional int, arbitrary bit field used for server-specific flags

Returns

True.

cache_memlimit(memlimit) bool

The memcached “cache_memlimit” command.

Parameters

memlimit – int, the number of megabytes to set as the new cache memory limit.

Returns

If no exception is raised, always returns True.

cas(key, value, cas, expire: int = 0, noreply=False, flags: Optional[int] = None) Optional[bool]

The memcached “cas” command.

Parameters
  • key – str, see class docs for details.

  • value – str, see class docs for details.

  • cas – int or str that only contains the characters ‘0’-‘9’.

  • expire – optional int, number of seconds until the item is expired from the cache, or zero for no expiry (the default).

  • noreply – optional bool, False to wait for the reply (the default).

  • flags – optional int, arbitrary bit field used for server-specific flags

Returns

If noreply is True (or if it is unset and self.default_noreply is True), the return value is always True. Otherwise returns None if the key didn’t exist, False if it existed but had a different cas value and True if it existed and was changed.

check_key(key: Union[bytes, str], key_prefix: bytes) bytes

Checks key and add key_prefix.

close() None

Close the connection to memcached, if it is open. The next call to a method that requires a connection will re-open it.

decr(key: Union[bytes, str], value: int, noreply: Optional[bool] = False) Optional[int]

The memcached “decr” command.

Parameters
  • key – str, see class docs for details.

  • value – int, the amount by which to decrement the value.

  • noreply – optional bool, False to wait for the reply (the default).

Returns

If noreply is True, always returns None. Otherwise returns the new value of the key, or None if the key wasn’t found.

delete(key: Union[bytes, str], noreply: Optional[bool] = None) bool

The memcached “delete” command.

Parameters
  • key – str, see class docs for details.

  • noreply – optional bool, True to not wait for the reply (defaults to self.default_noreply).

Returns

If noreply is True (or if it is unset and self.default_noreply is True), the return value is always True. Otherwise returns True if the key was deleted, and False if it wasn’t found.

delete_many(keys: Iterable[Union[bytes, str]], noreply: Optional[bool] = None) bool

A convenience function to delete multiple keys.

Parameters
  • keys – list(str), the list of keys to delete.

  • noreply – optional bool, True to not wait for the reply (defaults to self.default_noreply).

Returns

True. If an exception is raised then all, some or none of the keys may have been deleted. Otherwise all the keys have been sent to memcache for deletion and if noreply is False, they have been acknowledged by memcache.

delete_multi(keys: Iterable[Union[bytes, str]], noreply: Optional[bool] = None) bool

A convenience function to delete multiple keys.

Parameters
  • keys – list(str), the list of keys to delete.

  • noreply – optional bool, True to not wait for the reply (defaults to self.default_noreply).

Returns

True. If an exception is raised then all, some or none of the keys may have been deleted. Otherwise all the keys have been sent to memcache for deletion and if noreply is False, they have been acknowledged by memcache.

disconnect_all() None

Close the connection to memcached, if it is open. The next call to a method that requires a connection will re-open it.

flush_all(delay: int = 0, noreply: Optional[bool] = None) bool

The memcached “flush_all” command.

Parameters
  • delay – optional int, the number of seconds to wait before flushing, or zero to flush immediately (the default).

  • noreply – optional bool, True to not wait for the reply (defaults to self.default_noreply).

Returns

True.

gat(key: Union[bytes, str], expire: int = 0, default: Optional[Any] = None) Any

The memcached “gat” command, but only for one key, as a convenience.

Parameters
  • key – str, see class docs for details.

  • expire – optional int, number of seconds until the item is expired from the cache, or zero for no expiry (the default).

  • default – value that will be returned if the key was not found.

Returns

The value for the key, or default if the key wasn’t found.

gats(key: Union[bytes, str], expire: int = 0, default: Optional[Any] = None, cas_default: Optional[Any] = None) Tuple[Any, Any]

The memcached “gats” command, but only for one key, as a convenience.

Parameters
  • key – str, see class docs for details.

  • expire – optional int, number of seconds until the item is expired from the cache, or zero for no expiry (the default).

  • default – value that will be returned if the key was not found.

  • cas_default – same behaviour as default argument.

Returns

A tuple of (value, cas) or (default, cas_defaults) if the key was not found.

get(key: Union[bytes, str], default: Optional[Any] = None) Any

The memcached “get” command, but only for one key, as a convenience.

Parameters
  • key – str, see class docs for details.

  • default – value that will be returned if the key was not found.

Returns

The value for the key, or default if the key wasn’t found.

get_many(keys: Iterable[Union[bytes, str]]) Dict[Union[bytes, str], Any]

The memcached “get” command.

Parameters

keys – list(str), see class docs for details.

Returns

A dict in which the keys are elements of the “keys” argument list and the values are values from the cache. The dict may contain all, some or none of the given keys.

get_multi(keys: Iterable[Union[bytes, str]]) Dict[Union[bytes, str], Any]

The memcached “get” command.

Parameters

keys – list(str), see class docs for details.

Returns

A dict in which the keys are elements of the “keys” argument list and the values are values from the cache. The dict may contain all, some or none of the given keys.

gets(key: Union[bytes, str], default: Optional[Any] = None, cas_default: Optional[Any] = None) Tuple[Any, Any]

The memcached “gets” command for one key, as a convenience.

Parameters
  • key – str, see class docs for details.

  • default – value that will be returned if the key was not found.

  • cas_default – same behaviour as default argument.

Returns

A tuple of (value, cas) or (default, cas_defaults) if the key was not found.

gets_many(keys: Iterable[Union[bytes, str]]) Dict[Union[bytes, str], Tuple[Any, Any]]

The memcached “gets” command.

Parameters

keys – list(str), see class docs for details.

Returns

A dict in which the keys are elements of the “keys” argument list and the values are tuples of (value, cas) from the cache. The dict may contain all, some or none of the given keys.

incr(key: Union[bytes, str], value: int, noreply: Optional[bool] = False) Optional[int]

The memcached “incr” command.

Parameters
  • key – str, see class docs for details.

  • value – int, the amount by which to increment the value.

  • noreply – optional bool, False to wait for the reply (the default).

Returns

If noreply is True, always returns None. Otherwise returns the new value of the key, or None if the key wasn’t found.

prepend(key, value, expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None)

The memcached “prepend” command.

Parameters
  • key – str, see class docs for details.

  • value – str, see class docs for details.

  • expire – optional int, number of seconds until the item is expired from the cache, or zero for no expiry (the default).

  • noreply – optional bool, True to not wait for the reply (defaults to self.default_noreply).

  • flags – optional int, arbitrary bit field used for server-specific flags

Returns

True.

quit() None

The memcached “quit” command.

This will close the connection with memcached. Calling any other method on this object will re-open the connection, so this object can be re-used after quit.

raw_command(command: Union[str, bytes], end_tokens: Union[str, bytes] = '\r\n') bytes

Sends an arbitrary command to the server and parses the response until a specified token is encountered.

Parameters
  • command – str|bytes: The command to send.

  • end_tokens – str|bytes: The token expected at the end of the response. If the end_token is not found, the client will wait until the timeout specified in the constructor.

Returns

The response from the server, with the end_token removed.

replace(key: Union[bytes, str], value, expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None) bool

The memcached “replace” command.

Parameters
  • key – str, see class docs for details.

  • value – str, see class docs for details.

  • expire – optional int, number of seconds until the item is expired from the cache, or zero for no expiry (the default).

  • noreply – optional bool, True to not wait for the reply (defaults to self.default_noreply).

  • flags – optional int, arbitrary bit field used for server-specific flags

Returns

If noreply is True (or if it is unset and self.default_noreply is True), the return value is always True. Otherwise returns True if the value was stored and False if it wasn’t (because the key didn’t already exist).

set(key: Union[bytes, str], value: Any, expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None) Optional[bool]

The memcached “set” command.

Parameters
  • key – str, see class docs for details.

  • value – str, see class docs for details.

  • expire – optional int, number of seconds until the item is expired from the cache, or zero for no expiry (the default).

  • noreply – optional bool, True to not wait for the reply (defaults to self.default_noreply).

  • flags – optional int, arbitrary bit field used for server-specific flags

Returns

If no exception is raised, always returns True. If an exception is raised, the set may or may not have occurred. If noreply is True, then a successful return does not guarantee a successful set.

set_many(values: Dict[Union[bytes, str], Any], expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None) List[Union[bytes, str]]

A convenience function for setting multiple values.

Parameters
  • values – dict(str, str), a dict of keys and values, see class docs for details.

  • expire – optional int, number of seconds until the item is expired from the cache, or zero for no expiry (the default).

  • noreply – optional bool, True to not wait for the reply (defaults to self.default_noreply).

  • flags – optional int, arbitrary bit field used for server-specific flags

Returns

Returns a list of keys that failed to be inserted. If noreply is True, always returns empty list.

set_multi(values: Dict[Union[bytes, str], Any], expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None) List[Union[bytes, str]]

A convenience function for setting multiple values.

Parameters
  • values – dict(str, str), a dict of keys and values, see class docs for details.

  • expire – optional int, number of seconds until the item is expired from the cache, or zero for no expiry (the default).

  • noreply – optional bool, True to not wait for the reply (defaults to self.default_noreply).

  • flags – optional int, arbitrary bit field used for server-specific flags

Returns

Returns a list of keys that failed to be inserted. If noreply is True, always returns empty list.

shutdown(graceful: bool = False) None

The memcached “shutdown” command.

This will request shutdown and eventual termination of the server, optionally preceded by a graceful stop of memcached’s internal state machine. Note that the server needs to have been started with the shutdown protocol command enabled with the –enable-shutdown flag.

Parameters

graceful – optional bool, True to request a graceful shutdown with SIGUSR1 (defaults to False, i.e. SIGINT shutdown).

stats(*args)

The memcached “stats” command.

The returned keys depend on what the “stats” command returns. A best effort is made to convert values to appropriate Python types, defaulting to strings when a conversion cannot be made.

Parameters

*arg – extra string arguments to the “stats” command. See the memcached protocol documentation for more information.

Returns

A dict of the returned stats.

touch(key: Union[bytes, str], expire: int = 0, noreply: Optional[bool] = None) bool

The memcached “touch” command.

Parameters
  • key – str, see class docs for details.

  • expire – optional int, number of seconds until the item is expired from the cache, or zero for no expiry (the default).

  • noreply – optional bool, True to not wait for the reply (defaults to self.default_noreply).

Returns

True if the expiration time was updated, False if the key wasn’t found.

version() bytes

The memcached “version” command.

Returns

A string of the memcached version.

class pymemcache.client.base.KeepaliveOpts(idle: int = 1, intvl: int = 1, cnt: int = 5)

Bases: object

A configuration structure to define the socket keepalive.

This structure must be passed to a client. The client will configure its socket keepalive by using the elements of the structure.

Parameters
  • idle – The time (in seconds) the connection needs to remain idle before TCP starts sending keepalive probes. Should be a positive integer most greater than zero.

  • intvl – The time (in seconds) between individual keepalive probes. Should be a positive integer most greater than zero.

  • cnt – The maximum number of keepalive probes TCP should send before dropping the connection. Should be a positive integer most greater than zero.

__init__(idle: int = 1, intvl: int = 1, cnt: int = 5) None
cnt
idle
intvl
class pymemcache.client.base.PooledClient(server: ~typing.Union[~typing.Tuple[str, int], str], serde=None, serializer=None, deserializer=None, connect_timeout=None, timeout=None, no_delay=False, ignore_exc=False, socket_module=<module 'socket' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/socket.py'>, socket_keepalive=None, key_prefix=b'', max_pool_size=None, pool_idle_timeout=0, lock_generator=None, default_noreply: bool = True, allow_unicode_keys=False, encoding='ascii', tls_context=None)

Bases: object

A thread-safe pool of clients (with the same client api).

Parameters
  • max_pool_size – maximum pool size to use (going above this amount triggers a runtime error), by default this is 2147483648L when not provided (or none).

  • pool_idle_timeout – pooled connections are discarded if they have been unused for this many seconds. A value of 0 indicates that pooled connections are never discarded.

  • lock_generator – a callback/type that takes no arguments that will be called to create a lock or semaphore that can protect the pool from concurrent access (for example a eventlet lock or semaphore could be used instead)

Further arguments are interpreted as for Client constructor.

Note: if serde is given, the same object will be used for all clients in the pool. Your serde object must therefore be thread-safe.

__init__(server: ~typing.Union[~typing.Tuple[str, int], str], serde=None, serializer=None, deserializer=None, connect_timeout=None, timeout=None, no_delay=False, ignore_exc=False, socket_module=<module 'socket' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/socket.py'>, socket_keepalive=None, key_prefix=b'', max_pool_size=None, pool_idle_timeout=0, lock_generator=None, default_noreply: bool = True, allow_unicode_keys=False, encoding='ascii', tls_context=None)
add(key: Union[bytes, str], value, expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None)
append(key, value, expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None)
cas(key, value, cas, expire: int = 0, noreply=False, flags: Optional[int] = None)
check_key(key: Union[bytes, str]) bytes

Checks key and add key_prefix.

client_class

Client class used to create new clients

alias of Client

close() None
decr(key: Union[bytes, str], value, noreply=False)
delete(key: Union[bytes, str], noreply: Optional[bool] = None) bool
delete_many(keys: Iterable[Union[bytes, str]], noreply: Optional[bool] = None) bool
delete_multi(keys: Iterable[Union[bytes, str]], noreply: Optional[bool] = None) bool
disconnect_all() None
flush_all(delay=0, noreply=None) bool
gat(key: Union[bytes, str], expire: int = 0, default: Optional[Any] = None) Any
gats(key: Union[bytes, str], expire: int = 0, default: Optional[Any] = None) Any
get(key: Union[bytes, str], default: Optional[Any] = None) Any
get_many(keys: Iterable[Union[bytes, str]]) Dict[Union[bytes, str], Any]
get_multi(keys: Iterable[Union[bytes, str]]) Dict[Union[bytes, str], Any]
gets(key: Union[bytes, str]) Tuple[Any, Any]
gets_many(keys: Iterable[Union[bytes, str]]) Dict[Union[bytes, str], Tuple[Any, Any]]
incr(key: Union[bytes, str], value, noreply=False)
prepend(key, value, expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None)
quit() None
raw_command(command, end_tokens=b'\r\n')
replace(key, value, expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None)
set(key, value, expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None)
set_many(values, expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None)
set_multi(values, expire: int = 0, noreply: Optional[bool] = None, flags: Optional[int] = None)
shutdown(graceful: bool = False) None
stats(*args)
touch(key: Union[bytes, str], expire: int = 0, noreply=None)
version() bytes
pymemcache.client.base.check_key_helper(key: Union[bytes, str], allow_unicode_keys: bool, key_prefix: bytes = b'') bytes

Checks key and add key_prefix.

pymemcache.client.base.normalize_server_spec(server: Union[Tuple[str, int], str]) Union[Tuple[str, int], str]