Comments and README.

README.rst

@@ -1,4 +1,5 @@
 |buildstatus|_
+|coverage|_
 
 About
 =====
@@ -7,6 +8,8 @@ This module is intended to have a similar interface as the python
 struct module, but working on bits instead of primitive data types
 (char, int, ...).
 
+Project homepage: https://github.com/eerimoq/bitstruct
+
 Documentation: http://bitstruct.readthedocs.org/en/latest
 
 
@@ -21,9 +24,8 @@ Installation
 Example usage
 =============
 
-See the test suite: https://github.com/eerimoq/bitstruct/blob/master/tests/test_bitstruct.py
-
-A basic example of packing/unpacking four integers:
+A basic example of `packing`_ and `unpacking`_ four integers using the
+format string ``'u1u3u4s16'``:
 
 .. code-block:: python
 
@@ -35,7 +37,19 @@ A basic example of packing/unpacking four integers:
     >>> calcsize('u1u3u4s16')
     24
 
-The unpacked fields can be named by assigning them to variables or by
+An example `compiling`_ the format string once, and use it to `pack`_
+and `unpack`_ data:
+
+.. code-block:: python
+
+    >>> import bitstruct
+    >>> cf = bitstruct.compile('u1u3u4s16')
+    >>> cf.pack(1, 2, 3, -4)
+    b'\xa3\xff\xfc'
+    >>> cf.unpack(b'\xa3\xff\xfc')
+    (1, 2, 3, -4)
+
+The unpacked values can be named by assigning them to variables or by
 wrapping the result in a named tuple:
 
 .. code-block:: python
@@ -50,8 +64,8 @@ wrapping the result in a named tuple:
     >>> myname.c
     3
 
-An example of packing/unpacking a unsinged integer, a signed integer,
-a float, a boolean, a byte string and a string:
+An example of `packing`_ and `unpacking`_ an unsinged integer, a
+signed integer, a float, a boolean, a byte string and a string:
 
 .. code-block:: python
 
@@ -63,9 +77,9 @@ a float, a boolean, a byte string and a string:
     >>> calcsize('u5s5f32b1r13t40')
     96
 
-The same format and values as in the previous example, but using LSB
-(Least Significant Bit) first instead of the default MSB (Most
-Significant Bit) first:
+The same format string and values as in the previous example, but
+using LSB (Least Significant Bit) first instead of the default MSB
+(Most Significant Bit) first:
 
 .. code-block:: python
 
@@ -77,7 +91,7 @@ Significant Bit) first:
     >>> calcsize('<u5s5f32b1r13t40')
     96
 
-An example of unpacking values from a hexstring and a binary file:
+An example of `unpacking`_ values from a hexstring and a binary file:
 
 .. code-block:: python
 
@@ -87,11 +101,11 @@ An example of unpacking values from a hexstring and a binary file:
     (582, -3751, b'\xe2j\xf3')
     >>> with open("test.bin", "rb") as fin:
     ...     unpack('s17s13r24', fin.read(8))
-    ...     
-    ... 
+    ...
+    ...
     (582, -3751, b'\xe2j\xf3')
 
-Change endianness of the data with byteswap(), and then unpack the
+Change endianness of the data with `byteswap`_, and then unpack the
 values:
 
 .. code-block:: python
@@ -103,3 +117,18 @@ values:
 
 .. |buildstatus| image:: https://travis-ci.org/eerimoq/bitstruct.svg
 .. _buildstatus: https://travis-ci.org/eerimoq/bitstruct
+
+.. |coverage| image:: https://coveralls.io/repos/github/eerimoq/bitstruct/badge.svg?branch=master
+.. _coverage: https://coveralls.io/github/eerimoq/bitstruct
+
+.. _packing: http://bitstruct.readthedocs.io/en/latest/#bitstruct.pack
+
+.. _unpacking: http://bitstruct.readthedocs.io/en/latest/#bitstruct.unpack
+
+.. _pack: http://bitstruct.readthedocs.io/en/latest/#bitstruct.CompiledFormat.pack
+
+.. _unpack: http://bitstruct.readthedocs.io/en/latest/#bitstruct.CompiledFormat.unpack
+
+.. _byteswap: http://bitstruct.readthedocs.io/en/latest/#bitstruct.byteswap
+
+.. _compiling: http://bitstruct.readthedocs.io/en/latest/#bitstruct.compile

bitstruct.py

@@ -117,8 +117,8 @@ def _unpack_text(size, bits):
 
 
 class CompiledFormat(object):
-    """A compiled format that can be used to pack and/or unpack data
-    multiple.
+    """A compiled format string that can be used to pack and/or unpack
+    data multiple.
 
     Instances of this class are created by the factory function
     :func:`~bitstruct.compile()`.
@@ -141,9 +141,9 @@ def __init__(self, fmt):
 
     def pack(self, *args):
         """Return a byte string containing the values v1, v2, ... packed
-        according to the compiled format. If the total number of bits
-        are not a multiple of 8, padding will be added at the end of
-        the last byte.
+        according to the compiled format string. If the total number
+        of bits are not a multiple of 8, padding will be added at the
+        end of the last byte.
 
         :param args: Variable argument list of values to pack.
         :returns: A byte string of the packed values.
@@ -207,8 +207,8 @@ def pack(self, *args):
 
     def unpack(self, data):
         """Unpack `data` (byte string, bytearray or list of integers)
-        according to the compiled format. The result is a tuple even
-        if it contains exactly one item.
+        according to the compiled format string. The result is a tuple
+        even if it contains exactly one item.
 
         :param data: Byte string of values to unpack.
         :returns: A tuple of the unpacked values.
@@ -271,7 +271,7 @@ def unpack(self, data):
         return tuple(res)
 
     def calcsize(self):
-        """Calculate the number of bits in the compiled format.
+        """Calculate the number of bits in the compiled format string.
 
         :returns: Number of bits in the format string.
 
@@ -282,9 +282,9 @@ def calcsize(self):
 
 def pack(fmt, *args):
     """Return a byte string containing the values v1, v2, ... packed
-    according to the given format. If the total number of bits are not
-    a multiple of 8, padding will be added at the end of the last
-    byte.
+    according to given format string `fmt`. If the total number of
+    bits are not a multiple of 8, padding will be added at the end of
+    the last byte.
 
     :param fmt: Bitstruct format string. See format description below.
     :param args: Variable argument list of values to pack.
@@ -334,8 +334,8 @@ def pack(fmt, *args):
 
 def unpack(fmt, data):
     """Unpack `data` (byte string, bytearray or list of integers)
-    according to the given format. The result is a tuple even if it
-    contains exactly one item.
+    according to given format string `fmt`. The result is a tuple even
+    if it contains exactly one item.
 
     :param fmt: Bitstruct format string. See :func:`~bitstruct.pack()`
                 for details.
@@ -348,7 +348,7 @@ def unpack(fmt, data):
 
 
 def calcsize(fmt):
-    """Calculate the number of bits in given format.
+    """Calculate the number of bits in given format string `fmt`.
 
     :param fmt: Bitstruct format string. See :func:`~bitstruct.pack()`
                 for details.
@@ -386,7 +386,7 @@ def byteswap(fmt, data, offset = 0):
 
 
 def compile(fmt):
-    """Compile given format string and return a
+    """Compile given format string `fmt` and return a
     :class:`~bitstruct.CompiledFormat` object that can be used to pack
     and unpack data multiple times.