buffer - Memory buffer manager¶

Overview¶

This module provides a raw memory buffer manager with convenient methods to read/write data of various data type.

MemoryBuffer¶

class firebird.base.buffer.MemoryBuffer(init: int | bytes, size: int | None = None, *, factory: ~typing.Type[~firebird.base.buffer.BufferFactory] = <class 'firebird.base.buffer.BytesBufferFactory'>, eof_marker: int | None = None, max_size: int | ~firebird.base.types.Sentinel = Sentinel('UNLIMITED'), byteorder: ~firebird.base.types.ByteOrder = ByteOrder.LITTLE)[source]¶

Bases: object

Generic memory buffer manager.

Parameters:

init (Union[int, bytes]) –
size (int) –
factory (Type[BufferFactory]) –
eof_marker (int) –
max_size (Union[int, Sentinel]) –
byteorder (ByteOrder) –

__init__(init: int | bytes, size: int | None = None, *, factory: ~typing.Type[~firebird.base.buffer.BufferFactory] = <class 'firebird.base.buffer.BytesBufferFactory'>, eof_marker: int | None = None, max_size: int | ~firebird.base.types.Sentinel = Sentinel('UNLIMITED'), byteorder: ~firebird.base.types.ByteOrder = ByteOrder.LITTLE)[source]¶

Parameters:

init (int | bytes) – Must be an integer which specifies the size of the array, or a bytes object which will be used to initialize the array items.
size (int | None) – Size of the array. The argument value is used only when init is a bytes object.
factory (Type[BufferFactory]) – Factory object used to create/resize the internal memory buffer.
eof_marker (int | None) – Value that indicates the end of data. Could be None.
max_size (int | Sentinel) – If specified, the buffer couldn’t grow beyond specified number of bytes.
byteorder (ByteOrder) – The byte order used to read/write numbers.

clear() → None[source]¶

Fills the buffer with zeros and resets the position in buffer to zero.

Return type:: None

is_eof() → bool[source]¶

Return True when positioned past the end of buffer or on eof_marker (if defined).

Return type:: bool

read(size: int = -1) → bytes[source]¶

Reads specified number of bytes, or all remaining data.

Parameters:: size (int) –
Return type:: bytes

read_bigint(*, signed: bool = False) → int[source]¶

Read 8 byte number (c_ulonglong).

Parameters:: signed (bool) –
Return type:: int

read_byte(*, signed: bool = False) → int[source]¶

Read 1 byte number (c_ubyte).

Parameters:: signed (bool) –
Return type:: int

read_bytes() → bytes[source]¶

Read content of binary cluster (2 bytes data length followed by data).

Return type:: bytes

read_int(*, signed: bool = False) → int[source]¶

Read 4 byte number (c_uint).

Parameters:: signed (bool) –
Return type:: int

read_number(size: int, *, signed=False) → int[source]¶

Read number with specified size in bytes.

Parameters:: size (int) –
Return type:: int

read_pascal_string(*, encoding: str = 'ascii', errors: str = 'strict') → str[source]¶

Read Pascal string (1 byte length followed by string data).

Parameters:

encoding (str) –
errors (str) –

Return type:

str

read_short(*, signed: bool = False) → int[source]¶

Read 2 byte number (c_ushort).

Parameters:: signed (bool) –
Return type:: int

read_sized_int(*, signed: bool = False) → int[source]¶

Read number cluster (2 byte length followed by data).

Parameters:: signed (bool) –
Return type:: int

read_sized_string(*, encoding: str = 'ascii', errors: str = 'strict') → str[source]¶

Read string (2 byte length followed by data).

Parameters:

encoding (str) –
errors (str) –

Return type:

str

read_string(*, encoding: str = 'ascii', errors: str = 'strict') → str[source]¶

Read null-terminated string.

Parameters:

encoding (str) –
errors (str) –

Return type:

str

resize(size: int) → None[source]¶

Resize buffer to specified length.

Parameters:: size (int) –
Return type:: None

write(data: bytes) → None[source]¶

Write bytes.

Parameters:: data (bytes) –
Return type:: None

write_bigint(value: int) → None[source]¶

Write tagged 8 byte number (c_ulonglong).

Parameters:: value (int) –
Return type:: None

write_byte(byte: int) → None[source]¶

Write one byte.

Parameters:: byte (int) –
Return type:: None

write_int(value: int) → None[source]¶

Write 4 byte number (c_uint).

Parameters:: value (int) –
Return type:: None

write_number(value: int, size: int, *, signed: bool = False) → None[source]¶

Write number with specified size (in bytes).

Parameters:

value (int) –
size (int) –
signed (bool) –

Return type:

None

write_pascal_string(value: str, *, encoding: str = 'ascii', errors: str = 'strict') → None[source]¶

Write tagged Pascal string (2 byte length followed by data).

Parameters:

value (str) –
encoding (str) –
errors (str) –

Return type:

None

write_short(value: int) → None[source]¶

Write 2 byte number (c_ushort).

Parameters:: value (int) –
Return type:: None

write_sized_string(value: str, *, encoding: str = 'ascii', errors: str = 'strict') → None[source]¶

Write string (2 byte length followed by data).

Parameters:

value (str) –
encoding (str) –
errors (str) –

Return type:

None

write_string(value: str, *, encoding: str = 'ascii', errors: str = 'strict') → None[source]¶

Write zero-terminated string.

Parameters:

value (str) –
encoding (str) –
errors (str) –

Return type:

None

property buffer_size: int¶: Current buffer size in bytes.

byteorder: ByteOrder¶

LITTLE].

Type:: The byte order used to read/write numbers [default

eof_marker: int¶: Value that indicates the end of data. Could be None.

factory: BufferFactory¶

BytesBufferFactory].

Type:: Buffer factory instance used by manager [default

property last_data: int¶: Index of first non-zero byte when searched from the end of buffer.

max_size: int | Sentinel¶

UNLIMITED].

Type:: The buffer couldn’t grow beyond specified number of bytes [default

pos: int¶: Current position in buffer, i.e. the next read/writen byte would be at this position.

raw: bytearray¶: The memory buffer. The actual data type of buffer depends on buffer factory, but it must provide direct acces to cells, slices and length like bytearray.

Buffer factories¶

class firebird.base.buffer.BufferFactory(*args, **kwargs)[source]¶

Bases: Protocol

BufferFactory Protocol definition.

clear(buffer: Any) → None[source]¶

Fills the buffer with zero.

Argument:: buffer: A memory buffer previously created by BufferFactory.create() method.

Parameters:: buffer (Any) –
Return type:: None

create(init_or_size: int | bytes, size: int | None = None) → Any[source]¶

This function must create and return a mutable character buffer.

Parameters:

init_or_size (int | bytes) – Must be an integer which specifies the size of the array, or a bytes object which will be used to initialize the array items.
size (int | None) – Size of the array.

Return type:

Any

class firebird.base.buffer.BytesBufferFactory[source]¶

Bases: object

Buffer factory for bytearray buffers.

clear(buffer: bytearray) → None[source]¶

Fills the buffer with zero.

Parameters:: buffer (bytearray) –
Return type:: None

create(init_or_size: int | bytes, size: int | None = None) → bytearray[source]¶

This function creates a mutable character buffer. The returned object is a bytearray.

Parameters:

init_or_size (int | bytes) – Must be an integer which specifies the size of the array, or a bytes object which will be used to initialize the array items.
size (int | None) – Size of the array.

Return type:

bytearray

Important

Although arguments are the same as for ctypes.create_string_buffer, the behavior is different when new buffer is initialized from bytes:

If there are more bytes than specified size, this function copies only size bytes into new buffer. The create_string_buffer raises an excpetion.
Unlike create_string_buffer when size is NOT specified, the buffer is NOT made one item larger than its length so that the last element in the array is a NUL termination character.

class firebird.base.buffer.CTypesBufferFactory[source]¶

Bases: object

Buffer factory for ctypes array of c_char buffers.

clear(buffer: bytearray, init: int = 0) → None[source]¶

Fills the buffer with specified value (default).

Parameters:

buffer (bytearray) –
init (int) –

Return type:

None

create(init_or_size: int | bytes, size: int | None = None) → bytearray[source]¶

This function creates a ctypes mutable character buffer. The returned object is an array of ctypes.c_char.

Parameters:

init_or_size (int | bytes) – Must be an integer which specifies the size of the array, or a bytes object which will be used to initialize the array items.
size (int | None) – Size of the array.

Return type:

bytearray

Important

Although arguments are the same as for ctypes.create_string_buffer, the behavior is different when new buffer is initialized from bytes:

If there are more bytes than specified size, this function copies only size bytes into new buffer. The create_string_buffer raises an excpetion.
Unlike create_string_buffer when size is NOT specified, the buffer is NOT made one item larger than its length so that the last element in the array is a NUL termination character.