firebird.driver.interfaces

This module contains interface wrappers for Firebird new API.

Important

  1. Firebird OO API interfaces use inheritance, i.e. they could be inherited from other interface. In fact, all interfaces returned by Firebird are inherited from IVersioned interface.

  2. Firebird OO API interfaces are versioned. Any addition to particular interface increases its version number. Application developers are responsible to check the version of returned interface to verify that it supports methods they want to use.

If you want to use Firebird OO API interfaces directly in you application, read next section very carefuly.

In Python driver, interfaces are represented as instances of interface wrapper classes that expose the methods provided by particular Firebird interface version. The wrapper class hierarchy thus represent not only inheritabce between Firebird interfaces, but also between versions of particular Firebird interface.

Because all interfaces returned by Firebird are inherited from IVersioned interface, all wrapper classes have VERSION class attribute that contain version number of wrapped interface.

Each Firebird interface has it’s “canonical” Python wrapper with coresponding name. For example interface IService has wrapper class iService. However, if there are multiple public versions of Firebird interface, there are multiple wrapper classes for each published interface version (interim, non-public versions used during Firebird development are skipped). These wrapper classes have names based on their canonical name with suffix that represent the interface version they wrap. It means that canonical wrapper always represents the highest interface version.

Whenever Firebird interface is returned from Firebird OO API call, it’s wrapped to its Python wrapper class according to interface type and version. The Python driver ensures that correct wrapper class is used according to returned interface version.

However, this architecture has several important consequences:

  1. The interface wrapper classes may change between driver releases as new interface versions are introduced. For example, driver versions up to 1.5.2 had only canonical iService (version 3), but in version 1.6.0 it was renamed to iService_v3, new wrappers iService_v4 and (new canonical) iService (version 5) were added.

  2. Instead using isinstance to check interface versions, you should always use VERSION attribute on wrapper class instance.

Metaclasses

class firebird.driver.interfaces.iVersionedMeta[source]

Bases: type

Metaclass for iVersioned interfaces.

This metaclass uses MRO to instantiate wrapper interface with version that matches version of wrapped interface.

Firebird API Interface wrappers

Base interfaces

class firebird.driver.interfaces.iVersioned(intf)[source]

Bases: object

IVersioned interface wrapper

VERSION = 1
property status: iStatus

iStatus for interface

property version: int

Interface version

property vtable

Interface method table

class firebird.driver.interfaces.iReferenceCounted(intf)[source]

Bases: iVersioned

IReferenceCounted interface wrapper

add_ref() → None[source]

Increase the reference by one

Return type:

None

release() → int[source]

Decrease the reference by one

Return type:

int

VERSION = 2
class firebird.driver.interfaces.iDisposable(intf)[source]

Bases: iVersioned

IDisposable interface wrapper

dispose() → None[source]

Dispose the interfaced object

Return type:

None

VERSION = 2
class firebird.driver.interfaces.iStatus(intf)[source]

Bases: iDisposable

Class that wraps IStatus interface for use from Python

IStatus replaces ISC_STATUS_ARRAY. Functionality is extended – Status has separate access to errors and warnings vectors, can hold vectors of unlimited length, itself stores strings used in vectors avoiding need in circular strings buffer. Interface is on purpose minimized (methods like convert it to text are moved to Util interface) in order to simplify it’s implementation by users when needed.

clone() → iStatus[source]

Create clone of current interface

Return type:

iStatus

get_errors() → LP_c_long_Array_20[source]

Returns errors vector

Return type:

LP_c_long_Array_20

get_state() → StateFlag[source]

Returns state flags, may be OR-ed.

Return type:

StateFlag

get_warning() → LP_c_long_Array_20[source]

Returns warnings vector

Return type:

LP_c_long_Array_20

init() → None[source]

Cleanup interface, set it to initial state

Return type:

None

set_errors(value: ByteString) → None[source]

Set contents of errors vector, length is defined by value context

Parameters:

value (ByteString)

Return type:

None

set_errors2(length: int, value: ByteString) → None[source]

Set contents of errors vector with length explicitly specified in a call

Parameters:
Return type:

None

set_warning2(length: int, value: ByteString) → None[source]

Set contents of warnings vector with length explicitly specified in a call

Parameters:
Return type:

None

set_warnings(value: ByteString) → None[source]

Set contents of warnings vector, length is defined by value context

Parameters:

value (ByteString)

Return type:

None

VERSION = 3
class firebird.driver.interfaces.iPluginBase(intf)[source]

Bases: iReferenceCounted

IPluginBase interface wrapper

get_owner() → iReferenceCounted[source]

Returns owner

Return type:

iReferenceCounted

set_owner(r: iReferenceCounted) → None[source]

Set the owner

Parameters:

r (iReferenceCounted)

Return type:

None

VERSION = 3
class firebird.driver.interfaces.iMaster(intf)[source]

Bases: iVersioned

Class that wraps IMaster interface for use from Python

get_config_manager() → iConfigManager[source]

Get instance of iConfigManager interface.

Return type:

iConfigManager

get_dispatcher() → iProvider[source]

Get instance of iProvider interface, implemented by yValve (main provider instance).

Return type:

iProvider

get_dtc() → iDtc[source]

Get instance of iDtc interface.

Return type:

iDtc

get_metadata_builder(fieldCount: int) → iMetadataBuilder[source]

Get instance of iMetadataBuilder interface.

Parameters:

fieldCount (int)

Return type:

iMetadataBuilder

get_plugin_manager() → iPluginManager[source]

Get instance of iPluginManager interface.

Return type:

iPluginManager

get_process_exiting() → bool[source]

Information not available

Return type:

bool

get_status() → iStatus[source]

Get instance if iStatus interface.

Return type:

iStatus

get_timer_control() → iTimerControl[source]

Get instance of iTimerControl interface.

Return type:

iTimerControl

get_util_interface() → iUtil[source]

Get instance of iUtil interface.

Return type:

iUtil

register_attachment(provider: iProvider, attachment: iAttachment) → iAttachment[source]

Information not available

Parameters:
Return type:

iAttachment

register_transaction(attachment: iAttachment, transaction: iTransaction) → iTransaction[source]

Information not available

Parameters:
Return type:

iTransaction

server_mode(mode: int) → int[source]

Information not available

Parameters:

mode (int)

Return type:

int

VERSION = 2

Configuration

class firebird.driver.interfaces.iConfigEntry(intf)[source]

Bases: iReferenceCounted

Class that wraps IConfigEntry interface for use from Python

get_bool_value() → bool[source]

Returns value as boolean

Return type:

bool

get_int_value() → int[source]

Returns value as integer

Return type:

int

get_name() → str[source]

Returns key name

Return type:

str

get_sub_config(status: iStatus) → iConfig[source]

Treats sub-entries as separate configuration file and returns IConfig interface for it

Parameters:

status (iStatus)

Return type:

iConfig

get_value() → str[source]

Returnd value string value

Return type:

str

VERSION = 3
class firebird.driver.interfaces.iConfig(intf)[source]

Bases: iReferenceCounted

Class that wraps IConfig interface for use from Python

find(name: str) → iConfigEntry[source]

Find entry by name

Parameters:

name (str)

Return type:

iConfigEntry

find_pos(name: str, pos: int) → iConfigEntry[source]

Find entry by name and position. If configuration file contains lines:

Db=DBA
Db=DBB
Db=DBC

call to find_pos(status, “Db”, 2) will return entry with value DBB.

Parameters:
Return type:

iConfigEntry

find_value(name: str, value: str) → iConfigEntry[source]

Find entry by name and value

Parameters:
Return type:

iConfigEntry

VERSION = 3
class firebird.driver.interfaces.iFirebirdConf_v3(intf)[source]

Bases: iReferenceCounted

Class that wraps IFirebirdConf v3 interface for use from Python

as_boolean(key: str) → bool[source]

Returns boolean value of conf. parameter

Parameters:

key (str)

Return type:

bool

as_integer(key: int) → int[source]

Returns integer value of conf. parameter

Parameters:

key (int)

Return type:

int

as_string(key: int) → str[source]

Returns string value of conf. parameter

Parameters:

key (int)

Return type:

str

get_key(name: str) → int[source]

Returns key for configuration parameter.

Note

If parameter with given name does not exists, returns 0xffffffff.

Parameters:

name (str)

Return type:

int

VERSION = 3
class firebird.driver.interfaces.iFirebirdConf(intf)[source]

Bases: iFirebirdConf_v3

Class that wraps IFirebirdConf v4 interface for use from Python

get_version() → int[source]

Returns configuration version

Return type:

int

VERSION = 4
class firebird.driver.interfaces.iConfigManager_v2(intf)[source]

Bases: iVersioned

Class that wraps IConfigManager v2 interface for use from Python

get_database_conf(database: str) → iFirebirdConf[source]

Returns interface to access db-specific configuration. Takes into an account firebird.conf and appropriate part of databases.conf.

Parameters:

database (str)

Return type:

iFirebirdConf

get_directory(dirspec: DirectoryCode) → str[source]

Returns location of appropriate directory in current firebird instance

Parameters:

dirspec (DirectoryCode)

Return type:

str

get_firebird_conf() → iFirebirdConf[source]

Returns interface to access default configuration values (from firebird.conf)

Return type:

iFirebirdConf

get_install_directory() → str[source]

Returns directory where firebird is installed

Return type:

str

get_plugin_config(plugin: str) → iConfig[source]

Returns interface to access named plugin configuration

Parameters:

plugin (str)

Return type:

iConfig

get_root_directory() → str[source]

Returns root directory of current instance, in single-instance case usually matches install directory

Return type:

str

VERSION = 2
class firebird.driver.interfaces.iConfigManager(intf)[source]

Bases: iConfigManager_v2

Class that wraps IConfigManager v3 interface for use from Python

get_default_security_db() → str[source]

Returns default security database.

Return type:

str

VERSION = 3

Database and service attachments

class firebird.driver.interfaces.iProvider(intf)[source]

Bases: iPluginBase

Class that wraps IProvider interface for use from Python

attach_database(filename: str, dpb: bytes | None = None, encoding: str = 'ascii') → iAttachment[source]

Replaces isc_attach_database()

Parameters:
Return type:

iAttachment

attach_service_manager(service: str, spb: bytes) → iService[source]

Replaces isc_service_attach()

Parameters:
Return type:

iService

create_database(filename: str, dpb: bytes, encoding: str = 'ascii') → iAttachment[source]

Replaces isc_create_database()

Parameters:
Return type:

iAttachment

set_dbcrypt_callback(callback: iCryptKeyCallbackImpl) → None[source]

Sets database encryption callback interface that will be used for following database and service attachments

Parameters:

callback (iCryptKeyCallbackImpl)

Return type:

None

shutdown(timeout: int, reason: int) → None[source]

Replaces fb_shutdown()

Parameters:
Return type:

None

VERSION = 4
class firebird.driver.interfaces.iAttachment_v3(intf)[source]

Bases: iReferenceCounted

Class that wraps IAttachment v3 interface for use from Python

cancel_operation(option: int) → None[source]

Replaces fb_cancel_operation()

Parameters:

option (int)

Return type:

None

compile_request(blr: bytes) → iRequest[source]

Support of ISC API

Parameters:

blr (bytes)

Return type:

iRequest

create_blob(transaction: iTransaction, id_: ISC_QUAD, bpb: bytes = None) → iBlob[source]

Creates new blob, stores it’s identifier in id, replaces isc_create_blob2()

Parameters:
Return type:

iBlob

detach() → None[source]

Replaces isc_detach_database(). On success releases interface.

Return type:

None

drop_database() → None[source]

Replaces isc_drop_database(). On success releases interface.

Return type:

None

execute(transaction: iTransaction, stmt: str, dialect: int, in_metadata: iMessageMetadata = None, in_buffer: bytes = None, out_metadata: iMessageMetadata = None, out_buffer: bytes = None) → None[source]

Executes any SQL statement except returning multiple rows of data. Partial analogue of isc_dsql_execute2() - in and out XSLQDAs replaced with input and output messages with appropriate buffers.

Parameters:
Return type:

None

execute_dyn(transaction: iTransaction, dyn: bytes) → None[source]

Support of ISC API

Parameters:
Return type:

None

get_info(items: bytes, buffer: bytes) → None[source]

Replaces isc_database_info()

Parameters:
Return type:

None

get_slice(transaction: iTransaction, id_: ISC_QUAD, sdl: bytes, param: bytes, slice_: bytes) → int[source]

Support of ISC API

Parameters:
Return type:

int

open_blob(transaction: iTransaction, id_: ISC_QUAD, bpb: bytes = None) → iBlob[source]

Opens existing blob, replaces isc_open_blob2()

Parameters:
Return type:

iBlob

open_cursor(transaction: iTransaction, stmt: str, dialect: int, in_metadata: iMessageMetadata, in_buffer: bytes, out_metadata: iMessageMetadata, cursor_name: str, cursor_flags: int) → iResultSet[source]

Executes SQL statement potentially returning multiple rows of data. Returns iResultSet interface which should be used to fetch that data. Format of output data is defined by out_metadata parameter, leaving it NULL default format may be used. Parameter cursor_name specifies name of opened cursor (analogue of isc_dsql_set_cursor_name()). Parameter cursor_flags is needed to open bidirectional cursor setting it’s value to Istatement::CURSOR_TYPE_SCROLLABLE.

Parameters:
Return type:

iResultSet

ping() → None[source]

Checks connection status. If test fails the only operation possible with attachment is to close it.

Return type:

None

prepare(transaction: ~firebird.driver.interfaces.iTransaction, stmt: str, dialect: int, flags: ~firebird.driver.types.PreparePrefetchFlag = <PreparePrefetchFlag.METADATA: 71>) → iStatement[source]

Replaces isc_dsql_prepare(). Additional parameter flags makes it possible to control what information will be preloaded from engine at once (i.e. in single network packet for remote operation).

Parameters:
Return type:

iStatement

put_slice(transaction: iTransaction, id_: ISC_QUAD, sdl: bytes, param: bytes, slice_: bytes) → None[source]

Support of ISC API

Parameters:
Return type:

None

que_events(callback: iEventCallbackImpl, events: bytes) → iEvents[source]

Replaces isc_que_events() call. Instead callback function with void* parameter callback interface is used.

Parameters:
Return type:

iEvents

reconnect_transaction(id_: bytes) → iTransaction[source]

Makes it possible to connect to a transaction in limbo. Id parameter contains transaction number in network format of given length.

Parameters:

id_ (bytes)

Return type:

iTransaction

start_transaction(tpb: bytes) → iTransaction[source]

Partially replaces isc_start_multiple(), to start >1 transaction distributed transactions coordinator should be used, also possible to join 2 transactions into single distributed transaction

Parameters:

tpb (bytes)

Return type:

iTransaction

transact_request(transaction: iTransaction, blr: bytes, in_msg: bytes, out_msg: bytes) → None[source]

Support of ISC API

Parameters:
Return type:

None

VERSION = 3
encoding: str

Encoding used for string values

class firebird.driver.interfaces.iAttachment_v4(intf)[source]

Bases: iAttachment_v3

Class that wraps IAttachment v4 interface for use from Python

create_batch(transaction: iTransaction, stmt: str, dialect: int, in_metadata: iMessageMetadata, params: bytes) → iBatch[source]

Prepares stmt and creates iBatch interface ready to accept multiple sets of input parameters in in_metadata format. Leaving in_metadata None makes batch use default format for stmt. Parameters block may be passed to create_batch making it possible to adjust batch behavior.

Parameters:
Return type:

iBatch

get_idle_timeout() → int[source]

Returns idle timeout for attachment.

Return type:

int

get_statement_timeout() → int[source]

Returns idle timeout for statement.

Return type:

int

set_idle_timeout(timeout: int) → None[source]

Sets idle timeout for attachment.

Parameters:

timeout (int)

Return type:

None

set_statement_timeout(timeout: int) → None[source]

Sets idle timeout for statement.

Parameters:

timeout (int)

Return type:

None

VERSION = 4
encoding: str

Encoding used for string values

class firebird.driver.interfaces.iAttachment(intf)[source]

Bases: iAttachment_v4

Class that wraps IAttachment v5 interface for use from Python

detach() → None[source]

Replaces isc_detach_database(). On success releases interface.

Return type:

None

drop_database() → None[source]

Replaces isc_drop_database(). On success releases interface.

Return type:

None

VERSION = 5
encoding: str

Encoding used for string values

class firebird.driver.interfaces.iService_v3(intf)[source]

Bases: iReferenceCounted

Class that wraps IService v3 interface for use from Python

detach() → None[source]

Close attachment to services manager, on success releases interface. Replaces isc_service_detach().

Return type:

None

query(send: bytes, receive: bytes, buffer: bytes) → None[source]

Send and request information to/from service, with different receive may be used for both running services and to obtain various server-wide information. Replaces isc_service_query().

Parameters:
Return type:

None

start(spb: bytes) → None[source]

Start utility in services manager. Replaces isc_service_start().

Parameters:

spb (bytes)

Return type:

None

VERSION = 3
class firebird.driver.interfaces.iService_v4(intf)[source]

Bases: iService_v3

Class that wraps IService v4 interface for use from Python

detach() → None[source]

Close attachment to services manager, on success releases interface. Replaces isc_service_detach().

Return type:

None

VERSION = 4
class firebird.driver.interfaces.iService(intf)[source]

Bases: iService_v4

Class that wraps IService v5 interface for use from Python

cancel() → None[source]

Cancel wait of current query() call. Supported only for embedded connections.

Return type:

None

VERSION = 5
class firebird.driver.interfaces.iXpbBuilder(intf)[source]

Bases: iDisposable

Class that wraps IXpbBuilder interface for use from Python

clear() → None[source]

Reset builder to empty state.

Return type:

None

find_first(tag: int) → bool[source]

Finds first clumplet with given tag.

Parameters:

tag (int)

Return type:

bool

find_next() → bool[source]

Finds next clumplet with given tag.

Return type:

bool

get_bigint() → int[source]

Returns value of current clumplet as 64-bit integer.

Return type:

int

get_buffer() → bytes[source]

Returns the parameters block.

Return type:

bytes

get_buffer_length() → int[source]

Returns length of parameters block.

Return type:

int

get_bytes() → bytes[source]

Returns value of current clumplet as bytes.

Return type:

bytes

get_int() → int[source]

Returns value of current clumplet as integer.

Return type:

int

get_length() → int[source]

Returns length of current clumplet value.

Return type:

int

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

Returns value of current clumplet as string.

Parameters:
Return type:

str

get_tag() → int[source]

Returns tag for current clumplet.

Return type:

int

insert_bigint(tag: int, value: int) → None[source]

Inserts a clumplet with value representing integer in network format.

Parameters:
Return type:

None

insert_bytes(tag: int, value: bytes) → None[source]

Inserts a clumplet with value containing passed bytes.

Parameters:
Return type:

None

insert_int(tag: int, value: int) → None[source]

Inserts a clumplet with value representing integer in network format.

Parameters:
Return type:

None

insert_string(tag: int, value: str, *, encoding: str = 'ascii', errors: str = 'strict') → None[source]

Inserts a clumplet with value containing passed string.

Parameters:
Return type:

None

insert_tag(tag: int) → None[source]

Inserts a clumplet without a value.

Parameters:

tag (int)

Return type:

None

is_eof() → bool[source]

Checks that there is no current clumplet.

Return type:

bool

move_next() → None[source]

Moves to next clumplet.

Return type:

None

remove_current() → None[source]

Removes current clumplet.

Return type:

None

rewind() → None[source]

Moves to first clumplet.

Return type:

None

VERSION = 3

Blobs

class firebird.driver.interfaces.iBlob_v3(intf)[source]

Bases: iReferenceCounted

Class that wraps IBlob interface for use from Python

cancel() → None[source]

Replaces isc_cancel_blob(). On success releases interface.

Return type:

None

close() → None[source]

Replaces isc_close_blob(). On success releases interface.

Return type:

None

get_info(items: bytes, buffer: bytes) → None[source]

Replaces isc_blob_info()

Parameters:
Return type:

None

get_info2(code: BlobInfoCode) → Any[source]

Returns information about BLOB

Parameters:

code (BlobInfoCode)

Return type:

Any

get_segment(size: int, buffer: c_void_p, bytes_read: c_uint) → StateResult[source]

Replaces isc_get_segment(). Unlike it never returns isc_segstr_eof and isc_segment errors (that are actually not errors), instead returns completion codes StateResult.NO_DATA and StateResult.SEGMENT, normal return is StateResult.OK.

Parameters:
Return type:

StateResult

put_segment(length: int, buffer: Any) → None[source]

Replaces isc_put_segment()

Parameters:
Return type:

None

seek(mode: int, offset: int) → int[source]

Replaces isc_seek_blob()

Parameters:
Return type:

int

VERSION = 3
class firebird.driver.interfaces.iBlob(intf)[source]

Bases: iBlob_v3

Class that wraps IBlob interface for use from Python

cancel() → None[source]

Replaces isc_cancel_blob(). On success releases interface.

Return type:

None

close() → None[source]

Replaces isc_close_blob(). On success releases interface.

Return type:

None

VERSION = 4

Transactions

class firebird.driver.interfaces.iTransaction_v3(intf)[source]

Bases: iReferenceCounted

Class that wraps ITransaction interface for use from Python

commit() → None[source]

Replaces isc_commit_transaction()

Return type:

None

commit_retaining() → None[source]

Replaces isc_commit_retaining()

Return type:

None

disconnect() → None[source]

Replaces fb_disconnect_transaction()

Return type:

None

enter_dtc() → iTransaction[source]

This method is used to support distributed transactions coordinator

Return type:

iTransaction

get_info(items: bytes, buffer: bytes) → None[source]

Replaces isc_transaction_info()

Parameters:
Return type:

None

join(transaction: iTransaction) → iTransaction[source]

Joins current transaction and passed as parameter transaction into single distributed transaction (using Dtc). On success both current transaction and passed as parameter transaction are released and should not be used any more.

Parameters:

transaction (iTransaction)

Return type:

iTransaction

prepare(message: bytes = None) → None[source]

Replaces isc_prepare_transaction2()

Parameters:

message (bytes)

Return type:

None

rollback() → None[source]

Replaces isc_rollback_transaction()

Return type:

None

rollback_retaining() → None[source]

Replaces isc_rollback_retaining()

Return type:

None

validate(attachment: iAttachment) → iTransaction[source]

This method is used to support distributed transactions coordinator

Parameters:

attachment (iAttachment)

Return type:

iTransaction

VERSION = 3
class firebird.driver.interfaces.iTransaction(intf)[source]

Bases: iTransaction_v3

Class that wraps ITransaction interface for use from Python

commit() → None[source]

Replaces isc_commit_transaction()

Return type:

None

disconnect() → None[source]

Replaces fb_disconnect_transaction()

Return type:

None

rollback() → None[source]

Replaces isc_rollback_transaction()

Return type:

None

VERSION = 4
class firebird.driver.interfaces.iDtcStart(intf)[source]

Bases: iDisposable

Class that wraps IDtcStart interface for use from Python

add_attachment(attachment: iAttachment) → None[source]

Adds attachment, transaction for it will be started with default TPB

Parameters:

attachment (iAttachment)

Return type:

None

add_with_tpb(attachment: iAttachment, tpb: bytes) → None[source]

Adds attachment and TPB which will be used to start transaction for this attachment

Parameters:
Return type:

None

start() → iTransaction[source]

Start distributed transaction for accumulated attachments. On successful return DtcStart interface is disposed automatically.

Return type:

iTransaction

VERSION = 3
class firebird.driver.interfaces.iDtc(intf)[source]

Bases: iVersioned

Class that wraps IDtc interface for use from Python

join(one: iTransaction, two: iTransaction) → iTransaction[source]

Joins 2 independent transactions into distributed transaction. On success both transactions passed to join() are released and pointers to them should not be used any more.

Parameters:
Return type:

iTransaction

start_builder() → iDtcStart[source]

Returns DtcStart interface

Return type:

iDtcStart

VERSION = 2

Metadata

class firebird.driver.interfaces.iMessageMetadata_v3(intf)[source]

Bases: iReferenceCounted

Class that wraps IMessageMetadata v3 interface for use from Python

get_alias(index: int) → str[source]

Returns field alias

Parameters:

index (int)

Return type:

str

get_builder() → iMetadataBuilder[source]

Returns MetadataBuilder interface initialized with this message metadata

Return type:

iMetadataBuilder

get_charset(index: int) → int[source]

Returns character set for character field and text blob

Parameters:

index (int)

Return type:

int

get_count() → int[source]

Returns number of fields/parameters in a message. In all calls, containing index parameter, it’s value should be: 0 <= index < getCount().

Return type:

int

get_field(index: int) → str[source]

Returns field name

Parameters:

index (int)

Return type:

str

get_length(index: int) → int[source]

Returns maximum field length

Parameters:

index (int)

Return type:

int

get_message_length() → int[source]

Returns length of message buffer (use it to allocate memory for the buffer)

Return type:

int

get_null_offset(index: int) → int[source]

Returns offset of null indicator for a field in message buffer

Parameters:

index (int)

Return type:

int

get_offset(index: int) → int[source]

Returns offset of field data in message buffer (use it to access data in message buffer)

Parameters:

index (int)

Return type:

int

get_owner(index: int) → str[source]

Returns relation’s owner name

Parameters:

index (int)

Return type:

str

get_relation(index: int) → str[source]

Returns relation name (from which given field is selected)

Parameters:

index (int)

Return type:

str

get_scale(index: int) → int[source]

Returns scale factor for numeric field

Parameters:

index (int)

Return type:

int

get_subtype(index: int) → int[source]

Returns blob field subtype (0 – binary, 1 – text, etc.)

Parameters:

index (int)

Return type:

int

get_type(index: int) → SQLDataType[source]

Returns field SQL type

Parameters:

index (int)

Return type:

SQLDataType

is_nullable(index: int) → bool[source]

Returns True if field is nullable

Parameters:

index (int)

Return type:

bool

VERSION = 3
class firebird.driver.interfaces.iMessageMetadata(intf)[source]

Bases: iMessageMetadata_v3

Class that wraps IMessageMetadata v4 interface for use from Python

get_aligned_length() → int[source]

Returns length of message buffer taking into an account alignment requirements (use it to allocate memory for an array of buffers and navigate through that array).

Return type:

int

get_alignment() → int[source]

Returns alignment required for message buffer.

Return type:

int

VERSION = 4
class firebird.driver.interfaces.iMetadataBuilder_v3(intf)[source]

Bases: iReferenceCounted

Class that wraps IMetadataBuilder v3 interface for use from Python

add_field() → int[source]

Add field

Return type:

int

get_metadata() → iMessageMetadata[source]

Returns MessageMetadata interface built by this builder

Return type:

iMessageMetadata

move_name_to_index(name: str, index: int) → None[source]

Reorganize fields in a message – move field “name” to given position

Parameters:
Return type:

None

remove(index: int) → None[source]

Remove field

Parameters:

index (int)

Return type:

None

set_charset(index: int, charset: int) → None[source]

Set character set for character field and text blob

Parameters:
Return type:

None

set_length(index: int, length: int) → None[source]

Set maximum length of character field

Parameters:
Return type:

None

set_scale(index: int, scale: int) → None[source]

Set scale factor for numeric field

Parameters:
Return type:

None

set_subtype(index: int, subtype: int) → None[source]

Set blob field subtype

Parameters:
Return type:

None

set_type(index: int, field_type: SQLDataType) → None[source]

Set SQL type of a field

Parameters:
Return type:

None

truncate(count: int) → None[source]

Truncate message to contain not more than count fields

Parameters:

count (int)

Return type:

None

VERSION = 3
class firebird.driver.interfaces.iMetadataBuilder(intf)[source]

Bases: iMetadataBuilder_v3

Class that wraps IMetadataBuilder v4 interface for use from Python

set_alias(index: int, alias: str) → None[source]

Set the alias

Parameters:
Return type:

None

set_field(index: int, field: str) → None[source]

Set field name

Parameters:
Return type:

None

set_owner(index: int, owner: str) → None[source]

Set owner name

Parameters:
Return type:

None

set_relation(index: int, relation: str) → None[source]

Set relation name

Parameters:
Return type:

None

VERSION = 4

SQL execution

class firebird.driver.interfaces.iStatement_v3(intf)[source]

Bases: iReferenceCounted

Class that wraps IStatement v3 interface for use from Python

execute(transaction: iTransaction, in_meta: iMessageMetadata, in_buffer: bytes, out_meta: iMessageMetadata, out_buffer: bytes) → None[source]

Executes any SQL statement except returning multiple rows of data. Partial analogue of isc_dsql_execute2() - in and out XSLQDAs replaced with input and output messages with appropriate buffers.

Parameters:
Return type:

None

free() → None[source]

Free statement, releases interface on success

Return type:

None

get_affected_records() → int[source]

Returns number of records affected by statement

Return type:

int

get_flags() → StatementFlag[source]

Returns flags describing how this statement should be executed, simplified replacement of getType() method

Return type:

StatementFlag

get_info(items: bytes, buffer: bytes) → None[source]

Replaces isc_dsql_sql_info()

Parameters:
Return type:

None

get_input_metadata() → iMessageMetadata[source]

Returns parameters metadata

Return type:

iMessageMetadata

get_output_metadata() → iMessageMetadata[source]

Returns output values metadata

Return type:

iMessageMetadata

get_plan(detailed: bool) → str[source]

Returns statement execution plan

Parameters:

detailed (bool)

Return type:

str

get_type() → StatementType[source]

Statement type, currently can be found only in firebird sources in dsql/dsql.h

Return type:

StatementType

open_cursor(transaction: iTransaction, in_meta: iMessageMetadata, in_buffer: bytes, out_meta: iMessageMetadata, flags: CursorFlag) → iResultSet[source]

Executes SQL statement potentially returning multiple rows of data. Returns ResultSet interface which should be used to fetch that data. Format of output data is defined by outMetadata parameter, leaving it NULL default format may be used. Parameter flags is needed to open bidirectional cursor setting it’s value to IStatement::CURSOR_TYPE_SCROLLABLE.

Parameters:
Return type:

iResultSet

set_cursor_name(name: str) → None[source]

Replaces isc_dsql_set_cursor_name()

Parameters:

name (str)

Return type:

None

VERSION = 3
class firebird.driver.interfaces.iStatement_v4(intf)[source]

Bases: iStatement_v3

Class that wraps IStatement v4 interface for use from Python

create_batch(in_meta: iMessageMetadata, params: bytes) → iBatch[source]

Create new batch

Parameters:
Return type:

iBatch

get_timeout() → int[source]

Return statement timeout

Return type:

int

set_timeout(timeout: int) → None[source]

Set the statement timeout

Parameters:

timeout (int)

Return type:

None

VERSION = 4
class firebird.driver.interfaces.iStatement(intf)[source]

Bases: iStatement_v4

Class that wraps IStatement v4 interface for use from Python

free() → None[source]

Free statement, releases interface on success

Return type:

None

VERSION = 5
class firebird.driver.interfaces.iResultSet_v3(intf)[source]

Bases: iReferenceCounted

Class that wraps IResultSet interface for use from Python

close() → None[source]

Close result set, releases interface on success

Return type:

None

fetch_absolute(position: int, message: bytes) → StateResult[source]

Fetch record by it’s absolute position in result set

Parameters:
Return type:

StateResult

fetch_first(message: bytes) → StateResult[source]

Fetch first record

Parameters:

message (bytes)

Return type:

StateResult

fetch_last(message: bytes) → StateResult[source]

Fetch last record

Parameters:

message (bytes)

Return type:

StateResult

fetch_next(message: bytes) → StateResult[source]

Fetch next record, replaces isc_dsql_fetch(). This method (and other fetch methods) returns completion code Status::RESULT_NO_DATA when EOF is reached, Status::RESULT_OK on success.

Parameters:

message (bytes)

Return type:

StateResult

fetch_prior(message: bytes) → StateResult[source]

Fetch previous record

Parameters:

message (bytes)

Return type:

StateResult

fetch_relative(offset: int, message: bytes) → StateResult[source]

Fetch record by position relative to current

Parameters:
Return type:

StateResult

get_metadata() → iMessageMetadata[source]

Get metadata for messages in result set, specially useful when result set is opened by IAttachment::openCursor() call with NULL output metadata format parameter (this is the only way to obtain message format in this case)

Return type:

iMessageMetadata

is_bof() → bool[source]

Check for BOF

Return type:

bool

is_eof() → bool[source]

Check for EOF

Return type:

bool

set_delayed_output_format(fmt: iMessageMetadata) → None[source]

Important: This item is for ISC API emulation only. It may be gone in future versions. Please do not use it!

Parameters:

fmt (iMessageMetadata)

Return type:

None

VERSION = 3
class firebird.driver.interfaces.iResultSet(intf)[source]

Bases: iResultSet_v3

Class that wraps IResultSet interface for use from Python

get_info(items: bytes, buffer: bytes) → None[source]

Returns information about result set.

Parameters:
Return type:

None

VERSION = 5
class firebird.driver.interfaces.iBatch_v3(intf)[source]

Bases: iReferenceCounted

Class that wraps IBatch interface for use from Python

add(count: int, in_buffer: bytes) → None[source]

Adds count messages from inBuffer to the batch. Total size of messages that can be added to the batch is limited by TAG_BUFFER_BYTES_SIZE parameter of batch creation.

Parameters:
Return type:

None

add_blob(length: int, in_buffer: bytes, id_: ISC_QUAD, params: bytes) → None[source]

Adds single blob having length bytes from in_buffer to the batch, blob identifier is located at id_ address. If blob should be created with non-default parameters BPB may be passed (format matches one used in create_blob). Total size of inline blobs that can be added to the batch (including optional BPBs, blob headers, segment sizes and taking into an accoount alignment) is limited by TAG_BUFFER_BYTES_SIZE parameter of batch creation (affects all blob-oriented methods except register_blob()).

Parameters:
Return type:

None

add_blob_stream(length: int, in_buffer: bytes) → None[source]

Adds blob data (this can be multiple objects or part of single blob) to the batch. Header of each blob in the stream is aligned at get_blob_alignment() boundary and contains 3 fields: first - 8-bytes blob identifier (in ISC_QUAD format), second - 4-bytes length of blob, third – 4-bytes length of BPB. Blob header should not cross boundaries of buffer in this function call. BPB data is placed right after header, blob data goes next. Length of blob includes BPB (if it present). All data may be distributed between multiple add_blob_stream() calls. Blob data in turn may be structured in case of segmented blob, see chapter “Modifying data in a batch” in Using_OO_API guide.

Parameters:
Return type:

None

append_blob_data(length: int, in_buffer: bytes) → None[source]

Extend last added blob: append length bytes taken from in_buffer to it.

Parameters:
Return type:

None

cancel() → None[source]

Clear messages and blobs buffers, return batch to a state it had right after creation.

Note

Being reference counted interface batch does not contain any special function to close it, please use release() for this purposes.

Return type:

None

close() → None[source]

Sets BPB which will be used for all blobs missing non-default BPB. Must be called before adding any message or blob to batch.

Return type:

None

execute(transaction: iTransaction) → iBatchCompletionState[source]

Execute batch with parameters passed to it in the messages. If parameter MULTIERROR is not set in parameters block when creating the batch execution will be stopped after first error, in MULTIERROR mode an unlimited number of errors can happen, after an error execution is continued from the next message. This function returns iBatchCompletionState interface that contains all requested information about the results of batch execution.

Parameters:

transaction (iTransaction)

Return type:

iBatchCompletionState

get_blob_alignment() → int[source]

Returns required alignment for the data placed into the buffer of add_blob_stream().

Return type:

int

get_metadata() → iMessageMetadata[source]

Returns format of metadata used in batch’s messages.

Return type:

iMessageMetadata

register_blob(existing: ISC_QUAD, id_: ISC_QUAD)[source]

Makes it possible to use in batch blobs added using standard Blob interface. This function contains 2 ISC_QUAD* parameters, it’s important not to mix them – first parameter (existing) is a blob identifier, already added out of batch scope, second (id_) is blob identifier that will be placed in a message in this batch.

Parameters:
set_default_bpb(bpb: bytes) → None[source]

Sets BPB which will be used for all blobs missing non-default BPB. Must be called before adding any message or blob to batch.

Parameters:

bpb (bytes)

Return type:

None

BLOB_ID_ENGINE = 1
BLOB_ID_USER = 2
BLOB_NONE = 0
BLOB_SEGHDR_ALIGN = 2
BLOB_STREAM = 3
INF_BLOBS_BYTES_SIZE = 12
INF_BLOB_ALIGNMENT = 13
INF_BLOB_HEADER = 14
INF_BUFFER_BYTES_SIZE = 10
INF_DATA_BYTES_SIZE = 11
TAG_BLOB_POLICY = 4
TAG_BUFFER_BYTES_SIZE = 3
TAG_DETAILED_ERRORS = 5
TAG_MULTIERROR = 1
TAG_RECORD_COUNTS = 2
VERSION = 3
class firebird.driver.interfaces.iBatch(intf)[source]

Bases: iBatch_v3

Class that wraps IBatch interface for use from Python

close() → None[source]

Sets BPB which will be used for all blobs missing non-default BPB. Must be called before adding any message or blob to batch.

Return type:

None

get_info(items: bytes, buffer: bytes) → None[source]

Requests information about batch.

Parameters:
Return type:

None

VERSION = 4
class firebird.driver.interfaces.iBatchCompletionState(intf)[source]

Bases: iDisposable

Class that wraps IBatchCompletionState interface for use from Python

find_error(pos: int) → int[source]

Finds next (starting with pos) message which processing caused an error. When such message is missing NO_MORE_ERRORS constant is returned. Number of status vectors, returned in this interface, is limited by the value of DETAILED_ERRORS parameter of batch creation.

Parameters:

pos (int)

Return type:

int

get_size() → int[source]

Returns the total number of processed messages.

Return type:

int

get_state(pos: int) → int[source]

Returns the result of execution of message number pos. On any error with the message this is EXECUTE_FAILED constant, value returned on success depends upon presence of RECORD_COUNTS parameter of batch creation. When it present and has non-zero value number of records inserted, updated or deleted during particular message processing is returned, else SUCCESS_NO_INFO constant is returned.

Parameters:

pos (int)

Return type:

int

get_status(pos: int) → iStatus[source]

Returns detailed information (full status vector) about an error that took place when processing pos message.

Parameters:

pos (int)

Return type:

iStatus

EXECUTE_FAILED = -1
NO_MORE_ERRORS = 4294967295
SUCCESS_NO_INFO = -2
VERSION = 3

Events

class firebird.driver.interfaces.iEvents_v3(intf)[source]

Bases: iReferenceCounted

Class that wraps IEvents interface for use from Python

cancel() → None[source]

Cancels events monitoring started by IAttachment::queEvents()

Return type:

None

VERSION = 3
class firebird.driver.interfaces.iEvents(intf)[source]

Bases: iEvents_v3

Class that wraps IEvents interface for use from Python

cancel() → None[source]

Cancels events monitoring started by IAttachment::queEvents()

Return type:

None

VERSION = 4

Utilities

class firebird.driver.interfaces.iTimerControl(intf)[source]

Bases: iVersioned

Class that wraps ITimerControl interface for use from Python

start(timer: iTimerImpl, microseconds: int) → None[source]

Start ITimer to alarm after given delay (in microseconds, 10-6 seconds). Timer will be waked up only once after this call.

Parameters:
Return type:

None

stop(timer: iTimerImpl) → None[source]

Stop ITimer. It’s not an error to stop not started timer thus avoiding problems with races between stop() and timer alarm.

Parameters:

timer (iTimerImpl)

Return type:

None

VERSION = 2
class firebird.driver.interfaces.iUtil_v2(intf)[source]

Bases: iVersioned

Class that wraps IUtil v2 interface for use from Python

decode_date(date: c_int | bytes) → date[source]

Replaces isc_decode_sql_date()

Parameters:

date (c_int | bytes)

Return type:

date

decode_time(atime: c_uint | bytes) → time[source]

Replaces isc_decode_sql_time()

Parameters:

atime (c_uint | bytes)

Return type:

time

dump_blob(blob_id: ISC_QUAD, attachment: iAttachment, transaction: iTransaction, filename: str, is_text: bool) → None[source]

Save blob to file

Parameters:
Return type:

None

encode_date(date: date) → c_int[source]

Replaces isc_encode_sql_date()

Parameters:

date (date)

Return type:

c_int

encode_time(atime: time) → c_uint[source]

Replaces isc_encode_sql_time()

Parameters:

atime (time)

Return type:

c_uint

execute_create_database(stmt: str, dialect: int) → iAttachment[source]

Execute “CREATE DATABASE …” statement – ISC trick with NULL statement handle does not work with interfaces.

Parameters:
Return type:

iAttachment

format_status(status: iStatus, encoding: str = 'UTF-8') → str[source]

Replaces fb_interpret().

Parameters:
Return type:

str

get_client_version() → int[source]

Returns integer, containing major version in byte 0 and minor version in byte 1

Return type:

int

get_fb_version(attachment: iAttachment, callback: iVersionCallbackImpl) → None[source]

Produce long and beautiful report about firebird version used. It may be seen in ISQL when invoked with -Z switch.

Parameters:
Return type:

None

get_perf_counters(attachment: iAttachment, counters_set: str) → int[source]

Get statistics for given attachment

Parameters:
Return type:

int

get_xpb_builder(kind: XpbKind, buffer: bytes = None) → iXpbBuilder[source]

Returns XpbBuilder interface.

Parameters:
Return type:

iXpbBuilder

load_blob(blob_id: ISC_QUAD, attachment: iAttachment, transaction: iTransaction, filename: str, is_text: bool) → None[source]

Load blob from file

Parameters:
Return type:

None

set_offsets(metadata: iMessageMetadata, callback: iOffsetsCallbackImp) → int[source]

Sets valid offsets in MessageMetadata. Performs calls to callback in OffsetsCallback for each field/parameter.

Parameters:
Return type:

int

VERSION = 2
class firebird.driver.interfaces.iUtil(intf)[source]

Bases: iUtil_v2

Class that wraps IUtil v4 interface for use from Python

decode_time_tz(timetz: ISC_TIME_TZ | bytes) → time[source]

Decodes TIME WITH TIMEZONE from internal format to datetime.time with tzinfo.

Parameters:

timetz (ISC_TIME_TZ | bytes)

Return type:

time

decode_time_tz_ex(timetz: ISC_TIME_TZ_EX, hours: c_uint, minutes: c_uint, seconds: c_uint, fractions: c_uint, zone_bufer: bytes)[source]

TODO

Parameters:
decode_timestamp_tz(timestamptz: ISC_TIMESTAMP_TZ | bytes) → datetime[source]

Decodes TIMESTAMP WITH TIMEZONE from internal format to datetime.datetime with tzinfo.

Parameters:

timestamptz (ISC_TIMESTAMP_TZ | bytes)

Return type:

datetime

decode_timestamp_tz_ex(timestamptz: ISC_TIMESTAMP_TZ_EX, year: c_uint, month: c_uint, day: c_uint, hours: c_uint, minutes: c_uint, seconds: c_uint, fractions: c_uint, zone_bufer: bytes)[source]

TODO

Parameters:
encode_time_tz(time: time) → bytes[source]

Encodes datetime.time with tzinfo into internal format for TIME WITH TIMEZONE.

Parameters:

time (time)

Return type:

bytes

encode_timestamp_tz(timestamp: datetime) → bytes[source]

Encodes datetime.datetime with tzinfo into internal format for TIMESTAMP WITH TIMEZONE.

Parameters:

timestamp (datetime)

Return type:

bytes

get_decfloat16() → iDecFloat16[source]

Returns iDecFloat16 interface.

Return type:

iDecFloat16

get_decfloat34() → iDecFloat34[source]

Returns iDecFloat34 interface.

Return type:

iDecFloat34

get_int128() → iInt128[source]

Returns iInt128 interface.

Return type:

iInt128

STR_SIZE = 200
VERSION = 4
class firebird.driver.interfaces.iDecFloat16(intf)[source]

Bases: iVersioned

Class that wraps IDecFloat16 interface for use from Python

from_bcd(value: BCD, into: c_ulong = None) → c_ulong[source]

Make decimal float value from BCD

Parameters:
Return type:

c_ulong

from_str(value: str, into: c_ulong = None) → c_ulong[source]

Make decimal float value from string

Parameters:
Return type:

c_ulong

to_bcd(value: c_ulong) → BCD[source]

Convert decimal float value to BCD

Parameters:

value (c_ulong)

Return type:

BCD

to_str(value: c_ulong) → str[source]

Convert decimal float value to string

Parameters:

value (c_ulong)

Return type:

str

BCD_SIZE = 16
STR_SIZE = 24
VERSION = 2
class firebird.driver.interfaces.iDecFloat34(intf)[source]

Bases: iVersioned

Class that wraps IDecFloat34 interface for use from Python

from_bcd(value: BCD, into: c_ulong_Array_2 = None) → c_ulong_Array_2[source]

Make decimal float value from BCD

Parameters:

  • value (BCD)

  • into (c_ulong_Array_2)

Return type:

c_ulong_Array_2

from_str(value: str, into: c_ulong_Array_2 = None) → c_ulong_Array_2[source]

Make decimal float value from string

Parameters:

  • value (str)

  • into (c_ulong_Array_2)

Return type:

c_ulong_Array_2

to_bcd(value: c_ulong_Array_2) → BCD[source]

Convert decimal float value to BCD

Parameters:

value (c_ulong_Array_2)

Return type:

BCD

to_str(value: c_ulong_Array_2) → str[source]

Convert decimal float value to string

Parameters:

value (c_ulong_Array_2)

Return type:

str

BCD_SIZE = 34
STR_SIZE = 43
VERSION = 2
class firebird.driver.interfaces.iInt128(intf)[source]

Bases: iVersioned

Class that wraps IInt128 interface for use from Python

from_str(value: str, scale: int, into: c_ulong_Array_2 = None) → c_ulong_Array_2[source]

Converts string to INT128

Parameters:

  • value (str)

  • scale (int)

  • into (c_ulong_Array_2)

Return type:

c_ulong_Array_2

to_str(value: c_ulong_Array_2, scale: int) → str[source]

Converts INT128 to string

Parameters:

  • value (c_ulong_Array_2)

  • scale (int)

Return type:

str

STR_SIZE = 46
VERSION = 2

Other

class firebird.driver.interfaces.iPluginManager(intf)[source]

Bases: iVersioned

IPluginManager interface wrapper. This is only STUB.

VERSION = 2
class firebird.driver.interfaces.iRequest_v3(intf)[source]

Bases: iReferenceCounted

Class that wraps IRequest interface for use from Python

free() → None[source]

Information not available

Return type:

None

get_info(level: int, items: bytes, buffer: bytes) → None[source]

Information not available

Parameters:
Return type:

None

receive(level: int, msg_type: int, message: bytes) → None[source]

Information not available

Parameters:
Return type:

None

send(level: int, msg_type: int, message: bytes) → None[source]

Information not available

Parameters:
Return type:

None

start(transaction: iTransaction, level: int) → None[source]

Information not available

Parameters:
Return type:

None

start_and_send(transaction: iTransaction, level: int, msg_type: int, message: bytes) → None[source]

Information not available

Parameters:
Return type:

None

unwind(level: int) → None[source]

Information not available

Parameters:

level (int)

Return type:

None

VERSION = 3
class firebird.driver.interfaces.iRequest(intf)[source]

Bases: iRequest_v3

Class that wraps IRequest interface for use from Python

free() → None[source]

Information not available

Return type:

None

VERSION = 4

Interface implementations

class firebird.driver.interfaces.iVersionedImpl[source]

Bases: object

Base class for objects that implement IVersioned interface

VERSION = 1
property vtable
class firebird.driver.interfaces.iReferenceCountedImpl[source]

Bases: iVersionedImpl

IReferenceCounted interface wrapper

add_ref() → None[source]

Increase the reference by one

Return type:

None

release() → int[source]

Decrease the reference by one

Return type:

int

VERSION = 2
class firebird.driver.interfaces.iDisposableImpl[source]

Bases: iVersionedImpl

IDisposable interface wrapper

dispose() → None[source]

Dispose the interfaced object

Return type:

None

VERSION = 2
class firebird.driver.interfaces.iVersionCallbackImpl[source]

Bases: iVersionedImpl

Class that wraps IVersionCallback interface for use from Python

callback(text: str) → None[source]

Method called by engine

Parameters:

text (str)

Return type:

None

VERSION = 2
class firebird.driver.interfaces.iCryptKeyCallbackImpl[source]

Bases: iVersionedImpl

Class that wraps ICryptKeyCallback interface for use from Python

get_crypt_key(data: bytes, max_key_size: int) → bytes[source]

Should return crypt key

Parameters:
Return type:

bytes

VERSION = 2
class firebird.driver.interfaces.iOffsetsCallbackImp[source]

Bases: iVersionedImpl

Class that wraps IOffsetsCallback interface for use from Python

set_offset(index: int, offset: int, nullOffset: int) → None[source]

Method called by engine

Parameters:
Return type:

None

VERSION = 2
class firebird.driver.interfaces.iEventCallbackImpl[source]

Bases: iReferenceCountedImpl

IEventCallback interface wrapper

events_arrived(events: bytes) → None[source]

Method called by engine

Parameters:

events (bytes)

Return type:

None

VERSION = 3
class firebird.driver.interfaces.iTimerImpl[source]

Bases: iReferenceCountedImpl

Class that wraps ITimer interface for use from Python

handler() → None[source]

Timer callback handler

Return type:

None

VERSION = 3