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

Parameters

init (Union[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 (Optional[int]) – 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 (Optional[int]) – Value that indicates the end of data. Could be None.
max_size (Union[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: Union[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: Union[int, bytes], size: Optional[int] = None) → Any[source]¶

This function must create and return a mutable character buffer.

Parameters

init_or_size (Union[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 (Optional[int]) – 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: Union[int, bytes], size: Optional[int] = None) → bytearray[source]¶

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

Parameters

init_or_size (Union[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 (Optional[int]) – 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: Union[int, bytes], size: Optional[int] = 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 (Union[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 (Optional[int]) – 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.