<html><head><!-- THIS PAGE IS AUTOMATICALLY GENERATED. DO NOT EDIT. --><!-- Fri Aug 31 01:24:36 2001 --><!-- USING HT2HTML 1.1 --><!-- SEE http://www.python.org/~bwarsaw/software/pyware.html --><!-- User-specified headers:
Title: Python Database API v2.0
-->
<title>Python Database API v2.0</title><meta name="description" content="Version 2.0 of the standard Python database interface."></head>
<body bgcolor="#ffffff" text="#000000" topmargin="0" leftmargin="0" marginwidth="0" marginheight="0" link="#0000bb" vlink="#551a8b" alink="#ff0000">
<!-- BEGIN DSR EDIT 2002.02.11 -->
<font size="-2">
This is a local copy of the specification. The online source copy is available at
<a href="http://www.python.org/topics/database/DatabaseAPI-2.0.html">http://www.python.org/topics/database/DatabaseAPI-2.0.html</a>
</font>
<hr>
<!-- END DSR EDIT 2002.02.11 -->
<h3>Python Database API Specification 2.0</h3>
<p>
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.
</p><p>
The interface specification consists of several sections:
</p><p>
</p><ul>
<li> <a href="#module">Module Interface</a>
</li><li> <a href="#connection">Connection Objects</a>
</li><li> <a href="#cursor">Cursor Objects</a>
</li><li> <a href="#types">Type Objects and Constructors</a>
</li><li> <a href="#hints">Implementation Hints</a>
</li><li> <a href="#changes">Major Changes from 1.0 to 2.0</a>
</li></ul>
<p>
Comments and questions about this specification may be directed
to the <a href="mailto:db-sig@python.org">SIG for Database
Interfacing with Python</a>.
</p><p>
For more information on database interfacing with Python and
available packages see the <a href="http://www.python.org/topics/database/">Database Topics
Guide</a> on <a href="http://www.python.org/">www.python.org</a>.
</p><p>
This document describes the Python Database API Specification
2.0. The previous <a href="http://www.python.org/topics/database/DatabaseAPI-1.0.html">version 1.0
version</a> is still available as reference. Package writers are
encouraged to use this version of the specification as basis for
new interfaces.
</p><p>
</p><hr>
<a name="module"><h3>Module Interface</h3></a>
<ul>
<p>
Access to the database is made available through connection
objects. The module must provide the following constructor for
these:
</p><p>
</p><dl><dt> <b>connect</b>(parameters...)
</dt><dd>
Constructor for creating a connection to the database.
Returns a <a href="#connection"><i>Connection
Object</i></a>. It takes a number of parameters which are
database dependent. <a href="#Footnote1">[1]</a>
<p>
</p></dd></dl>
<p>
These module globals must be defined:
</p><p>
</p><dl><dt> <b>apilevel</b>
</dt><dd>
String constant stating the supported DB API level.
Currently only the strings <code>'1.0'</code> and
<code>'2.0'</code> are allowed.
<p>
If not given, a <a href="http://www.python.org/topics/database/DatabaseAPI-1.0.html">Database
API 1.0</a> level interface should be assumed.
</p><p>
</p></dd><dt> <b>threadsafety</b>
</dt><dd>
Integer constant stating the level of thread safety the
interface supports. Possible values are:
<table>
<tbody><tr>
<td><code>0</code></td>
<td>= Threads may not share the module.</td>
</tr><tr>
<td><code>1</code></td>
<td>= Threads may share the module, but not
connections.</td>
</tr><tr>
<td><code>2</code></td>
<td>= Threads may share the module and
connections.</td>
</tr><tr>
<td><code>3</code></td>
<td>= Threads may share the module, connections and
cursors.</td>
</tr></tbody></table>
<p>
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.
</p><p>
</p></dd><dt> <b>paramstyle</b>
</dt><dd>
String constant stating the type of parameter marker
formatting expected by the interface. Possible values are
<a href="#Footnote2">[2]</a>:
<table>
<tbody><tr>
<td><code>'qmark'</code></td>
<td>= Question mark style, e.g. '...WHERE name=?'</td>
</tr><tr>
<td><code>'numeric'</code></td>
<td>= Numeric, positional style, e.g. '...WHERE name=:1'</td>
</tr><tr>
<td><code>'named'</code></td>
<td>= Named style, e.g. '...WHERE name=:name'</td>
</tr><tr>
<td><code>'format'</code></td>
<td>= ANSI C printf format codes, e.g. '...WHERE name=%s'</td>
</tr><tr>
<td><code>'pyformat'</code></td>
<td>= Python extended format codes, e.g. '...WHERE
name=%(name)s'</td>
</tr></tbody></table>
<p>
</p></dd></dl>
<p>
The module should make all error information available
through these exceptions or subclasses thereof:
</p><p>
</p><dl><dt> <b>Warning</b>
</dt><dd>
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).
<p>
</p></dd><dt> <b>Error</b>
</dt><dd>
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).
<p>
</p></dd><dt> <b>InterfaceError</b>
</dt><dd>
Exception raised for errors that are related to the
database interface rather than the database itself. It
must be a subclass of Error.
<p>
</p></dd><dt> <b>DatabaseError</b>
</dt><dd>
Exception raised for errors that are related to the
database. It must be a subclass of Error.
<p>
</p></dd><dt> <b>DataError</b>
</dt><dd>
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.
<p>
</p></dd><dt> <b>OperationalError</b>
</dt><dd>
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.
<p>
</p></dd><dt> <b>IntegrityError</b>
</dt><dd>
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.
<p>
</p></dd><dt> <b>InternalError</b>
</dt><dd>
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.
<p>
</p></dd><dt> <b>ProgrammingError</b>
</dt><dd>
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.
<p>
</p></dd><dt> <b>NotSupportedError</b>
</dt><dd>
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.
<p>
</p></dd></dl>
<p>
This is the exception inheritance layout:
</p><pre>StandardError
|__Warning
|__Error
|__InterfaceError
|__DatabaseError
|__DataError
|__OperationalError
|__IntegrityError
|__InternalError
|__ProgrammingError
|__NotSupportedError
</pre>
<p>
<i>Note: The values of these exceptions are not
defined. They should give the user a fairly good idea of
what went wrong though.</i>
</p><p>
</p></ul>
<a name="connection"><h3>Connection Objects</h3></a>
<ul>
<p>
Connections Objects should respond to the following methods:
</p><p>
</p><dl><dt> <b>close</b>()
</dt><dd>
Close the connection now (rather than whenever __del__ is
called). The connection will be unusable from this point
forward; an <code>Error</code> (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.
<p>
</p></dd><dt> <b>commit</b>()
</dt><dd>
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.
<p>
Database modules that do not support transactions should
implement this method with void functionality.
</p><p>
</p></dd><dt> <b>rollback</b>()
</dt><dd>
<i>This method is optional since not all databases provide
transaction support.</i><a href="#Footnote3">[3]</a>
<p>
In case a database does provide transactions this method
causes the the database to roll back to the start of any
pending transaction. Closing a connection without
committing the changes first will cause an implicit
rollback to be performed.
</p><p>
</p></dd><dt> <b>cursor</b>()
</dt><dd>
Return a new <a href="#cursor"><i>Cursor Object</i></a>
using the connection. If the database does not provide a
direct cursor concept, the module will have to emulate
cursors using other means to the extent needed by this
specification. <a href="#Footnote4">[4]</a>
<p>
</p></dd></dl>
<p>
</p></ul>
<a name="cursor"><h3>Cursor Objects</h3></a>
<ul>
<p>
These objects represent a database cursor, which is used to
manage the context of a fetch operation.
</p><p>
Cursor Objects should respond to the following methods and
attributes:
</p><p>
</p><dl><dt> <b>description</b>
</dt><dd>
This read-only attribute is a sequence of 7-item sequences.
Each of these sequences contains information describing one
result column: <code>(name, type_code, display_size,
internal_size, precision, scale, null_ok)</code>. This
attribute will be <code>None</code> for operations that do not
return rows or if the cursor has not had an operation invoked
via the <code>executeXXX()</code> method yet.
<p>
The <code>type_code</code> can be interpreted by
comparing it to the <a href="#types">Type Objects</a>
specified in the section below.
</p><p>
</p></dd><dt> <b>rowcount</b>
</dt><dd>
This read-only attribute specifies the number of rows that
the last <code>executeXXX()</code> produced (for DQL
statements like <tt>select</tt>) or affected (for DML
statements like <tt>update</tt> or <tt>insert</tt>).
<p>
The attribute is -1 in case no <code>executeXXX()</code>
has been performed on the cursor or the rowcount of the
last operation is not determinable by the interface.<a href="#Footnote7">[7]</a>
</p><p>
</p></dd><dt> <b>callproc</b>(procname[,parameters])
</dt><dd>
<i>This method is optional since not all databases provide
stored procedures.</i><a href="#Footnote3">[3]</a>
<p>
Call a stored database procedure with the given
name. The sequence of parameters must contain one entry
for each argument that the procedure expects. The result
of the call is returned as modified copy of the input
sequence. Input parameters are left untouched, output
and input/output parameters replaced with possibly new
values.
</p><p>
The procedure may also provide a result set as
output. This must then be made available through the
standard <code>fetchXXX()</code> methods.
</p><p>
</p></dd><dt> <b>close</b>()
</dt><dd>
Close the cursor now (rather than whenever __del__ is
called). The cursor will be unusable from this point
forward; an <code>Error</code> (or subclass) exception
will be raised if any operation is attempted with the
cursor.
<p>
</p></dd><dt> <b>execute</b>(operation[,parameters])
</dt><dd>
Prepare and execute a database operation (query or
command). Parameters may be provided as sequence or
mapping and will be bound to variables in the operation.
Variables are specified in a database-specific notation
(see the module's <code>paramstyle</code> attribute for
details). <a href="#Footnote5">[5]</a>
<p>
A reference to the operation will be retained by the cursor.
If the same operation object is passed in again, then the
cursor can optimize its behavior. This is most effective
for algorithms where the same operation is used, but
different parameters are bound to it (many times).
</p><p>
For maximum efficiency when reusing an operation, it is best
to use the setinputsizes() method to specify the parameter
types and sizes ahead of time. It is legal for a parameter
to not match the predefined information; the implementation
should compensate, possibly with a loss of efficiency.
</p><p>
The parameters may also be specified as list of tuples
to e.g. insert multiple rows in a single operation, but
this kind of usage is depreciated:
<code>executemany()</code> should be used instead.
</p><p>
Return values are not defined.
</p><p>
</p></dd><dt> <b>executemany</b>(operation,seq_of_parameters)
</dt><dd>
Prepare a database operation (query or command) and then
execute it against all parameter sequences or mappings
found in the sequence <code>seq_of_parameters</code>.
<p>
Modules are free to implement this method using multiple
calls to the <code>execute()</code> method or by using
array operations to have the database process the
sequence as a whole in one call.
</p><p>
The same comments as for <code>execute()</code> also
apply accordingly to this method.
</p><p>
Return values are not defined.
</p><p>
</p></dd><dt> <b>fetchone</b>()
</dt><dd>
Fetch the next row of a query result set, returning a single
sequence, or <code>None</code> when no more data is available.
<a href="#Footnote6">[6]</a>
<p>
An <code>Error</code> (or subclass) exception is raised
if the previous call to <code>executeXXX()</code> did
not produce any result set or no call was issued yet.
</p><p>
</p></dd><dt> <b>fetchmany</b>([size=cursor.arraysize])
</dt><dd>
Fetch the next set of rows of a query result, returning a
sequence of sequences (e.g. a list of tuples). An empty
sequence is returned when no more rows are available.
<p>
The number of rows to fetch per call is specified by the
parameter. If it is not given, the cursor's
<code>arraysize</code> determines the number of rows to
be fetched. The method should try to fetch as many rows
as indicated by the size parameter. If this is not
possible due to the specified number of rows not being
available, fewer rows may be returned.
</p><p>
An <code>Error</code> (or subclass) exception is raised
if the previous call to <code>executeXXX()</code> did
not produce any result set or no call was issued yet.
</p><p>
Note there are performance considerations involved with
the size parameter. For optimal performance, it is
usually best to use the arraysize attribute. If the
size parameter is used, then it is best for it to retain
the same value from one <code>fetchmany()</code> call to
the next.
</p><p>
</p></dd><dt> <b>fetchall</b>()
</dt><dd>
Fetch all (remaining) rows of a query result, returning
them as a sequence of sequences (e.g. a list of tuples).
Note that the cursor's <code>arraysize</code> attribute
can affect the performance of this operation.
<p>
An <code>Error</code> (or subclass) exception is raised
if the previous call to <code>executeXXX()</code> did
not produce any result set or no call was issued yet.
</p><p>
</p></dd><dt> <b>nextset</b>()
</dt><dd>
<i>This method is optional since not all databases support
multiple result sets.</i> <a href="#Footnote3">[3]</a>
<p>
This method will make the cursor skip to the next
available set, discarding any remaining rows from the
current set.
</p><p>
If there are no more sets, the method returns
<code>None</code>. Otherwise, it returns a true value
and subsequent calls to the fetch methods will return
rows from the next result set.
</p><p>
An <code>Error</code> (or subclass) exception is raised
if the previous call to <code>executeXXX()</code> did
not produce any result set or no call was issued yet.
</p><p>
</p></dd><dt> <b>arraysize</b>
</dt><dd>
This read/write attribute specifies the number of rows to
fetch at a time with <code>fetchmany()</code>. It defaults
to 1 meaning to fetch a single row at a time.
<p>
Implementations must observe this value with respect to
the <code>fetchmany()</code> method, but are free to
interact with the database a single row at a time. It
may also be used in the implementation of
<code>executemany()</code>.
</p><p>
</p></dd><dt> <b>setinputsizes</b>(sizes)
</dt><dd>
This can be used before a call to
<code>executeXXX()</code> to predefine memory areas for
the operation's parameters.
<p>
<code>sizes</code> is specified as a sequence -- one
item for each input parameter. The item should be a
Type Object that corresponds to the input that will be
used, or it should be an integer specifying the maximum
length of a string parameter. If the item is
<code>None</code>, then no predefined memory area will
be reserved for that column (this is useful to avoid
predefined areas for large inputs).
</p><p>
This method would be used before the
<code>executeXXX()</code> method is invoked.
</p><p>
Implementations are free to have this method do nothing
and users are free to not use it.
</p><p>
</p></dd><dt> <b>setoutputsize</b>(size[,column])
</dt><dd>
Set a column buffer size for fetches of large columns
(e.g. LONGs, BLOBs, etc.). The column is specified as an
index into the result sequence. Not specifying the column
will set the default size for all large columns in the
cursor.
<p>
This method would be used before the
<code>executeXXX()</code> method is invoked.
</p><p>
Implementations are free to have this method do nothing
and users are free to not use it.
</p><p>
</p></dd></dl>
<p>
</p></ul>
<a name="types"><h3>Type Objects and Constructors</h3></a>
<ul>
<p>
Many databases need to have the input in a particular format
for binding to an operation's input parameters. For
example, if an input is destined for a DATE column, then it
must be bound to the database in a particular string format.
Similar problems exist for "Row ID" columns or large binary
items (e.g. blobs or RAW columns). This presents problems
for Python since the parameters to the
<code>executeXXX()</code> method are untyped. When the
database module sees a Python string object, it doesn't know
if it should be bound as a simple CHAR column, as a raw
BINARY item, or as a DATE.
</p><p>
To overcome this problem, a module must provide the
constructors defined below to create objects that can hold
special values. When passed to the cursor methods, the
module can then detect the proper type of the input
parameter and bind it accordingly.
</p><p>
A Cursor Object's <code>description</code> attribute returns
information about each of the result columns of a query.
The <code>type_code</code> must compare <i>equal</i> to one
of Type Objects defined below. Type Objects may be equal to
more than one type code (e.g. DATETIME could be equal to the
type codes for date, time and timestamp columns; see the <a href="#hints">Implementation Hints</a> below for details).
</p><p>
The module exports the following constructors and
singletons:
</p><p>
</p><dl><dt> <b>Date</b>(year,month,day)
</dt><dd>
This function constructs an object holding a date value.
<p>
</p></dd><dt> <b>Time</b>(hour,minute,second)
</dt><dd>
This function constructs an object holding a time value.
<p>
</p></dd><dt> <b>Timestamp</b>(year,month,day,hour,minute,second)
</dt><dd>
This function constructs an object holding a time stamp
value.
<p>
</p></dd><dt> <b>DateFromTicks</b>(ticks)
</dt><dd>
This function constructs an object holding a date value
from the given ticks value (number of seconds since the
epoch; see the documentation of the standard Python
<tt>time</tt> module for details).
<p>
</p></dd><dt> <b>TimeFromTicks</b>(ticks)
</dt><dd>
This function constructs an object holding a time value
from the given ticks value (number of seconds since the
epoch; see the documentation of the standard Python
<tt>time</tt> module for details).
<p>
</p></dd><dt> <b>TimestampFromTicks</b>(ticks)
</dt><dd>
This function constructs an object holding a time stamp
value from the given ticks value (number of seconds since
the epoch; see the documentation of the standard Python
<tt>time</tt> module for details).
<p>
</p></dd><dt> <b>Binary</b>(string)
</dt><dd>
This function constructs an object capable of holding a
binary (long) string value.
<p>
</p></dd><dt> <b>STRING</b>
</dt><dd>
This type object is used to describe columns in a database
that are string-based (e.g. CHAR).
<p>
</p></dd><dt> <b>BINARY</b>
</dt><dd>
This type object is used to describe (long) binary columns
in a database (e.g. LONG, RAW, BLOBs).
<p>
</p></dd><dt> <b>NUMBER</b>
</dt><dd>
This type object is used to describe numeric columns in a
database.
<p>
</p></dd><dt> <b>DATETIME</b>
</dt><dd>
This type object is used to describe date/time columns in
a database.
<p>
</p></dd><dt> <b>ROWID</b>
</dt><dd>
This type object is used to describe the "Row ID" column
in a database.
<p>
</p></dd></dl>
<p>
SQL NULL values are represented by the Python
<code>None</code> singleton on input and output.
</p><p>
Note: Usage of Unix ticks for database interfacing can cause
troubles because of the limited date range they cover.
</p><p>
</p></ul>
<a name="hints"><h3>Implementation Hints</h3></a>
<ul>
<li>
The preferred object types for the date/time objects are
those defined in the <a href="http://starship.python.net/%7Elemburg/mxDateTime.html">mxDateTime
</a> package. It provides all necessary constructors and
methods both at Python and C level.
<p>
</p></li><li>
The preferred object type for Binary objects are the
buffer types available in standard Python starting with
version 1.5.2. Please see the Python documentation for
details. For information about the the C interface have a
look at <tt>Include/bufferobject.h</tt> and
<tt>Objects/bufferobject.c</tt> in the Python source
distribution.
<p>
</p></li><li>
Here is a sample implementation of the Unix ticks based
constructors for date/time delegating work to the generic
constructors:
<pre>import time
def DateFromTicks(ticks):
return apply(Date,time.localtime(ticks)[:3])
def TimeFromTicks(ticks):
return apply(Time,time.localtime(ticks)[3:6])
def TimestampFromTicks(ticks):
return apply(Timestamp,time.localtime(ticks)[:6])
</pre>
<p>
</p></li><li>
This Python class allows implementing the above type
objects even though the description type code field yields
multiple values for on type object:
<pre>class DBAPITypeObject:
def __init__(self,*values):
self.values = values
def __cmp__(self,other):
if other in self.values:
return 0
if other < self.values:
return 1
else:
return -1
</pre>
<p>
The resulting type object compares equal to all values
passed to the constructor.
</p><p>
</p></li><li>
Here is a snippet of Python code that implements the exception
hierarchy defined above:
<pre>import exceptions
class Error(exceptions.StandardError):
pass
class Warning(exceptions.StandardError):
pass
class InterfaceError(Error):
pass
class DatabaseError(Error):
pass
class InternalError(DatabaseError):
pass
class OperationalError(DatabaseError):
pass
class ProgrammingError(DatabaseError):
pass
class IntegrityError(DatabaseError):
pass
class DataError(DatabaseError):
pass
class NotSupportedError(DatabaseError):
pass
</pre>
<p>
In C you can use the <code>PyErr_NewException(fullname,
base, NULL)</code> API to create the exception objects.
</p><p>
</p></li></ul>
<a name="changes"><h3>Major Changes from Version 1.0 to Version
2.0</h3></a>
<ul>
<p>
The Python Database API 2.0 introduces a few major changes
compared to the 1.0 version. Because some of these changes
will cause existing <a href="http://www.python.org/topics/database/DatabaseAPI-1.0.html">DB API
1.0</a> based scripts to break, the major version number was
adjusted to reflect this change.
</p><p>
These are the most important changes from 1.0 to 2.0:
</p><p>
</p><ul>
<li>
The need for a separate dbi module was dropped and the
functionality merged into the module interface itself.
<p>
</p></li><li>
New constructors and Type Objects were added for date/time
values, the RAW Type Object was renamed to BINARY. The
resulting set should cover all basic data types commonly
found in modern SQL databases.
<p>
</p></li><li>
New constants (apilevel, threadlevel, paramstyle) and
methods (executemany, nextset) were added to provide
better database bindings.
<p>
</p></li><li>
The semantics of .callproc() needed to call stored
procedures are now clearly defined.
<p>
</p></li><li>
The definition of the .execute() return value changed.
Previously, the return value was based on the SQL
statement type (which was hard to implement right) -- it
is undefined now; use the more flexible .rowcount
attribute instead. Modules are free to return the old
style return values, but these are no longer mandated by
the specification and should be considered database
interface dependent.
<p>
</p></li><li>
Class based exceptions were incorporated into the
specification. Module implementors are free to extend the
exception layout defined in this specification by
subclassing the defined exception classes.
<p>
</p></li></ul>
</ul>
<p>
</p><h3>Open Issues</h3>
<ul>
<p>
Although the version 2.0 specification clarifies a lot of
questions that were left open in the 1.0 version, there are
still some remaining issues:
</p><p>
</p><li>
Define a useful return value for .nextset() for the case where
a new result set is available.
<p>
</p></li><li>
Create a fixed point numeric type for use as loss-less
monetary and decimal interchange format.
<p>
</p></li></ul>
<p>
</p><h3><hr>Footnotes</h3>
<ol>
<li>
<a name="Footnote1"></a> As a guideline the connection
constructor parameters should be implemented as keyword
parameters for more intuitive use and follow this order of
parameters:
<p>
<table width="70%">
<tbody><tr>
<td><code>dsn</code></td>
<td>= Data source name as string</td>
<td></td>
</tr><tr>
<td><code>user</code></td>
<td>= User name as string</td>
<td>(optional)</td>
</tr><tr>
<td><code>password</code></td>
<td>= Password as string</td>
<td>(optional)</td>
</tr><tr>
<td><code>host</code></td>
<td>= Hostname</td>
<td>(optional)</td>
</tr><tr>
<td><code>database</code></td>
<td>= Database name</td>
<td>(optional)</td>
</tr></tbody></table>
</p><p>
E.g. a connect could look like this:
</p><p>
<code>connect(dsn='myhost:MYDB',user='guido',password='234$?')</code>
</p><p>
</p></li><li>
<a name="Footnote2"></a> Module implementors should prefer
'numeric', 'named' or 'pyformat' over the other formats
because these offer more clarity and flexibility.
<p>
</p></li><li>
<a name="Footnote3"></a> If the database does not support the
functionality required by the method, the interface should
throw an exception in case the method is used.
<p>
The preferred approach is to not implement the method and
thus have Python generate an <code>AttributeError</code> in
case the method is requested. This allows the programmer to
check for database capabilities using the standard
<code>hasattr()</code> function.
</p><p>
For some dynamically configured interfaces it may not be
appropriate to require dynamically making the method
available. These interfaces should then raise a
<code>NotSupportedError</code> to indicate the non-ability
to perform the roll back when the method is invoked.
</p><p>
</p></li><li>
<a name="Footnote4"></a> A database interface may choose to
support named cursors by allowing a string argument to the
method. This feature is not part of the specification, since
it complicates semantics of the <code>.fetchXXX()</code>
methods.
<p>
</p></li><li>
<a name="Footnote5"></a> The module will use the __getitem__
method of the parameters object to map either positions
(integers) or names (strings) to parameter values. This allows
for both sequences and mappings to be used as input.
<p>
The term "bound" refers to the process of binding an input
value to a database execution buffer. In practical terms,
this means that the input value is directly used as a value
in the operation. The client should not be required to
"escape" the value so that it can be used -- the value
should be equal to the actual database value.
</p><p>
</p></li><li>
<a name="Footnote6"></a> Note that the interface may implement
row fetching using arrays and other optimizations. It is not
guaranteed that a call to this method will only move the
associated cursor forward by one row.
<p>
</p></li><li>
<a name="Footnote7"></a> The <code>rowcount</code> attribute
may be coded in a way that updates its value dynamically. This
can be useful for databases that return useable rowcount
values only after the first call to a <code>.fetchXXX()</code>
method.
<p>
</p></li></ol>
</body></html>
distrib
>
Mandriva
>
2007.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
0993846d17e795d45984b12af4ba9206
>
files
>
74
