From 92c1fbb5851d3ab1f707703eb15f6c18ef724006 Mon Sep 17 00:00:00 2001
From: lericson <ludvig@lericson.se>
Date: Mon, 22 Mar 2010 21:52:09 +0100
Subject: [PATCH] Fix up docstrings for pylibmc module

---
 _pylibmcmodule.c |  1 +
 pylibmc.py       | 68 +++++++++++++++++++++++++++++++++++-------------
 tests.py         | 15 +++++++++++
 3 files changed, 66 insertions(+), 18 deletions(-)

diff --git a/_pylibmcmodule.c b/_pylibmcmodule.c
index 0a22269..c824c73 100644
--- a/_pylibmcmodule.c
+++ b/_pylibmcmodule.c
@@ -284,6 +284,7 @@ error:
     return NULL;
 }
 #endif
+/* }}} */
 
 static PyObject *_PylibMC_parse_memcached_value(char *value, size_t size,
         uint32_t flags) {
diff --git a/pylibmc.py b/pylibmc.py
index 2b5702d..78c8a5a 100644
--- a/pylibmc.py
+++ b/pylibmc.py
@@ -1,23 +1,55 @@
-"""`python-memcached`-compatible wrapper around `_pylibmc`.
+"""Snappy libmemcached wrapper
 
-The interface is pretty much exactly the same as python-memcached, with some
-minor differences. If you should happen to spot any, file a bug!
+pylibmc is a Python wrapper around TangentOrg's libmemcached library.
 
->>> import pylibmc
->>> mc = pylibmc.Client(["127.0.0.1"])
->>> b = mc.behaviors
->>> ks = list(sorted(k for k in b.keys() if not k.startswith("_")))
->>> ks  # doctest: +NORMALIZE_WHITESPACE
-['buffer_requests', 'cache_lookups', 'cas', 'connect_timeout', 'distribution',
- 'failure_limit', 'hash', 'ketama', 'ketama_hash', 'ketama_weighted',
- 'no_block', 'receive_timeout', 'send_timeout', 'tcp_nodelay', 'verify_keys']
->>> b["hash"]
-'default'
->>> b["hash"] = 'fnv1a_32'
->>> mc.behaviors["hash"]
-'fnv1a_32'
->>> super(pylibmc.Client, mc).get_behaviors()["hash"]
-6
+The interface is intentionally made as close to python-memcached as possible,
+so that applications can drop-in replace it.
+
+Example usage
+=============
+
+Create a connection and configure it::
+
+    >>> import pylibmc
+    >>> mc = pylibmc.Client(["127.0.0.1"], binary=True)
+    >>> mc.behaviors = {"tcp_nodelay": True, "ketama": True}
+
+Basic operation::
+
+    >>> mc.set("some_key", "Some value")
+    True
+    >>> value = mc.get("some_key")
+    >>> value
+    'Some value'
+    >>> mc.set("another_key", 3)
+    True
+    >>> mc.delete("another_key")
+    True
+    >>> mc.set("key", "1")  # str or int is fine
+    True
+
+Atomic increments and decrements::
+
+    >>> mc.incr("key")
+    2L
+    >>> mc.decr("key")
+    1L
+
+Batch operation::
+
+    >>> mc.get_multi(["key", "another_key"])
+    {'key': '1'}
+    >>> mc.set_multi({"cats": ["on acid", "furry"], "dogs": True})
+    []
+    >>> mc.get_multi(["cats", "dogs"])
+    {'cats': ['on acid', 'furry'], 'dogs': True}
+    >>> mc.delete_multi(["cats", "dogs", "nonextant"])
+    False
+
+Further Reading
+===============
+
+See http://sendapatch.se/projects/pylibmc/
 """
 
 import _pylibmc
diff --git a/tests.py b/tests.py
index 9aa8285..4846d9a 100644
--- a/tests.py
+++ b/tests.py
@@ -195,6 +195,21 @@ Python-wrapped behaviors dict
 >>> pc.behaviors.update({"hash": "fnv1a_32", "distribution": "consistent"})
 >>> (pc.behaviors["hash"], pc.behaviors["distribution"])
 ('fnv1a_32', 'consistent')
+
+>>> pc = pylibmc.Client(["%s:%d" % test_server[1:]])
+>>> b = pc.behaviors
+>>> ks = list(sorted(k for k in b.keys() if not k.startswith("_")))
+>>> ks  # doctest: +NORMALIZE_WHITESPACE
+['buffer_requests', 'cache_lookups', 'cas', 'connect_timeout', 'distribution',
+ 'failure_limit', 'hash', 'ketama', 'ketama_hash', 'ketama_weighted',
+ 'no_block', 'receive_timeout', 'send_timeout', 'tcp_nodelay', 'verify_keys']
+>>> b["hash"]
+'default'
+>>> b["hash"] = 'fnv1a_32'
+>>> pc.behaviors["hash"]
+'fnv1a_32'
+>>> super(pylibmc.Client, pc).get_behaviors()["hash"]
+6
 """
 
 # Used to test pickling.