
=============
FDB Reference
=============

.. module:: fdb
   :synopsis: Python Database API 2.0 Compliant driver for Firebird

Module globals
==============

.. data:: __version__

   Current driver version, string.

.. data:: apilevel

   String constant stating the supported DB API level (2.0).

.. data:: threadsafety

   Integer constant stating the level of thread safety the interface supports. 

   Curretly `1` = Threads may share the module, but not connections. 

.. data:: paramstyle

   String constant stating the type of parameter marker
   formatting expected by the interface.

   `'qmark'`    = Question mark style, e.g. '...WHERE name=?' 

.. data:: DESCRIPTION_NAME
.. data:: DESCRIPTION_TYPE_CODE
.. data:: DESCRIPTION_DISPLAY_SIZE
.. data:: DESCRIPTION_INTERNAL_SIZE
.. data:: DESCRIPTION_PRECISION
.. data:: DESCRIPTION_SCALE
.. data:: DESCRIPTION_NULL_OK

   Helper constants for work with :attr:`Cursor.description` content.

.. data:: ISOLATION_LEVEL_READ_COMMITED_LEGACY

   TPB for R/W WAIT READ COMMITTED NO RECORD VERSION transaction.

.. data:: ISOLATION_LEVEL_READ_COMMITED

   TPB for R/W WAIT READ COMMITTED RECORD VERSION transaction.

.. data:: ISOLATION_LEVEL_REPEATABLE_READ
.. data:: ISOLATION_LEVEL_SNAPSHOT

   TPB's for R/W WAIT SNAPSHOT transaction.

.. data:: ISOLATION_LEVEL_SERIALIZABLE
.. data:: ISOLATION_LEVEL_SNAPSHOT_TABLE_STABILITY

   TPB's for R/W WAIT SNAPSHOT TABLE STABILITY transaction.

.. data:: ISOLATION_LEVEL_READ_COMMITED_RO

   TPB for R/O WAIT READ COMMITTED RECORD VERSION transaction.

.. data:: MAX_BLOB_SEGMENT_SIZE

.. data:: charset_map

   Python dictionary that maps Firebird character set names (key) to Python character sets (value).

.. data:: ODS_FB_20
.. data:: ODS_FB_21
.. data:: ODS_FB_25

   ODS version numbers introduced by Firebird engine version.

.. data:: IMPLEMENTATION_NAMES

.. data:: PROVIDER_NAMES

.. data:: DB_CLASS_NAMES

Exceptions
==========

.. autoexception:: Warning
   :show-inheritance:

.. autoexception:: Error
   :show-inheritance:

.. autoexception:: InterfaceError
   :show-inheritance:

.. autoexception:: DatabaseError
   :show-inheritance:

.. autoexception:: DataError
   :show-inheritance:

.. autoexception:: OperationalError
   :show-inheritance:

.. autoexception:: IntegrityError
   :show-inheritance:

.. autoexception:: InternalError
   :show-inheritance:

.. autoexception:: ProgrammingError
   :show-inheritance:

.. autoexception:: NotSupportedError
   :show-inheritance:

.. autoexception:: TransactionConflict
   :show-inheritance:

This is the exception inheritance layout::

    StandardError
    |__Warning
    |__Error
       |__InterfaceError
       |__DatabaseError
          |__DataError
          |__OperationalError
          |__IntegrityError
          |__InternalError
          |__ProgrammingError
          |__NotSupportedError

Functions
=========

.. autofunction:: connect

.. autofunction:: create_database

.. autofunction:: load_api

Classes
=======

Connection
----------

.. autoclass:: Connection
   :member-order: groupwise
   :members:
   :inherited-members:

.. autoclass:: ConnectionWithSchema
   :member-order: groupwise
   :members:
   :undoc-members:

.. note::

   For list of methods see :class:`fdb.schema.Schema`.

Cursor
------

.. autoclass:: Cursor
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Transaction
-----------

.. autoclass:: Transaction
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

PreparedStatement
-----------------

.. autoclass:: PreparedStatement
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

ConnectionGroup
---------------

.. autoclass:: ConnectionGroup
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

TransactionContext
------------------

.. autoclass:: TransactionContext
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

EventConduit
------------

.. autoclass:: EventConduit
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

BlobReader
----------

.. autoclass:: BlobReader
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

TPB
---

.. autoclass:: TPB
   :member-order: groupwise
   :members:
   :undoc-members:

TableReservation
----------------

.. autoclass:: TableReservation
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:


Internally used classes exposed to driver users
===============================================

.. module:: fdb.fbcore
   :synopsis: Implementation of Firebird driver

RowMapping
----------

.. autoclass:: _RowMapping
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

EventBlock
----------

.. autoclass:: EventBlock
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

TableAccessStats
----------------

.. autoclass:: _TableAccessStats
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

.. _services_api:

Services
========

.. module:: fdb.services
   :synopsis: Submodule for work with Firebird Services

Module globals
--------------

.. data:: SHUT_LEGACY

.. data:: SHUT_NORMAL

.. data:: SHUT_MULTI

.. data:: SHUT_SINGLE

.. data:: SHUT_FULL

   These constants are to be passed as the `shutdown_mode` parameter to :meth:`Connection.shutdown`
   and :meth:`Connection.bring_online`.


.. data:: SHUT_FORCE

.. data:: SHUT_DENY_NEW_TRANSACTIONS

.. data:: SHUT_DENY_NEW_ATTACHMENTS

   These constants are to be passed as the `shutdown_method` parameter to :meth:`Connection.shutdown`

.. data:: WRITE_FORCED

.. data:: WRITE_BUFFERED

   These constants are to be passed as the `mode` parameter to :meth:`Connection.setWriteMode`

.. data:: ACCESS_READ_WRITE

.. data:: ACCESS_READ_ONLY

   These constants are to be passed as the `mode` parameter to :meth:`Connection.setAccessMode`

.. data:: CAPABILITY_MULTI_CLIENT

.. data:: CAPABILITY_REMOTE_HOP

.. data:: CAPABILITY_SERVER_CONFIG

.. data:: CAPABILITY_QUOTED_FILENAME

.. data:: CAPABILITY_NO_SERVER_SHUTDOWN

   These constants are return values of :meth:`Connection.get_server_capabilities`

.. data:: STATS_TOTAL_TIME

.. data:: STATS_TIME_DELTA

.. data:: STATS_PAGE_READS

.. data:: STATS_PAGE_WRITES

   These constants are options for :meth:`Connection.backup`/:meth:`Connection.restore` 'stats' parameter.

Functions
---------

.. autofunction:: connect

Connection
----------

.. autoclass:: Connection
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

User
----

.. autoclass:: User
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Database schema
===============

.. module:: fdb.schema
   :synopsis: Submodule for work with database metadata (schema)

Functions
---------

.. autofunction:: get_grants

.. autofunction:: isKeyword


Schema
------

.. autoclass:: Schema
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

BaseSchemaItem
--------------

.. autoclass:: BaseSchemaItem
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Collation
---------

.. autoclass:: Collation
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

CharacterSet
------------

.. autoclass:: CharacterSet
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

DatabaseException
-----------------

.. autoclass:: DatabaseException
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Sequence
--------

.. autoclass:: Sequence
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Index
-----

.. autoclass:: Index
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

TableColumn
-----------

.. autoclass:: TableColumn
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

ViewColumn
----------

.. autoclass:: ViewColumn
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Domain
------

.. autoclass:: Domain
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Dependency
----------

.. autoclass:: Dependency
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Constraint
----------

.. autoclass:: Constraint
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Table
-----

.. autoclass:: Table
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

View
----

.. autoclass:: View
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Trigger
-------

.. autoclass:: Trigger
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

ProcedureParameter
------------------

.. autoclass:: ProcedureParameter
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Procedure
---------

.. autoclass:: Procedure
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Role
----

.. autoclass:: Role
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

FunctionArgument
----------------

.. autoclass:: FunctionArgument
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Function
--------

.. autoclass:: Function
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

DatabaseFile
------------

.. autoclass:: DatabaseFile
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Shadow
------

.. autoclass:: Shadow
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

Privilege
-------------

.. autoclass:: Privilege
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

SchemaVisitor
-------------

.. autoclass:: SchemaVisitor
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:


Monitoring information
======================

.. module:: fdb.monitor
   :synopsis: Submodule for work with database monitoring tables

Constants
---------

.. data:: SHUTDOWN_MODE_ONLINE
.. data:: SHUTDOWN_MODE_MULTI
.. data:: SHUTDOWN_MODE_SINGLE
.. data:: SHUTDOWN_MODE_FULL

   Shutdown modes for :attr:`DatabaseInfo.shutdown_mode`.

.. data:: BACKUP_STATE_NORMAL
.. data:: BACKUP_STATE_STALLED
.. data:: BACKUP_STATE_MERGE

   Backup states for  :attr:`DatabaseInfo.backup_state`.

.. data:: STATE_IDLE
.. data:: STATE_ACTIVE

   States for :attr:`AttachmentInfo.state`, :attr:`TransactionInfo.state`.
   and :attr:`StatementInfo.state`.

.. data:: ISOLATION_CONSISTENCY
.. data:: ISOLATION_CONCURRENCY
.. data:: ISOLATION_READ_COMMITTED_RV
.. data:: ISOLATION_READ_COMMITTED_NO_RV

   Isolation modes for :attr:`TransactionInfo.isolation_mode`.

.. data:: INFINITE_WAIT
.. data:: NO_WAIT

   Special timeout values for :attr:`TransactionInfo.lock_timeout`.

.. data:: STAT_DATABASE
.. data:: STAT_ATTACHMENT
.. data:: STAT_TRANSACTION
.. data:: STAT_STATEMENT
.. data:: STAT_CALL

   Group codes for :attr:`IOStatsInfo.group`.

Monitor
-------

.. autoclass:: Monitor
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

BaseInfoItem
------------

.. autoclass:: BaseInfoItem
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

DatabaseInfo
------------

.. autoclass:: DatabaseInfo
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

AttachmentInfo
--------------

.. autoclass:: AttachmentInfo
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

TransactionInfo
---------------

.. autoclass:: TransactionInfo
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

StatementInfo
-------------

.. autoclass:: StatementInfo
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

CallStackInfo
-------------

.. autoclass:: CallStackInfo
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

IOStatsInfo
-----------

.. autoclass:: IOStatsInfo
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:

ContextVariableInfo
-------------------

.. autoclass:: ContextVariableInfo
   :member-order: groupwise
   :members:
   :inherited-members:
   :undoc-members:


Utilities
=========

.. module:: fdb.utils
   :synopsis: Submodule with various classes and functions


Functions
---------

.. autofunction:: update_meta
.. autofunction:: iter_class_properties
.. autofunction:: iter_class_variables
.. autofunction:: embed_attributes

LateBindingProperty
-------------------

.. autoclass:: LateBindingProperty
   :member-order: groupwise
   :members:

Iterator
--------

.. autoclass:: Iterator
   :member-order: groupwise
   :members: __iter__, next, __next__
   :inherited-members:
   :undoc-members:

EmbeddedProperty
----------------

.. autoclass:: EmbeddedProperty
   :member-order: groupwise
   :members: 

EmbeddedAttribute
-----------------

.. autoclass:: EmbeddedAttribute
   :member-order: groupwise
   :members: 

.. module:: fdb.blr
   :synopsis: Python ctypes interface to Firebird client library (BLR)

.. module:: fdb.ibase
   :synopsis: Python ctypes interface to Firebird client library

ctypes interface to Firebird client library
===========================================

:ref:`ctypes <python:module-ctypes>` interface to `fbclient.so/dll` is defined in submodule :mod:`fdb.ibase`
and :mod:`fdb.blr`.

.. autoclass:: fbclient_API
   :member-order: groupwise
   :members: 

