Functions

The google.appengine.api.memcache module provides the following functions:

Function List

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. The value type can be any value supported by the Python pickle module for serializing values. The combined size of the serialized key and value must be at most 1 megabyte.
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. See set() for a description of allowed keys and values. The combined size of all keys and values must be at most 32 megabytes.
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 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 , for_cas = False )

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.
for_cas: If called in the function interface, this value must be set to false. If called as a Client instance method, supply the value True if you wish to use the compare and set (cas) feature or supply the value False if you don't want to use that feature.

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

get_multi ( 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.

The combined size of all values returned must not exceed 32 megabytes.

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.
for_cas: If called in the function interface, this value must be set to false. If called as a Client instance method, supply the value True if you wish to use the compare and set (cas) feature or supply the value False if you don't want to use that feature.

The returned value is a dictionary of the keys and values that were present in memcache. Even if the key_prefix is specified, that key_prefix is not included 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. The value type can be any value supported by the Python pickle module for serializing values. The combined size of the serialized key and value must be at most 1 megabyte.
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. See add() for a description of allowed keys and values. The combined size of all keys and values must be at most 32 megabytes.
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. Even if the key_prefix is specified, that key_prefix won't be on the keys in the returned list. 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. The value type can be any value supported by the Python pickle module for serializing values. The combined size of the serialized key and value must be at most 1 megabyte.
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. See replace() for a description of allowed keys and values. The combined size of all keys and values must be at most 32 megabytes.
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. Even if the key_prefix is specified, that key_prefix won't be on the keys in the returned list. 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 , 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.

If the key does not yet exist in the cache and you specify an initial_value , the key's value will be set to this initial value and then incremented. If the key does not exist and no initial_value is specified, the key's value will not be set.

Arguments

key: Key to increment, or a list of keys to increment. Each 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.
initial_value: An initial value to be used if the key does not yet exist in the cache. Ignored if the key already exists. If None and the key does not exist, the key remains unset.

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 , initial_value = 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.

If the key does not yet exist in the cache and you specify an initial_value , the key's value will be set to this initial value and then decremented. If the key does not exist and no initial_value is specified, the key's value will not be set.

Arguments

key: Key to decrement, or a list of keys to decrement. Each 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.
initial_value: An initial value to be used if the key does not yet exist in the cache. Ignored if the key already exists. If None and the key does not exist, the key remains unset.

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.

offset_multi ( mapping , key_prefix = '' , namespace = None , initial_value = None )

Increments or decrements multiple keys with integer values in a single service call. Each key can have a separate offset. The offset can be positive or negative.

Applying an offset to a single key is atomic. Applying an offset to multiple keys may succeed for some keys and fail for others.

Arguments

mapping: Dictionary of keys to offsets. An offset can be a positive or negative integer to be added to the key's value.
key_prefix: Prefix to prepend to all keys.
namespace: An optional namespace for all keys in the mapping.
initial_value: An initial value to be used if a key in the mapping does not yet exist in the cache. If None and a key in the mapping does not exist in the cache, the key remains unset in the cache.

The return value is a mapping of the provided keys to their new values. If there was an error applying an offset to a key, if a key doesn't exist in the cache and no initial_value is provided, or if a key is set with a non-integer value, its return value is None .

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.

create_rpc ( deadline = None , callback = None )

Creates an RPC object for use with asynchronous calls. An application calls asynchronously to perform the operation in the background while the application does other things. To set up the asynchronous call, the application first calls create_rpc() to create an RPC object used for the call. Next, the asynchronous call is made, passing the RPC object as an argument. The call returns immediately, freeing your app to do other things. When your app is ready for the results, it calls the get_result() method directly on the RPC object.

Arguments

deadline: Optional deadline in seconds for the operation. Normally, you would not need to specify a deadline because the return is from async calls are made in milliseconds, faster than the deadline.
callback: Callback is an optional function in which you can specify another function to call after the asynchronous call is completed.

Returns an RPC object for use in the asynchonous calls.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

Last updated May 6, 2014.

Python

Functions

Function List

Authentication required

Signing you in...