# `cement.ext.ext_memcached`

The Memcached Extension provides application caching and key/value store support via Memcache.

## Requirements

> - pylibmc (`pip install pylibmc`)
>     - Note: There are known issues installing `pylibmc` on OSX/Homebrew via PIP. This post might be helpful.

## Configuration

This extension honors the following config settings under a `[cache.memcached]` section in any configuration file:

> - expire_time - The default time in second to expire items in the cache. Default: 0 (does not expire).
> - hosts - List of Memcached servers.

Configurations can be passed as defaults to a CementApp:

    from cement.core.foundation import CementApp
    from cement.utils.misc import init_defaults

    defaults = init_defaults('myapp', 'cache.memcached')
    defaults['cache.memcached']['expire_time'] = 0
    defaults['cache.memcached']['hosts'] = ['127.0.0.1']

    class MyApp(CementApp):
        class Meta:
            label = 'myapp'
            config_defaults = defaults
            extensions = ['memcached']
            cache_handler = 'memcached'

Additionally, an application configuration file might have a section like the following:

    [myapp]

    # set the cache handler to use
    cache_handler = memcached

    [cache.memcached]

    # time in seconds that an item in the cache will expire
    expire_time = 3600

    # comma seperated list of memcached servers
    hosts = 127.0.0.1, cache.example.com

## Usage

    from cement.core import foundation
    from cement.utils.misc import init_defaults

    defaults = init_defaults('myapp', 'memcached')
    defaults['cache.memcached']['expire_time'] = 300 # seconds
    defaults['cache.memcached']['hosts'] = ['127.0.0.1']

    class MyApp(foundation.CementApp):
        class Meta:
            label = 'myapp'
            config_defaults = defaults
            extensions = ['memcached']
            cache_handler = 'memcached'

    with MyApp() as app:
        # Run the app
        app.run()

        # Set a cached value
        app.cache.set('my_key', 'my value')

        # Get a cached value
        app.cache.get('my_key')

        # Delete a cached value
        app.cache.delete('my_key')

        # Delete the entire cache
        app.cache.purge()

class `cement.ext.ext_memcached.``MemcachedCacheHandler`(*args, **kw)

  Bases: `cement.core.cache.CementCacheHandler`

  This class implements the ICache interface. It provides a caching interface using the pylibmc library.

  Note This extension has an external dependency on `pylibmc`. You must include `pylibmc` in your applications dependencies as Cement explicitly does not include external dependencies for optional extensions.

  class `Meta`

    Bases: `object`

    Handler meta-data.

    `interface`

      alias of `cement.core.cache.ICache`

  `_config`(key)

    This is a simple wrapper, and is equivalent to: `self.app.config.get('cache.memcached', <key>)`.

    Parameters: | key – The key to get a config value from the ‘cache.memcached’ config section.
    Returns: | The value of the given key.

  `_fix_hosts`()

    Useful to fix up the hosts configuration (i.e. convert a comma-separated string into a list). This function does not return anything, however it is expected to set the hosts value of the `[cache.memcached]` section (which is what this extension reads for it’s host configution).

    Returns: | `None`

  `_setup`(*args, **kw)

    The _setup function is called during application initialization and must `setup` the handler object making it ready for the framework or the application to make further calls to it.

    Parameters: | app_obj – The application object.
    Returns: | None

  `delete`(key, **kw)

    Delete an item from the cache for the given `key`. Any additional keyword arguments will be passed directly to the pylibmc delete function.

    Parameters: | key – The key to delete from the cache.
    Returns: | `None`

  `get`(key, fallback=None, **kw)

    Get a value from the cache. Any additional keyword arguments will be passed directly to pylibmc get function.

    Parameters:

    - key – The key of the item in the cache to get.
    - fallback – The value to return if the item is not found in the cache.

    Returns: | The value of the item in the cache, or the fallback value.

  `purge`(**kw)

    Purge the entire cache, all keys and values will be lost. Any additional keyword arguments will be passed directly to the pylibmc `flush_all()` function.

    Returns: | `None`

  `set`(key, value, time=None, **kw)

    Set a value in the cache for the given `key`. Any additional keyword arguments will be passed directly to the pylibmc set function.

    Parameters:

    - key – The key of the item in the cache to set.
    - value – The value of the item to set.
    - time – The expiration time (in seconds) to keep the item cached. Defaults to expire_time as defined in the applications configuration.

    Returns: | `None`