Configuration

You need to configure the memcache service to be loaded (wtf.app.services.memcache.MemcacheService) in the services section). This requires the following additional configuration:

[memcache]
servers = host[:port] ...

# pool failover/maintenance options
# ---------------------------------
#grace_time = [int] Grace time on dead pools until they're backuped
#             (Default: 30)
#retry_time = [int] Retry interval after they're backuped (Default: 60)

# storage options
#compress_threshold = [int] Min size for value compression (Default: 128)
#padded = [bool] Use padding for small values (< 16 bytes)? (Default: yes)
#prefix = [str] Prefix keys with some arbitrary string (intended for
#         developers using the same memcache) (Default: ``''``)
#split = [bool] Allow splitting of values if they are bigger than the
#        largest slab? See largest_slab option below. (Default: yes)
#largest_slab = [int] Size of the largest slab in bytes. The value is
#               directly connected to the memcache implementation.
#               (Default: 1MB)

# global defaults
#max_age = [int] expire time (max age) per item
#          (Default: no default max_age)

# default values *per server*
#maxconn = [int] hard connection maximum (Default: 0 == unlimited)
#maxcached = [int] max cached connections (Default: 0)
#weight = [int] relative weight, compared to the other servers. The higher
#         the more requests it gets. (Default: 1)
#timeout = [float] communication timeout in seconds. (Default: 2.6)

# You can refine various settings per server with optional sections:
#[memcache host[:port]]
# set specific settings per server here
# (maxconn, maxcached, weight, timeout)

Usage

Now you can import __svc__.wtf.memcache and take the connection decorator from there. It will inject you an mc keyword into the argument list:

from __svc__.wtf import memcache

@memcache.connection
def foo(..., mc=None):
    mc.set(...)

The decorator takes optional arguments, max_age, nocache, prepare and exceptions. max_age defines the default max age for this connector (overriding the configured one).

nocache determines whether the nocache call argument should be evaluated. The value can be False (0), True (1), 2 or -1. If it evaluates to False, no special handling will be applied. Otherwise the function (keyword) argument nocache will be checked as boolean. If the caller supplies a true value, the memcache connector will behave like the memcache was not available. If the decorator nocache argument is 2 (> 1), the nocache function call argument will be passed through, otherwise it's been swallowed by the decorator. If it's -1, the nocache parameter is swallowed but not evaluated. Default is False. Now this all sounds confusing, I guess. Here's an example:

@memcache.connection(nocache=True)
def foo(..., mc=None):
  ...

foo(nocache=True)

The call to foo causes every memcache operation inside foo like the memcache was not running, without any change on foo. For a more complex handling, you can define:

@memcache.connection(nocache=2)
def foo(..., nocache=None, mc=None):
  ...

foo(nocache=True)

This call to foo causes the same "oblivion" of the memcache connector, but passes the nocache value to the foo function for further evaluation.

One further note: If the connector is passed from outside, like:

@memcache.connection(nocache=True)
def foo(..., mc=None):
  ...

@memcache.connection(nocache=False)
def bar(..., mc=None):
  foo(..., mc=mc)

The "inside" settings (here: foo's decorator's parameters) are ignored.

prepare defines a key preparation callable (overriding the default one, which MD5s the keys). This callables takes a key and returns a key (at least the returned value must be a str):

# identify preparation. Note that a configured prefix is still applied to
# the result.
prepare = lambda x: x

@memcache.connection(prepare=prepare)
def foo(..., mc=None):
    mc.set(...)

exceptions determines whether the memcache user wants to see memcache exceptions or not. If True the exceptions are passed through. If False, they're swallowed and treated as failed memcache response.