Class Client

Create a new Client object with the given list of servers.

Parameters:

• servers - servers is passed to set_servers.
• debug - whether to display error messages when a server can't be contacted.

Overrides: object.__init__

Set the pool of servers used by this client.

Parameters:

• servers - an array of servers. Servers can be passed in two forms:
  1. Strings of the form "host:port", which implies a default weight of 1.
  2. Tuples of the form ("host:port", weight), where weight is an integer weight value.

Unconditionally sets a key to a given value in the memcache.

The key can optionally be an tuple, with the first element being the hash value, if you want to avoid making this module calculate a hash value. You may prefer, for example, to keep all of a given user's objects on the same memcache server, so you could use the user's unique id as the hash value.

Parameters:

• time - Tells memcached the time which this value should expire, either as a delta number of seconds, or an absolute unix time-since-the-epoch value. See the memcached protocol docs section "Storage Commands" for more info on <exptime>. We default to 0 == cache forever.
• min_compress_len - The threshold length to kick in auto-compression of the value using the zlib.compress() routine. If the value being cached is a string, then the length of the string is measured, else if the value is an object, then the length of the pickle result is measured. If the resulting attempt at compression yeilds a larger string than the input, then it is discarded. For backwards compatability, this parameter defaults to 0, indicating don't ever try to compress.

Returns: int

Nonzero on success.

Sets multiple keys in the memcache doing just one query.

>>> notset_keys = mc.set_multi({'key1' : 'val1', 'key2' : 'val2'})
>>> mc.get_multi(['key1', 'key2']) == {'key1' : 'val1', 'key2' : 'val2'}
1

This method is recommended over regular set as it lowers the number of total packets flying around your network, reducing total latency, since your app doesn't have to wait for each round-trip of set before sending the next one.

Parameters:

• mapping - A dict of key/value pairs to set.
• time - Tells memcached the time which this value should expire, either as a delta number of seconds, or an absolute unix time-since-the-epoch value. See the memcached protocol docs section "Storage Commands" for more info on <exptime>. We default to 0 == cache forever.
• key_prefix - Optional string to prepend to each key when sending to memcache. Allows you to efficiently stuff these keys into a pseudo-namespace in memcache: >>> notset_keys = mc.set_multi({'key1' : 'val1', 'key2' : 'val2'}, key_prefix='subspace_') >>> len(notset_keys) == 0 True >>> mc.get_multi(['subspace_key1', 'subspace_key2']) == {'subspace_key1' : 'val1', 'subspace_key2' : 'val2'} True

  Causes key 'subspace_key1' and 'subspace_key2' to be set. Useful in conjunction with a higher-level layer which applies namespaces to data in memcache. In this case, the return result would be the list of notset original keys, prefix not applied.

• min_compress_len - The threshold length to kick in auto-compression of the value using the zlib.compress() routine. If the value being cached is a string, then the length of the string is measured, else if the value is an object, then the length of the pickle result is measured. If the resulting attempt at compression yeilds a larger string than the input, then it is discarded. For backwards compatability, this parameter defaults to 0, indicating don't ever try to compress.

Returns: list

List of keys which failed to be stored [ memcache out of memory, etc. ].

Add new key with value.

Like set, but only stores in memcache if the key doesn't already exist.

Returns: int

Nonzero on success.

Replace existing key with value.

Like set, but only stores in memcache if the key already exists. The opposite of add.

Returns: int

Nonzero on success.

Retrieves a key from the memcache.

Returns:

The value or None.

Retrieves multiple keys from the memcache doing just one query.

>>> success = mc.set("foo", "bar")
>>> success = mc.set("baz", 42)
>>> mc.get_multi(["foo", "baz", "foobar"]) == {"foo": "bar", "baz": 42}
1
>>> mc.set_multi({'k1' : 1, 'k2' : 2}, key_prefix='pfx_') == []
1

This looks up keys 'pfx_k1', 'pfx_k2', ... . Returned dict will just have unprefixed keys 'k1', 'k2'. >>> mc.get_multi(['k1', 'k2', 'nonexist'], key_prefix='pfx_') == {'k1' : 1, 'k2' : 2} 1

get_mult [ and set_multi ] can take str()-ables like ints / longs as keys too. Such as your db pri key fields. They're rotored through str() before being passed off to memcache, with or without the use of a key_prefix. In this mode, the key_prefix could be a table name, and the key itself a db primary key number.

>>> mc.set_multi({42: 'douglass adams', 46 : 'and 2 just ahead of me'}, key_prefix='numkeys_') == []
1
>>> mc.get_multi([46, 42], key_prefix='numkeys_') == {42: 'douglass adams', 46 : 'and 2 just ahead of me'}
1

This method is recommended over regular get as it lowers the number of total packets flying around your network, reducing total latency, since your app doesn't have to wait for each round-trip of get before sending the next one.

See also set_multi.

Parameters:

• keys - An array of keys.
• key_prefix - A string to prefix each key when we communicate with memcache. Facilitates pseudo-namespaces within memcache. Returned dictionary keys will not have this prefix.

Returns:

A dictionary of key/value pairs that were available. If key_prefix was provided, the keys in the retured dictionary will not have it present.

Sends a command to the server to atomically increment the value for key by delta, or by 1 if delta is unspecified. Returns None if key doesn't exist on server, otherwise it returns the new value after incrementing.

Note that the value for key must already exist in the memcache, and it must be the string representation of an integer.

>>> mc.set("counter", "20")  # returns 1, indicating success
1
>>> mc.incr("counter")
21
>>> mc.incr("counter")
22

Overflow on server is not checked. Be aware of values approaching 2**32. See decr.

Parameters:

• delta - Integer amount to increment by (should be zero or greater).

Returns: int

New value after incrementing.

Like incr, but decrements. Unlike incr, underflow is checked and new values are capped at 0. If server value is 1, a decrement of 2 returns 0, not -1.

Parameters:

• delta - Integer amount to decrement by (should be zero or greater).

Returns: int

New value after decrementing.

Deletes a key from the memcache.

Parameters:

• time - number of seconds any subsequent set / update commands should fail. Defaults to 0 for no delay.

Returns: int

Nonzero on success.

Delete multiple keys in the memcache doing just one query.

>>> notset_keys = mc.set_multi({'key1' : 'val1', 'key2' : 'val2'})
>>> mc.get_multi(['key1', 'key2']) == {'key1' : 'val1', 'key2' : 'val2'}
1
>>> mc.delete_multi(['key1', 'key2'])
1
>>> mc.get_multi(['key1', 'key2']) == {}
1

This method is recommended over iterated regular deletes as it reduces total latency, since your app doesn't have to wait for each round-trip of delete before sending the next one.

Parameters:

• keys - An iterable of keys to clear
• seconds - number of seconds any subsequent set / update commands should fail. Defaults to 0 for no delay.
• key_prefix - Optional string to prepend to each key when sending to memcache. See docs for get_multi and set_multi.

Returns: int

1 if no failure in communication with any memcacheds.

Get statistics from each of the servers.

Returns:

A list of tuples ( server_identifier, stats_dictionary ). The dictionary contains a number of name/value pairs specifying the name of the status field and the string value associated with it. The values are not converted from strings.