bitarray 3.6.1__tar.gz → 3.7.1__tar.gz

{bitarray-3.6.1 → bitarray-3.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bitarray
-Version: 3.6.1
+Version: 3.7.1
 Summary: efficient arrays of booleans -- C extension
 Home-page: https://github.com/ilanschnell/bitarray
 Author: Ilan Schnell
@@ -59,7 +59,7 @@ Key features
 * Immutable ``frozenbitarray`` objects which are hashable
 * Sequential search
 * Type hinting
-* Extensive test suite with over 500 unittests
+* Extensive test suite with about 600 unittests
 * Utility module ``bitarray.util``:
 
   * conversion to and from hexadecimal strings
@@ -89,7 +89,7 @@ Once you have installed the package, you may want to test it:
 
     $ python -c 'import bitarray; bitarray.test()'
     bitarray is installed in: /Users/ilan/bitarray/bitarray
-    bitarray version: 3.6.1
+    bitarray version: 3.7.1
     sys.version: 3.13.5 (main, Jun 16 2025) [Clang 18.1.8]
     sys.prefix: /Users/ilan/miniforge
     pointer size: 64 bit
@@ -98,12 +98,13 @@ Once you have installed the package, you may want to test it:
     HAVE_BUILTIN_BSWAP64: 1
     default bit-endianness: big
     machine byte-order: little
+    Py_DEBUG: 0
     DEBUG: 0
     .........................................................................
     .........................................................................
     ................................................................
     ----------------------------------------------------------------------
-    Ran 591 tests in 0.163s
+    Ran 597 tests in 0.165s
 
     OK
 
@@ -255,85 +256,15 @@ shift (``>>``) always shifts towards higher indices.
 Bit-endianness
 --------------
 
-Unless explicitly converting to machine representation, i.e. initializing
-the buffer directly, using ``.tobytes()``, ``.frombytes()``, ``.tofile()``
-or ``.fromfile()``, as well as using ``memoryview()``, the bit-endianness
-will have no effect on any computation, and one can skip this section.
-
-Since bitarrays allows addressing individual bits, where the machine
-represents 8 bits in one byte, there are two obvious choices for this
-mapping: little-endian and big-endian.
-
-When dealing with the machine representation of bitarray objects, it is
-recommended to always explicitly specify the endianness.
-
-By default, bitarrays use big-endian representation:
-
-.. code-block:: python
-
-    >>> a = bitarray(b'A')
-    >>> a.endian
-    'big'
-    >>> a
-    bitarray('01000001')
-    >>> a[6] = 1
-    >>> a.tobytes()
-    b'C'
-
-Big-endian means that the most-significant bit comes first.
-Here, ``a[0]`` is the lowest address (index) and most significant bit,
-and ``a[7]`` is the highest address and least significant bit.
-
-When creating a new bitarray object, the endianness can always be
-specified explicitly:
-
-.. code-block:: python
-
-    >>> a = bitarray(b'A', endian='little')
-    >>> a
-    bitarray('10000010')
-    >>> a.endian
-    'little'
-
-Here, the low-bit comes first because little-endian means that increasing
-numeric significance corresponds to an increasing address.
-So ``a[0]`` is the lowest address and least significant bit,
-and ``a[7]`` is the highest address and most significant bit.
-
-The bit-endianness is a property of the bitarray object.
-The endianness cannot be changed once a bitarray object has been created.
-When comparing bitarray objects, the endianness (and hence the machine
-representation) is irrelevant; what matters is the mapping from indices
-to bits:
-
-.. code-block:: python
-
-    >>> bitarray('11001', endian='big') == bitarray('11001', endian='little')
-    True
-    >>> a = bitarray(b'\x01', endian='little')
-    >>> b = bitarray(b'\x80', endian='big')
-    >>> a == b
-    True
-    >>> a.tobytes() == b.tobytes()
-    False
-
-Bitwise operations (``|``, ``^``, ``&=``, ``|=``, ``^=``, ``~``) are
-implemented efficiently using the corresponding byte operations in C, i.e. the
-operators act on the machine representation of the bitarray objects.
-Therefore, it is not possible to perform bitwise operators on bitarrays
-with different endianness.
-
-As mentioned above, the endianness can not be changed once an object is
-created.  However, you can create a new bitarray with different endianness:
-
-.. code-block:: python
-
-    >>> a = bitarray('111000', endian='little')
-    >>> b = bitarray(a, endian='big')
-    >>> b
-    bitarray('111000')
-    >>> a == b
-    True
+For many purposes the bit-endianness is not of any relevance to the end user
+and can be regarded as an implementation detail of bitarray objects.
+However, there are use cases when the bit-endianness becomes important.
+These use cases involve explicitly reading and writing the bitarray buffer
+using ``.tobytes()``, ``.frombytes()``, ``.tofile()`` or ``.fromfile()``,
+importing and exporting buffers.  Also, a number of utility functions
+in ``bitarray.util`` will return different results depending on
+bit-endianness, such as ``ba2hex()`` or ``ba2int``.
+To better understand this topic, please read `bit-endianness <https://github.com/ilanschnell/bitarray/blob/master/doc/endianness.rst>`__.
 
 
 Buffer protocol
@@ -420,7 +351,7 @@ and can therefore be used as a dictionary key:
 Reference
 =========
 
-bitarray version: 3.6.1 -- `change log <https://github.com/ilanschnell/bitarray/blob/master/doc/changelog.rst>`__
+bitarray version: 3.7.1 -- `change log <https://github.com/ilanschnell/bitarray/blob/master/doc/changelog.rst>`__
 
 In the following, ``item`` and ``value`` are usually a single bit -
 an integer 0 or 1.
@@ -459,34 +390,36 @@ bitarray methods:
 -----------------
 
 ``all()`` -> bool
-   Return True when all bits in bitarray are True.
-   Note that ``a.all()`` is faster than ``all(a)``.
+   Return ``True`` when all bits in bitarray are 1.
+   ``a.all()`` is a faster version of ``all(a)``.
 
 
 ``any()`` -> bool
-   Return True when any bit in bitarray is True.
-   Note that ``a.any()`` is faster than ``any(a)``.
+   Return ``True`` when any bit in bitarray is 1.
+   ``a.any()`` is a faster version of ``any(a)``.
 
 
 ``append(item, /)``
    Append ``item`` to the end of the bitarray.
 
 
-``buffer_info()`` -> tuple
-   Return a tuple containing:
+``buffer_info()`` -> BufferInfo
+   Return named tuple with following fields:
+
+   0. ``address``: memory address of buffer
+   1. ``nbytes``: buffer size (in bytes)
+   2. ``endian``: bit-endianness as a string
+   3. ``padbits``: number of pad bits
+   4. ``alloc``: allocated memory for buffer (in bytes)
+   5. ``readonly``: memory is read-only (bool)
+   6. ``imported``: buffer is imported (bool)
+   7. ``exports``: number of buffer exports
 
-   0. memory address of buffer
-   1. buffer size (in bytes)
-   2. bit-endianness as a Unicode string
-   3. number of pad bits
-   4. allocated memory for the buffer (in bytes)
-   5. memory is read-only
-   6. buffer is imported
-   7. number of buffer exports
+   New in version 3.7: return named tuple
 
 
 ``bytereverse(start=0, stop=<end of buffer>, /)``
-   For each byte in byte-range(start, stop) reverse bits in-place.
+   For each byte in byte-range(``start``, ``stop``) reverse bits in-place.
    The start and stop indices are given in terms of bytes (not bits).
    Also note that this method only changes the buffer; it does not change the
    bit-endianness of the bitarray object.  Pad bits are left unchanged such
@@ -496,13 +429,13 @@ bitarray methods:
 
 
 ``clear()``
-   Remove all items from the bitarray.
+   Remove all items from bitarray.
 
    New in version 1.4
 
 
 ``copy()`` -> bitarray
-   Return a copy of the bitarray.
+   Return copy of bitarray (with same bit-endianness).
 
 
 ``count(value=1, start=0, stop=<end>, step=1, /)`` -> int
@@ -538,7 +471,7 @@ bitarray methods:
 
 ``extend(iterable, /)``
    Append items from to the end of the bitarray.
-   If ``iterable`` is a Unicode string, each ``0`` and ``1`` are appended as
+   If ``iterable`` is a (Unicode) string, each ``0`` and ``1`` are appended as
    bits (ignoring whitespace and underscore).
 
    New in version 3.4: allow ``bytes`` object
@@ -578,7 +511,7 @@ bitarray methods:
 ``index(sub_bitarray, start=0, stop=<end>, /, right=False)`` -> int
    Return lowest (or rightmost when ``right=True``) index where sub_bitarray
    is found, such that sub_bitarray is contained within ``[start:stop]``.
-   Raises ``ValueError`` when the sub_bitarray is not present.
+   Raises ``ValueError`` when sub_bitarray is not present.
 
    New in version 2.9: add optional keyword argument ``right``
 
@@ -589,7 +522,7 @@ bitarray methods:
 
 ``invert(index=<all bits>, /)``
    Invert all bits in bitarray (in-place).
-   When the optional ``index`` is given, only invert the single bit at index.
+   When the optional ``index`` is given, only invert the single bit at ``index``.
 
    New in version 1.5.3: optional index argument
 
@@ -644,7 +577,7 @@ bitarray methods:
 
 
 ``to01(group=0, sep=' ')`` -> str
-   Return bitarray as Unicode string of '0's and '1's.
+   Return bitarray as (Unicode) string of ``0``s and ``1``s.
    The bits are grouped into ``group`` bits (default is no grouping).
    When grouped, the string ``sep`` is inserted between groups
    of ``group`` characters, default is a space.
@@ -653,11 +586,11 @@ bitarray methods:
 
 
 ``tobytes()`` -> bytes
-   Return the bitarray buffer in bytes (pad bits are set to zero).
+   Return the bitarray buffer (pad bits are set to zero).
 
 
 ``tofile(f, /)``
-   Write byte representation of bitarray to file object f.
+   Write bitarray buffer to file object ``f``.
 
 
 ``tolist()`` -> list
@@ -731,7 +664,7 @@ Functions defined in the `bitarray` module:
 
 
 ``test(verbosity=1)`` -> TextTestResult
-   Run self-test, and return unittest.runner.TextTestResult object.
+   Run self-test, and return ``unittest.runner.TextTestResult`` object.
 
 
 Functions defined in `bitarray.util` module:
@@ -789,7 +722,7 @@ This sub-module was added in version 1.2.
    New in version 3.3: ignore whitespace
 
 
-``byteswap(a, /, n=<buffer size>)``
+``byteswap(a, n=<buffer size>, /)``
    Reverse every ``n`` consecutive bytes of ``a`` in-place.
    By default, all bytes are reversed.  Note that ``n`` is not limited to 2, 4
    or 8, but can be any positive integer.
@@ -865,6 +798,19 @@ This sub-module was added in version 1.2.
    New in version 2.5.0: allow bytes-like argument
 
 
+``gen_primes(n, /, endian=None, odd=False)`` -> bitarray
+   Generate a bitarray of length ``n`` in which active indices are prime numbers.
+   By default (``odd=False``), active indices correspond to prime numbers directly.
+   When ``odd=True``, only odd prime numbers are represented in the resulting
+   bitarray ``a``, and ``a[i]`` corresponds to ``2*i+1`` being prime or not.
+
+   Apart from working with prime numbers, this function is useful for
+   testing, as it provides a simple way to create a well-defined bitarray
+   of any length.
+
+   New in version 3.7
+
+
 ``hex2ba(hexstr, /, endian=None)`` -> bitarray
    Bitarray of hexadecimal representation.  hexstr may contain any number
    (including odd numbers) of hex digits (upper or lower case).
@@ -912,11 +858,9 @@ This sub-module was added in version 1.2.
 
 
 ``pprint(bitarray, /, stream=None, group=8, indent=4, width=80)``
-   Prints the formatted representation of object on ``stream`` (which defaults
-   to ``sys.stdout``).  By default, elements are grouped in bytes (8 elements),
-   and 8 bytes (64 elements) per line.
-   Non-bitarray objects are printed by the standard library
-   function ``pprint.pprint()``.
+   Pretty-print bitarray object to ``stream``, defaults is ``sys.stdout``.
+   By default, bits are grouped in bytes (8 bits), and 64 bits per line.
+   Non-bitarray objects are printed using ``pprint.pprint()``.
 
    New in version 1.8
 
@@ -951,7 +895,7 @@ This sub-module was added in version 1.2.
    New in version 3.5
 
 
-``sc_decode(stream)`` -> bitarray
+``sc_decode(stream, /)`` -> bitarray
    Decompress binary stream (an integer iterator, or bytes-like object) of a
    sparse compressed (``sc``) bitarray, and return the decoded  bitarray.
    This function consumes only one bitarray and leaves the remaining stream
@@ -994,12 +938,15 @@ This sub-module was added in version 1.2.
    iteration is stopped as soon as one mismatch is found.
 
 
-``sum_indices(a, /)`` -> int
+``sum_indices(a, /, mode=1)`` -> int
    Return sum of indices of all active bits in bitarray ``a``.
    Equivalent to ``sum(i for i, v in enumerate(a) if v)``.
+   ``mode=2`` sums square of indices.
 
    New in version 3.6
 
+   New in version 3.7: add optional mode argument
+
 
 ``urandom(n, /, endian=None)`` -> bitarray
    Return random bitarray of length ``n`` (uses ``os.urandom()``).

{bitarray-3.6.1 → bitarray-3.7.1}/README.rst

@@ -27,7 +27,7 @@ Key features
 * Immutable ``frozenbitarray`` objects which are hashable
 * Sequential search
 * Type hinting
-* Extensive test suite with over 500 unittests
+* Extensive test suite with about 600 unittests
 * Utility module ``bitarray.util``:
 
   * conversion to and from hexadecimal strings
@@ -57,7 +57,7 @@ Once you have installed the package, you may want to test it:
 
     $ python -c 'import bitarray; bitarray.test()'
     bitarray is installed in: /Users/ilan/bitarray/bitarray
-    bitarray version: 3.6.1
+    bitarray version: 3.7.1
     sys.version: 3.13.5 (main, Jun 16 2025) [Clang 18.1.8]
     sys.prefix: /Users/ilan/miniforge
     pointer size: 64 bit
@@ -66,12 +66,13 @@ Once you have installed the package, you may want to test it:
     HAVE_BUILTIN_BSWAP64: 1
     default bit-endianness: big
     machine byte-order: little
+    Py_DEBUG: 0
     DEBUG: 0
     .........................................................................
     .........................................................................
     ................................................................
     ----------------------------------------------------------------------
-    Ran 591 tests in 0.163s
+    Ran 597 tests in 0.165s
 
     OK
 
@@ -223,85 +224,15 @@ shift (``>>``) always shifts towards higher indices.
 Bit-endianness
 --------------
 
-Unless explicitly converting to machine representation, i.e. initializing
-the buffer directly, using ``.tobytes()``, ``.frombytes()``, ``.tofile()``
-or ``.fromfile()``, as well as using ``memoryview()``, the bit-endianness
-will have no effect on any computation, and one can skip this section.
-
-Since bitarrays allows addressing individual bits, where the machine
-represents 8 bits in one byte, there are two obvious choices for this
-mapping: little-endian and big-endian.
-
-When dealing with the machine representation of bitarray objects, it is
-recommended to always explicitly specify the endianness.
-
-By default, bitarrays use big-endian representation:
-
-.. code-block:: python
-
-    >>> a = bitarray(b'A')
-    >>> a.endian
-    'big'
-    >>> a
-    bitarray('01000001')
-    >>> a[6] = 1
-    >>> a.tobytes()
-    b'C'
-
-Big-endian means that the most-significant bit comes first.
-Here, ``a[0]`` is the lowest address (index) and most significant bit,
-and ``a[7]`` is the highest address and least significant bit.
-
-When creating a new bitarray object, the endianness can always be
-specified explicitly:
-
-.. code-block:: python
-
-    >>> a = bitarray(b'A', endian='little')
-    >>> a
-    bitarray('10000010')
-    >>> a.endian
-    'little'
-
-Here, the low-bit comes first because little-endian means that increasing
-numeric significance corresponds to an increasing address.
-So ``a[0]`` is the lowest address and least significant bit,
-and ``a[7]`` is the highest address and most significant bit.
-
-The bit-endianness is a property of the bitarray object.
-The endianness cannot be changed once a bitarray object has been created.
-When comparing bitarray objects, the endianness (and hence the machine
-representation) is irrelevant; what matters is the mapping from indices
-to bits:
-
-.. code-block:: python
-
-    >>> bitarray('11001', endian='big') == bitarray('11001', endian='little')
-    True
-    >>> a = bitarray(b'\x01', endian='little')
-    >>> b = bitarray(b'\x80', endian='big')
-    >>> a == b
-    True
-    >>> a.tobytes() == b.tobytes()
-    False
-
-Bitwise operations (``|``, ``^``, ``&=``, ``|=``, ``^=``, ``~``) are
-implemented efficiently using the corresponding byte operations in C, i.e. the
-operators act on the machine representation of the bitarray objects.
-Therefore, it is not possible to perform bitwise operators on bitarrays
-with different endianness.
-
-As mentioned above, the endianness can not be changed once an object is
-created.  However, you can create a new bitarray with different endianness:
-
-.. code-block:: python
-
-    >>> a = bitarray('111000', endian='little')
-    >>> b = bitarray(a, endian='big')
-    >>> b
-    bitarray('111000')
-    >>> a == b
-    True
+For many purposes the bit-endianness is not of any relevance to the end user
+and can be regarded as an implementation detail of bitarray objects.
+However, there are use cases when the bit-endianness becomes important.
+These use cases involve explicitly reading and writing the bitarray buffer
+using ``.tobytes()``, ``.frombytes()``, ``.tofile()`` or ``.fromfile()``,
+importing and exporting buffers.  Also, a number of utility functions
+in ``bitarray.util`` will return different results depending on
+bit-endianness, such as ``ba2hex()`` or ``ba2int``.
+To better understand this topic, please read `bit-endianness <https://github.com/ilanschnell/bitarray/blob/master/doc/endianness.rst>`__.
 
 
 Buffer protocol
@@ -388,7 +319,7 @@ and can therefore be used as a dictionary key:
 Reference
 =========
 
-bitarray version: 3.6.1 -- `change log <https://github.com/ilanschnell/bitarray/blob/master/doc/changelog.rst>`__
+bitarray version: 3.7.1 -- `change log <https://github.com/ilanschnell/bitarray/blob/master/doc/changelog.rst>`__
 
 In the following, ``item`` and ``value`` are usually a single bit -
 an integer 0 or 1.
@@ -427,34 +358,36 @@ bitarray methods:
 -----------------
 
 ``all()`` -> bool
-   Return True when all bits in bitarray are True.
-   Note that ``a.all()`` is faster than ``all(a)``.
+   Return ``True`` when all bits in bitarray are 1.
+   ``a.all()`` is a faster version of ``all(a)``.
 
 
 ``any()`` -> bool
-   Return True when any bit in bitarray is True.
-   Note that ``a.any()`` is faster than ``any(a)``.
+   Return ``True`` when any bit in bitarray is 1.
+   ``a.any()`` is a faster version of ``any(a)``.
 
 
 ``append(item, /)``
    Append ``item`` to the end of the bitarray.
 
 
-``buffer_info()`` -> tuple
-   Return a tuple containing:
+``buffer_info()`` -> BufferInfo
+   Return named tuple with following fields:
+
+   0. ``address``: memory address of buffer
+   1. ``nbytes``: buffer size (in bytes)
+   2. ``endian``: bit-endianness as a string
+   3. ``padbits``: number of pad bits
+   4. ``alloc``: allocated memory for buffer (in bytes)
+   5. ``readonly``: memory is read-only (bool)
+   6. ``imported``: buffer is imported (bool)
+   7. ``exports``: number of buffer exports
 
-   0. memory address of buffer
-   1. buffer size (in bytes)
-   2. bit-endianness as a Unicode string
-   3. number of pad bits
-   4. allocated memory for the buffer (in bytes)
-   5. memory is read-only
-   6. buffer is imported
-   7. number of buffer exports
+   New in version 3.7: return named tuple
 
 
 ``bytereverse(start=0, stop=<end of buffer>, /)``
-   For each byte in byte-range(start, stop) reverse bits in-place.
+   For each byte in byte-range(``start``, ``stop``) reverse bits in-place.
    The start and stop indices are given in terms of bytes (not bits).
    Also note that this method only changes the buffer; it does not change the
    bit-endianness of the bitarray object.  Pad bits are left unchanged such
@@ -464,13 +397,13 @@ bitarray methods:
 
 
 ``clear()``
-   Remove all items from the bitarray.
+   Remove all items from bitarray.
 
    New in version 1.4
 
 
 ``copy()`` -> bitarray
-   Return a copy of the bitarray.
+   Return copy of bitarray (with same bit-endianness).
 
 
 ``count(value=1, start=0, stop=<end>, step=1, /)`` -> int
@@ -506,7 +439,7 @@ bitarray methods:
 
 ``extend(iterable, /)``
    Append items from to the end of the bitarray.
-   If ``iterable`` is a Unicode string, each ``0`` and ``1`` are appended as
+   If ``iterable`` is a (Unicode) string, each ``0`` and ``1`` are appended as
    bits (ignoring whitespace and underscore).
 
    New in version 3.4: allow ``bytes`` object
@@ -546,7 +479,7 @@ bitarray methods:
 ``index(sub_bitarray, start=0, stop=<end>, /, right=False)`` -> int
    Return lowest (or rightmost when ``right=True``) index where sub_bitarray
    is found, such that sub_bitarray is contained within ``[start:stop]``.
-   Raises ``ValueError`` when the sub_bitarray is not present.
+   Raises ``ValueError`` when sub_bitarray is not present.
 
    New in version 2.9: add optional keyword argument ``right``
 
@@ -557,7 +490,7 @@ bitarray methods:
 
 ``invert(index=<all bits>, /)``
    Invert all bits in bitarray (in-place).
-   When the optional ``index`` is given, only invert the single bit at index.
+   When the optional ``index`` is given, only invert the single bit at ``index``.
 
    New in version 1.5.3: optional index argument
 
@@ -612,7 +545,7 @@ bitarray methods:
 
 
 ``to01(group=0, sep=' ')`` -> str
-   Return bitarray as Unicode string of '0's and '1's.
+   Return bitarray as (Unicode) string of ``0``s and ``1``s.
    The bits are grouped into ``group`` bits (default is no grouping).
    When grouped, the string ``sep`` is inserted between groups
    of ``group`` characters, default is a space.
@@ -621,11 +554,11 @@ bitarray methods:
 
 
 ``tobytes()`` -> bytes
-   Return the bitarray buffer in bytes (pad bits are set to zero).
+   Return the bitarray buffer (pad bits are set to zero).
 
 
 ``tofile(f, /)``
-   Write byte representation of bitarray to file object f.
+   Write bitarray buffer to file object ``f``.
 
 
 ``tolist()`` -> list
@@ -699,7 +632,7 @@ Functions defined in the `bitarray` module:
 
 
 ``test(verbosity=1)`` -> TextTestResult
-   Run self-test, and return unittest.runner.TextTestResult object.
+   Run self-test, and return ``unittest.runner.TextTestResult`` object.
 
 
 Functions defined in `bitarray.util` module:
@@ -757,7 +690,7 @@ This sub-module was added in version 1.2.
    New in version 3.3: ignore whitespace
 
 
-``byteswap(a, /, n=<buffer size>)``
+``byteswap(a, n=<buffer size>, /)``
    Reverse every ``n`` consecutive bytes of ``a`` in-place.
    By default, all bytes are reversed.  Note that ``n`` is not limited to 2, 4
    or 8, but can be any positive integer.
@@ -833,6 +766,19 @@ This sub-module was added in version 1.2.
    New in version 2.5.0: allow bytes-like argument
 
 
+``gen_primes(n, /, endian=None, odd=False)`` -> bitarray
+   Generate a bitarray of length ``n`` in which active indices are prime numbers.
+   By default (``odd=False``), active indices correspond to prime numbers directly.
+   When ``odd=True``, only odd prime numbers are represented in the resulting
+   bitarray ``a``, and ``a[i]`` corresponds to ``2*i+1`` being prime or not.
+
+   Apart from working with prime numbers, this function is useful for
+   testing, as it provides a simple way to create a well-defined bitarray
+   of any length.
+
+   New in version 3.7
+
+
 ``hex2ba(hexstr, /, endian=None)`` -> bitarray
    Bitarray of hexadecimal representation.  hexstr may contain any number
    (including odd numbers) of hex digits (upper or lower case).
@@ -880,11 +826,9 @@ This sub-module was added in version 1.2.
 
 
 ``pprint(bitarray, /, stream=None, group=8, indent=4, width=80)``
-   Prints the formatted representation of object on ``stream`` (which defaults
-   to ``sys.stdout``).  By default, elements are grouped in bytes (8 elements),
-   and 8 bytes (64 elements) per line.
-   Non-bitarray objects are printed by the standard library
-   function ``pprint.pprint()``.
+   Pretty-print bitarray object to ``stream``, defaults is ``sys.stdout``.
+   By default, bits are grouped in bytes (8 bits), and 64 bits per line.
+   Non-bitarray objects are printed using ``pprint.pprint()``.
 
    New in version 1.8
 
@@ -919,7 +863,7 @@ This sub-module was added in version 1.2.
    New in version 3.5
 
 
-``sc_decode(stream)`` -> bitarray
+``sc_decode(stream, /)`` -> bitarray
    Decompress binary stream (an integer iterator, or bytes-like object) of a
    sparse compressed (``sc``) bitarray, and return the decoded  bitarray.
    This function consumes only one bitarray and leaves the remaining stream
@@ -962,12 +906,15 @@ This sub-module was added in version 1.2.
    iteration is stopped as soon as one mismatch is found.
 
 
-``sum_indices(a, /)`` -> int
+``sum_indices(a, /, mode=1)`` -> int
    Return sum of indices of all active bits in bitarray ``a``.
    Equivalent to ``sum(i for i, v in enumerate(a) if v)``.
+   ``mode=2`` sums square of indices.
 
    New in version 3.6
 
+   New in version 3.7: add optional mode argument
+
 
 ``urandom(n, /, endian=None)`` -> bitarray
    Return random bitarray of length ``n`` (uses ``os.urandom()``).