bitarray 3.6.1__tar.gz → 3.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bitarray
-Version: 3.6.1
+Version: 3.7.0
 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.0
     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 599 tests in 0.166s
 
     OK
 
@@ -420,7 +421,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.0 -- `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 +460,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. 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
+   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
+
+   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 +499,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 +541,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 +581,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 +592,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 +647,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 +656,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 +734,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 +792,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 +868,15 @@ 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.
+
+   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 +924,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 +961,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 +1004,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.0}/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.0
     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 599 tests in 0.166s
 
     OK
 
@@ -388,7 +389,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.0 -- `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 +428,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. 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
+   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
+
+   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 +467,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 +509,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 +549,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 +560,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 +615,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 +624,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 +702,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 +760,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 +836,15 @@ 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.
+
+   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 +892,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 +929,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 +972,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.0}/bitarray/__init__.py

@@ -10,6 +10,7 @@ Please find a description of this package at:
 Author: Ilan Schnell
 """
 from __future__ import absolute_import
+from collections import namedtuple
 
 from bitarray._bitarray import (bitarray, decodetree, _sysinfo,
                                 bits2bytes, _bitarray_reconstructor,
@@ -19,6 +20,9 @@ from bitarray._bitarray import (bitarray, decodetree, _sysinfo,
 
 __all__ = ['bitarray', 'frozenbitarray', 'decodetree', 'bits2bytes']
 
+BufferInfo = namedtuple('BufferInfo',
+                        ['address', 'nbytes', 'endian', 'padbits',
+                         'alloc', 'readonly', 'imported', 'exports'])
 
 class frozenbitarray(bitarray):
     """frozenbitarray(initializer=0, /, endian='big', buffer=None) -> \
@@ -57,7 +61,7 @@ and may therefore be used as a dictionary key.
 def test(verbosity=1):
     """test(verbosity=1) -> TextTestResult
 
-Run self-test, and return unittest.runner.TextTestResult object.
+Run self-test, and return `unittest.runner.TextTestResult` object.
 """
     from bitarray import test_bitarray
     return test_bitarray.run(verbosity=verbosity)

{bitarray-3.6.1 → bitarray-3.7.0}/bitarray/__init__.pyi

@@ -5,7 +5,7 @@
 from collections.abc import Iterable, Iterator, Sequence
 from unittest.runner import TextTestResult
 
-from typing import Any, BinaryIO, Dict, Union, overload
+from typing import Any, BinaryIO, Dict, Union, overload, NamedTuple
 
 
 CodeDict = Dict[Any, bitarray]
@@ -13,6 +13,17 @@ CodeDict = Dict[Any, bitarray]
 BytesLike = Union[bytes, bytearray]
 
 
+class BufferInfo(NamedTuple):
+    address: int
+    nbytes: int
+    endian: str
+    padbits: int
+    alloc: int
+    readonly: bool
+    imported: bool
+    exports: int
+
+
 class decodetree:
     def __init__(self, code: CodeDict) -> None: ...
     def complete(self) -> bool: ...
@@ -29,7 +40,7 @@ class bitarray:
     def all(self) -> bool: ...
     def any(self) -> bool: ...
     def append(self, value: int) -> None: ...
-    def buffer_info(self) -> tuple: ...
+    def buffer_info(self) -> BufferInfo: ...
     def bytereverse(self,
                     start: int = ...,
                     stop: int = ...) -> None: ...
@@ -149,7 +160,7 @@ def bits2bytes(n: int) -> int: ...
 def get_default_endian() -> str: ...
 def test(verbosity: int = ...) -> TextTestResult: ...
 def _set_default_endian(endian: str) -> None: ...
-def _sysinfo() -> tuple: ...
+def _sysinfo(key: str) -> int: ...
 def _bitarray_reconstructor(cls: type,
                             buffer: bytes,
                             endian: str,