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).

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.

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.

See also

set(), replace()

replace(key, value[, time, min_compress_len, compress_level]) → success¶: Sets key only if it already exists.

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) -> (value, cas_id)¶

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).

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.

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.