Rework of compiled format class hierarchy.

Author: eerimoq

bitstruct.py

@@ -6,7 +6,7 @@
 import binascii
 
 
-__version__ = "5.2.1"
+__version__ = "6.0.0"
 
 
 class Error(Exception):
@@ -246,27 +246,15 @@ def _unpack_bytearray(size, bits):
     return binascii.unhexlify(hex(int('10000000' + bits, 2))[4:].rstrip('L'))
 
 
-class CompiledFormat(object):
-    """A compiled format string that can be used to pack and/or unpack
-    data multiple times.
-
-    Instances of this class are created by the factory function
-    :func:`~bitstruct.compile()`.
-
-    """
+class _CompiledFormat(object):
 
     def __init__(self, fmt, names=None):
         infos, byte_order = _parse_format(fmt, names)
         self._infos = infos
         self._byte_order = byte_order
         self._number_of_bits_to_unpack = sum([info.size for info in infos])
-        self._number_of_arguments = 0
-
-        for info in infos:
-            if not isinstance(info, _Padding):
-                self._number_of_arguments += 1
 
-    def _pack_value(self, info, value, bits):
+    def pack_value(self, info, value, bits):
         value_bits = info.pack(value)
 
         # Reverse the bit order in little endian values.
@@ -288,14 +276,14 @@ def _pack_value(self, info, value, bits):
 
         return bits
 
-    def _pack(self, values):
+    def pack_any(self, values):
         bits = ''
 
         for info in self._infos:
             if isinstance(info, _Padding):
                 bits += info.pack()
             else:
-                bits = self._pack_value(info, values[info.name], bits)
+                bits = self.pack_value(info, values[info.name], bits)
 
         # Padding of last byte.
         tail = len(bits) % 8
@@ -305,7 +293,7 @@ def _pack(self, values):
 
         return bytes(_unpack_bytearray(len(bits), bits))
 
-    def _unpack_from(self, data, offset):
+    def unpack_from_any(self, data, offset):
         bits = bin(int(b'01' + binascii.hexlify(bytearray(data)), 16))[3 + offset:]
 
         # Sanity check.
@@ -345,7 +333,7 @@ def _unpack_from(self, data, offset):
 
             offset += info.size
 
-    def _pack_into(self, buf, offset, data, **kwargs):
+    def pack_into_any(self, buf, offset, data, **kwargs):
         fill_padding = kwargs.get('fill_padding', True)
         buf_bits = _pack_bytearray(8 * len(buf), buf)
         bits = buf_bits[0:offset]
@@ -358,7 +346,7 @@ def _pack_into(self, buf, offset, data, **kwargs):
                 else:
                     bits += buf_bits[len(bits):len(bits) + info.size]
             else:
-                bits = self._pack_value(info, data[info.name], bits)
+                bits = self.pack_value(info, data[info.name], bits)
                 i += 1
 
         bits += buf_bits[len(bits):]
@@ -370,8 +358,33 @@ def _pack_into(self, buf, offset, data, **kwargs):
 
         buf[:] = _unpack_bytearray(len(bits), bits)
 
+    def calcsize(self):
+        """Return the number of bits in the compiled format string.
+
+        """
+
+        return self._number_of_bits_to_unpack
+
+
+class CompiledFormat(_CompiledFormat):
+    """A compiled format string that can be used to pack and/or unpack
+    data multiple times.
+
+    Instances of this class are created by the factory function
+    :func:`~bitstruct.compile()`.
+
+    """
+
+    def __init__(self, fmt):
+        super(CompiledFormat, self).__init__(fmt, None)
+        self._number_of_arguments = 0
+
+        for info in self._infos:
+            if not isinstance(info, _Padding):
+                self._number_of_arguments += 1
+
     def pack(self, *args):
-        """See :func:`pack()`.
+        """See :func:`~bitstruct.pack()`.
 
         """
 
@@ -382,17 +395,17 @@ def pack(self, *args):
                     self._number_of_arguments,
                     len(args)))
 
-        return self._pack(args)
+        return self.pack_any(args)
 
     def unpack(self, data):
-        """See :func:`unpack()`.
+        """See :func:`~bitstruct.unpack()`.
 
         """
 
         return self.unpack_from(data)
 
     def pack_into(self, buf, offset, *args, **kwargs):
-        """See :func:`pack_into()`.
+        """See :func:`~bitstruct.pack_into()`.
 
         """
 
@@ -403,55 +416,54 @@ def pack_into(self, buf, offset, *args, **kwargs):
                     self._number_of_arguments,
                     len(args)))
 
-        self._pack_into(buf, offset, args, **kwargs)
+        self.pack_into_any(buf, offset, args, **kwargs)
 
     def unpack_from(self, data, offset=0):
-        """See :func:`unpack_from()`.
+        """See :func:`~bitstruct.unpack_from()`.
 
         """
 
-        return tuple([v[1] for v in self._unpack_from(data, offset)])
+        return tuple([v[1] for v in self.unpack_from_any(data, offset)])
+
+
+class CompiledFormatDict(_CompiledFormat):
+    """See :class:`~bitstruct.CompiledFormat`.
+
+    """
 
-    def pack_dict(self, data):
-        """See :func:`pack_dict()`.
+    def pack(self, data):
+        """See :func:`~bitstruct.pack_dict()`.
 
         """
 
         try:
-            return self._pack(data)
+            return self.pack_any(data)
         except KeyError as e:
             raise Error('{} not found in data dictionary'.format(str(e)))
 
-    def unpack_dict(self, data):
-        """See :func:`unpack_dict()`.
+    def unpack(self, data):
+        """See :func:`~bitstruct.unpack_dict()`.
 
         """
 
-        return self.unpack_from_dict(data)
+        return self.unpack_from(data)
 
-    def pack_into_dict(self, buf, offset, data, **kwargs):
-        """See :func:`pack_into_dict()`.
+    def pack_into(self, buf, offset, data, **kwargs):
+        """See :func:`~bitstruct.pack_into_dict()`.
 
         """
 
         try:
-            self._pack_into(buf, offset, data, **kwargs)
+            self.pack_into_any(buf, offset, data, **kwargs)
         except KeyError as e:
             raise Error('{} not found in data dictionary'.format(str(e)))
 
-    def unpack_from_dict(self, data, offset=0):
-        """See :func:`unpack_from_dict()`.
-
-        """
-
-        return {info.name: v for info, v in self._unpack_from(data, offset)}
-
-    def calcsize(self):
-        """Return the number of bits in the compiled format string.
+    def unpack_from(self, data, offset=0):
+        """See :func:`~bitstruct.unpack_from_dict()`.
 
         """
 
-        return self._number_of_bits_to_unpack
+        return {info.name: v for info, v in self.unpack_from_any(data, offset)}
 
 
 def pack(fmt, *args):
@@ -542,7 +554,8 @@ def unpack_from(fmt, data, offset=0):
 
 
 def pack_dict(fmt, names, data):
-    """Same as :func:`pack()`, but data is read from a dictionary.
+    """Same as :func:`~bitstruct.pack()`, but data is read from a
+    dictionary.
 
     The names list `names` contains the format group names, used as
     keys in the dictionary.
@@ -552,43 +565,45 @@ def pack_dict(fmt, names, data):
 
     """
 
-    return CompiledFormat(fmt, names).pack_dict(data)
+    return CompiledFormatDict(fmt, names).pack(data)
 
 
 def unpack_dict(fmt, names, data):
-    """Same as :func:`unpack()`, but returns a dictionary.
+    """Same as :func:`~bitstruct.unpack()`, but returns a dictionary.
 
-    See :func:`pack_dict()` for details on `names`.
+    See :func:`~bitstruct.pack_dict()` for details on `names`.
 
     >>> unpack_dict('u4u4', ['foo', 'bar'], b'\\x12')
     {'foo': 1, 'bar': 2}
 
     """
 
-    return CompiledFormat(fmt, names).unpack_dict(data)
+    return CompiledFormatDict(fmt, names).unpack(data)
 
 
 def pack_into_dict(fmt, names, buf, offset, data, **kwargs):
-    """Same as :func:`pack_into()`, but data is read from a dictionary.
+    """Same as :func:`~bitstruct.pack_into()`, but data is read from a
+    dictionary.
 
-    See :func:`pack_dict()` for details on `names`.
+    See :func:`~bitstruct.pack_dict()` for details on `names`.
 
     """
 
-    return CompiledFormat(fmt, names).pack_into_dict(buf,
-                                                     offset,
-                                                     data,
-                                                     **kwargs)
+    return CompiledFormatDict(fmt, names).pack_into(buf,
+                                                    offset,
+                                                    data,
+                                                    **kwargs)
 
 
 def unpack_from_dict(fmt, names, data, offset=0):
-    """Same as :func:`unpack_from_dict()`, but returns a dictionary.
+    """Same as :func:`~bitstruct.unpack_from_dict()`, but returns a
+    dictionary.
 
-    See :func:`pack_dict()` for details on `names`.
+    See :func:`~bitstruct.pack_dict()` for details on `names`.
 
     """
 
-    return CompiledFormat(fmt, names).unpack_from_dict(data, offset)
+    return CompiledFormatDict(fmt, names).unpack_from(data, offset)
 
 
 def calcsize(fmt):
@@ -623,12 +638,18 @@ def byteswap(fmt, data, offset=0):
 
 
 def compile(fmt, names=None):
-    """Compile given format string `fmt` and return a
-    :class:`~bitstruct.CompiledFormat` object that can be used to pack
-    and/or unpack data multiple times.
+    """Compile given format string `fmt` and return a compiled format
+    object that can be used to pack and/or unpack data multiple times.
+
+    Returns a :class:`~bitstruct.CompiledFormat` object if `names` is
+    ``None``, and otherwise a :class:`~bitstruct.CompiledFormatDict`
+    object.
 
-    See :func:`pack_dict()` for details on `names`.
+    See :func:`~bitstruct.pack_dict()` for details on `names`.
 
     """
 
-    return CompiledFormat(fmt, names)
+    if names is None:
+        return CompiledFormat(fmt)
+    else:
+        return CompiledFormatDict(fmt, names)

docs/index.rst

@@ -31,11 +31,14 @@ Classes
 
 .. autoclass:: bitstruct.CompiledFormat
 
-   .. automethod:: pack
-   .. automethod:: unpack
-   .. automethod:: pack_into
-   .. automethod:: unpack_from
-   .. automethod:: pack_dict
-   .. automethod:: unpack_dict
-   .. automethod:: pack_into_dict
-   .. automethod:: unpack_from_dict
+   .. automethod:: bitstruct.CompiledFormat.pack
+   .. automethod:: bitstruct.CompiledFormat.unpack
+   .. automethod:: bitstruct.CompiledFormat.pack_into
+   .. automethod:: bitstruct.CompiledFormat.unpack_from
+
+.. autoclass:: bitstruct.CompiledFormatDict
+
+   .. automethod:: bitstruct.CompiledFormatDict.pack
+   .. automethod:: bitstruct.CompiledFormatDict.unpack
+   .. automethod:: bitstruct.CompiledFormatDict.pack_into
+   .. automethod:: bitstruct.CompiledFormatDict.unpack_from

tests/test_bitstruct.py

@@ -727,7 +727,7 @@ def test_compile_pack_unpack_formats(self):
                 packed_2 = pack(fmt, *decoded)
             else:
                 cf = bitstruct.compile(fmt, names)
-                packed_1 = cf.pack_dict(decoded)
+                packed_1 = cf.pack(decoded)
                 packed_2 = pack_dict(fmt, names, decoded)
 
             self.assertEqual(packed_1, b'\xe0')