From c8c7f741c553bceb0d15a66cbede73a2a4db1f37 Mon Sep 17 00:00:00 2001 From: Scott Griffiths Date: Sun, 5 May 2024 19:43:41 +0100 Subject: [PATCH] Updating release notes for 4.2.2. Adding some decorative line breaks in the documentation. --- doc/array.rst | 3 +++ doc/bitarray.rst | 5 ++++- doc/bits.rst | 3 +++ doc/constbitstream.rst | 5 +++++ doc/dtypes.rst | 2 ++ doc/functions.rst | 3 +++ doc/interpretation.rst | 1 + doc/introduction.rst | 16 ++++++++++++---- release_notes.txt | 11 ++++++++++- 9 files changed, 43 insertions(+), 6 deletions(-) diff --git a/doc/array.rst b/doc/array.rst index 9fe60181..0e879fbc 100644 --- a/doc/array.rst +++ b/doc/array.rst @@ -133,6 +133,7 @@ Array * The ``'b'`` and ``'B'`` type codes need to be preceded by an endianness character even though it makes no difference which one you use as they are only 1 byte long. +---- Methods ------- @@ -328,6 +329,7 @@ Methods Each packed element of the Array is converted to an ordinary Python object such as a ``float`` or an ``int`` depending on the Array's format, and returned in a Python list. +---- Special Methods --------------- @@ -496,6 +498,7 @@ Python language operators ``del[start:end:step]`` +---- Properties ---------- diff --git a/doc/bitarray.rst b/doc/bitarray.rst index fbb0b0e6..cf86b069 100644 --- a/doc/bitarray.rst +++ b/doc/bitarray.rst @@ -10,6 +10,8 @@ BitArray A :class:`BitArray` is a mutable :class:`Bits`, and so the one thing all of the methods listed here have in common is that they can modify the contents of the bitstring. +---- + Methods ------- @@ -181,6 +183,7 @@ Methods >>> s.bin '1010101010101010' +---- Properties ---------- @@ -214,7 +217,7 @@ When used as a setter without a new length the value must fit into the current Other types also have restrictions on their lengths, and using an invalid length will raise a :exc:`CreationError`. For example trying to create a 20 bit floating point number or a two bit bool will raise this exception. - +---- Special Methods --------------- diff --git a/doc/bits.rst b/doc/bits.rst index 1606c23d..d48a8df1 100644 --- a/doc/bits.rst +++ b/doc/bits.rst @@ -37,6 +37,7 @@ The ``Bits`` class is the simplest type in the bitstring module, and represents In the methods below we use ``BitsType`` to indicate that any of the types that can auto initialise can be used. +---- Methods ------- @@ -308,6 +309,7 @@ Methods s = bitstring.pack('uint10, hex, int13, 0b11', 130, '3d', -23) a, b, c, d = s.unpack('uint10, hex, int13, bin2') +---- Properties ---------- @@ -460,6 +462,7 @@ Note that the ``bin``, ``oct``, ``hex``, ``int``, ``uint`` and ``float`` propert Property for the byte-wise native-endian unsigned base-2 integer representation of the bitstring. +---- Special Methods --------------- diff --git a/doc/constbitstream.rst b/doc/constbitstream.rst index fec4ffdf..4e141906 100644 --- a/doc/constbitstream.rst +++ b/doc/constbitstream.rst @@ -9,6 +9,8 @@ ConstBitStream A :class:`ConstBitStream` is a :class:`Bits` with added methods and properties that allow it to be parsed as a stream of bits. +---- + Reading and parsing --------------------- @@ -62,6 +64,7 @@ In addition to the read methods there are matching peek methods. These are ident s.find('0x47') +---- Methods ------- @@ -164,6 +167,8 @@ Methods >>> s.readto('0x47', bytealigned=True) ConstBitStream('0x04050647') +---- + Properties ---------- diff --git a/doc/dtypes.rst b/doc/dtypes.rst index 3319dc93..789d3f50 100644 --- a/doc/dtypes.rst +++ b/doc/dtypes.rst @@ -23,6 +23,7 @@ It can however be advantageous to to create `Dtype` objects directly for efficie If you need to use the `scale` parameter then there is no way to specify this in the format token string, so you must directly use a `Dtype` object. +---- Methods ------- @@ -45,6 +46,7 @@ Parse a bitstring to find its value. The *b* parameter should be a bitstring of >>> d.parse('0b0001010101') # Equivalent to: Bits('0b0001010101').u10 85 +---- Properties ---------- diff --git a/doc/functions.rst b/doc/functions.rst index f52ade24..94b0a764 100644 --- a/doc/functions.rst +++ b/doc/functions.rst @@ -86,6 +86,7 @@ Finally it is also possible just to use a keyword as a token:: s = bitstring.pack('hello, world', world='0x123', hello='0b110') +---- Options ------- @@ -227,6 +228,7 @@ See https://no-color.org for more information. The terminal colours can also be turned off by setting ``bitstring.options.no_color`` to ``True``. +---- Command Line Usage ------------------ @@ -247,6 +249,7 @@ The bitstring module can be called from the command line to perform simple opera Command-line parameters are concatenated and a bitstring created from them. If the final parameter is either an interpretation string or ends with a ``.`` followed by an interpretation string then that interpretation of the bitstring will be used when printing it. If no interpretation is given then the bitstring is just printed. +---- Exceptions ---------- diff --git a/doc/interpretation.rst b/doc/interpretation.rst index ec19fb72..07d2bb74 100644 --- a/doc/interpretation.rst +++ b/doc/interpretation.rst @@ -16,6 +16,7 @@ For example if you have initialised a bitstring from a 10 GiB file object and as If you're in an interactive session then the pretty-print method :meth:`~Bits.pp` can be useful as it will only convert the bitstring one chunk at a time for display. +---- Properties ---------- diff --git a/doc/introduction.rst b/doc/introduction.rst index 644941ba..184ceec1 100644 --- a/doc/introduction.rst +++ b/doc/introduction.rst @@ -33,11 +33,17 @@ To summarise when to use each class: The :class:`Bits` class is the base class of the other three class. This means that ``isinstance(s, Bits)`` will be true if ``s`` is an instance of any of the four classes. +---- -``Bits(auto, /, length: Optional[int], offset: Optional[int], **kwargs)`` +Constructing bitstrings +----------------------- When initialising a bitstring you need to specify at most one initialiser. -This can either be the first parameter in the constructor ('auto' initialisation, described below), or using a keyword argument for a data type: +This can either be the first parameter in the constructor ('auto' initialisation, described below), or using a keyword argument for a data type. + +``Bits(auto, /, length: Optional[int], offset: Optional[int], **kwargs)`` + +Some of the keyword arguments that can be used are: * ``bytes`` : A ``bytes`` object, for example read from a binary file. * ``hex``, ``oct``, ``bin``: Hexadecimal, octal or binary strings. @@ -57,7 +63,7 @@ The data type name can be combined with its length if appropriate, or the length For example:: a = Bits(hex='deadbeef') - b = BitArray(float32=100.25) # or = BitArray(float=100.25, length=32) + b = BitArray(f32=100.25) # or = BitArray(float=100.25, length=32) c = ConstBitStream(filename='a_big_file') d = Bits(u12=105) e = BitArray(bool=True) @@ -67,6 +73,8 @@ Note that some types need a length to be specified, some don't need one, and oth Another way to create a bitstring is via the ``pack`` function, which packs multiple values according to a given format. See the entry on :func:`pack` for more information. +---- + .. _auto_init: The auto initialiser @@ -140,7 +148,7 @@ Integers won't be auto promoted, but instead will raise a ``TypeError``:: It's just a union of types rather than an actual class (though it's documented here as a class as I could find no alternative). It's not user accessible, but is just a shorthand way of saying any of the above types. - +---- Keyword initialisers -------------------- diff --git a/release_notes.txt b/release_notes.txt index c468f83d..64970bd6 100644 --- a/release_notes.txt +++ b/release_notes.txt @@ -2,6 +2,15 @@ bitstring module version history -------------------------------- +----------------------- +May 2024: version 4.2.2 +----------------------- +A couple more minor bug fixes. + +* Sometimes a ValueError was being raised instead of a ReadError. Bug #325. +* Initialising a bitstring from None now raises a TypeError rather than generating + an empty bitstring. Bug #323. + ------------------------- April 2024: version 4.2.1 ------------------------- @@ -44,7 +53,7 @@ Other changes: * New fromstring method as another way to create bitstrings from formatted strings. Instead of relying on the `auto` parameter you can now optionally use `fromstring`. - >>> s1 = BitArray('u24=1000') # This is still fine + >>> s1 = BitArray('u24=1000') # This is still fine. >>> s2 = BitArray.fromstring('u24=1000') # This may be clearer and more efficient. * More types can now be pretty printed. For example integer and float formats can be used.