reformatting and clean up

vsergeev · vsergeev · commit 605ef849e0ab · 2013-09-29T23:21:17.000-07:00
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # u-msgpack-python v1.0
 
-u-msgpack-python is a lightweight [msgpack](https://github.com/msgpack/msgpack) serializer and deserializer module that is compatible with Python 2 and Python 3. u-msgpack-python is fully compliant with the latest msgpack specification, as of 09/29/2013. In particular, it supports the new binary, UTF-8 string, and application ext types.
+u-msgpack-python is a lightweight [msgpack](https://github.com/msgpack/msgpack) serializer and deserializer module that is compatible with Python 2 and Python 3. u-msgpack-python is fully compliant with the latest [msgpack specification](https://github.com/msgpack/msgpack/blob/master/spec.md), as of 09/29/2013. In particular, it supports the new binary, UTF-8 string, and application ext types.
 
 u-msgpack-python is written in pure Python and is currently distributed as a single file: [umsgpack.py](umsgpack.py)
 
@@ -42,6 +42,7 @@ An example of encoding and decoding an application ext type:
 >>> umsgpack.packb({u"special stuff": foo, u"awesome": True})
 b'\x82\xadspecial stuff\xc7\x03\x05\x01\x02\x03\xa7awesome\xc3'
 >>> bar = umsgpack.unpackb(_)
+
 >>> print(bar["special stuff"])
 Ext Object
    Type: 05
@@ -95,17 +96,17 @@ If a non-byte-string argument is passed to `umsgpack.unpackb()`, it will raise a
     >>> 
     ```
 
-* `InsufficientdataException`: Insufficient data to unpack encoded object.
+* `InsufficientDataException`: Insufficient data to unpack encoded object.
 
     ```
     >>> # Attempt to unpack a cut-off encoded 32-bit unsigned int
-    ... umsgpack.unpackb("\xce\xff\xff\xff")
+    ... umsgpack.unpackb(b"\xce\xff\xff\xff")
     ...
     umsgpack.InsufficientDataException
     >>> 
 
     >>> # Attempt to unpack an array of length 2 missing the second item
-    ... umsgpack.unpackb("\x92\xc2")
+    ... umsgpack.unpackb(b"\x92\xc2")
     ...
     umsgpack.InsufficientDataException
     >>> 
@@ -117,7 +118,7 @@ If a non-byte-string argument is passed to `umsgpack.unpackb()`, it will raise a
 
     ```
     >>> # Attempt to unpack the string "\x80\x81"
-    ... umsgpack.unpackb("\xa2\x80\x81")
+    ... umsgpack.unpackb(b"\xa2\x80\x81")
     ...
     umsgpack.InvalidStringException: unpacked string is not utf-8
     >>> 
@@ -127,7 +128,7 @@ If a non-byte-string argument is passed to `umsgpack.unpackb()`, it will raise a
 
     ```
     >>> # Attempt to unpack reserved code 0xc1
-    ... umsgpack.unpackb("\xc1")
+    ... umsgpack.unpackb(b"\xc1")
     ...
     umsgpack.ReservedCodeException: reserved code encountered: 0xc1
     >>> 
@@ -139,7 +140,7 @@ If a non-byte-string argument is passed to `umsgpack.unpackb()`, it will raise a
 
     ```
     >>> # Attempt to unpack { {} : False }
-    ... umsgpack.unpackb("\x82\x80\xc2")
+    ... umsgpack.unpackb(b"\x82\x80\xc2")
     ...
     umsgpack.KeyNotPrimitiveException: encountered non-primitive key type: <type 'dict'>
     >>> 
@@ -151,23 +152,23 @@ If a non-byte-string argument is passed to `umsgpack.unpackb()`, it will raise a
 
     ```
     >>> # Attempt to unpack { 1: True, 1: False }
-    ... umsgpack.unpackb("\x82\x01\xc3\x01\xc2")
+    ... umsgpack.unpackb(b"\x82\x01\xc3\x01\xc2")
     ...
     umsgpack.KeyDuplicateException: encountered duplicate key: 1, <type 'int'>
     >>> 
     ```
 
-## Notes
+## Behavior Notes
 
 * Python 2
-  * `unicode` type objects are packed into, and unpacked from, the msgpack string format
-  * `str` type objects are packed into, and unpacked from, the msgpack bytes format
+  * `unicode` type objects are packed into, and unpacked from, the msgpack `string` format
+  * `str` type objects are packed into, and unpacked from, the msgpack `binary` format
 * Python 3
-  * `str` type objects are packed into, and unpacked from, the msgpack string format
-  * `bytes` type objects are packed into, and unpacked from, the msgpack bytes format
+  * `str` type objects are packed into, and unpacked from, the msgpack `string` format
+  * `bytes` type objects are packed into, and unpacked from, the msgpack `binary` format
 * The msgpack string format is strictly decoded with UTF-8. An exception is thrown if the string bytes cannot be decoded into a valid UTF-8 string.
-* msgpack arrays are unpacked into Python lists, not tuples
-* Python floats are packed into the msgpack float32 or float64 format depending on the system's sys.float\_info
+* The msgpack array format is unpacked into a Python list, not tuple
+* Python float types are packed into the msgpack float32 or float64 format depending on the system's `sys.float_info`
 
 ## Testing
 
diff --git a/test_umsgpack.py b/test_umsgpack.py
@@ -3,7 +3,7 @@
 # or
 #   $ py.test2      # Python 2
 #
-# (Default Python version may depend on your system.)
+# (Actual Python version invoked may depend on your system.)
 
 import umsgpack
 import struct
@@ -213,3 +213,4 @@ def test_unpack_exceptions():
     for (name, data, exception) in unpack_exception_test_vectors:
         print("\tTesting %s" % name)
         with pytest.raises(exception): umsgpack.unpackb(data)
+
diff --git a/umsgpack.py b/umsgpack.py
@@ -1,8 +1,9 @@
 # u-msgpack-python v1.0 - vsergeev at gmail
 #
 # u-msgpack-python is a Python 2 and Python 3 compatible serializer and
-# deserializer for msgpack written in pure Python. It fully supports the latest
-# msgpack spec, as of 09/29/2013.
+# deserializer for msgpack written in pure Python. It supports the latest
+# msgpack spec, as of 09/29/2013, namely the utf-8 string, binary, and ext
+# types.
 #
 
 import struct
@@ -16,12 +17,15 @@ class Ext:
     def __init__(self, ext_type, data):
         self.type = ext_type
         self.data = data
+
     def __eq__(self, other):
         return (isinstance(other, self.__class__) and
                 self.type == other.type and
                 self.data == other.data)
+
     def __ne__(self, other):
         return not self.__eq__(other)
+
     def __str__(self):
         s = "Ext Object\n"
         s += "   Type: %02x\n" % self.type
@@ -59,6 +63,11 @@ class KeyDuplicateException(UnpackException): pass
 
 ################################################################################
 
+# You may notice struct.pack("B", x) instead of the simpler chr(x) in the code
+# below. This is to allow for seamless Python 2 and 3 compatibility, as chr(x)
+# has a str return type instead of bytes in Python 3, and struct.pack(...) has
+# the right return type in both versions.
+
 def pack_integer(x):
     if x < 0:
         if x >= -32:
@@ -174,8 +183,6 @@ def pack_map(x):
 
     return s
 
-########################################
-
 # Pack for Python 2, with 'unicode' type, 'str' type, and 'long' type
 def packb2(x):
     if x is None:
@@ -346,12 +353,15 @@ def unpack_map(code, read_fn):
 
     d = {}
     for i in range(length):
+        # Unpack key
         k = _unpackb(read_fn)
 
         if not isinstance(k, collections.Hashable):
             raise KeyNotPrimitiveException("encountered non-primitive key type: %s" % str(type(k)))
         elif k in d:
             raise KeyDuplicateException("encountered duplicate key: %s, %s" % (str(k), str(type(k))))
+
+        # Unpack value
         v = _unpackb(read_fn)
 
         d[k] = v
@@ -373,8 +383,6 @@ def _unpackb(read_fn):
     code = read_fn(1)
     return unpack_dispatch_table[code](code, read_fn)
 
-# Wrapper unpack function that builds a read stream function from s
-
 # For Python 2, expects a str object
 def unpackb2(s):
     if not isinstance(s, str):
@@ -397,7 +405,6 @@ def __init():
     global unpackb
     global unpack_dispatch_table
 
-
     # Auto-detect system float precision
     if sys.float_info.mant_dig == 53:
         float_size = 64
