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, size=None, *, factory=<class 'firebird.base.buffer.BytesBufferFactory'>, eof_marker=None, max_size=Sentinel('UNLIMITED'), byteorder=<ByteOrder.LITTLE: 'little'>)¶

Bases: object

Generic memory buffer manager.

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.

raw¶: 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.

pos¶

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

Type: int

factory¶

Buffer factory instance used by manager [default: BytesBufferFactory].

Type: BufferFactory

eof_marker¶

Value that indicates the end of data. Could be None.

Type: int

max_size¶

The buffer couldn’t grow beyond specified number of bytes [default: UNLIMITED].

Type: int or UNLIMITED

byteorder¶

The byte order used to read/write numbers [default: LITTLE].

Type: ByteOrder

clear()¶

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

Return type: None

is_eof()¶

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

Return type: bool

read(size=- 1)¶

Reads specified number of bytes, or all remaining data.

Return type: bytes

read_bigint(*, signed=False)¶

Read 8 byte number (c_ulonglong)

Return type: int

read_byte(*, signed=False)¶

Read 1 byte number (c_ubyte)

Return type: int

read_bytes()¶

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

Return type: bytes

read_int(*, signed=False)¶

Read 4 byte number (c_uint)

Return type: int

read_number(size, *, signed=False)¶

Read number with specified size in bytes

Return type: int

read_pascal_string(*, encoding='ascii')¶

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

Return type: str

read_short(*, signed=False)¶

Read 2 byte number (c_ushort)

Return type: int

read_sized_int(*, signed=False)¶

Read number cluster (2 byte length followed by data)

Return type: int

read_sized_string(*, encoding='ascii')¶

Read string (2 byte length followed by data)

Return type: str

read_string(*, encoding='ascii')¶

Read null-terminated string

Return type: str

resize(size)¶

Resize buffer to specified length.

Return type: None

write(data)¶

Write bytes

Return type: None

write_bigint(value)¶

Write tagged 8 byte number (c_ulonglong)

Return type: None

write_byte(byte)¶

Write byte

Return type: None

write_int(value)¶

Write 4 byte number (c_uint)

Return type: None

write_number(value, size, *, signed=False)¶

Write number with specified size in bytes

Return type: None

write_pascal_string(value, *, encoding='ascii')¶

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

Return type: None

write_short(value)¶

Write 2 byte number (c_ushort)

Return type: None

write_string(value, *, encoding='ascii')¶

Write zero-terminated string

Return type: None

property buffer_size¶

Current buffer size in bytes.

Return type: int

property last_data¶

Index of first non-zero byte when searched from the end of buffer.

Return type: int

Buffer factories¶

Buffer factory protocol¶

class firebird.base.buffer.BufferFactory(*args, **kwds)¶

Bases: typing.Protocol

BufferFactory Protocol definition

clear(buffer)¶

Fills the buffer with zero.

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

Return type: None

create(init_or_size, size=None)¶

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

bytes factory¶

class firebird.base.buffer.BytesBufferFactory¶

Bases: object

Buffer factory for bytearray buffers.

clear(buffer)¶

Fills the buffer with zero

Return type: None

create(init_or_size, size=None)¶

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.

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.

Return type: bytearray

ctypes factory¶

class firebird.base.buffer.CTypesBufferFactory¶

Bases: object

Buffer factory for ctypes array of c_char buffers.

clear(buffer, init=0)¶

Fills the buffer with specified value (default)

Return type: None

create(init_or_size, size=None)¶

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.

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.

Return type: bytearray