better packer docstring

Author: methane

Makefile

@@ -1,12 +1,16 @@
 .PHONY: test all python3
 
-all:
+all: cython
 	python setup.py build_ext -i -f
-	python setup.py build sdist
 
-python3:
+doc-serve: all
+	cd docs && make serve
+
+cython:
+	cython msgpack/*.pyx
+
+python3: cython
 	python3 setup.py build_ext -i -f
-	python3 setup.py build sdist
 
 test:
 	py.test test

docs/Makefile

@@ -10,7 +10,7 @@ BUILDDIR      = _build
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -E -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 

docs/api.rst

@@ -36,3 +36,8 @@ These exceptions are accessible via `msgpack` package.
     :undoc-members:
     :show-inheritance:
 
+.. automodule:: msgpack.fallback
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

msgpack/_packer.pyx

@@ -39,23 +39,29 @@ cdef int DEFAULT_RECURSE_LIMIT=511
 
 
 cdef class Packer(object):
-    """MessagePack Packer
+    """
+    MessagePack Packer
 
-    usage:
+    usage::
 
         packer = Packer()
         astream.write(packer.pack(a))
         astream.write(packer.pack(b))
 
     Packer's constructor has some keyword arguments:
 
-    * *defaut* - Convert user type to builtin type that Packer supports.
-      See also simplejson's document.
-    * *encoding* - Convert unicode to bytes with this encoding. (default: 'utf-8')
-    * *unicode_erros* - Error handler for encoding unicode. (default: 'strict')
-    * *use_single_float* - Use single precision float type for float. (default: False)
-    * *autoreset* - Reset buffer after each pack and return it's content as `bytes`. (default: True).
-      If set this to false, use `bytes()` to get content and `.reset()` to clear buffer.
+    :param callable default:
+        Convert user type to builtin type that Packer supports.
+        See also simplejson's document.
+    :param str encoding:
+        Convert unicode to bytes with this encoding. (default: 'utf-8')
+    :param str unicode_erros:
+        Error handler for encoding unicode. (default: 'strict')
+    :param bool use_single_float:
+        Use single precision float type for float. (default: False)
+    :param bool autoreset:
+        Reset buffer after each pack and return it's content as `bytes`. (default: True).
+        If set this to false, use `bytes()` to get content and `.reset()` to clear buffer.
     """
     cdef msgpack_packer pk
     cdef object _default
@@ -75,6 +81,8 @@ cdef class Packer(object):
         self.pk.length = 0
 
     def __init__(self, default=None, encoding='utf-8', unicode_errors='strict', use_single_float=False, bint autoreset=1):
+        """
+        """
         self.use_float = use_single_float
         self.autoreset = autoreset
         if default is not None:
@@ -218,7 +226,7 @@ cdef class Packer(object):
         Pack *pairs* as msgpack map type.
 
         *pairs* should sequence of pair.
-        (`len(pairs)` and `for k, v in *pairs*:` should be supported.)
+        (`len(pairs)` and `for k, v in pairs:` should be supported.)
         """
         cdef int ret = msgpack_pack_map(&self.pk, len(pairs))
         if ret == 0:
@@ -245,15 +253,21 @@ cdef class Packer(object):
         return PyBytes_FromStringAndSize(self.pk.buf, self.pk.length)
 
 
-def pack(object o, object stream, default=None, encoding='utf-8', unicode_errors='strict'):
+def pack(object o, object stream, default=None, str encoding='utf-8', str unicode_errors='strict'):
+    """
+    pack an object `o` and write it to stream)
+
+    See :class:`Packer` for options.
     """
-    pack an object `o` and write it to stream)."""
     packer = Packer(default=default, encoding=encoding, unicode_errors=unicode_errors)
     stream.write(packer.pack(o))
 
-def packb(object o, default=None, encoding='utf-8', unicode_errors='strict', use_single_float=False):
+def packb(object o, default=None, encoding='utf-8', str unicode_errors='strict', bint use_single_float=False):
+    """
+    pack o and return packed bytes
+
+    See :class:`Packer` for options.
     """
-    pack o and return packed bytes."""
     packer = Packer(default=default, encoding=encoding, unicode_errors=unicode_errors,
                     use_single_float=use_single_float)
     return packer.pack(o)

msgpack/fallback.py

@@ -423,6 +423,30 @@ def read_map_header(self, write_bytes=None):
 
 
 class Packer(object):
+    """
+    MessagePack Packer
+
+    usage:
+
+        packer = Packer()
+        astream.write(packer.pack(a))
+        astream.write(packer.pack(b))
+
+    Packer's constructor has some keyword arguments:
+
+    :param callable default:
+        Convert user type to builtin type that Packer supports.
+        See also simplejson's document.
+    :param str encoding:
+            Convert unicode to bytes with this encoding. (default: 'utf-8')
+    :param str unicode_erros:
+        Error handler for encoding unicode. (default: 'strict')
+    :param bool use_single_float:
+        Use single precision float type for float. (default: False)
+    :param bool autoreset:
+        Reset buffer after each pack and return it's content as `bytes`. (default: True).
+        If set this to false, use `bytes()` to get content and `.reset()` to clear buffer.
+    """
     def __init__(self, default=None, encoding='utf-8', unicode_errors='strict',
                  use_single_float=False, autoreset=True):
         self._use_float = use_single_float