Add hashing client

.travis.yml

@@ -10,7 +10,6 @@ env:
   - TOXENV=py33
   - TOXENV=py34
   - TOXENV=pypy
-  - TOXENV=pypy3
 
 install:
   - travis_retry pip install tox

docs/apidoc/pymemcache.client.rst

@@ -0,0 +1,30 @@
+pymemcache.client package
+=========================
+
+Submodules
+----------
+
+pymemcache.client.base module
+-----------------------------
+
+.. automodule:: pymemcache.client.base
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+pymemcache.client.hash module
+-----------------------------
+
+.. automodule:: pymemcache.client.hash
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: pymemcache.client
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/getting_started.rst

@@ -7,20 +7,37 @@ Basic Usage
 
 .. code-block:: python
 
-    from pymemcache.client import Client
+    from pymemcache.client.base import Client
 
     client = Client(('localhost', 11211))
     client.set('some_key', 'some_value')
     result = client.get('some_key')
 
+Using a memcached cluster
+-------------------------
+This will use a consistent hashing algorithm to choose which server to
+set/get the values from. It will also automatically rebalance depending
+on if a server goes down.
+
+.. code-block:: python
+
+    from pymemcache.client.hash import HashClient
+
+    client = HashClient([
+        ('127.0.0.1', 11211),
+        ('127.0.0.1', 11212)
+    ])
+    client.set('some_key', 'some value')
+    result = client.get('some_key')
+
 
 Serialization
 --------------
 
 .. code-block:: python
 
      import json
-     from pymemcache.client import Client
+     from pymemcache.client.base import Client
 
      def json_serializer(key, value):
          if type(value) == str:

pymemcache/client/__init__.py

@@ -0,0 +1,2 @@
+# API Backwards compatibility
+from pymemcache.client.base import Client  # noqa

pymemcache/client.py → pymemcache/client/base.py

@@ -20,6 +20,15 @@
 
 from pymemcache import pool
 
+from pymemcache.exceptions import (
+    MemcacheClientError,
+    MemcacheUnknownCommandError,
+    MemcacheIllegalInputError,
+    MemcacheServerError,
+    MemcacheUnknownError,
+    MemcacheUnexpectedCloseError
+)
+
 
 RECV_SIZE = 4096
 VALID_STORE_RESULTS = {
@@ -56,51 +65,9 @@
     b'slab_automove': lambda value: int(value) != 0,
 }
 
-
-class MemcacheError(Exception):
-    "Base exception class"
-    pass
-
-
-class MemcacheClientError(MemcacheError):
-    """Raised when memcached fails to parse the arguments to a request, likely
-    due to a malformed key and/or value, a bug in this library, or a version
-    mismatch with memcached."""
-    pass
-
-
-class MemcacheUnknownCommandError(MemcacheClientError):
-    """Raised when memcached fails to parse a request, likely due to a bug in
-    this library or a version mismatch with memcached."""
-    pass
-
-
-class MemcacheIllegalInputError(MemcacheClientError):
-    """Raised when a key or value is not legal for Memcache (see the class docs
-    for Client for more details)."""
-    pass
-
-
-class MemcacheServerError(MemcacheError):
-    """Raised when memcached reports a failure while processing a request,
-    likely due to a bug or transient issue in memcached."""
-    pass
-
-
-class MemcacheUnknownError(MemcacheError):
-    """Raised when this library receives a response from memcached that it
-    cannot parse, likely due to a bug in this library or a version mismatch
-    with memcached."""
-    pass
-
-
-class MemcacheUnexpectedCloseError(MemcacheServerError):
-    "Raised when the connection with memcached closes unexpectedly."
-    pass
-
-
 # Common helper functions.
 
+
 def _check_key(key, key_prefix=b''):
     """Checks key and add key_prefix."""
     if isinstance(key, six.text_type):
@@ -131,7 +98,7 @@ class Client(object):
      Values must have a __str__() method to convert themselves to a byte
      string. Unicode objects can be a problem since str() on a Unicode object
      will attempt to encode it as ASCII (which will fail if the value contains
-     code points larger than U+127). You can fix this will a serializer or by
+     code points larger than U+127). You can fix this with a serializer or by
      just calling encode on the string (using UTF-8, for instance).
 
      If you intend to use anything but str as a value, it is a good idea to use
@@ -656,7 +623,6 @@ def _fetch_cmd(self, name, keys, expect_cas):
             while True:
                 buf, line = _readline(self.sock, buf)
                 self._raise_errors(line, name)
-
                 if line == b'END':
                     return result
                 elif line.startswith(b'VALUE'):
@@ -684,7 +650,7 @@ def _fetch_cmd(self, name, keys, expect_cas):
                     result[key] = value
                 else:
                     raise MemcacheUnknownError(line[:32])
-        except Exception:
+        except Exception as e:
             self.close()
             if self.ignore_exc:
                 return {}