hbutils.binary.buffer

Fixed-size binary buffer utilities.

This module provides a binary I/O type for reading and writing fixed-size byte buffers. The core abstraction is CBufferType, which reads an exact number of bytes from a binary stream and writes byte data padded with null bytes (\x00) when the input is shorter than the configured buffer size.

The module contains the following main components:

CBufferType - Fixed-size buffer reader/writer implementation
c_buffer() - Convenience factory for CBufferType

Example:

>>> import io
>>> from hbutils.binary.buffer import c_buffer
>>>
>>> # Reading example
>>> with io.BytesIO(b'\xde\xad\xbe\xef\x00\x12\x34\x56\x78\x00') as file:
...     print(c_buffer(1).read(file))
...     print(c_buffer(2).read(file))
...     print(c_buffer(3).read(file))
...     print(c_buffer(4).read(file))
b'\xde'
b'\xad\xbe'
b'\xef\x00\x12'
b'4Vx\x00'
>>>
>>> # Writing example
>>> with io.BytesIO() as file:
...     c_buffer(1).write(file, b'\xde')
...     c_buffer(2).write(file, b'\xad\xbe')
...     c_buffer(3).write(file, b'\xef\x00\x12')
...     c_buffer(4).write(file, b'4Vx')  # length is 3, will be padded to 4
...     print(file.getvalue())
b'\xde\xad\xbe\xef\x00\x124Vx\x00'

Note

The read operation returns exactly the number of bytes requested by the buffer size. If fewer bytes are available in the stream, the returned value may be shorter, depending on the underlying stream behavior.

all

hbutils.binary.buffer.__all__ = ['CBufferType', 'c_buffer']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

CBufferType

class hbutils.binary.buffer.CBufferType(size: int)[source]

A binary I/O type for handling fixed-size byte buffers.

This class provides methods to read and write byte data with a predetermined size. When writing data shorter than the buffer size, it automatically pads the output with null bytes (\x00) to the configured size.

Parameters:: size (int) – Size of the buffer in bytes.
Variables:: __size (int) – Internal buffer size in bytes.

Example:

>>> import io
>>> buf = CBufferType(4)
>>> with io.BytesIO(b'\x01\x02\x03\x04\x05') as file:
...     buf.read(file)
b'\x01\x02\x03\x04'

__init__(size: int)[source]

Constructor of CBufferType.

Parameters:: size (int) – Size of the buffer in bytes.

read(file: BinaryIO) → bytes[source]

Read bytes value from a binary file.

Parameters:: file (BinaryIO) – Binary file object to read from. io.BytesIO is supported as well.
Returns:: Bytes value read from the file with the specified buffer size.
Return type:: bytes

Note

The returned value is exactly what the stream returns for read(size).

property size: int

Get the size of the buffer.

Returns:: Size of the buffer in bytes.
Return type:: int

write(file: BinaryIO, val: bytearray | bytes) → None[source]

Write bytes value to binary IO object.

If the length of the provided value is less than the buffer size, null bytes (\x00) will be appended to reach the specified size.

Parameters:

file (BinaryIO) – Binary file object to write to. io.BytesIO is supported as well.
val (Union[bytearray, bytes]) – Bytes value to write. Must be of type bytearray or bytes.

Returns:

None.

Return type:

None

Raises:

TypeError – If val is not a bytearray or bytes object.
ValueError – If the length of val exceeds the buffer size.

Example:

>>> import io
>>> buf = CBufferType(4)
>>> with io.BytesIO() as file:
...     buf.write(file, b'\x01\x02')
...     file.getvalue()
b'\x01\x02\x00\x00'

c_buffer

hbutils.binary.buffer.c_buffer(size: int) → CBufferType[source]

Create a buffer type for reading and writing bytes with a given size.

This function returns a CBufferType object that can be used to read and write fixed-size byte buffers. When writing, if the data is shorter than the specified size, it will be padded with null bytes.

Parameters:: size (int) – Size of the buffer in bytes.
Returns:: A CBufferType object configured with the specified size.
Return type:: CBufferType

Example:

>>> import io
>>> from hbutils.binary.buffer import c_buffer
>>> with io.BytesIO() as file:
...     c_buffer(3).write(file, b'\x10\x20')
...     file.getvalue()
b'\x10\x20\x00'

hbutils.binary.buffer

__all__

CBufferType

c_buffer

all