English
Skip to page content Skip to main navigation

e.g. "templates" or "datastore"

# The Client Class

The Memcache API provides a class-based interface for compatibility with other Memcache APIs. See also the function interface, which provides identical functionality.

The `Client` class is provided by the `google.appengine.api.memcache` module.

- Introduction
- Client()
- Instance methods:
  - set()
  - set_multi()
  - get()
  - get_multi()
  - delete()
  - delete_multi()
  - add()
  - add_multi()
  - replace()
  - replace_multi()
  - incr()
  - decr()
  - flush_all()
  - get_stats()
- Memcached Compatibility

## Introduction

As a developer, you invoke all memcache operations through the Memcache client object

Several methods are no-ops and some method values are ignored to retain source-level compatibility with the existing popular Python memcache library. For example, Google App Engine deals with the sharding transparently but still allows any method that takes a 'key' argument will accept that key as a string or a tuple of (hash_value, string). Generally that hash_value, is used for sharding onto a memcache instance but with App Engine it is ignored. See Memcached Compatibility for more information.

## Constructor

class Client()

  A client for communicating with the Memcache service.

## Instance Methods

A Client instance has the following methods:

set(key, value, time=0, min_compress_len=0, namespace=None)

  Sets a key's value, regardless of previous contents in cache.

  Arguments:

  key
    Key to set. The Key can be a string 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.
  value
    Value to set.
  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
    An optional namespace for the key.

  The return value is True if set, False on error.

set_multi(mapping, time=0, key_prefix='', min_compress_len=0, namespace=None)

  Set multiple keys' values at once. Reduces the network latency of doing many requests in serial.

  Arguments:

  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
    Ignored option for compatibility.
  namespace
    An optional namespace for the keys.

  The return value is a list of keys whose values were NOT set. On total success, this list should be empty.

get(key, namespace=None)

  Looks up a single key in memcache.

  Arguments:

  key
    The key in memcache to look up. The Key can be a string 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.
  namespace
    An optional namespace for the key.

  The return value is the value of the key, if found in memcache, else None.

get_multi(keys, key_prefix='', namespace=None)

  Looks up multiple keys from memcache in one operation.

  Arguments:

  keys
    List of keys to look up. A Key can be a string 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.
  key_prefix
    Prefix to prepend to all keys when talking to the server; not included in the returned dictionary.
  namespace
    An optional namespace for the keys.

  The returned value is 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.

delete(key, seconds=0, namespace=None)

  Deletes a key from memcache.

  Arguments:

  key
    Key to delete. A Key can be a string 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.
  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
    An optional namespace for the key.

  The return value is 0 (DELETE_NETWORK_FAILURE) on network failure, 1 (DELETE_ITEM_MISSING) if the server tried to delete the item but didn't have it, and 2 (DELETE_SUCCESSFUL) if the item was actually deleted. This can be used as a boolean value, where a network failure is the only bad condition.

delete_multi(keys, seconds=0, key_prefix='', namespace=None)

  Delete multiple keys at once.

  Arguments:

  keys
    List of keys to delete. A Key can be a string 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.
  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
    An optional namespace for the keys.

  The return value is True if all operations completed successfully. False if one or more failed to complete.

add(key, value, time=0, min_compress_len=0, namespace=None)

  Sets a key's value, if and only if the item is not already in memcache.

  Arguments:

  key
    Key to set. The Key can be a string 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.
  value
    Value to set.
  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
    An optional namespace for the key.

  The return value is True if added, False on error.

add_multi(mapping, time=0, key_prefix='', min_compress_len=0, namespace=None)

  Adds multiple values at once, with no effect for keys already in memcache.

  Arguments:

  mapping
    A mapping 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 to put on all keys when sending specified keys to memcache. See get_multi().
  min_compress_len
    Ignored option for compatibility.
  namespace
    An optional namespace for the keys.

  The return value is a list of keys whose values were not set because they were already set in memcache, or an empty list.

replace(key, value, time=0, min_compress_len=0, namespace=None)

  Replaces a key's value, failing if item isn't already in memcache.

  Arguments:

  key
    Key to set. The Key can be a string 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.
  value
    Value to set.
  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
    An optional namespace for the key.

  the return value is True if replaced. False on error or cache miss.

replace_multi(mapping, time=0, key_prefix='', min_compress_len=0, namespace=None)

  Replaces multiple values at once, with no effect for keys not in memcache.

  Arguments:

  mapping
    A mapping 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 to put on all keys when sending specified keys to memcache. See get_multi().
  min_compress_len
    Ignored option for compatibility.
  namespace
    An optional namespace for the keys.

  The return value is a list of keys whose values were not set because they were not set in memcache, or an empty list.

incr(key, delta=1, namespace=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.

  The key must already exist in the cache to be incremented. To initialize a counter, 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.

  Arguments:

  key
    Key to increment. The Key can be a string 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.
  delta
    Non-negative integer value (int or long) to increment key by, defaulting to 1.
  namespace
    An optional namespace for the key.

  The return value is a new long integer value, or None if key was not in the cache or could not be incremented for any other reason.

decr(key, delta=1, namespace=None)

  Atomically decrements 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.

  The key must already exist in the cache to be decremented. To initialize a counter, 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.

  Arguments:

  key
    Key to decrement. The Key can be a string 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.
  delta
    Non-negative integer value (int or long) to decrement key by, defaulting to 1.
  namespace
    An optional namespace for the key.

  The return value is a new long integer value, or None if key was not in the cache or could not be decremented for any other reason.

flush_all()

  Deletes everything in memcache.

  The return value is True on success, False on RPC or server error.
get_stats()

  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.

  The return value is a 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.

## Memcached Compatibility

The Client class includes methods and arguments for compatibility with the Memcached API. Because some of these methods and arguments do not apply to the App Engine Memcache service, they have no effect.

Methods provided for compatibility purposes that have no effect in the App Engine Memcache API include the following:

- `disconnect_all()`
- `set_servers(...)`