From f84dcf42e960e6b7e2d69143908c03279ad16d72 Mon Sep 17 00:00:00 2001 From: Nicholas Charriere Date: Wed, 3 Aug 2016 13:43:07 -0700 Subject: [PATCH] Fixed docs --- .gitignore | 4 ++ docs/apidoc/modules.rst | 7 +++ docs/apidoc/pymemcache.client.rst | 46 +++++++++++++++++++ docs/apidoc/pymemcache.rst | 54 ++++++++++++++++++++++ docs/getting_started.rst | 75 +++++++++++++++++++++++++++++++ docs/index.rst | 3 ++ 6 files changed, 189 insertions(+) create mode 100644 docs/apidoc/modules.rst create mode 100644 docs/apidoc/pymemcache.client.rst create mode 100644 docs/apidoc/pymemcache.rst create mode 100644 docs/getting_started.rst diff --git a/.gitignore b/.gitignore index a53e6c5..50ddd1c 100644 --- a/.gitignore +++ b/.gitignore @@ -28,12 +28,16 @@ env/ #Translations *.mo +# Mac FS +.DS_Store + #Mr Developer .mr.developer.cfg # Swap files. *.swp +.pip .pypirc coverage.xml \#*\# 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.client.rst b/docs/apidoc/pymemcache.client.rst new file mode 100644 index 0000000..0f2622b --- /dev/null +++ b/docs/apidoc/pymemcache.client.rst @@ -0,0 +1,46 @@ +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: + +pymemcache.client.murmur3 module +-------------------------------- + +.. automodule:: pymemcache.client.murmur3 + :members: + :undoc-members: + :show-inheritance: + +pymemcache.client.rendezvous module +----------------------------------- + +.. automodule:: pymemcache.client.rendezvous + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: pymemcache.client + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/apidoc/pymemcache.rst b/docs/apidoc/pymemcache.rst new file mode 100644 index 0000000..8009023 --- /dev/null +++ b/docs/apidoc/pymemcache.rst @@ -0,0 +1,54 @@ +pymemcache package +================== + +Subpackages +----------- + +.. toctree:: + + pymemcache.client + pymemcache.test + +Submodules +---------- + +pymemcache.exceptions module +---------------------------- + +.. automodule:: pymemcache.exceptions + :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/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 0000000..10b66c1 --- /dev/null +++ b/docs/getting_started.rst @@ -0,0 +1,75 @@ +Getting started! +================ +A comprehensive, fast, pure-Python memcached client library. + +Basic Usage +------------ + +.. code-block:: python + + 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.base 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 index b95c23a..9d3b828 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,6 +11,9 @@ Contents: .. toctree:: :maxdepth: 2 + Getting Started + Source Code + Indices and tables