# Memcached Backend

class cachelib.memcached.MemcachedCache(servers=None, default_timeout=300, key_prefix=None)

  Bases: `BaseCache`

  A cache that uses memcached as backend.

  The first argument can either be an object that resembles the API of a `memcache.Client` or a tuple/list of server addresses. In the event that a tuple/list is passed, Werkzeug tries to import the best available memcache library.

  This cache looks into the following packages/modules to find bindings for memcached:

  > - `pylibmc`

  > - `google.appengine.api.memcached`

  > - `memcached`

  > - `libmc`

  Implementation notes: This cache backend works around some limitations in memcached to simplify the interface. For example unicode keys are encoded to utf-8 on the fly. Methods such as `get_dict()` return the keys in the same format as passed. Furthermore all get methods silently ignore key errors to not cause problems when untrusted user data is passed to the get methods which is often the case in web applications.

  Parameters:

    - servers (Any) – a list or tuple of server addresses or alternatively a `memcache.Client` or a compatible client.

    - default_timeout (int) – the default timeout that is used if no timeout is specified on `set()`. A timeout of 0 indicates that the cache never expires.

    - key_prefix (str | None) – a prefix that is added before all keys. This makes it possible to use the same memcached server for different applications. Keep in mind that `clear()` will also clear keys with a different prefix.

  add(key, value, timeout=None)

    Works like `set()` but does not overwrite the values of already existing keys.

    Parameters:

      - key (str) – the key to set

      - value (Any) – the value for the key

      - timeout (int | None) – the cache timeout for the key in seconds (if not specified, it uses the default timeout). A timeout of 0 indicates that the cache never expires.

    Returns:

      Same as `set()`, but also `False` for already existing keys.

    Return type:

      boolean

  clear()

    Clears the cache. Keep in mind that not all caches support completely clearing the cache.

    Returns:

      Whether the cache has been cleared.

    Return type:

      boolean

  dec(key, delta=1)

    Decrements the value of a key by delta. If the key does not yet exist it is initialized with -delta.

    For supporting caches this is an atomic operation.

    Parameters:

      - key (str) – the key to increment.

      - delta (int) – the delta to subtract.

    Returns:

      The new value or None for backend errors.

    Return type:

      int | None

  delete(key)

    Delete key from the cache.

    Parameters:

      key (str) – the key to delete.

    Returns:

      Whether the key existed and has been deleted.

    Return type:

      boolean

  delete_many(*keys)

    Deletes multiple keys at once.

    Parameters:

      keys (str) – The function accepts multiple keys as positional arguments.

    Returns:

      A list containing all successfully deleted keys

    Return type:

      boolean

  get(key)

    Look up key in the cache and return the value for it.

    Parameters:

      key (str) – the key to be looked up.

    Returns:

      The value if it exists and is readable, else `None`.

    Return type:

      Any

  get_dict(*keys)

    Like `get_many()` but return a dict:

        d = cache.get_dict("foo", "bar")
        foo = d["foo"]
        bar = d["bar"]

    Parameters:

      keys (str) – The function accepts multiple keys as positional arguments.

    Return type:

      Dict[str, Any]

  get_many(*keys)

    Returns a list of values for the given keys. For each key an item in the list is created:

        foo, bar = cache.get_many("foo", "bar")

    Has the same error handling as `get()`.

    Parameters:

      keys (str) – The function accepts multiple keys as positional arguments.

    Return type:

      List[Any]

  has(key)

    Checks if a key exists in the cache without returning it. This is a cheap operation that bypasses loading the actual data on the backend.

    Parameters:

      key (str) – the key to check

    Return type:

      bool

  import_preferred_memcache_lib(servers)

    Returns an initialized memcache client. Used by the constructor.

    Parameters:

      servers (Any)

    Return type:

      Any

  inc(key, delta=1)

    Increments the value of a key by delta. If the key does not yet exist it is initialized with delta.

    For supporting caches this is an atomic operation.

    Parameters:

      - key (str) – the key to increment.

      - delta (int) – the delta to add.

    Returns:

      The new value or `None` for backend errors.

    Return type:

      int | None

  set(key, value, timeout=None)

    Add a new key/value to the cache (overwrites value, if key already exists in the cache).

    Parameters:

      - key (str) – the key to set

      - value (Any) – the value for the key

      - timeout (int | None) – the cache timeout for the key in seconds (if not specified, it uses the default timeout). A timeout of 0 indicates that the cache never expires.

    Returns:

      `True` if key has been updated, `False` for backend errors. Pickling errors, however, will raise a subclass of `pickle.PickleError`.

    Return type:

      boolean

  set_many(mapping, timeout=None)

    Sets multiple keys and values from a mapping.

    Parameters:

      - mapping (Dict[str, Any]) – a mapping with the keys/values to set.

      - timeout (int | None) – the cache timeout for the key in seconds (if not specified, it uses the default timeout). A timeout of 0 indicates that the cache never expires.

    Returns:

      A list containing all keys successfully set

    Return type:

      boolean