pw_bytes Python package#

pw_bytes: Utilities for manipulating binary data

The pw_bytes Python package provides utilities to read and write binary data streams.

pw_bytes.io#

Classes for reading and writing binary data streams.

class pw_bytes.io.BinaryReader(reader: IO[bytes], byteorder: Literal['little', 'big'])#

Facilitates reading binary data (integers) from an I/O stream.

__init__(reader: IO[bytes], byteorder: Literal['little', 'big'])#

Creates a new BinaryReader instance wrapping the given reader.

Parameters:

  • reader – The I/O stream from which to read. Note that BinaryReader does not “own” the stream; it “borrows” it.

  • byteorder – The byte order of multi-byte integers; either “little” (least significant byte first) or “big” (most significant byte first).

read(n: int) → bytes#

Reads exactly n bytes from the underlying stream.

Parameters:

n – The exact number of bytes to read.

Returns:

The read binary bytes (guaranteed to be exactly n bytes long).

Raises:

  • EOFError – If EOF is reached before reading n bytes.

  • BlockingIOError – If the stream is in non-blocking mode and no bytes are available to be read.

read_u16(byteorder: Literal['little', 'big'] | None = None) → int#

Reads an unsigned 16-bit integer from the stream.

read_u32(byteorder: Literal['little', 'big'] | None = None) → int#

Reads an unsigned 32-bit integer from the stream.

read_u64(byteorder: Literal['little', 'big'] | None = None) → int#

Reads an unsigned 64-bit integer from the stream.

read_u8(byteorder: Literal['little', 'big'] | None = None) → int#

Reads an unsigned 8-bit integer from the stream.

read_uint(size: int, byteorder: Literal['little', 'big'] | None = None) → int#

Reads an unsigned integer of the given byte size from the stream.

Parameters:

  • size – The number of bytes representing the integer (e.g., 2, 4, 8).

  • byteorder – The byte order of the integer (“little” or “big”). If not specified, defaults to the reader’s default byte order.

Returns:

The unpacked unsigned integer value.

Raises:

  • EOFError – If EOF is reached before reading size bytes.

  • BlockingIOError – If the stream is in non-blocking mode and no bytes are available to be read.

seek(offset: int, whence: int = 0) → int#

Changes the position of the underlying stream.

See io.IOBase.seek().

tell() → int#

Returns the current position of the underlying stream.

See io.IOBase.tell().

class pw_bytes.io.BinaryWriter(writer: IO[bytes], byteorder: Literal['little', 'big'])#

Facilitates writing binary data (integers) to a stream.

__init__(writer: IO[bytes], byteorder: Literal['little', 'big'])#

Creates a new BinaryWriter instance wrapping the given writer.

Parameters:

  • writer – The I/O stream to which to write. Note that BinaryWriter does not “own” the stream; it “borrows” it.

  • byteorder – The byte order of multi-byte integers; either “little” (least significant byte first) or “big” (most significant byte first).

seek(offset: int, whence: int = 0) → int#

Changes the position of the underlying stream.

See io.IOBase.seek().

tell() → int#

Returns the current position of the underlying stream.

See io.IOBase.tell().

write(data: bytes) → None#

Writes all data to the underlying stream.

Parameters:

data – The raw binary bytes to write.

Raises:

  • OSError – If an I/O error occurs (e.g. zero bytes written).

  • BlockingIOError – If the stream is in non-blocking mode and no bytes can be written to it.

write_u16(val: int, byteorder: Literal['little', 'big'] | None = None) → None#

Writes an unsigned 16-bit integer to the stream.

write_u32(val: int, byteorder: Literal['little', 'big'] | None = None) → None#

Writes an unsigned 32-bit integer to the stream.

write_u64(val: int, byteorder: Literal['little', 'big'] | None = None) → None#

Writes an unsigned 64-bit integer to the stream.

write_u8(val: int, byteorder: Literal['little', 'big'] | None = None) → None#

Writes an unsigned 8-bit integer to the stream.

write_uint(val: int, length: int, byteorder: Literal['little', 'big'] | None = None) → None#

Writes an unsigned integer of the given byte length to the stream.

Parameters:

  • val – The unsigned integer value to pack and write.

  • length – The size of the integer in bytes (e.g., 2, 4, 8).

  • byteorder – The byte order of the integer (“little” or “big”). If not specified, defaults to the writer’s default byte order.

Raises:

  • OverflowError – If the integer value is negative or too large for the specified byte length.

  • BlockingIOError – If the stream is in non-blocking mode and no bytes can be written to it.

On this page