# `pylibmc` - Python client for memcached

`pylibmc` is a client in Python for memcached. It is a wrapper around TangentOrg’s libmemcached library.

The interface is intentionally made as close to python-memcached as possible, so that applications can drop-in replace it.

`pylibmc` leverages among other things configurable behaviors, data pickling, data compression, battle-tested GIL retention, consistent distribution, and the binary memcached protocol.

## Example usage

Create a memcached connection and configure it:

    >>> import pylibmc
    >>> mc = pylibmc.Client(["127.0.0.1"], binary=True,
    ...                     behaviors={"tcp_nodelay": True,
    ...                                "ketama": True})

Hint

In earlier versions `behaviors` was no keyword argument, only an attribute. To safe-guard version compatibility use `mc.behaviors = {...}`

Basic memcached operations can be accomplished with the mapping interface:

    >>> mc["some_key"] = "Some value"
    >>> mc["some_key"]
    'Some value'
    >>> del mc["some_key"]
    >>> "some_key" in mc
    False

“Classic” style memcached operations allow for more control and clarity:

    >>> mc.set("some_key", "Some value")
    True
    >>> value = mc.get("some_key")
    >>> value
    'Some value'
    >>> mc.set("another_key", 3)
    True
    >>> mc.delete("another_key")
    True

Automatic pickling of complex Python types:

    >>> mc.set("complex_plane=awesome", 4+3j)
    True
    >>> mc.get("complex_plane=awesome")
    (4+3j)
    >>> import fractions
    >>> mc.set("structured", {"a": ("b", "c"),
    ...                       "a2": fractions.Fraction(1, 3)})
    True
    >>> mc.get("structured")
    {'a': ('b', 'c'), 'a2': Fraction(1, 3)}

Atomic memcached-side increments and decrements:

    >>> mc.set("key", "1")  # str or int is fine
    True
    >>> mc.incr("key")
    2L
    >>> mc.decr("key")
    1L

Batch operations lessen GIL contention and thus I/O is faster:

    >>> mc.get_multi(["key", "another_key"])
    {'key': '1'}
    >>> mc.set_multi({"cats": ["on acid", "furry"], "dogs": True})
    []
    >>> mc.get_multi(["cats", "dogs"])
    {'cats': ['on acid', 'furry'], 'dogs': True}
    >>> mc.delete_multi(["cats", "dogs", "nonextant"])
    False

## Further Reading

- Change Log
  - New in version 1.5.0
  - New in version 1.4.0
  - New in version 1.3.0
  - New in version 1.2.0
  - New in version 1.1
  - New in version 1.0
  - New in version 0.9
  - New in version 0.8
  - New in version 0.7
  - New in version 0.6
  - New in version 0.5
  - New in version 0.4
- Installing
  - Requirements
  - Building
- Reference
- Pooling
  - An example with Werkzeug
  - FIFO-like pooling
  - Thread-mapped pooling
- Behaviors
  - Hashing
  - Distribution
  - Failover
- Miscellaneous information
  - Differences from `python-memcached`
  - Exceptions
  - Compression
  - Threading
  - Python 3 `str` vs. `bytes` keys
  - verify_keys ⋁ ¬ verify_keys
- The List of Honored People

## Links and resources

- sendapatch.se: sendapatch.se/
- GitHub: github.com/lericson/pylibmc
- PyPI: pypi.python.org/pypi/pylibmc
- libmemcached: tangent.org/552/libmemcached.html
- memcached: memcached.org/
- BitCoin fund: 12dveKhqiJWCY8zXT4kaHdHELXPeGAUo9h