App Engine Python SDK  v1.6.9 rev.445
The Python runtime is available as an experimental Preview feature.
Public Member Functions | List of all members
google.appengine.api.memcache.Client Class Reference
Inheritance diagram for google.appengine.api.memcache.Client:

Public Member Functions

def __init__
 
def cas_reset
 
def set_servers
 
def disconnect_all
 
def forget_dead_hosts
 
def debuglog
 
def get_stats
 
def get_stats_async
 
def flush_all
 
def flush_all_async
 
def get
 
def gets
 
def get_multi
 
def get_multi_async
 
def delete
 
def delete_multi
 
def delete_multi_async
 
def set
 
def add
 
def replace
 
def cas
 
def set_multi
 
def set_multi_async
 
def add_multi
 
def add_multi_async
 
def replace_multi
 
def replace_multi_async
 
def cas_multi
 
def cas_multi_async
 
def incr
 
def incr_async
 
def decr
 
def decr_async
 
def offset_multi
 
def offset_multi_async
 

Detailed Description

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.

Constructor & Destructor Documentation

def google.appengine.api.memcache.Client.__init__ (   self,
  servers = None,
  debug = 0,
  pickleProtocol = cPickle.HIGHEST_PROTOCOL,
  pickler = cPickle.Pickler,
  unpickler = cPickle.Unpickler,
  pload = None,
  pid = None,
  make_sync_call = None,
  _app_id = None 
)
Create a new Client object.

No parameters are required.

Arguments:
  servers: Ignored; only for compatibility.
  debug: Ignored; only for compatibility.
  pickleProtocol: Pickle protocol to use for pickling the object.
  pickler: pickle.Pickler sub-class to use for pickling.
  unpickler: pickle.Unpickler sub-class to use for unpickling.
  pload: Callable to use for retrieving objects by persistent id.
  pid: Callable to use for determine the persistent id for objects, if any.
  make_sync_call: Ignored; only for compatibility with an earlier version.

Member Function Documentation

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.add_multi_async (   self,
  mapping,
  time = 0,
  key_prefix = '',
  min_compress_len = 0,
  namespace = None,
  rpc = None 
)
Async version of add_multi() -- note different return value.

Returns:
  See _set_multi_async_with_policy().
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.cas_multi_async (   self,
  mapping,
  time = 0,
  key_prefix = '',
  min_compress_len = 0,
  namespace = None,
  rpc = None 
)
Async version of cas_multi() -- note different return value.

Returns:
  See _set_multi_async_with_policy().
def google.appengine.api.memcache.Client.cas_reset (   self)
Clear the remembered CAS ids.
def google.appengine.api.memcache.Client.debuglog (   self)
Logging function for debugging information.

This is purely a compatibility method.  In Google App Engine, it's a no-op.
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.decr_async (   self,
  key,
  delta = 1,
  namespace = None,
  initial_value = None,
  rpc = None 
)
Async version of decr().

Returns:
  A UserRPC instance whose get_result() method returns the same
  kind of value as decr() returns.
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.delete_multi (   self,
  keys,
  seconds = 0,
  key_prefix = '',
  namespace = None 
)
Delete multiple keys at once.

Args:
  keys: List of keys to delete.
  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.
  key_prefix: Prefix to put on all keys when sending specified
keys to memcache.  See docs for get_multi() and set_multi().
  namespace: a string specifying an optional namespace to use in
the request.

Returns:
  True if all operations completed successfully.  False if one
  or more failed to complete.
def google.appengine.api.memcache.Client.delete_multi_async (   self,
  keys,
  seconds = 0,
  key_prefix = '',
  namespace = None,
  rpc = None 
)
Async version of delete_multi() -- note different return value.

Returns:
  A UserRPC instance whose get_result() method returns None if
  there was a network error, or a list of status values otherwise,
  where each status corresponds to a key and is either
  DELETE_SUCCESSFUL, DELETE_ITEM_MISSING, or DELETE_NETWORK_FAILURE
  (see delete() docstring for details).
def google.appengine.api.memcache.Client.disconnect_all (   self)
Closes all connections to memcache servers.

This is purely a compatibility method.  In Google App Engine, it's a no-op.
def google.appengine.api.memcache.Client.flush_all (   self)
Deletes everything in memcache.

Returns:
  True on success, False on RPC or server error.
def google.appengine.api.memcache.Client.flush_all_async (   self,
  rpc = None 
)
Async version of flush_all().

Returns:
  A UserRPC instance whose get_result() method returns True on
  success, False on RPC or server error.
def google.appengine.api.memcache.Client.forget_dead_hosts (   self)
Resets all servers to the alive status.

This is purely a compatibility method.  In Google App Engine, it's a no-op.
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.get_multi_async (   self,
  keys,
  key_prefix = '',
  namespace = None,
  for_cas = False,
  rpc = None 
)
Async version of get_multi().

Returns:
  A UserRPC instance whose get_result() method returns {} if
  there was a network error, otherwise a dict just like
  get_multi() returns.
def google.appengine.api.memcache.Client.get_stats (   self)
Gets memcache statistics for this application.

All of these statistics may reset due to various transient conditions. They
provide the best information available at the time of being called.

Returns:
  Dictionary mapping statistic names to associated values. Statistics and
  their associated meanings:

hits: Number of cache get requests resulting in a cache hit.
misses: Number of cache get requests resulting in a cache miss.
byte_hits: Sum of bytes transferred on get requests. Rolls over to
  zero on overflow.
items: Number of key/value pairs in the cache.
bytes: Total size of all items in the cache.
oldest_item_age: How long in seconds since the oldest item in the
  cache was accessed. Effectively, this indicates how long a new
  item will survive in the cache without being accessed. This is
  _not_ the amount of time that has elapsed since the item was
  created.

  On error, returns None.
def google.appengine.api.memcache.Client.get_stats_async (   self,
  rpc = None 
)
Async version of get_stats().

Returns:
  A UserRPC instance whose get_result() method returns None if
  there was a network error, otherwise a dict just like
  get_stats() returns.
def google.appengine.api.memcache.Client.gets (   self,
  key,
  namespace = None 
)
An alias for get(..., for_cas=True).
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.incr_async (   self,
  key,
  delta = 1,
  namespace = None,
  initial_value = None,
  rpc = None 
)
Async version of incr().

Returns:
  A UserRPC instance whose get_result() method returns the same
  kind of value as incr() returns.
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.offset_multi_async (   self,
  mapping,
  key_prefix = '',
  namespace = None,
  initial_value = None,
  rpc = None 
)
Async version of offset_multi().

Returns:
  A UserRPC instance whose get_result() method returns a dict just
  like offset_multi() returns.
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.replace_multi_async (   self,
  mapping,
  time = 0,
  key_prefix = '',
  min_compress_len = 0,
  namespace = None,
  rpc = None 
)
Async version of replace_multi() -- note different return value.

Returns:
  See _set_multi_async_with_policy().
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.
def google.appengine.api.memcache.Client.set_multi_async (   self,
  mapping,
  time = 0,
  key_prefix = '',
  min_compress_len = 0,
  namespace = None,
  rpc = None 
)
Async version of set_multi() -- note different return value.

Returns:
  See _set_multi_async_with_policy().
def google.appengine.api.memcache.Client.set_servers (   self,
  servers 
)
Sets the pool of memcache servers used by the client.

This is purely a compatibility method.  In Google App Engine, it's a no-op.

The documentation for this class was generated from the following file: