hbutils.binary.base

This module provides basic IO types for binary file operations.

It defines a hierarchy of classes for reading and writing binary data with different characteristics: - CIOType: Base class for all IO types - CFixedType: Types with fixed size (int, uint, float, etc.) - CRangedIntType: Fixed-size types with value range constraints - CMarkedType: Types that can be read/written using Python’s struct module

These classes are designed to work with binary file objects and io.BytesIO instances.

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)[source]

Read from binary IO object.

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

Warning

Need to be implemented in subclasses.

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

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

Write object to binary IO object.

Parameters:

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

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)[source]

Read from binary IO object.

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

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)[source]

Write object to binary IO object.

Parameters:

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

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)[source]

Read from binary IO object.

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

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)[source]

Write object to binary IO object.

Parameters:

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

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)[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.

Example::

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

property size: int

Size of the given type in bytes.

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

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

Write value to binary IO with struct module.

Parameters:

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

Example::

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