Fix up docstrings for pylibmc module

_pylibmcmodule.c

@@ -284,6 +284,7 @@ error:
     return NULL;
 }
 #endif
+/* }}} */
 
 static PyObject *_PylibMC_parse_memcached_value(char *value, size_t size,
         uint32_t flags) {

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
+pylibmc is a Python wrapper around TangentOrg's libmemcached library.
-minor differences. If you should happen to spot any, file a bug!
+
+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"])
+    >>> mc = pylibmc.Client(["127.0.0.1"], binary=True)
->>> b = mc.behaviors
+    >>> mc.behaviors = {"tcp_nodelay": True, "ketama": True}
->>> ks = list(sorted(k for k in b.keys() if not k.startswith("_")))
+
->>> ks  # doctest: +NORMALIZE_WHITESPACE
+Basic operation::
-['buffer_requests', 'cache_lookups', 'cas', 'connect_timeout', 'distribution',
+
- 'failure_limit', 'hash', 'ketama', 'ketama_hash', 'ketama_weighted',
+    >>> mc.set("some_key", "Some value")
- 'no_block', 'receive_timeout', 'send_timeout', 'tcp_nodelay', 'verify_keys']
+    True
->>> b["hash"]
+    >>> value = mc.get("some_key")
-'default'
+    >>> value
->>> b["hash"] = 'fnv1a_32'
+    'Some value'
->>> mc.behaviors["hash"]
+    >>> mc.set("another_key", 3)
-'fnv1a_32'
+    True
->>> super(pylibmc.Client, mc).get_behaviors()["hash"]
+    >>> mc.delete("another_key")
-6
+    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

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.