pymemcache 2.0.0

A comprehensive, fast, pure Python memcached client

pymemcache
==========

.. image:: https://travis-ci.org/pinterest/pymemcache.png
:target: https://travis-ci.org/pinterest/pymemcache

.. image:: https://img.shields.io/pypi/v/pymemcache.svg
:target: https://pypi.python.org/pypi/pymemcache

.. image:: https://readthedocs.org/projects/pymemcache/badge/?version=master
:target: https://pymemcache.readthedocs.io/en/latest/
:alt: Master Documentation Status

A comprehensive, fast, pure-Python memcached client.

pymemcache supports the following features:

* Complete implementation of the memcached text protocol.
* Configurable timeouts for socket connect and send/recv calls.
* Access to the "noreply" flag, which can significantly increase the speed of writes.
* Flexible, modular and simple approach to serialization and deserialization.
* The (optional) ability to treat network and memcached errors as cache misses.

Installing pymemcache
=====================

Install from pip:

.. code-block:: bash

pip install pymemcache

For development, clone from github and run the tests:

.. code-block:: bash

git clone https://github.com/pinterest/pymemcache.git
cd pymemcache

Run the tests (make sure you have a local memcached server running):

.. code-block:: bash

tox

Usage
=====

See the documentation here: https://pymemcache.readthedocs.io/en/latest/

Comparison with Other Libraries
===============================

pylibmc
-------

The pylibmc library is a wrapper around libmemcached, implemented in C. It is
fast, implements consistent hashing, the full memcached protocol and timeouts.
It does not provide access to the "noreply" flag. It also isn't pure Python,
so using it with libraries like gevent is out of the question, and its
dependency on libmemcached poses challenges (e.g., it must be built against
the same version of libmemcached that it will use at runtime).

Python-memcache
---------------

The python-memcache library implements the entire memcached text protocol, has
a single timeout for all socket calls and has a flexible approach to
serialization and deserialization. It is also written entirely in Python, so
it works well with libraries like gevent. However, it is tied to using thread
locals, doesn't implement "noreply", can't treat errors as cache misses and is
slower than both pylibmc and pymemcache. It is also tied to a specific method
for handling clusters of memcached servers.

memcache_client
---------------

The team at mixpanel put together a pure Python memcached client as well. It
has more fine grained support for socket timeouts, only connects to a single
host. However, it doesn't support most of the memcached API (just get, set,
delete and stats), doesn't support "noreply", has no serialization or
deserialization support and can't treat errors as cache misses.

External Links
==============

The memcached text protocol reference page:
https://github.com/memcached/memcached/blob/master/doc/protocol.txt

The python-memcached library (another pure-Python library):
https://github.com/linsomniac/python-memcached

Mixpanel's Blog post about their memcached client for Python:
http://code.mixpanel.com/2012/07/16/we-went-down-so-we-wrote-a-better-pure-python-memcache-client/

Mixpanel's pure Python memcached client:
https://github.com/mixpanel/memcache_client

Credits
=======

* `Charles Gordon <http://github.com/cgordon>`_
* `Dave Dash <http://github.com/davedash>`_
* `Dan Crosta <http://github.com/dcrosta>`_
* `Julian Berman <http://github.com/Julian>`_
* `Mark Shirley <http://github.com/maspwr>`_
* `Tim Bart <http://github.com/pims>`_
* `Thomas Orozco <http://github.com/krallin>`_
* `Marc Abramowitz <http://github.com/msabramo>`_
* `Marc-Andre Courtois <http://github.com/mcourtois>`_
* `Julien Danjou <http://github.com/jd>`_
* `INADA Naoki <http://github.com/methane>`_
* `James Socol <http://github.com/jsocol>`_
* `Joshua Harlow <http://github.com/harlowja>`_
* `John Anderson <http://github.com/sontek>`_
* `Adam Chainz <http://github.com/adamchainz>`_
* `Ernest W. Durbin III <https://github.com/ewdurbin>`_
* `Remco van Oosterhout <https://github.com/Vhab>`_
* `Nicholas Charriere <https://github.com/nichochar>`_
* `Joe Gordon <https://github.com/jogo>`_

We're Hiring!
=============
Are you really excited about open-source? Or great software engineering?
Pinterest is [hiring](https://careers.pinterest.com/)!

Change Log
==========
New in version 2.0.0
--------------------
* Change set_many and set_multi api return value. `PR#179 <https://github.com/pinterest/pymemcache/pull/179>`_
* Fix support for newbytes from python-future. `PR#187 <https://github.com/pinterest/pymemcache/pull/187>`_
* Add support for Python 3.7, and drop support for Python 3.3
* Properly batch Client.set_many() call. `PR#182 <https://github.com/pinterest/pymemcache/pull/182>`_
* Improve _check_key() and _store_cmd() performance. `PR#183 <https://github.com/pinterest/pymemcache/pull/183>`_
* Properly batch Client.delete_many() call. `PR#184 <https://github.com/pinterest/pymemcache/pull/184>`_
* Add option to explicitly set pickle version used by serde. `PR#190 <https://github.com/pinterest/pymemcache/pull/190>`_

New in version 1.4.4
--------------------
* pypy3 to travis test matrix
* full benchmarks in test
* fix flake8 issues
* Have mockmemcacheclient support non-ascii strings
* Switch from using pickle format 0 to the highest available version. See `PR#156 <https://github.com/pinterest/pymemcache/pull/156>`_

*Warning*: different versions of python have different highest pickle versions: https://docs.python.org/3/library/pickle.html


New in version 1.4.3
--------------------
* Documentation improvements
* Fixed cachedump stats command, see `ticket <https://github.com/pinterest/pymemcache/issues/103>`_
* Honor default_value in HashClient

New in version 1.4.2
--------------------
* Drop support for python 2.6, see `ticket <https://github.com/pinterest/pymemcache/issues/139>`_

New in version 1.4.1
--------------------
* Python 3 serializations `fixes <https://github.com/pinterest/pymemcache/pull/131>`_
* Drop support for pypy3
* Comment cleanup
* Add gets_many to hash_client
* Better checking for illegal chars in key

New in version 1.4.0
--------------------
* Unicode keys support. It is now possible to pass the flag `allow_unicode_keys` when creating the clients, thanks @jogo!
* Fixed a bug where PooledClient wasn't following `default_noreply` arg set on init, thanks @kols!
* Improved documentation

New in version 1.3.8
--------------------
* use cpickle instead of pickle when possible (python2)

New in version 1.3.7
--------------------
* default parameter on get(key, default=0)
* fixed docs to autogenerate themselves with sphinx
* fix linter to work with python3
* improve error message on illegal Input for the key
* refactor stat parsing
* fix MockMemcacheClient
* fix unicode char in middle of key bug

New in version 1.3.6
--------------------
* Fix flake8 and cleanup tox building
* Fix security vulnerability by sanitizing key input

New in version 1.3.5
--------------------
* Bug fix for HashClient when retries is set to zero.
* Adding the VERSION command to the clients.

New in version 1.3.4
--------------------
* Bug fix for the HashClient that corrects behavior when there are no working servers.

New in version 1.3.3
--------------------
* Adding caching to the Travis build.
* A bug fix for pluggable hashing in HashClient.
* Adding a default_noreply argument to the Client ctor.

New in version 1.3.2
--------------------
* Making the location of Memcache Exceptions backwards compatible.

New in version 1.3.0
--------------------
* Python 3 Support
* Introduced HashClient that uses consistent hasing for allocating keys across many memcached nodes. It also can detect servers going down and rebalance keys across the available nodes.
* Retry sock.recv() when it raises EINTR

New in version 1.2.9
--------------------
* Introduced PooledClient a thread-safe pool of clients