Merge pull request #1 from sprockets/initial-version

Initial version

.travis.yml

@@ -0,0 +1,30 @@
+%YAML 1.1
+---
+language: python
+python:
+  - 2.6
+  - 2.7
+  - pypy
+  - 3.2
+  - 3.3
+  - 3.4
+install:
+  - if [[ $TRAVIS_PYTHON_VERSION == '2.6' ]]; then pip install unittest2; fi
+  - if [[ $TRAVIS_PYTHON_VERSION == 2* ]]; then pip install -r requirements2.txt; fi
+  - if [[ $TRAVIS_PYTHON_VERSION == pypy ]]; then pip install -r requirements2.txt; fi
+  - if [[ $TRAVIS_PYTHON_VERSION == 3* ]]; then pip install -r requirements3.txt; fi
+  - pip install -r test-requirements.txt
+script: nosetests
+after_success:
+  - coveralls
+services:
+  - memcached
+deploy:
+  provider: pypi
+  user: sprockets
+  on:
+    python: 2.7
+    tags: true
+    all_branches: true
+  password:
+    secure: F0sivvBoagfbkCnKBlmTEtQXccDRmpfTJSRtL2Vnk8RfsCtoPMEfx8pshuvw5Mp8m6fRxulFd8Qrg3suQjCDFdwlCGxtHricmSfW1LHxNQW/xjDBUvQpdLylv+Am/3CJXso3FZjzji9Z8z5sfBMRUID+jucjhRRbgF68yMUyMXk=

LICENSE

@@ -1,28 +1,25 @@
-Copyright (c) 2014, Sprockets
+Copyright (c) 2014 AWeber Communications
 All rights reserved.
 
-Redistribution and use in source and binary forms, with or without
+Redistribution and use in source and binary forms, with or without modification,
-modification, are permitted provided that the following conditions are met:
+are permitted provided that the following conditions are met:
 
-* Redistributions of source code must retain the above copyright notice, this
+ * Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
+   list of conditions and the following disclaimer.
-
+ * Redistributions in binary form must reproduce the above copyright notice,
-* Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
-  this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
-  and/or other materials provided with the distribution.
+ * Neither the name of Sprockets nor the names of its
-
+   contributors may be used to endorse or promote products derived from this
-* Neither the name of the {organization} nor the names of its
+   software without specific prior written permission.
-  contributors may be used to endorse or promote products derived from
-  this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE
+include README.rst

README.md

@@ -1,2 +0,0 @@
-sprockets.clients.memcached
-===========================

README.rst

@@ -0,0 +1,63 @@
+sprockets.clients.memcached
+===========================
+Memcached client wrapper that is configured via environment variables.
+
+|Version| |Downloads| |Status| |Coverage| |License|
+
+Installation
+------------
+``sprockets.clients.memcached`` is available on the
+`Python Package Index <https://pypi.python.org/pypi/sprockets.clients.memcached>`_
+and can be installed via ``pip`` or ``easy_install``:
+
+.. code:: bash
+
+  pip install sprockets.clients.memcached
+
+Documentation
+-------------
+https://sprocketsclientsmemcached.readthedocs.org
+
+Requirements
+------------
+-  `python-memcached <https://pypi.python.org/pypi/python-memcached>`_ (Python 2)
+-  `python3-memcached <https://pypi.python.org/pypi/python3-memcached>`_ (Python 3)
+
+Example
+-------
+The following example sets the environment variables for connecting to
+memcached on ``192.168.1.2`` and ``192.168.1.3`` and subsequently issuing a few
+memcached commands:
+
+.. code:: python
+
+    import os
+
+    from sprockets.clients import memcached
+
+    os.environ['MEMCACHED_SERVERS'] = '192.168.1.2:11211,192.168.1.3:11211'
+
+
+    client = memcached.Client()
+    client.set('foo', 'bar')
+    print(client.get('foo'))
+
+
+Version History
+---------------
+Available at https://sprocketsclientsmemcached.readthedocs.org/en/latest/history.html
+
+.. |Version| image:: https://badge.fury.io/py/sprockets.clients.memcached.svg?
+   :target: http://badge.fury.io/py/sprockets.clients.memcached
+
+.. |Status| image:: https://travis-ci.org/sprockets/sprockets.clients.memcached.svg?branch=master
+   :target: https://travis-ci.org/sprockets/sprockets.clients.memcached
+
+.. |Coverage| image:: https://img.shields.io/coveralls/sprockets/sprockets.clients.memcached.svg?
+   :target: https://coveralls.io/r/sprockets/sprockets.clients.memcached
+
+.. |Downloads| image:: https://pypip.in/d/sprockets.clients.memcached/badge.svg?
+   :target: https://pypi.python.org/pypi/sprockets.clients.memcached
+
+.. |License| image:: https://pypip.in/license/sprockets.clients.memcached/badge.svg?
+   :target: https://sprocketsclientsmemcached.readthedocs.org

dev-requirements.txt

@@ -0,0 +1,5 @@
+# Include this version only for documentation building purposes, normally ignored
+-e git://github.com/gmr/python-memcached.git@docstring-update#egg=python-memcached
+sphinx>=1.2,<2
+sphinx-rtd-theme>=0.1,<1.0
+sphinxcontrib-httpdomain>=1.2,<2

docs/api.rst

@@ -0,0 +1,3 @@
+.. automodule:: sprockets.clients.memcached
+   :members:
+   :inherited-members:

docs/conf.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python
+import sphinx_rtd_theme
+
+from sprockets.clients.memcached import version_info, __version__
+
+needs_sphinx = '1.0'
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.inheritance_diagram',
+    'sphinxcontrib.httpdomain',
+]
+templates_path = []
+source_suffix = '.rst'
+master_doc = 'index'
+project = 'sprockets.clients.memcached'
+copyright = '2014, AWeber Communications'
+version = '.'.join(__version__.split('.')[0:1])
+release = __version__
+if len(version_info) > 3:
+    release += '-{0}'.format(str(v) for v in version_info[3:])
+exclude_patterns = []
+pygments_style = 'sphinx'
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/2/', None)
+}

docs/examples.rst

@@ -0,0 +1,31 @@
+Examples
+========
+The following example sets the environment variables for connecting to
+memcached on ``192.168.1.2`` and ``192.168.1.3`` and subsequently issuing a few
+memcached commands:
+
+.. code:: python
+
+    import os
+
+    from sprockets.clients import memcached
+
+    os.environ['MEMCACHED_SERVERS'] = '192.168.1.2:11211,192.168.1.3:11211'
+
+    client = memcached.Client()
+    client.set('foo', 'bar')
+    print(client.get('foo'))
+
+The next example uses a prefixed environment variable for configuration data:
+
+.. code:: python
+
+    import os
+
+    from sprockets.clients import memcached
+
+    os.environ['FOO_MEMCACHED_SERVERS'] = '192.168.1.2:11211'
+
+    client = memcached.Client('foo')
+    client.set('foo', 'bar')
+    print(client.get('foo'))

docs/history.rst

@@ -0,0 +1,4 @@
+Version History
+---------------
+- 1.0.0 [2014-09-03]
+ - Initial release

docs/index.rst

@@ -0,0 +1,67 @@
+sprockets.clients.memcached
+===========================
+Memcached client wrapper that is configured via environment variables
+
+|Version| |Downloads| |Status| |Coverage| |License|
+
+Installation
+------------
+``sprockets.clients.memcached`` is available on the
+`Python Package Index <https://pypi.python.org/pypi/sprockets.clients.memcached>`_
+and can be installed via ``pip`` or ``easy_install``:
+
+.. code:: bash
+
+  pip install sprockets.clients.memcached
+
+Requirements
+------------
+-  `sprockets <https://github.com/sprockets/sprockets>`_
+-  `python-memcached <https://pypi.python.org/pypi/python-memcached>`_ (Python 2)
+-  `python3-memcached <https://pypi.python.org/pypi/python3-memcached>`_ (Python 3)
+
+API Documentation
+-----------------
+.. toctree::
+   :maxdepth: 2
+
+   api
+   examples
+
+Version History
+---------------
+See :doc:`history`
+
+Issues
+------
+Please report any issues to the Github project at `https://github.com/sprockets/sprockets.clients.memcached/issues <https://github.com/sprockets/sprockets.clients.memcached/issues>`_
+
+Source
+------
+``sprockets.clients.memcached`` source is available on Github at `https://github.com/sprockets/sprockets.clients.memcached <https://github.com/sprockets/sprockets.clients.memcached>`_
+
+License
+-------
+``sprockets.clients.memcached`` is released under the `3-Clause BSD license <https://github.com/sprockets/sprockets.clients.memcached/blob/master/LICENSE>`_.
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+.. |Version| image:: https://badge.fury.io/py/sprockets.clients.memcached.svg?
+   :target: http://badge.fury.io/py/sprockets.clients.memcached
+
+.. |Status| image:: https://travis-ci.org/sprockets/sprockets.clients.memcached.svg?branch=master
+   :target: https://travis-ci.org/sprockets/sprockets.clients.memcached
+
+.. |Coverage| image:: https://img.shields.io/coveralls/sprockets/sprockets.clients.memcached.svg?
+   :target: https://coveralls.io/r/sprockets/sprockets.clients.memcached
+
+.. |Downloads| image:: https://pypip.in/d/sprockets.clients.memcached/badge.svg?
+   :target: https://pypi.python.org/pypi/sprockets.clients.memcached
+
+.. |License| image:: https://pypip.in/license/sprockets.clients.memcached/badge.svg?
+   :target: https://sprocketsclientsmemcached.readthedocs.org

requirements2.txt

@@ -0,0 +1 @@
+python-memcached

requirements3.txt

@@ -0,0 +1 @@
+python3-memcached

setup.cfg

@@ -0,0 +1,9 @@
+[build_sphinx]
+all-files = 1
+source-dir = docs
+build-dir = build/docs
+
+[nosetests]
+with-coverage = 1
+cover-package = sprockets.clients.memcached
+verbose = 1

setup.py

@@ -0,0 +1,50 @@
+import codecs
+import sys
+
+import setuptools
+
+install_requires = ['sprockets']
+
+if sys.version_info < (3, 0):
+    install_requires.append('python-memcached')
+if sys.version_info >= (3, 0):
+    install_requires.append('python3-memcached')
+
+
+setuptools.setup(
+    name='sprockets.clients.memcached',
+    version='1.0.0',
+    description=('Memcached client wrapper that is configured via '
+                 'environment variables'),
+    long_description=codecs.open('README.rst', encoding='utf-8').read(),
+    url='https://github.com/sprockets/sprockets.clients.memcached.git',
+    author='AWeber Communications',
+    author_email='api@aweber.com',
+    license=codecs.open('LICENSE', encoding='utf-8').read(),
+    classifiers=[
+        'Development Status :: 4 - Beta',
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: BSD License',
+        'Natural Language :: English',
+        'Operating System :: OS Independent',
+        'Programming Language :: Python :: 2',
+        'Programming Language :: Python :: 2.6',
+        'Programming Language :: Python :: 2.7',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.2',
+        'Programming Language :: Python :: 3.3',
+        'Programming Language :: Python :: 3.4',
+        'Programming Language :: Python :: Implementation :: CPython',
+        'Programming Language :: Python :: Implementation :: PyPy',
+        'Topic :: Software Development :: Libraries',
+        'Topic :: Software Development :: Libraries :: Python Modules'
+    ],
+    packages=['sprockets',
+              'sprockets.clients',
+              'sprockets.clients.memcached'],
+    package_data={'': ['LICENSE', 'README.rst']},
+    include_package_data=True,
+    namespace_packages=['sprockets',
+                        'sprockets.clients'],
+    install_requires=install_requires,
+    zip_safe=False)

sprockets/__init__.py

@@ -0,0 +1 @@
+__import__('pkg_resources').declare_namespace(__name__)

sprockets/clients/__init__.py

@@ -0,0 +1 @@
+__import__('pkg_resources').declare_namespace(__name__)

sprockets/clients/memcached/__init__.py

@@ -0,0 +1,62 @@
+"""
+Memcached Client API
+====================
+The memcached client API wraps the :py:class:`memcache.Client` adding
+environment variable based configuration.
+
+Example environment variable configuration:
+
+    ``<PREFIX>_MEMCACHED_SERVERS = '10.0.0.1:11211:64,10.0.0.2:11211:64'``
+
+"""
+import logging
+import os
+
+import memcache
+
+version_info = (0, 0, 0)
+__version__ = '.'.join(str(v) for v in version_info)
+
+LOGGER = logging.getLogger(__name__)
+
+DEFAULT_SERVER = '127.0.0.1:11211'
+
+
+def _get_servers(prefix):
+    """Return the list of memcached servers from the environment variable
+    value, defaulting to ``DEFAULT_SERVER`` if it is not set.
+
+    If prefix is not set, then the environment variable ``MEMCACHED_SERVERS``
+    will be be used. If both ``<PREFIX>_MEMCACHED_SERVERS`` and
+    ``MEMCACHED_SERVERS`` are not set, the default server value of
+    ``127.0.0.1`` will be returned.
+
+    :param str prefix: The environment variable prefix
+    :rtype: list
+
+    """
+    key = '%s_MEMCACHED_SERVERS' % prefix if prefix else 'MEMCACHED_SERVERS'
+    return os.environ.get(key, DEFAULT_SERVER).split(',')
+
+
+class Client(memcache.Client):
+    """Wraps :py:class:`memcache.Client`, passing in the environment
+    variable prefix. If prefix is set, the environment variable key is in the
+    format ``<PREFIX>_MEMCACHED_SERVERS``. If the prefix is not set, the list
+    will attempt to be retrieved from the ``MEMCACHED_SERVERS``. If neither
+    environment variable is set, the default value of ``127.0.0.1:11211`` is
+    used.
+
+    The per server format in the comma separated list is:
+
+        ``[HOST]:[PORT]<:WEIGHT>``
+
+    Where host and port are required but weight is optional.
+
+    :param str prefix: The environment variable prefix. Default: ``None``
+
+    """
+    def __init__(self, prefix=None):
+        servers = _get_servers(prefix.upper() if prefix else '')
+        LOGGER.debug('Connecting to %r', servers)
+        super(Client, self).__init__(servers)

test-requirements.txt

@@ -0,0 +1,4 @@
+coverage>=3.7,<4
+coveralls>=0.4,<1
+nose>=1.3,<2
+mock==1.0.1

tests.py

@@ -0,0 +1,57 @@
+"""
+Tests for the sprockets.clients.memcached package
+
+"""
+import mock
+import os
+try:
+    import unittest2 as unittest
+except ImportError:
+    import unittest
+
+from sprockets.clients import memcached
+
+
+class TestGetServers(unittest.TestCase):
+
+    def tearDown(self):
+        for key in ['MEMCACHED_SERVERS', 'TEST1_MEMCACHED_SERVERS']:
+            if key in os.environ:
+                del os.environ[key]
+
+    def test_get_servers_for_prefixed_key(self):
+        os.environ['TEST1_MEMCACHED_SERVERS'] = '1.1.1.1:11211,1.1.1.2:11211'
+        self.assertListEqual(memcached._get_servers('TEST1'),
+                             ['1.1.1.1:11211', '1.1.1.2:11211'])
+
+    def test_get_servers_for_non_prefixed_key(self):
+        os.environ['MEMCACHED_SERVERS'] = '2.1.1.1:11211'
+        self.assertListEqual(memcached._get_servers(None), ['2.1.1.1:11211'])
+
+    def test_get_servers_returns_default_value(self):
+        self.assertListEqual(memcached._get_servers(None), ['127.0.0.1:11211'])
+
+
+class TestClientWrapsMemcacheClient(unittest.TestCase):
+
+    @mock.patch('memcache.Client.__init__')
+    def test_client_super_init(self, mock_init):
+        memcached.Client()
+        mock_init.assert_called_once_with(['127.0.0.1:11211'])
+
+
+class ClientIntegrationTests(unittest.TestCase):
+
+    def setUp(self):
+        self.client = memcached.Client()
+        self.client.incr('test')
+        if any([s.deaduntil for s in self.client.servers]):
+            raise unittest.SkipTest('No memcached daemon present')
+
+    def test_that_incr_returns_a_value_for_a_set_key(self):
+        self.client.set('test-incr', 2)
+        self.assertEqual(self.client.incr('test-incr'), 3)
+
+    def test_that_set_key_is_gettable(self):
+        self.client.set('foo', 'bar', 60)
+        self.assertEqual(self.client.get('foo'), 'bar')