bitformat 0.1.0

:warning: 此项目为预alpha版本，API稳定性无法保证。文档有时更倾向于理想化而非准确性。

bitformat 是一个用于创建、操作和解释二进制数据的Python模块。它还支持解析和创建更复杂的二进制格式。

它由广泛使用的bitstring模块的作者所编写。

功能：hammer_and_wrench

• Bits类表示任意长度的二进制数据序列。它提供用于创建、修改和解释数据的方法。
• Format类提供了一种使用简单灵活的语法定义二进制格式的方法。
• 支持多种数据类型，长度没有任意限制。
• 数据始终以连续的位数组形式高效存储。

[!NOTE] 要查看已添加、改进或修复的内容，以及下一版本即将推出的内容，请参阅发布说明。

文档：book

• bitformat 文档 包含了库的完整参考。
• bitformat 之旅 是一个笔记本，快速介绍了库和一些工作示例。

一些示例 :bulb

创建一些位

提供了多种构造函数方法来创建 Bits，包括从二进制、十六进制或八进制字符串、格式化字符串、字节字面量和可迭代对象。

>>> from bitformat import *

>>> a = Bits('0b1010')  # Create from a binary string
>>> b = Bits('u12 = 54')  # Create from a formatted string.
>>> c = Bits.from_bytes(b'\x01\x02\x03')  # Create from a bytes or bytearray object.
>>> d = Bits.pack('f16', -0.75)  # Pack a value into a data type.
>>> e = Bits.join([a, b, c, d])  # The best way to join lots of bits together.

解释这些位

尽管上面的示例来自各种数据类型，但 Bits 实例并不保留任何关于其创建方式的知识 - 它只是位序列。因此，您可以按需解释它们

>>> a.i
-6
>>> b.hex
'036'
>>> c.unpack(['u4', 'f16', 'u4'])
[0, 0.0005035400390625, 3]
>>> d.bytes
b'\xba\x00'

提供了 unpack 方法，作为将位解包为单个或多个数据类型的一般方法。如果您只想解包为单个数据类型，可以使用 Bits 的属性作为快捷方式。

数据类型

支持广泛的数据类型。这些本质上是对如何将二进制数据转换为有用值的描述。《Dtype》类用于定义这些，但通常可以使用字符串表示。

一些示例数据类型字符串包括

• 'u3' - 3 位无符号整数。
• 'i_le32' - 32 位小端有符号整数。
• 'f64' - 64 位 IEEE 浮点数。支持 16、32 和 64 位长度。
• 'bool' - 单位位布尔值。
• 'bytes10' - 10 字节序列。
• 'hex' - 十六进制字符串。
• 'bin' - 二进制字符串。
• '[u8; 40]' - 40 个无符号 8 位整数的数组。

浮点数和整数数据类型的字节序由基本类型后缀 _le、_be 和 _ne 指定。

位操作

提供了一套丰富的操作来查询 Bits 或创建新的 Bits。例如

>>> a + b  # Concatenation
Bits('0xa036')
>>> c.find('0b11')  # Returns found bit position
22
>>> b.replace('0b1', '0xfe')
Bits('0x03fbf9fdfc')
>>> b[0:10] | d[2:12]  # Slicing and logical operators
Bits('0b1110101101')

数组

提供了一个 Array 类，用于存储相同数据类型的 Bits 的连续序列。这与同一名称的标准模块中的 array 类型类似，但它不受仅限于十几种类型的限制。

>>> r = Array('i5', [4, -3, 0, 1, -5, 15])  # An array of 5 bit signed ints
>>> r -= 2  # Operates on each element
>>> r.unpack()
[2, -5, -2, -1, -7, 13]
>>> r.dtype = 'u6'  # You can freely change the data type
>>> r
Array('u6', [5, 47, 55, 60, 45])
>>> r.to_bits()
Bits('0b000101101111110111111100101101')

格式化示例

Format 类可用于为位提供结构，以及以人类可读的格式存储数据。

>>> f = Format('[width: u12, height: u12, flags: [bool; 4]]')
>>> f.pack([320, 240, [True, False, True, False]])
Bits('0x1400f0a')
>>> print(f)
[
    width: u12 = 320,
    height: u12 = 240,
    flags: [bool; 4] = (True, False, True, False)
]
>>> f['height'].value /= 2
>>> f.to_bits()
Bits('0x140078a')
>>> f.to_bits() == 'u12=320, u12=120, 0b1010'
True

Format 及其字段可以可选地具有名称（上面的 Format 是无名的，但其字段是有名的）。在此示例中，使用了适当的值调用 pack 方法，然后返回一个 Bits 对象。《Format》现在包含所有已解释的值，可以轻松访问和修改。

上面示例中的最后一行演示了如何通过提升其他类型来创建所需的新的 Bits 对象，在这种情况下，格式化的字符串在比较之前提升为 Bits 对象。

Format 可以对称地用于创建和解析二进制数据

>>> f.parse(b'x\x048\x10')
28
>>> f
Format([
    'width: u12 = 1920',
    'height: u12 = 1080',
    'flags: [bool; 4] = (False, False, False, True)'
])

parse 方法能够延迟解析输入字节，并简单地返回消耗的位数。直到需要时才计算各个字段的实际值，这允许有效地处理大型和复杂文件格式。

更多内容即将到来 :construction

bitformat 库仍然是预alpha版本，正在积极开发。我希望能于2024年底发布一个或两个alpha版本，并在2025年添加更多功能。

计划了许多重要功能，其中一些来自核心库所基于的 bitstring 库，其他则是为了实现完整的二进制格式体验所必需的。

待办事项列表（无顺序）包括：

• 流式方法。 没有位位置的概念，也没有通过 Bits 读取的概念。这在 bitstring 中是可用的，但我在将其添加到 bitformat 之前想找到更好的方法。
• 字段表达式。 在字段中不是硬编码一切，一些部分将在解析过程中计算。例如，在格式 '[w: u16, h: u16, [u8; {w * h}]]' 中，'u8' 数组的尺寸将取决于它之前解析的值。
• 新的字段类型。 计划添加诸如 Repeat、Find 和 If 这样的字段，这将允许编写更灵活的格式。
• 奇特的浮点类型。 在 bitstring 中有许多额外的浮点类型，如 bfloat 和 MXFP 8、6 和 4 位变体。这些将被移植到 bitformat。
• 性能改进。 bitformat 设计的重点之一是它应该很快。早期版本可能不会很好地优化，但迄今为止的测试结果非常令人鼓舞，设计哲学意味着它可以在以后变得更具性能。
• LSB0。 目前所有位位置都是以最高有效位为位零（MSB0）的方式进行的。我计划添加对最低有效位为零（LSB0）的位编号的支持。

_{版权（c）2024 Scott Griffiths}