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:

  1. If there are more bytes than specified size, this function copies only size bytes into new buffer. The create_string_buffer raises an excpetion.

  2. 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:

  1. If there are more bytes than specified size, this function copies only size bytes into new buffer. The create_string_buffer raises an excpetion.

  2. 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