Reference

class pylibmc.Client(servers[, binary=False, username=None, password=None, behaviors=None])

Interface to a set of memcached servers.

servers is a sequence of strings specifying the servers to use.

binary specifies whether or not to use the binary protocol to talk to the memcached servers.

username and password are credentials for SASL authentication. It requires support in libmemcached, and binary=True. Test for local support with pylibmc.support_sasl.

behaviors, if given, is passed to Client.set_behaviors() after initialization.

Supported transport mechanisms are TCP, UDP and UNIX domain sockets. The default transport type is TCP.

To specify UDP, the server address should be prefixed with "udp:", as in "udp:127.0.0.1".

To specify UNIX domain socket, the server address must start with a slash, as in "/run/foo.sock".

Mixing transport types is prohibited by pylibmc as this is not supported by libmemcached.

clone() → clone

Clone client, making new connections as necessary.

get(key[, default]) → value

Get key if it exists, otherwise default. If default is not given, it defaults to None.

get_multi(keys[, key_prefix=None]) → values

Get each of the keys in sequence keys.

If key_prefix is given, specifies a string to prefix each of the values in keys with.

Returns a mapping of each unprefixed key to its corresponding value in memcached. If a key doesn’t exist, no corresponding key is set in the returned mapping.

set(key, value[, time=0, min_compress_len=0, compress_level=-1]) → success

Set key to value.

Parameters:

• key – Key to use

• value – Value to set

• time – Time until expiry

• min_compress_len – Minimum length before compression is triggered

If time is given, it specifies the number of seconds until key will expire. Default behavior is to never expire (equivalent of specifying 0).

Warning

The time argument is passed on to memcached as is, and memcached interprets it in two ways. A value up to and including 30 days (60 * 60 * 24 * 30 = 2592000 seconds) is a number of seconds from now. A larger value is taken as an absolute Unix timestamp. So time=30 * 86400 + 1 is a moment in January 1970, and the key is already expired when it is stored (the call still returns True). To expire a key more than 30 days from now, pass int(time.time()) + seconds.

Negative values are not meaningful, and the two protocols disagree about them: with the text protocol (the default) the key is expired immediately, with the binary protocol (binary=True) it is stored and does not expire. This is observed behavior, not a guarantee, and it may change; do not rely on it. Use delete() to remove a key.

The same rules apply to every method below that takes time.

If min_compress_len is given, it specifies the maximum number of actual bytes stored in memcached before compression is used. Default behavior is to never compress (which is what 0 means). See Compression.

If compress_level is given, it specifies the compression level for the data. It accepts the same values as the zlib family, for which zlib.Z_BEST_SPEED and zlib.Z_BEST_COMPRESSION are commonly used constants. It accepts values between [0, 9] inclusively.

set_multi(mapping[, time=0, key_prefix=None, min_compress_len, compress_level]) → failed_keys

Set multiple keys as given by mapping. time is the same as for set(), including the 30 day limit for relative times.

If key_prefix is specified, each of the keys in mapping is prepended with this value.

Returns a list of keys which were not set for one reason or another, without their optional key prefix.

add(key, value[, time, min_compress_len, compress_level]) → success

Sets key if it does not exist. time is the same as for set().

See also

set(), replace()

replace(key, value[, time, min_compress_len, compress_level]) → success

Sets key only if it already exists. time is the same as for set().

See also

set(), add()

append(key, value) → success

Append value to key (i.e., m[k] = m[k] + v).

Note

Uses memcached’s appending support, and therefore should never be used on keys which may be compressed or non-string values.

prepend(key, value) → success

Prepend value to key (i.e., m[k] = v + m[k]).

Note

Uses memcached’s prepending support, and therefore should never be used on keys which may be compressed or non-string values.

incr(key[, delta=1]) → value

Increment value at key by delta.

Returns the new value for key, after incrementing.

Works for both strings and integer types.

Note

There is currently no way to set a default for key when incrementing.

decr(key[, delta=1]) → value

Decrement value at key by delta.

Returns the new value for key, after decrementing.

Works for both strings and integer types, but will never decrement below zero.

Note

There is currently no way to set a default for key when decrementing.

gets(key)

Get key and its compare-and-swap ID if it exists, otherwise (None, None).

The so-called CAS token or ID is used with cas() to update a value with the guarantee that no other value was written in between.

See also

get(), cas()

cas(key, value, cas[, time=0]) → swapped

Set key to value if key CAS token is cas.

Parameters:

• key – Key to use

• value – Value to set

• cas – Compare-and-swap token from gets()

• time – Time until expiry

If time is given, it specifies the number of seconds until key will expire. Default behavior is to never expire (equivalent of specifying 0). Times over 30 days are absolute timestamps and negative times are not meaningful, see set().

delete(key) → deleted

Delete key if it exists.

Returns True if the key was deleted, False otherwise (as is the case if it wasn’t set in the first place.)

delete_multi(keys[, key_prefix=None]) → deleted

Delete each of key in the sequence keys.

Parameters:

• keys – Sequence of keys to delete

• key_prefix – Prefix for the keys to delete

Returns True if all keys were successfully deleted, False otherwise (as is the case if it wasn’t set in the first place.)

touch(key, time) → touched

Touch a given key and set its expiry time to time seconds.

Parameters:

• key – Key to touch

• time – Number of seconds until the key expires.

Times over 30 days are absolute Unix timestamps, see set(). With libmemcached 1.0.x and the text protocol, a negative time raises pylibmc.AllocationError (libmemcached refuses to write the command); with libmemcached 1.1.x it expires the key immediately.

Returns True if the key was successfully touched. False if the key did not exist (so touching is not possible.)

disconnect_all()

Disconnect from all servers and reset internal state.

Exposed mainly for compatibility with python-memcached, as there really is no logical reason to do this.

flush_all() → success

Flush all data from all servers.

Note

This clears the specified memcacheds fully and entirely.

get_stats() → [name, stats, ...]

Retrieve statistics from each of the connected memcached instances.

Returns a list of two-tuples of the format (name, stats).

stats is a mapping of statistics item names to their values. Whether or not a key exists depends on the version of libmemcached and memcached used.

serialize(value) → bytestring, flag

Serialize a Python value to bytes bytestring and an integer flag field for storage in memcached. The default implementation has special cases for bytes, ints/longs, and bools, and falls back to pickle for all other objects. Override this method to use a custom serialization format, or otherwise modify the behavior.

flag is exposed by the memcached protocol. It adds flexibility in terms of encoding schemes: for example, objects a and b of different types may coincidentally encode to the same bytestring, just so long as they encode with different values of flag. If distinct values always encode to different byte strings (for example, when serializing all values with pickle), flag can simply be set to a constant.

deserialize(bytestring, flag) → value

Deserialize bytestring, stored with flag, back to a Python object. Override this method (in concert with serialize) to use a custom serialization format, or otherwise modify the behavior.

Raise CacheMiss in order to simulate a cache miss for the relevant key, i.e., get will return None and get_multi will omit the key from the returned mapping. This can be used to recover gracefully from version skew (e.g., retrieving a value that was pickled by a different, incompatible code version).

behaviors

The behaviors used by the underlying libmemcached object. See Behaviors for more information.