Permalink
Browse files

docs: better unpacker docstring.

  • Loading branch information...
1 parent 3ce005c commit 8e13598a36cbf56992454a04e1c4e92e4cfb15b8 @methane methane committed Feb 26, 2013
Showing with 46 additions and 24 deletions.
  1. +3 −0 Makefile
  2. +3 −0 docs/Makefile
  3. +40 −24 msgpack/_unpacker.pyx
View
3 Makefile
@@ -6,6 +6,9 @@ all: cython
doc-serve: all
cd docs && make serve
+doc:
+ cd docs && make zip
+
cython:
cython msgpack/*.pyx
View
3 docs/Makefile
@@ -154,3 +154,6 @@ doctest:
serve: html
cd _build/html && python3.3 -m http.server
+
+zip: html
+ cd _build/html && zip -r ../../../msgpack-doc.zip .
View
64 msgpack/_unpacker.pyx
@@ -81,9 +81,12 @@ def unpackb(object packed, object object_hook=None, object list_hook=None,
bint use_list=1, encoding=None, unicode_errors="strict",
object_pairs_hook=None,
):
- """Unpack packed_bytes to object. Returns an unpacked object.
+ """
+ Unpack packed_bytes to object. Returns an unpacked object.
Raises `ValueError` when `packed` contains extra bytes.
+
+ See :class:`Unpacker` for options.
"""
cdef template_context ctx
cdef size_t off = 0
@@ -121,9 +124,12 @@ def unpack(object stream, object object_hook=None, object list_hook=None,
bint use_list=1, encoding=None, unicode_errors="strict",
object_pairs_hook=None,
):
- """Unpack an object from `stream`.
+ """
+ Unpack an object from `stream`.
Raises `ValueError` when `stream` has extra bytes.
+
+ See :class:`Unpacker` for options.
"""
return unpackb(stream.read(), use_list=use_list,
object_hook=object_hook, object_pairs_hook=object_pairs_hook, list_hook=list_hook,
@@ -135,48 +141,58 @@ cdef class Unpacker(object):
"""
Streaming unpacker.
- `file_like` is a file-like object having `.read(n)` method.
- When `Unpacker` initialized with `file_like`, unpacker reads serialized data
- from it and `.feed()` method is not usable.
+ arguments:
+
+ :param file_like:
+ File-like object having `.read(n)` method.
+ If specified, unpacker reads serialized data from it and :meth:`feed()` is not usable.
- `read_size` is used as `file_like.read(read_size)`.
- (default: min(1024**2, max_buffer_size))
+ :param int read_size:
+ Used as `file_like.read(read_size)`. (default: `min(1024**2, max_buffer_size)`)
- If `use_list` is true (default), msgpack list is deserialized to Python list.
- Otherwise, it is deserialized to Python tuple.
+ :param bool use_list:
+ If true, unpack msgpack array to Python list.
+ Otherwise, unpack to Python tuple. (default: True)
- `object_hook` is same to simplejson. If it is not None, it should be callable
- and Unpacker calls it with a dict argument after deserializing a map.
+ :param callable object_hook:
+ When specified, it should be callable.
+ Unpacker calls it with a dict argument after unpacking msgpack map.
+ (See also simplejson)
- `object_pairs_hook` is same to simplejson. If it is not None, it should be callable
- and Unpacker calls it with a list of key-value pairs after deserializing a map.
+ :param callable object_pairs_hook:
+ When specified, it should be callable.
+ Unpacker calls it with a list of key-value pairs after unpacking msgpack map.
+ (See also simplejson)
- `encoding` is encoding used for decoding msgpack bytes. If it is None (default),
- msgpack bytes is deserialized to Python bytes.
+ :param str encoding:
+ Encoding used for decoding msgpack raw.
+ If it is None (default), msgpack raw is deserialized to Python bytes.
- `unicode_errors` is used for decoding bytes.
+ :param str unicode_errors:
+ Used for decoding msgpack raw with *encoding*.
+ (default: `'strict'`)
- `max_buffer_size` limits size of data waiting unpacked.
- 0 means system's INT_MAX (default).
- Raises `BufferFull` exception when it is insufficient.
- You shoud set this parameter when unpacking data from untrasted source.
+ :param int max_buffer_size:
+ Limits size of data waiting unpacked. 0 means system's INT_MAX (default).
+ Raises `BufferFull` exception when it is insufficient.
+ You shoud set this parameter when unpacking data from untrasted source.
example of streaming deserialize from file-like object::
unpacker = Unpacker(file_like)
for o in unpacker:
- do_something(o)
+ process(o)
example of streaming deserialize from socket::
unpacker = Unpacker()
- while 1:
+ while True:
buf = sock.recv(1024**2)
if not buf:
break
unpacker.feed(buf)
for o in unpacker:
- do_something(o)
+ process(o)
"""
cdef template_context ctx
cdef char* buf
@@ -197,7 +213,7 @@ cdef class Unpacker(object):
def __init__(self, file_like=None, Py_ssize_t read_size=0, bint use_list=1,
object object_hook=None, object object_pairs_hook=None, object list_hook=None,
- encoding=None, unicode_errors='strict', int max_buffer_size=0,
+ str encoding=None, str unicode_errors='strict', int max_buffer_size=0,
):
cdef char *cenc=NULL, *cerr=NULL

0 comments on commit 8e13598

Please sign in to comment.