PyPI 官网下载 | psycopg2-binary-2.8.4.tar.gz

PEP: 249 Title: Python Database API Specification v2.0 Version: $Revision: 1555 $ Author: db-sig@python.org (Python Database SIG) Editor: mal@lemburg.com (Marc-Andre Lemburg) Status: Final Type: Informational Replaces: 248 Release-Date: 07 Apr 1999 Introduction This API has been defined to encourage similarity between the Python modules that are used to access databases. By doing this, we hope to achieve a consistency leading to more easily understood modules, code that is generally more portable across databases, and a broader reach of database connectivity from Python. The interface specification consists of several sections: * Module Interface * Connection Objects * Cursor Objects * DBI Helper Objects * Type Objects and Constructors * Implementation Hints * Major Changes from 1.0 to 2.0 Comments and questions about this specification may be directed to the SIG for Database Interfacing with Python (db-sig@python.org). For more information on database interfacing with Python and available packages see the Database Topic Guide at http://www.python.org/topics/database/. This document describes the Python Database API Specification 2.0 and a set of common optional extensions. The previous version 1.0 version is still available as reference, in PEP 248. Package writers are encouraged to use this version of the specification as basis for new interfaces. Module Interface Access to the database is made available through connection objects. The module must provide the following constructor for these: connect(parameters...) Constructor for creating a connection to the database. Returns a Connection Object. It takes a number of parameters which are database dependent. [1] These module globals must be defined: apilevel String constant stating the supported DB API level. Currently only the strings '1.0' and '2.0' are allowed. If not given, a DB-API 1.0 level interface should be assumed. threadsafety Integer constant stating the level of thread safety the interface supports. Possible values are: 0 Threads may not share the module. 1 Threads may share the module, but not connections. 2 Threads may share the module and connections. 3 Threads may share the module, connections and cursors. Sharing in the above context means that two threads may use a resource without wrapping it using a mutex semaphore to implement resource locking. Note that you cannot always make external resources thread safe by managing access using a mutex: the resource may rely on global variables or other external sources that are beyond your control. paramstyle String constant stating the type of parameter marker formatting expected by the interface. Possible values are [2]: 'qmark' Question mark style, e.g. '...WHERE name=?' 'numeric' Numeric, positional style, e.g. '...WHERE name=:1' 'named' Named style, e.g. '...WHERE name=:name' 'format' ANSI C printf format codes, e.g. '...WHERE name=%s' 'pyformat' Python extended format codes, e.g. '...WHERE name=%(name)s' The module should make all error information available through these exceptions or subclasses thereof: Warning Exception raised for important warnings like data truncations while inserting, etc. It must be a subclass of the Python StandardError (defined in the module exceptions). Error Exception that is the base class of all other error exceptions. You can use this to catch all errors with one single 'except' statement. Warnings are not considered errors and thus should not use this class as base. It must be a subclass of the Python StandardError (defined in the module exceptions). InterfaceError Exception raised for errors that are related to the database interface rather than the database itself. It must be a subclass of Error. DatabaseError Exception raised for errors that are related to the database. It must be a subclass of Error. DataError Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc. It must be a subclass of DatabaseError. OperationalError Exception raised for errors that are related to the database's operation and not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, a memory allocation error occurred during processing, etc. It must be a subclass of DatabaseError. IntegrityError Exception raised when the relational integrity of the database is affected, e.g. a foreign key check fails. It must be a subclass of DatabaseError. InternalError Exception raised when the database encounters an internal error, e.g. the cursor is not valid anymore, the transaction is out of sync, etc. It must be a subclass of DatabaseError. ProgrammingError Exception raised for programming errors, e.g. table not found or already exists, syntax error in the SQL statement, wrong number of parameters specified, etc. It must be a subclass of DatabaseError. NotSupportedError Exception raised in case a method or database API was used which is not supported by the database, e.g. requesting a .rollback() on a connection that does not support transaction or has transactions turned off. It must be a subclass of DatabaseError. This is the exception inheritance layout: StandardError |__Warning |__Error |__InterfaceError |__DatabaseError |__DataError |__OperationalError |__IntegrityError |__InternalError |__ProgrammingError |__NotSupportedError Note: The values of these exceptions are not defined. They should give the user a fairly good idea of what went wrong, though. Connection Objects Connection Objects should respond to the following methods: .close() Close the connection now (rather than whenever __del__ is called). The connection will be unusable from this point forward; an Error (or subclass) exception will be raised if any operation is attempted with the connection. The same applies to all cursor objects trying to use the connection. Note that closing a connection without committing the changes first will cause an implicit rollback to be performed. .commit() Commit any pending transaction to the database. Note that if the database supports an auto-commit feature, this must be initially off. An interface method may be provided to turn it back on. Database modules that do not suppor