bitstring 4.2.0b1__tar.gz → 4.2.1__tar.gz

{bitstring-4.2.0b1/bitstring.egg-info → bitstring-4.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: bitstring
-Version: 4.2.0b1
+Version: 4.2.1
 Summary: Simple construction, analysis and modification of binary data.
 Author-email: Scott Griffiths <dr.scottgriffiths@gmail.com>
 Project-URL: homepage, https://github.com/scott-griffiths/bitstring
@@ -37,17 +37,23 @@ It has been actively maintained since 2006.
 [![Codacy Badge](https://img.shields.io/codacy/grade/8869499b2eed44548fa1a5149dd451f4?logo=codacy)](https://app.codacy.com/gh/scott-griffiths/bitstring/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 [![Dependents (via libraries.io)](https://img.shields.io/librariesio/dependents/pypi/bitstring?logo=libraries.io&logoColor=white)](https://libraries.io/pypi/bitstring)
 &nbsp; &nbsp;
-[![Pepy Total Downlods](https://img.shields.io/pepy/dt/bitstring?logo=python&logoColor=white&labelColor=blue&color=blue)](https://pypistats.org/packages/bitstring)
+[![Pepy Total Downlods](https://img.shields.io/pepy/dt/bitstring?logo=python&logoColor=white&labelColor=blue&color=blue)](https://www.pepy.tech/projects/bitstring)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/bitstring?label=%40&labelColor=blue&color=blue)](https://pypistats.org/packages/bitstring)
 
 
 News
 ----
-**29th November 2023**: bitstring 4.1.4 released. Version 4.1 is a large update in terms of how much of the code has changed.
-
-* New Array class for homogeneous data.
-* Support for 8-bit floating point values.
-* Speed increased with bitarray dependency.
+**April 2024**: bitstring 4.2.1 released.
+ 
+New in version 4.2:
+
+* Dropped support for Python 3.7. Minimum version is now 3.8.
+* A new `Dtype` class can be optionally used to specify types.
+* The `bitstring.options` object is now the preferred method for changing module options.
+* New `fromstring` method as another way to create bitstrings from formatted strings.
+* More types can now be pretty printed.
+* A range of 8-bit, 6-bit and even 4-bit floating point formats added (beta):
+* Performance improvements.
 
 See the [release notes](https://github.com/scott-griffiths/bitstring/blob/main/release_notes.txt) for details. Please let me know if you encounter any problems.
 
@@ -73,7 +79,7 @@ Some starting points are given below:
 * [Quick Reference](https://bitstring.readthedocs.io/en/stable/quick_reference.html)
 * [Full Reference](https://bitstring.readthedocs.io/en/stable/reference.html)
 
-You can also try out the interactive walkthrough notebook on [binder](https://mybinder.org/v2/gh/scott-griffiths/bitstring/main?labpath=doc%2Fwalkthrough.ipynb).
+There is also an introductory walkthrough notebook on [binder](https://mybinder.org/v2/gh/scott-griffiths/bitstring/main?labpath=doc%2Fwalkthrough.ipynb).
 
 Release Notes
 -------------
@@ -137,20 +143,5 @@ Examples
      Array('uint7', [45, 100, 15, 1])
 
 
-Unit Tests
-----------
-
-The 700+ unit tests should all pass. They can be run from the root of the project with
-
-     python -m unittest
-
-
-Credits
--------
-
-Created in 2006 to help with ad hoc parsing and creation of compressed video files.
-Maintained and expanded ever since as it became unexpectedly popular.
-Thanks to all those who have contributed ideas and code (and bug reports) over the years.
-
 
-<sub>Copyright (c) 2006 - 2023 Scott Griffiths</sub>
+<sub>Copyright (c) 2006 - 2024 Scott Griffiths</sub>

{bitstring-4.2.0b1 → bitstring-4.2.1}/README.md

@@ -13,17 +13,23 @@ It has been actively maintained since 2006.
 [![Codacy Badge](https://img.shields.io/codacy/grade/8869499b2eed44548fa1a5149dd451f4?logo=codacy)](https://app.codacy.com/gh/scott-griffiths/bitstring/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 [![Dependents (via libraries.io)](https://img.shields.io/librariesio/dependents/pypi/bitstring?logo=libraries.io&logoColor=white)](https://libraries.io/pypi/bitstring)
    
-[![Pepy Total Downlods](https://img.shields.io/pepy/dt/bitstring?logo=python&logoColor=white&labelColor=blue&color=blue)](https://pypistats.org/packages/bitstring)
+[![Pepy Total Downlods](https://img.shields.io/pepy/dt/bitstring?logo=python&logoColor=white&labelColor=blue&color=blue)](https://www.pepy.tech/projects/bitstring)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/bitstring?label=%40&labelColor=blue&color=blue)](https://pypistats.org/packages/bitstring)
 
 
 News
 ----
-**29th November 2023**: bitstring 4.1.4 released. Version 4.1 is a large update in terms of how much of the code has changed.
-
-* New Array class for homogeneous data.
-* Support for 8-bit floating point values.
-* Speed increased with bitarray dependency.
+**April 2024**: bitstring 4.2.1 released.
+ 
+New in version 4.2:
+
+* Dropped support for Python 3.7. Minimum version is now 3.8.
+* A new `Dtype` class can be optionally used to specify types.
+* The `bitstring.options` object is now the preferred method for changing module options.
+* New `fromstring` method as another way to create bitstrings from formatted strings.
+* More types can now be pretty printed.
+* A range of 8-bit, 6-bit and even 4-bit floating point formats added (beta):
+* Performance improvements.
 
 See the [release notes](https://github.com/scott-griffiths/bitstring/blob/main/release_notes.txt) for details. Please let me know if you encounter any problems.
 
@@ -49,7 +55,7 @@ Some starting points are given below:
 * [Quick Reference](https://bitstring.readthedocs.io/en/stable/quick_reference.html)
 * [Full Reference](https://bitstring.readthedocs.io/en/stable/reference.html)
 
-You can also try out the interactive walkthrough notebook on [binder](https://mybinder.org/v2/gh/scott-griffiths/bitstring/main?labpath=doc%2Fwalkthrough.ipynb).
+There is also an introductory walkthrough notebook on [binder](https://mybinder.org/v2/gh/scott-griffiths/bitstring/main?labpath=doc%2Fwalkthrough.ipynb).
 
 Release Notes
 -------------
@@ -113,20 +119,5 @@ Examples
      Array('uint7', [45, 100, 15, 1])
 
 
-Unit Tests
-----------
-
-The 700+ unit tests should all pass. They can be run from the root of the project with
-
-     python -m unittest
-
-
-Credits
--------
-
-Created in 2006 to help with ad hoc parsing and creation of compressed video files.
-Maintained and expanded ever since as it became unexpectedly popular.
-Thanks to all those who have contributed ideas and code (and bug reports) over the years.
-
 
-<sub>Copyright (c) 2006 - 2023 Scott Griffiths</sub>
+<sub>Copyright (c) 2006 - 2024 Scott Griffiths</sub>

{bitstring-4.2.0b1 → bitstring-4.2.1}/bitstring/__init__.py

@@ -10,15 +10,15 @@ BitArray -- A mutable container for binary data.
 ConstBitStream -- An immutable container with streaming methods.
 BitStream -- A mutable container with streaming methods.
 Array -- An efficient list-like container where each item has a fixed-length binary format.
+Dtype -- Encapsulate the data types used in the other classes.
 
 Functions:
 
 pack -- Create a BitStream from a format string.
 
 Data:
-options -- A container for module-wide options:
-    bytealigned -- Determines whether a number of methods default to working only on byte boundaries.
-    lsb0 -- If True, the least significant bit (the final bit) is indexed as bit zero.
+
+options -- Module-wide options.
 
 Exceptions:
 
@@ -55,7 +55,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 """
 
-__version__ = "4.2.0b1"
+__version__ = "4.2.1"
 
 __author__ = "Scott Griffiths"
 
@@ -71,6 +71,12 @@ from .exceptions import Error, ReadError, InterpretError, ByteAlignError, Creati
 from .dtypes import DtypeDefinition, dtype_register, Dtype
 import types
 from typing import List, Tuple, Literal
+from .mxfp import decompress_luts as mxfp_decompress_luts
+from .fp8 import decompress_luts as binary8_decompress_luts
+
+# Decompress the LUTs for the exotic floating point formats
+mxfp_decompress_luts()
+binary8_decompress_luts()
 
 # The Options class returns a singleton.
 options = Options()
@@ -80,6 +86,7 @@ bytealigned = lsb0 = None
 
 
 # An opaque way of adding module level properties. Taken from https://peps.python.org/pep-0549/
+# This is now deprecated. Use the options object directly instead.
 class _MyModuleType(types.ModuleType):
     @property
     def bytealigned(self) -> bool:
@@ -136,13 +143,40 @@ def float_bits2chars(bitlength: Literal[16, 32, 64]):
     else:
         return 24  # Empirical value
 
-def e5m2float_bits2chars(bitlength: Literal[8]):
+def p3binary_bits2chars(bitlength: Literal[8]):
     return 19  # Empirical value
 
-def e4m3float_bits2chars(bitlength: Literal[8]):
+def p4binary_bits2chars(bitlength: Literal[8]):
     # Found by looking at all the possible values
     return 13  # Empirical value
 
+def e4m3mxfp_bits2chars(bitlength: Literal[8]):
+    return 13
+
+def e5m2mxfp_bits2chars(bitlength: Literal[8]):
+    return 19
+
+def e3m2mxfp_bits2chars(bitlength: Literal[6]):
+    # Not sure what the best value is here. It's 7 without considering the scale that could be applied.
+    return 7
+
+def e2m3mxfp_bits2chars(bitlength: Literal[6]):
+    # Not sure what the best value is here.
+    return 7
+
+def e2m1mxfp_bits2chars(bitlength: Literal[4]):
+    # Not sure what the best value is here.
+    return 7
+
+def e8m0mxfp_bits2chars(bitlength: Literal[8]):
+    # Can range same as float32
+    return 23
+
+def mxint_bits2chars(bitlength: Literal[8]):
+    # Not sure what the best value is here.
+    return 10
+
+
 def bfloat_bits2chars(bitlength: Literal[16]):
     # Found by looking at all the possible values
     return 23  # Empirical value
@@ -175,13 +209,9 @@ dtype_definitions = [
                     allowed_lengths=(0, 4, 8, ...), description="a hexadecimal string"),
     DtypeDefinition('bin', Bits._setbin_safe, Bits._getbin, str, False, bin_bits2chars,
                     description="a binary string"),
-    DtypeDefinition('oct',Bits._setoct, Bits._getoct, str, False, oct_bits2chars,
+    DtypeDefinition('oct', Bits._setoct, Bits._getoct, str, False, oct_bits2chars,
                     allowed_lengths=(0, 3, 6, ...), description="an octal string"),
     # Float types
-    DtypeDefinition('e5m2float', Bits._sete5m2float, Bits._gete5m2float, float, True, e5m2float_bits2chars,
-                    allowed_lengths=(8,), description="an 8 bit float with e5m2float format"),
-    DtypeDefinition('e4m3float', Bits._sete4m3float, Bits._gete4m3float, float, True, e4m3float_bits2chars,
-                    allowed_lengths=(8,), description="an 8 bit float with e4m3float format"),
     DtypeDefinition('float', Bits._setfloatbe, Bits._getfloatbe, float, True, float_bits2chars,
                     allowed_lengths=(16, 32, 64), description="a big-endian floating point number"),
     DtypeDefinition('floatle', Bits._setfloatle, Bits._getfloatle, float, True, float_bits2chars,
@@ -209,6 +239,26 @@ dtype_definitions = [
     # Special case pad type
     DtypeDefinition('pad', Bits._setpad, Bits._getpad, None, False, None,
                     description="a skipped section of padding"),
+
+    # MXFP and IEEE 8-bit float types
+    DtypeDefinition('p3binary', Bits._setp3binary, Bits._getp3binary, float, True, p3binary_bits2chars,
+                    allowed_lengths=(8,), description="an 8 bit float with binary8p3 format"),
+    DtypeDefinition('p4binary', Bits._setp4binary, Bits._getp4binary, float, True, p4binary_bits2chars,
+                    allowed_lengths=(8,), description="an 8 bit float with binary8p4 format"),
+    DtypeDefinition('e4m3mxfp', Bits._sete4m3mxfp, Bits._gete4m3mxfp, float, True, e4m3mxfp_bits2chars,
+                    allowed_lengths=(8,), description="an 8 bit float with MXFP E4M3 format"),
+    DtypeDefinition('e5m2mxfp', Bits._sete5m2mxfp, Bits._gete5m2mxfp, float, True, e5m2mxfp_bits2chars,
+                    allowed_lengths=(8,), description="an 8 bit float with MXFP E5M2 format"),
+    DtypeDefinition('e3m2mxfp', Bits._sete3m2mxfp, Bits._gete3m2mxfp, float, True, e3m2mxfp_bits2chars,
+                    allowed_lengths=(6,), description="a 6 bit float with MXFP E3M2 format"),
+    DtypeDefinition('e2m3mxfp', Bits._sete2m3mxfp, Bits._gete2m3mxfp, float, True, e2m3mxfp_bits2chars,
+                    allowed_lengths=(6,), description="a 6 bit float with MXFP E2M3 format"),
+    DtypeDefinition('e2m1mxfp', Bits._sete2m1mxfp, Bits._gete2m1mxfp, float, True, e2m1mxfp_bits2chars,
+                    allowed_lengths=(4,), description="a 4 bit float with MXFP E2M1 format"),
+    DtypeDefinition('e8m0mxfp', Bits._sete8m0mxfp, Bits._gete8m0mxfp, float, False, e8m0mxfp_bits2chars,
+                    allowed_lengths=(8,), description="an 8 bit float with MXFP E8M0 format"),
+    DtypeDefinition('mxint', Bits._setmxint, Bits._getmxint, float, True, mxint_bits2chars,
+                    allowed_lengths=(8,), description="an 8 bit float with MXFP INT8 format"),
 ]
 
 
@@ -252,10 +302,15 @@ for alias in aliases:
 property_docstrings = [f'{name} -- Interpret as {dtype_register[name].description}.' for name in dtype_register.names]
 property_docstring = '\n    '.join(property_docstrings)
 
-Bits.__doc__ = Bits.__doc__.replace('[GENERATED_PROPERTY_DESCRIPTIONS]', property_docstring)
-BitArray.__doc__ = BitArray.__doc__.replace('[GENERATED_PROPERTY_DESCRIPTIONS]', property_docstring)
-ConstBitStream.__doc__ = ConstBitStream.__doc__.replace('[GENERATED_PROPERTY_DESCRIPTIONS]', property_docstring)
-BitStream.__doc__ = BitStream.__doc__.replace('[GENERATED_PROPERTY_DESCRIPTIONS]', property_docstring)
+# We can't be sure the docstrings are present, as it might be compiled without docstrings.
+if Bits.__doc__ is not None:
+    Bits.__doc__ = Bits.__doc__.replace('[GENERATED_PROPERTY_DESCRIPTIONS]', property_docstring)
+if BitArray.__doc__ is not None:
+    BitArray.__doc__ = BitArray.__doc__.replace('[GENERATED_PROPERTY_DESCRIPTIONS]', property_docstring)
+if ConstBitStream.__doc__ is not None:
+    ConstBitStream.__doc__ = ConstBitStream.__doc__.replace('[GENERATED_PROPERTY_DESCRIPTIONS]', property_docstring)
+if BitStream.__doc__ is not None:
+    BitStream.__doc__ = BitStream.__doc__.replace('[GENERATED_PROPERTY_DESCRIPTIONS]', property_docstring)
 
 
 __all__ = ['ConstBitStream', 'BitStream', 'BitArray', 'Array',

{bitstring-4.2.0b1 → bitstring-4.2.1}/bitstring/array_.py

@@ -70,6 +70,11 @@ class Array:
     def __init__(self, dtype: Union[str, Dtype], initializer: Optional[Union[int, Array, array.array, Iterable, Bits, bytes, bytearray, memoryview, BinaryIO]] = None,
                  trailing_bits: Optional[BitsType] = None) -> None:
         self.data = BitArray()
+        if isinstance(dtype, Dtype) and dtype.scale == 'auto':
+            if isinstance(initializer, (int, Bits, bytes, bytearray, memoryview, BinaryIO)):
+                raise TypeError("An Array with an 'auto' scale factor can only be created from an iterable of values.")
+            auto_scale = self._calculate_auto_scale(initializer, dtype.name, dtype.length)
+            dtype = Dtype(dtype.name, dtype.length, scale=auto_scale)
         try:
             self._set_dtype(dtype)
         except ValueError as e:
@@ -87,6 +92,43 @@ class Array:
         if trailing_bits is not None:
             self.data += BitArray._create_from_bitstype(trailing_bits)
 
+    _largest_values = None
+    @staticmethod
+    def _calculate_auto_scale(initializer, name: str, length: Optional[int]) -> float:
+        # Now need to find the largest power of 2 representable with this format.
+        if Array._largest_values is None:
+            Array._largest_values = {
+                'mxint8': Bits('0b01111111').mxint8,  # 1.0 + 63.0/64.0,
+                'e2m1mxfp4': Bits('0b0111').e2m1mxfp4,  # 6.0
+                'e2m3mxfp6': Bits('0b011111').e2m3mxfp6,  # 7.5
+                'e3m2mxfp6': Bits('0b011111').e3m2mxfp6,  # 28.0
+                'e4m3mxfp8': Bits('0b01111110').e4m3mxfp8,  # 448.0
+                'e5m2mxfp8': Bits('0b01111011').e5m2mxfp8,  # 57344.0
+                'p4binary8': Bits('0b01111110').p4binary8,  # 224.0
+                'p3binary8': Bits('0b01111110').p3binary8,  # 49152.0
+                'float16': Bits('0x7bff').float16,  # 65504.0
+                # The bfloat range is so large the scaling algorithm doesn't work well, so I'm disallowing it.
+                # 'bfloat16': Bits('0x7f7f').bfloat16,  # 3.38953139e38,
+            }
+        if f'{name}{length}' in Array._largest_values.keys():
+            float_values = Array('float64', initializer).tolist()
+            max_float_value = max(abs(x) for x in float_values)
+            if max_float_value == 0:
+                # This special case isn't covered in the standard. I'm choosing to return no scale.
+                return 1.0
+            log2 = int(math.log2(max_float_value))
+            lp2 = int(math.log2(Array._largest_values[f'{name}{length}']))
+            lg_scale = log2 - lp2
+            # Saturate at values representable in E8M0 format.
+            if lg_scale > 127:
+                lg_scale = 127
+            elif lg_scale < -127:
+                lg_scale = -127
+            return 2 ** lg_scale
+        else:
+            raise ValueError(f"Can't calculate auto scale for format '{name}{length}'. "
+                             f"This feature is only available for these formats: {list(Array._largest_values.keys())}.")
+
     @property
     def itemsize(self) -> int:
         return self._dtype.length
@@ -96,19 +138,6 @@ class Array:
         trailing_bit_length = len(self.data) % self._dtype.bitlength
         return BitArray() if trailing_bit_length == 0 else self.data[-trailing_bit_length:]
 
-    # Converting array.array typecodes to our equivalents.
-    _array_typecodes: dict[str, str] = {'b': 'int8',
-                                        'B': 'uint8',
-                                        'h': 'intne16',
-                                        'H': 'uintne16',
-                                        'l': 'intne32',
-                                        'L': 'uintne32',
-                                        'q': 'intne64',
-                                        'Q': 'uintne64',
-                                        'e': 'floatne16',
-                                        'f': 'floatne32',
-                                        'd': 'floatne64'}
-
     @property
     def dtype(self) -> Dtype:
         return self._dtype
@@ -120,7 +149,6 @@ class Array:
     def _set_dtype(self, new_dtype: Union[str, Dtype]) -> None:
         if isinstance(new_dtype, Dtype):
             self._dtype = new_dtype
-            self._fmt = str(self._dtype)
         else:
             try:
                 dtype = Dtype(new_dtype)
@@ -133,14 +161,14 @@ class Array:
             if dtype.length is None:
                 raise ValueError(f"A fixed length format is needed for an Array, received '{new_dtype}'.")
             self._dtype = dtype
-            self._fmt = new_dtype
+        if self._dtype.scale == 'auto':
+            raise ValueError("A Dtype with an 'auto' scale factor can only be used when creating a new Array.")
 
     def _create_element(self, value: ElementType) -> Bits:
         """Create Bits from value according to the token_name and token_length"""
-        b = Bits()
-        self._dtype.set_fn(b, value)
+        b = self._dtype.build(value)
         if len(b) != self._dtype.length:
-            raise ValueError(f"The value {value!r} has the wrong length for the format '{self._fmt}'.")
+            raise ValueError(f"The value {value!r} has the wrong length for the format '{self._dtype}'.")
         return b
 
     def __len__(self) -> int:
@@ -161,11 +189,11 @@ class Array:
                 d = BitArray()
                 for s in range(start * self._dtype.length, stop * self._dtype.length, step * self._dtype.length):
                     d.append(self.data[s: s + self._dtype.length])
-                a = Array(self._dtype)
+                a = self.__class__(self._dtype)
                 a.data = d
                 return a
             else:
-                a = Array(self._dtype)
+                a = self.__class__(self._dtype)
                 a.data = self.data[start * self._dtype.length: stop * self._dtype.length]
                 return a
         else:
@@ -234,15 +262,15 @@ class Array:
         trailing_bit_length = len(self.data) % self._dtype.length
         final_str = "" if trailing_bit_length == 0 else ", trailing_bits=" + repr(
             self.data[-trailing_bit_length:])
-        return f"Array('{self._fmt}', {list_str}{final_str})"
+        return f"Array('{self._dtype}', {list_str}{final_str})"
 
     def astype(self, dtype: Union[str, Dtype]) -> Array:
         """Return Array with elements of new dtype, initialised from current Array."""
-        new_array = Array(dtype, self.tolist())
+        new_array = self.__class__(dtype, self.tolist())
         return new_array
 
     def tolist(self) -> List[ElementType]:
-        return [self._dtype.read_fn(self.data, start=start)
+        return  [self._dtype.read_fn(self.data, start=start)
                 for start in range(0, len(self.data) - self._dtype.length + 1, self._dtype.length)]
 
     def append(self, x: ElementType) -> None:
@@ -250,13 +278,13 @@ class Array:
             raise ValueError("Cannot append to Array as its length is not a multiple of the format length.")
         self.data += self._create_element(x)
 
-    def extend(self, iterable: Union[Array, array.array, Iterable]) -> None:
+    def extend(self, iterable: Union[Array, array.array, Iterable[Any]]) -> None:
         if len(self.data) % self._dtype.length != 0:
             raise ValueError(f"Cannot extend Array as its data length ({len(self.data)} bits) is not a multiple of the format length ({self._dtype.length} bits).")
         if isinstance(iterable, Array):
             if self._dtype.name != iterable._dtype.name or self._dtype.length != iterable._dtype.length:
                 raise TypeError(
-                    f"Cannot extend an Array with format '{self._fmt}' from an Array of format '{iterable._fmt}'.")
+                    f"Cannot extend an Array with format '{self._dtype}' from an Array of format '{iterable._dtype}'.")
             # No need to iterate over the elements, we can just append the data
             self.data.append(iterable.data)
         elif isinstance(iterable, array.array):
@@ -264,10 +292,10 @@ class Array:
             name_value = utils.parse_single_struct_token('=' + iterable.typecode)
             if name_value is None:
                 raise ValueError(f"Cannot extend from array with typecode {iterable.typecode}.")
-            other_dtype = dtype_register.get_dtype(*name_value)
+            other_dtype = dtype_register.get_dtype(*name_value, scale=None)
             if self._dtype.name != other_dtype.name or self._dtype.length != other_dtype.length:
                 raise ValueError(
-                    f"Cannot extend an Array with format '{self._fmt}' from an array with typecode '{iterable.typecode}'.")
+                    f"Cannot extend an Array with format '{self._dtype}' from an array with typecode '{iterable.typecode}'.")
             self.data += iterable.tobytes()
         else:
             if isinstance(iterable, str):
@@ -302,7 +330,7 @@ class Array:
         """
         if self._dtype.length % 8 != 0:
             raise ValueError(
-                f"byteswap can only be used for whole-byte elements. The '{self._fmt}' format is {self._dtype.length} bits long.")
+                f"byteswap can only be used for whole-byte elements. The '{self._dtype}' format is {self._dtype.length} bits long.")
         self.data.byteswap(self.itemsize // 8)
 
     def count(self, value: ElementType) -> int:
@@ -368,7 +396,7 @@ class Array:
         stream -- A TextIO object with a write() method. Defaults to sys.stdout.
 
         """
-        colour = Colour(options.colourful_prettyprinting)
+        colour = Colour(not options.no_color)
         sep = ' '
         dtype2 = None
         tidy_fmt = None
@@ -381,7 +409,6 @@ class Array:
             if len(token_list) not in [1, 2]:
                 raise ValueError(f"Only one or two tokens can be used in an Array.pp() format - '{fmt}' has {len(token_list)} tokens.")
             dtype1 = Dtype(*utils.parse_name_length_token(token_list[0]))
-            parameter_str = f"fmt='{fmt}'"
             if len(token_list) == 2:
                 dtype2 = Dtype(*utils.parse_name_length_token(token_list[1]))
 
@@ -405,7 +432,7 @@ class Array:
         data = self.data if trailing_bit_length == 0 else self.data[0: -trailing_bit_length]
         length = len(self.data) // token_length
         len_str = colour.green + str(length) + colour.off
-        stream.write(f"<Array {tidy_fmt}, length={len_str}, itemsize={token_length} bits, total data size={(len(self.data) + 7) // 8} bytes> [\n")
+        stream.write(f"<{self.__class__.__name__} {tidy_fmt}, length={len_str}, itemsize={token_length} bits, total data size={(len(self.data) + 7) // 8} bytes> [\n")
         data._pp(dtype1, dtype2, token_length, width, sep, format_sep, show_offset, stream, False, token_length)
         stream.write("]")
         if trailing_bit_length != 0:
@@ -443,13 +470,13 @@ class Array:
             start += self._dtype.length
 
     def __copy__(self) -> Array:
-        a_copy = Array(self._fmt)
+        a_copy = self.__class__(self._dtype)
         a_copy.data = copy.copy(self.data)
         return a_copy
 
     def _apply_op_to_all_elements(self, op, value: Union[int, float, None], is_comparison: bool = False) -> Array:
         """Apply op with value to each element of the Array and return a new Array"""
-        new_array = Array('bool' if is_comparison else self._dtype)
+        new_array = self.__class__('bool' if is_comparison else self._dtype)
         new_data = BitArray()
         failures = index = 0
         msg = ''
@@ -505,7 +532,7 @@ class Array:
         """Apply op with value to each element of the Array as an unsigned integer in place."""
         value = BitArray._create_from_bitstype(value)
         if len(value) != self._dtype.length:
-            raise ValueError(f"Bitwise op needs a bitstring of length {self._dtype.length} to match format {self._fmt}.")
+            raise ValueError(f"Bitwise op needs a bitstring of length {self._dtype.length} to match format {self._dtype}.")
         for start in range(0, len(self) * self._dtype.length, self._dtype.length):
             self.data[start: start + self._dtype.length] = op(self.data[start: start + self._dtype.length], value)
         return self
@@ -513,14 +540,16 @@ class Array:
     def _apply_op_between_arrays(self, op, other: Array, is_comparison: bool = False) -> Array:
         if len(self) != len(other):
             msg = f"Cannot operate element-wise on Arrays with different lengths ({len(self)} and {len(other)})."
-            if op == operator.add or op == operator.iadd:
-                msg += " Use extend() if you want to concatenate Arrays."
+            if op in [operator.add, operator.iadd]:
+                msg += " Use extend() method to concatenate Arrays."
+            if op in [operator.eq, operator.ne]:
+                msg += " Use equals() method to compare Arrays for a single boolean result."
             raise ValueError(msg)
         if is_comparison:
             new_type = dtype_register.get_dtype('bool', 1)
         else:
             new_type = self._promotetype(self._dtype, other._dtype)
-        new_array = Array(new_type)
+        new_array = self.__class__(new_type)
         new_data = BitArray()
         failures = index = 0
         msg = ''
@@ -553,7 +582,7 @@ class Array:
 
         """
         def is_float(x): return x.return_type is float
-        def is_int(x): return x.return_type is int
+        def is_int(x): return x.return_type is int or x.return_type is bool
         if is_float(type1) + is_int(type1) + is_float(type2) + is_int(type2) != 2:
             raise ValueError(f"Only integer and floating point types can be combined - not '{type1}' and '{type2}'.")
         # If same type choose the widest
@@ -722,15 +751,21 @@ class Array:
             return self._apply_op_between_arrays(operator.le, other, is_comparison=True)
         return self._apply_op_to_all_elements(operator.le, other, is_comparison=True)
 
-    def __eq__(self, other: Union[int, float, str, BitsType, Array]) -> Array:
-        if isinstance(other, Array):
-            return self._apply_op_between_arrays(operator.eq, other, is_comparison=True)
-        return self._apply_op_to_all_elements(operator.eq, other, is_comparison=True)
+    def _eq_ne(self, op, other: Any) -> Array:
+        if isinstance(other, (int, float, str, Bits)):
+            return self._apply_op_to_all_elements(op, other, is_comparison=True)
+        try:
+            other = self.__class__(self.dtype, other)
+        except:
+            return NotImplemented
+        finally:
+            return self._apply_op_between_arrays(op, other, is_comparison=True)
 
-    def __ne__(self, other: Union[int, float, str, BitsType, Array]) -> Array:
-        if isinstance(other, Array):
-            return self._apply_op_between_arrays(operator.ne, other, is_comparison=True)
-        return self._apply_op_to_all_elements(operator.ne, other, is_comparison=True)
+    def __eq__(self, other: Any) -> Array:
+        return self._eq_ne(operator.eq, other)
+
+    def __ne__(self, other: Any) -> Array:
+        return self._eq_ne(operator.ne, other)
 
     # Unary operators
 

{bitstring-4.2.0b1 → bitstring-4.2.1}/bitstring/bitarray_.py

@@ -42,6 +42,7 @@ class BitArray(Bits):
     endswith() -- Return whether the bitstring ends with a sub-string.
     find() -- Find a sub-bitstring in the current bitstring.
     findall() -- Find all occurrences of a sub-bitstring in the current bitstring.
+    fromstring() -- Create a bitstring from a formatted string.
     join() -- Join bitstrings together using current bitstring.
     pp() -- Pretty print the bitstring.
     rfind() -- Seek backwards to find a sub-bitstring.