hbutils.binary.base

Binary IO type definitions and helpers for fixed-size data structures.

This module defines a small hierarchy of IO types designed to read and write binary data from file-like objects (e.g., io.BytesIO or any typing.BinaryIO). The core abstractions help describe fixed-size data structures, integer ranges, and types that can be directly packed with the struct module.

The module contains the following main components:

CIOType - Base class defining the read/write interface
CFixedType - Fixed-size IO type with a known byte width
CRangedIntType - Fixed-size integer type with value constraints
CMarkedType - Fixed-size type using a struct format mark

Example:

>>> import io
>>> int_type = CMarkedType('i', 4)
>>> buffer = io.BytesIO()
>>> int_type.write(buffer, 5)
>>> buffer.seek(0)
0
>>> int_type.read(buffer)
5

Note

All IO types operate on binary streams. Text streams are not supported.

CIOType

class hbutils.binary.base.CIOType[source]

Basic IO type.

Used as base class of all the IO types. Provides the interface for reading from and writing to binary IO objects.

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

Read from binary IO object.

Parameters:: file (BinaryIO) – Binary file, io.BytesIO is supported as well.
Returns:: Reading result.
Return type:: Any

Warning

Need to be implemented in subclasses.

Raises:: NotImplementedError – This method must be implemented by subclasses.

write(file: BinaryIO, val: Any) → None[source]

Write object to binary IO object.

Parameters:

file (BinaryIO) – Binary file, io.BytesIO is supported as well.
val (Any) – Object to write.

Returns:

None.

Return type:

None

Warning

Need to be implemented in subclasses.

Raises:: NotImplementedError – This method must be implemented by subclasses.

CFixedType

class hbutils.binary.base.CFixedType(size: int)[source]

Type with fixed size.

Represents types with a fixed size in bytes, such as int, uint and float. This class extends CIOType to add size information.

__init__(size: int)[source]

Constructor of CFixedType.

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

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

Read from binary IO object.

Parameters:: file (BinaryIO) – Binary file, io.BytesIO is supported as well.
Returns:: Reading result.
Return type:: Any

Warning

Need to be implemented in subclasses.

Raises:: NotImplementedError – This method must be implemented by subclasses.

property size: int

Size of the given type in bytes.

Returns:: The size of the type.
Return type:: int

write(file: BinaryIO, val: Any) → None[source]

Write object to binary IO object.

Parameters:

file (BinaryIO) – Binary file, io.BytesIO is supported as well.
val (Any) – Object to write.

Returns:

None.

Return type:

None

Warning

Need to be implemented in subclasses.

Raises:: NotImplementedError – This method must be implemented by subclasses.

CRangedIntType

class hbutils.binary.base.CRangedIntType(size: int, minimum: int, maximum: int)[source]

Type with fixed size and value range.

Represents integer types with fixed size and range constraints, such as int and uint. This class extends CFixedType to add minimum and maximum value constraints.

__init__(size: int, minimum: int, maximum: int)[source]

Constructor of CRangedIntType.

Parameters:

size (int) – Size of the type in bytes.
minimum (int) – Minimum value of the type.
maximum (int) – Maximum value of the type.

property maximum: int

Maximum value of the type.

Returns:: The maximum value that can be represented by this type.
Return type:: int

property minimum: int

Minimum value of the type.

Returns:: The minimum value that can be represented by this type.
Return type:: int

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

Read from binary IO object.

Parameters:: file (BinaryIO) – Binary file, io.BytesIO is supported as well.
Returns:: Reading result.
Return type:: Any

Warning

Need to be implemented in subclasses.

Raises:: NotImplementedError – This method must be implemented by subclasses.

write(file: BinaryIO, val: Any) → None[source]

Write object to binary IO object.

Parameters:

file (BinaryIO) – Binary file, io.BytesIO is supported as well.
val (Any) – Object to write.

Returns:

None.

Return type:

None

Warning

Need to be implemented in subclasses.

Raises:: NotImplementedError – This method must be implemented by subclasses.

CMarkedType

class hbutils.binary.base.CMarkedType(mark: str, size: int)[source]

Type with struct mark.

Represents types that can be directly read and written using Python’s struct module. The mark parameter corresponds to format characters used by struct (e.g., ‘i’ for int, ‘f’ for float).

Example::

>>> import io
>>> float_type = CMarkedType('f', 4)
>>> buffer = io.BytesIO()
>>> float_type.write(buffer, 3.14)
>>> buffer.seek(0)
0
>>> float_type.read(buffer)
3.140000104904175

__init__(mark: str, size: int)[source]

Constructor of CMarkedType.

Parameters:

mark (str) – Format character for the struct module (e.g., ‘i’, ‘f’, ‘d’).
size (int) – Size of the type in bytes.

property mark: str

Mark of the type.

The format character that will be used to read from and write to binary data with the struct module.

Returns:: The struct format character.
Return type:: str

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

Read from binary with struct module.

Parameters:: file (BinaryIO) – Binary file, io.BytesIO is supported as well.
Returns:: Result value read from the binary file.
Return type:: Any

Example::

>>> import io
>>> buffer = io.BytesIO(b'\x00\x00\x00\x05')
>>> int_type = CMarkedType('i', 4)
>>> int_type.read(buffer)
5

write(file: BinaryIO, val: Any) → None[source]

Write value to binary IO with struct module.

Parameters:

file (BinaryIO) – Binary file, io.BytesIO is supported as well.
val (Any) – Writing value. Will be converted to float before packing.

Returns:

None.

Return type:

None

Example::

>>> import io
>>> buffer = io.BytesIO()
>>> float_type = CMarkedType('f', 4)
>>> float_type.write(buffer, 3.14)
>>> buffer.getvalue()
b'\xc3\xf5H@'