diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | README.md | 2 | ||||
| -rw-r--r-- | docs-requirements.txt | 3 | ||||
| -rw-r--r-- | docs/apidoc/modules.rst | 7 | ||||
| -rw-r--r-- | docs/apidoc/pymemcache.rst | 53 | ||||
| -rw-r--r-- | docs/apidoc/pymemcache.test.rst | 54 | ||||
| -rw-r--r-- | docs/conf.py | 43 | ||||
| -rw-r--r-- | docs/getting_started.rst | 58 | ||||
| -rw-r--r-- | docs/index.rst | 17 | ||||
| -rw-r--r-- | pymemcache/client.py | 85 | ||||
| -rw-r--r-- | tox.ini | 8 |
11 files changed, 261 insertions, 70 deletions
@@ -35,3 +35,4 @@ pip-log.txt .pypirc coverage.xml \#*\# +docs/_build @@ -31,7 +31,7 @@ You can also use pip: Usage ===== -See the module documentation in pymemcache.client for details. +See the documentation here: http://pymemcache.readthedocs.org/en/latest/ Comparison with Other Libraries =============================== diff --git a/docs-requirements.txt b/docs-requirements.txt new file mode 100644 index 0000000..53de3b4 --- /dev/null +++ b/docs-requirements.txt @@ -0,0 +1,3 @@ +sphinx +sphinx_rtd_theme +sphinxcontrib-napoleon diff --git a/docs/apidoc/modules.rst b/docs/apidoc/modules.rst new file mode 100644 index 0000000..b992d89 --- /dev/null +++ b/docs/apidoc/modules.rst @@ -0,0 +1,7 @@ +pymemcache +========== + +.. toctree:: + :maxdepth: 4 + + pymemcache diff --git a/docs/apidoc/pymemcache.rst b/docs/apidoc/pymemcache.rst new file mode 100644 index 0000000..24a4fe8 --- /dev/null +++ b/docs/apidoc/pymemcache.rst @@ -0,0 +1,53 @@ +pymemcache package +================== + +Subpackages +----------- + +.. toctree:: + + pymemcache.test + +Submodules +---------- + +pymemcache.client module +------------------------ + +.. automodule:: pymemcache.client + :members: + :undoc-members: + :show-inheritance: + +pymemcache.fallback module +-------------------------- + +.. automodule:: pymemcache.fallback + :members: + :undoc-members: + :show-inheritance: + +pymemcache.pool module +---------------------- + +.. automodule:: pymemcache.pool + :members: + :undoc-members: + :show-inheritance: + +pymemcache.serde module +----------------------- + +.. automodule:: pymemcache.serde + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: pymemcache + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/apidoc/pymemcache.test.rst b/docs/apidoc/pymemcache.test.rst new file mode 100644 index 0000000..18a0ddc --- /dev/null +++ b/docs/apidoc/pymemcache.test.rst @@ -0,0 +1,54 @@ +pymemcache.test package +======================= + +Submodules +---------- + +pymemcache.test.benchmark module +-------------------------------- + +.. automodule:: pymemcache.test.benchmark + :members: + :undoc-members: + :show-inheritance: + +pymemcache.test.integration module +---------------------------------- + +.. automodule:: pymemcache.test.integration + :members: + :undoc-members: + :show-inheritance: + +pymemcache.test.test_client module +---------------------------------- + +.. automodule:: pymemcache.test.test_client + :members: + :undoc-members: + :show-inheritance: + +pymemcache.test.test_utils module +--------------------------------- + +.. automodule:: pymemcache.test.test_utils + :members: + :undoc-members: + :show-inheritance: + +pymemcache.test.utils module +---------------------------- + +.. automodule:: pymemcache.test.utils + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: pymemcache.test + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..76f647a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,43 @@ +import os + +extensions = [ + 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', + 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'sphinxcontrib.napoleon' +] + +templates_path = ['_templates'] +source_suffix = '.rst' +master_doc = 'index' +project = u'pymemcache' +copyright = u'2015, Pinterest.com' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.0.0' + +# The full version, including alpha/beta/rc tags. +release = '1.0.0' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +pygments_style = 'sphinx' +# on_rtd is whether we are on readthedocs.org, this line of code grabbed from +# docs.readthedocs.org +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + +if not on_rtd: # only import and set the theme if we're building docs locally + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +# otherwise, readthedocs.org uses their theme by default, so no need to specify + +html_static_path = ['_static'] +htmlhelp_basename = 'pymemcachedoc' + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 0000000..68125fc --- /dev/null +++ b/docs/getting_started.rst @@ -0,0 +1,58 @@ +Getting started! +================ +A comprehensive, fast, pure-Python memcached client library. + +Basic Usage +------------ + +.. code-block:: python + + from pymemcache.client import Client + + client = Client(('localhost', 11211)) + client.set('some_key', 'some_value') + result = client.get('some_key') + + +Serialization +-------------- + +.. code-block:: python + + import json + from pymemcache.client import Client + + def json_serializer(key, value): + if type(value) == str: + return value, 1 + return json.dumps(value), 2 + + def json_deserializer(key, value, flags): + if flags == 1: + return value + if flags == 2: + return json.loads(value) + raise Exception("Unknown serialization format") + + client = Client(('localhost', 11211), serializer=json_serializer, + deserializer=json_deserializer) + client.set('key', {'a':'b', 'c':'d'}) + result = client.get('key') + + +Best Practices +--------------- + + - Always set the connect_timeout and timeout arguments in the constructor to + avoid blocking your process when memcached is slow. + - Use the "noreply" flag for a significant performance boost. The "noreply" + flag is enabled by default for "set", "add", "replace", "append", "prepend", + and "delete". It is disabled by default for "cas", "incr" and "decr". It + obviously doesn't apply to any get calls. + - Use get_many and gets_many whenever possible, as they result in less + round trip times for fetching multiple keys. + - Use the "ignore_exc" flag to treat memcache/network errors as cache misses + on calls to the get* methods. This prevents failures in memcache, or network + errors, from killing your web requests. Do not use this flag if you need to + know about errors from memcache, and make sure you have some other way to + detect memcache server failures. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..bf4f27e --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,17 @@ +Welcome to pymemcached documentation! +===================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + Getting Started </getting_started> + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/pymemcache/client.py b/pymemcache/client.py index 9262234..3a09639 100644 --- a/pymemcache/client.py +++ b/pymemcache/client.py @@ -12,61 +12,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -""" -A comprehensive, fast, pure-Python memcached client library. - -Basic Usage: ------------- - - from pymemcache.client import Client - - client = Client(('localhost', 11211)) - client.set('some_key', 'some_value') - result = client.get('some_key') - - -Serialization: --------------- - - import json - from pymemcache.client import Client - - def json_serializer(key, value): - if type(value) == str: - return value, 1 - return json.dumps(value), 2 - - def json_deserializer(key, value, flags): - if flags == 1: - return value - if flags == 2: - return json.loads(value) - raise Exception("Unknown serialization format") - - client = Client(('localhost', 11211), serializer=json_serializer, - deserializer=json_deserializer) - client.set('key', {'a':'b', 'c':'d'}) - result = client.get('key') - - -Best Practices: ---------------- - - - Always set the connect_timeout and timeout arguments in the constructor to - avoid blocking your process when memcached is slow. - - Use the "noreply" flag for a significant performance boost. The "noreply" - flag is enabled by default for "set", "add", "replace", "append", "prepend", - and "delete". It is disabled by default for "cas", "incr" and "decr". It - obviously doesn't apply to any get calls. - - Use get_many and gets_many whenever possible, as they result in less - round trip times for fetching multiple keys. - - Use the "ignore_exc" flag to treat memcache/network errors as cache misses - on calls to the get* methods. This prevents failures in memcache, or network - errors, from killing your web requests. Do not use this flag if you need to - know about errors from memcache, and make sure you have some other way to - detect memcache server failures. -""" - __author__ = "Charles Gordon" import errno @@ -175,7 +120,7 @@ class Client(object): """ A client for a single memcached server. - Keys and Values: + Keys and Values ---------------- Keys must have a __str__() method which should return a str with no more @@ -194,7 +139,7 @@ class Client(object): already implemented serializers, including one that is compatible with the python-memcache library. - Serialization and Deserialization: + Serialization and Deserialization ---------------------------------- The constructor takes two optional functions, one for "serialization" of @@ -206,19 +151,23 @@ class Client(object): Here is an example using JSON for non-str values: - def serialize_json(key, value): - if type(value) == str: - return value, 1 - return json.dumps(value), 2 + .. code-block:: python + + def serialize_json(key, value): + if type(value) == str: + return value, 1 + return json.dumps(value), 2 + + def deserialize_json(key, value, flags): + if flags == 1: + return value + + if flags == 2: + return json.loads(value) - def deserialize_json(key, value, flags): - if flags == 1: - return value - if flags == 2: - return json.loads(value) - raise Exception("Unknown flags for value: {1}".format(flags)) + raise Exception("Unknown flags for value: {1}".format(flags)) - Error Handling: + Error Handling --------------- All of the methods in this class that talk to memcached can throw one of @@ -1,8 +1,14 @@ [tox] -envlist = py26, py27, pypy, py33, py34 +envlist = py26, py27, pypy, py33, py34, docs [testenv] commands = pip install -r test-requirements.txt pip install -e . py.test {posargs} + +[testenv:docs] +commands = + pip install -r docs-requirements.txt + sphinx-apidoc -o docs/apidoc/ pymemcache + sphinx-build -b html docs/ docs/_build |