Memcache client object, through which one invokes all memcache operations.
Several methods are no-ops to retain source-level compatibility
with the existing popular Python memcache library.
Any method that takes a 'key' argument will accept that key as a string
(unicode or not) or a tuple of (hash_value, string) where the hash_value,
normally used for sharding onto a memcache instance, is instead ignored, as
Google App Engine deals with the sharding transparently. Keys in memcache are
just bytes, without a specified encoding. All such methods may raise TypeError
if provided a bogus key value and a ValueError if the key is too large.
Any method that takes a 'value' argument will accept as that value any
string (unicode or not), int, long, or pickle-able Python object, including
all native types. You'll get back from the cache the same type that you
originally put in.
The Client class is not thread-safe with respect to the gets(), cas() and
cas_multi() methods (and other compare-and-set-related methods). Therefore,
Client objects should not be used by more than one thread for CAS purposes.
Note that the global Client for the module-level functions is okay because it
does not expose any of the CAS methods.
def google.appengine.api.memcache.Client.add |
( |
|
self, |
|
|
|
key, |
|
|
|
value, |
|
|
|
time = 0 , |
|
|
|
min_compress_len = 0 , |
|
|
|
namespace = None |
|
) |
| |
Sets a key's value, iff item is not already in memcache.
Args:
key: Key to set. See docs on Client for details.
value: Value to set. Any type. If complex, will be pickled.
time: Optional expiration time, either relative number of seconds
from current time (up to 1 month), or an absolute Unix epoch time.
By default, items never expire, though items may be evicted due to
memory pressure. Float values will be rounded up to the nearest
whole second.
min_compress_len: Ignored option for compatibility.
namespace: a string specifying an optional namespace to use in
the request.
Returns:
True if added. False on error.
def google.appengine.api.memcache.Client.add_multi |
( |
|
self, |
|
|
|
mapping, |
|
|
|
time = 0 , |
|
|
|
key_prefix = '' , |
|
|
|
min_compress_len = 0 , |
|
|
|
namespace = None |
|
) |
| |
Set multiple keys' values iff items are not already in memcache.
Args:
mapping: Dictionary of keys to values.
time: Optional expiration time, either relative number of seconds
from current time (up to 1 month), or an absolute Unix epoch time.
By default, items never expire, though items may be evicted due to
memory pressure. Float values will be rounded up to the nearest
whole second.
key_prefix: Prefix for to prepend to all keys.
min_compress_len: Unimplemented compatibility option.
namespace: a string specifying an optional namespace to use in
the request.
Returns:
A list of keys whose values were NOT set because they did not already
exist in memcache. On total success, this list should be empty.
def google.appengine.api.memcache.Client.cas |
( |
|
self, |
|
|
|
key, |
|
|
|
value, |
|
|
|
time = 0 , |
|
|
|
min_compress_len = 0 , |
|
|
|
namespace = None |
|
) |
| |
Compare-And-Set update.
This requires that the key has previously been successfully
fetched with gets() or get(..., for_cas=True), and that no changes
have been made to the key since that fetch. Typical usage is:
key = ...
client = memcache.Client()
value = client.gets(key) # OR client.get(key, for_cas=True)
<updated value>
ok = client.cas(key, value)
If two processes run similar code, the first one calling cas()
will succeed (ok == True), while the second one will fail (ok ==
False). This can be used to detect race conditions.
NOTE: some state (the CAS id) is stored on the Client object for
each key ever used with gets(). To prevent ever-increasing memory
usage, you must use a Client object when using cas(), and the
lifetime of your Client object should be limited to that of one
incoming HTTP request. You cannot use the global-function-based
API.
Args:
key: Key to set. See docs on Client for details.
value: The new value.
time: Optional expiration time, either relative number of seconds
from current time (up to 1 month), or an absolute Unix epoch time.
By default, items never expire, though items may be evicted due to
memory pressure. Float values will be rounded up to the nearest
whole second.
min_compress_len: Ignored option for compatibility.
namespace: a string specifying an optional namespace to use in
the request.
Returns:
True if updated. False on RPC error or if the CAS id didn't match.
def google.appengine.api.memcache.Client.cas_multi |
( |
|
self, |
|
|
|
mapping, |
|
|
|
time = 0 , |
|
|
|
key_prefix = '' , |
|
|
|
min_compress_len = 0 , |
|
|
|
namespace = None |
|
) |
| |
Compare-And-Set update for multiple keys.
See cas() docstring for an explanation.
Args:
mapping: Dictionary of keys to values.
time: Optional expiration time, either relative number of seconds
from current time (up to 1 month), or an absolute Unix epoch time.
By default, items never expire, though items may be evicted due to
memory pressure. Float values will be rounded up to the nearest
whole second.
key_prefix: Prefix for to prepend to all keys.
min_compress_len: Unimplemented compatibility option.
namespace: a string specifying an optional namespace to use in
the request.
Returns:
A list of keys whose values were NOT set because the compare
failed. On total success, this list should be empty.
def google.appengine.api.memcache.Client.decr |
( |
|
self, |
|
|
|
key, |
|
|
|
delta = 1 , |
|
|
|
namespace = None , |
|
|
|
initial_value = None |
|
) |
| |
Atomically decrements a key's value.
Internally, the value is a unsigned 64-bit integer. Memcache
caps decrementing below zero to zero.
The key must already exist in the cache to be decremented. See
docs on incr() for details.
Args:
key: Key to decrement. If an iterable collection, each one of the keys
will be offset. See Client's docstring for details.
delta: Non-negative integer value (int or long) to decrement key by,
defaulting to 1.
namespace: a string specifying an optional namespace to use in
the request.
initial_value: initial value to put in the cache, if it doesn't
already exist. The default value, None, will not create a cache
entry if it doesn't already exist.
Returns:
If key was a single value, the new long integer value, or None if key
was not in the cache, could not be decremented for any other reason, or
a network/RPC/server error occurred.
If key was an iterable collection, a dictionary will be returned
mapping supplied keys to values, with the values having the same meaning
as the singular return value of this method.
Raises:
ValueError: If number is negative.
TypeError: If delta isn't an int or long.
def google.appengine.api.memcache.Client.delete |
( |
|
self, |
|
|
|
key, |
|
|
|
seconds = 0 , |
|
|
|
namespace = None |
|
) |
| |
Deletes a key from memcache.
Args:
key: Key to delete. See docs on Client for detils.
seconds: Optional number of seconds to make deleted items 'locked'
for 'add' operations. Value can be a delta from current time (up to
1 month), or an absolute Unix epoch time. Defaults to 0, which means
items can be immediately added. With or without this option,
a 'set' operation will always work. Float values will be rounded up to
the nearest whole second.
namespace: a string specifying an optional namespace to use in
the request.
Returns:
DELETE_NETWORK_FAILURE (0) on network failure,
DELETE_ITEM_MISSING (1) if the server tried to delete the item but
didn't have it, or
DELETE_SUCCESSFUL (2) if the item was actually deleted.
This can be used as a boolean value, where a network failure is the
only bad condition.
def google.appengine.api.memcache.Client.get |
( |
|
self, |
|
|
|
key, |
|
|
|
namespace = None , |
|
|
|
for_cas = False |
|
) |
| |
Looks up a single key in memcache.
If you have multiple items to load, though, it's much more efficient
to use get_multi() instead, which loads them in one bulk operation,
reducing the networking latency that'd otherwise be required to do
many serialized get() operations.
Args:
key: The key in memcache to look up. See docs on Client
for details of format.
namespace: a string specifying an optional namespace to use in
the request.
for_cas: If True, request and store CAS ids on the client (see
cas() operation below).
Returns:
The value of the key, if found in memcache, else None.
def google.appengine.api.memcache.Client.get_multi |
( |
|
self, |
|
|
|
keys, |
|
|
|
key_prefix = '' , |
|
|
|
namespace = None , |
|
|
|
for_cas = False |
|
) |
| |
Looks up multiple keys from memcache in one operation.
This is the recommended way to do bulk loads.
Args:
keys: List of keys to look up. Keys may be strings or
tuples of (hash_value, string). Google App Engine
does the sharding and hashing automatically, though, so the hash
value is ignored. To memcache, keys are just series of bytes,
and not in any particular encoding.
key_prefix: Prefix to prepend to all keys when talking to the server;
not included in the returned dictionary.
namespace: a string specifying an optional namespace to use in
the request.
for_cas: If True, request and store CAS ids on the client.
Returns:
A dictionary of the keys and values that were present in memcache.
Even if the key_prefix was specified, that key_prefix won't be on
the keys in the returned dictionary.
def google.appengine.api.memcache.Client.incr |
( |
|
self, |
|
|
|
key, |
|
|
|
delta = 1 , |
|
|
|
namespace = None , |
|
|
|
initial_value = None |
|
) |
| |
Atomically increments a key's value.
Internally, the value is a unsigned 64-bit integer. Memcache
doesn't check 64-bit overflows. The value, if too large, will
wrap around.
Unless an initial_value is specified, the key must already exist
in the cache to be incremented. To initialize a counter, either
specify initial_value or set() it to the initial value, as an
ASCII decimal integer. Future get()s of the key, post-increment,
will still be an ASCII decimal value.
Args:
key: Key to increment. If an iterable collection, each one of the keys
will be offset. See Client's docstring for details.
delta: Non-negative integer value (int or long) to increment key by,
defaulting to 1.
namespace: a string specifying an optional namespace to use in
the request.
initial_value: initial value to put in the cache, if it doesn't
already exist. The default value, None, will not create a cache
entry if it doesn't already exist.
Returns:
If key was a single value, the new long integer value, or None if key
was not in the cache, could not be incremented for any other reason, or
a network/RPC/server error occurred.
If key was an iterable collection, a dictionary will be returned
mapping supplied keys to values, with the values having the same meaning
as the singular return value of this method.
Raises:
ValueError: If number is negative.
TypeError: If delta isn't an int or long.
def google.appengine.api.memcache.Client.offset_multi |
( |
|
self, |
|
|
|
mapping, |
|
|
|
key_prefix = '' , |
|
|
|
namespace = None , |
|
|
|
initial_value = None |
|
) |
| |
Offsets multiple keys by a delta, incrementing and decrementing in batch.
Args:
mapping: Dictionary mapping keys to deltas (positive or negative integers)
to apply to each corresponding key.
key_prefix: Prefix for to prepend to all keys.
initial_value: Initial value to put in the cache, if it doesn't
already exist. The default value, None, will not create a cache
entry if it doesn't already exist.
namespace: A string specifying an optional namespace to use in
the request.
Returns:
Dictionary mapping input keys to new integer values. The new value will
be None if an error occurs, the key does not already exist, or the value
was not an integer type. The values will wrap-around at unsigned 64-bit
integer-maximum and underflow will be floored at zero.
def google.appengine.api.memcache.Client.replace |
( |
|
self, |
|
|
|
key, |
|
|
|
value, |
|
|
|
time = 0 , |
|
|
|
min_compress_len = 0 , |
|
|
|
namespace = None |
|
) |
| |
Replaces a key's value, failing if item isn't already in memcache.
Args:
key: Key to set. See docs on Client for details.
value: Value to set. Any type. If complex, will be pickled.
time: Optional expiration time, either relative number of seconds
from current time (up to 1 month), or an absolute Unix epoch time.
By default, items never expire, though items may be evicted due to
memory pressure. Float values will be rounded up to the nearest
whole second.
min_compress_len: Ignored option for compatibility.
namespace: a string specifying an optional namespace to use in
the request.
Returns:
True if replaced. False on RPC error or cache miss.
def google.appengine.api.memcache.Client.replace_multi |
( |
|
self, |
|
|
|
mapping, |
|
|
|
time = 0 , |
|
|
|
key_prefix = '' , |
|
|
|
min_compress_len = 0 , |
|
|
|
namespace = None |
|
) |
| |
Replace multiple keys' values, failing if the items aren't in memcache.
Args:
mapping: Dictionary of keys to values.
time: Optional expiration time, either relative number of seconds
from current time (up to 1 month), or an absolute Unix epoch time.
By default, items never expire, though items may be evicted due to
memory pressure. Float values will be rounded up to the nearest
whole second.
key_prefix: Prefix for to prepend to all keys.
min_compress_len: Unimplemented compatibility option.
namespace: a string specifying an optional namespace to use in
the request.
Returns:
A list of keys whose values were NOT set because they already existed
in memcache. On total success, this list should be empty.
def google.appengine.api.memcache.Client.set |
( |
|
self, |
|
|
|
key, |
|
|
|
value, |
|
|
|
time = 0 , |
|
|
|
min_compress_len = 0 , |
|
|
|
namespace = None |
|
) |
| |
Sets a key's value, regardless of previous contents in cache.
Unlike add() and replace(), this method always sets (or
overwrites) the value in memcache, regardless of previous
contents.
Args:
key: Key to set. See docs on Client for details.
value: Value to set. Any type. If complex, will be pickled.
time: Optional expiration time, either relative number of seconds
from current time (up to 1 month), or an absolute Unix epoch time.
By default, items never expire, though items may be evicted due to
memory pressure. Float values will be rounded up to the nearest
whole second.
min_compress_len: Ignored option for compatibility.
namespace: a string specifying an optional namespace to use in
the request.
Returns:
True if set. False on error.
def google.appengine.api.memcache.Client.set_multi |
( |
|
self, |
|
|
|
mapping, |
|
|
|
time = 0 , |
|
|
|
key_prefix = '' , |
|
|
|
min_compress_len = 0 , |
|
|
|
namespace = None |
|
) |
| |
Set multiple keys' values at once, regardless of previous contents.
Args:
mapping: Dictionary of keys to values.
time: Optional expiration time, either relative number of seconds
from current time (up to 1 month), or an absolute Unix epoch time.
By default, items never expire, though items may be evicted due to
memory pressure. Float values will be rounded up to the nearest
whole second.
key_prefix: Prefix for to prepend to all keys.
min_compress_len: Unimplemented compatibility option.
namespace: a string specifying an optional namespace to use in
the request.
Returns:
A list of keys whose values were NOT set. On total success,
this list should be empty.