Compliance to PyDB API 2.0¶
Full text of Python Database API 2.0 (PEP 249) is available at http://www.python.org/dev/peps/pep-0249/
Unsupported Optional Features¶
Cursor.nextset
This method is not implemented because the database engine does not support opening multiple result sets simultaneously with a single cursor.
Supported Optional Features¶
Connection.Error
,Connection.ProgrammingError
, etc.All exception classes defined by the DB API standard are exposed on the Connection objects as attributes (in addition to being available at module scope).
Cursor.connection
This read-only attribute return a reference to the Connection object on which the cursor was created.
Nominally Supported Optional Features¶
As required by the spec, the value of this attribute is observed with respect to the
fetchmany
method. However, changing the value of this attribute does not make any difference in fetch efficiency because the database engine only supports fetching a single row at a time.Although this method is present, it does nothing, as allowed by the spec.
Although this method is present, it does nothing, as allowed by the spec.
Caveats¶
Firebird-driver offers a large feature set beyond the minimal requirements of the Python DB API. This section attempts to document only those features that overlap with the DB API.
commit(retaining=False)
rollback(retaining=False, savepoint=None)
The
commit
androllback
methods accept an optional boolean parameterretaining
(defaultFalse
) that indicates whether the transactional context of the transaction being resolved should be recycled. For details, see the Advanced Transaction Control: Retaining Operations section of this document. Therollback
method accepts an optional string parametersavepoint
that causes the transaction to roll back only as far as the designated savepoint, rather than rolling back entirely. For details, see the Advanced Transaction Control: Savepoints section of this document.
Firebird-driver makes absolutely no guarantees about
description
except those required by the Python Database API Specification 2.0 (that is,description
is eitherNone
or a sequence of 7-element sequences). Therefore, client programmers should not rely ondescription
being an instance of a particular class or type. Firebird-driver provides several named positional constants to be used as indices into a given element ofdescription
. The contents of alldescription
elements are defined by the DB API spec; these constants are provided merely for convenience.DESCRIPTION_NAME DESCRIPTION_TYPE_CODE DESCRIPTION_DISPLAY_SIZE DESCRIPTION_INTERNAL_SIZE DESCRIPTION_PRECISION DESCRIPTION_SCALE DESCRIPTION_NULL_OKHere is an example of accessing the name of the first field in the
description
of cursorcur
:nameOfFirstField = cur.description[0][firebird.driver.DESCRIPTION_NAME]For more information, see the documentation of Cursor.description in the DB API Specification.
Although
Cursor
in Firebird-driver implement this attribute, the database engine’s own support for the determination of “rows affected”/”rows selected” is quirky. The database engine only supports the determination of rowcount forINSERT
,UPDATE
,DELETE
, andSELECT
statements. When stored procedures become involved, row count figures are usually not available to the client. Determining rowcount forSELECT
statements is problematic: the rowcount is reported as zero until at least one row has been fetched from the result set, and the rowcount is misreported if the result set is larger than 1302 rows. The server apparently marshals result sets internally in batches of 1302, and will misreport the rowcount for result sets larger than 1302 rows until the 1303rd row is fetched, result sets larger than 2604 rows until the 2605th row is fetched, and so on, in increments of 1302. As required by the Python DB API Spec, the rowcount attribute “is -1 in case no executeXX() has been performed on the cursor or the rowcount of the last operation is not determinable by the interface”.Note
This attribute is just an alias for
Cursor.affected_rows
property.