Menu
▾
▴
[Firebird-checkins] SF.net SVN: firebird:[811] kinterbasdb/trunk
|
From: <pc...@us...> - 2009-01-13 12:42:51
|
Revision: 811
http://firebird.svn.sourceforge.net/firebird/?rev=811&view=rev
Author: pcisar
Date: 2009-01-13 12:29:19 +0000 (Tue, 13 Jan 2009)
Log Message:
-----------
- New documentation in reStructured Text and Sphinx
- change in init() conv_type default value from 1 to 200
Modified Paths:
--------------
kinterbasdb/trunk/MANIFEST.in
kinterbasdb/trunk/PKG-INFO
kinterbasdb/trunk/__init__.py
kinterbasdb/trunk/__ki_platform_config.h
kinterbasdb/trunk/docs/Python-DB-API-2.0.html
kinterbasdb/trunk/docs/index.html
kinterbasdb/trunk/docs/links.html
kinterbasdb/trunk/setup.py
Added Paths:
-----------
kinterbasdb/trunk/docs/_sources/
kinterbasdb/trunk/docs/_static/
kinterbasdb/trunk/docs/beyond-python-db-api.html
kinterbasdb/trunk/docs/changelog.html
kinterbasdb/trunk/docs/concurrency.html
kinterbasdb/trunk/docs/genindex.html
kinterbasdb/trunk/docs/installation.html
kinterbasdb/trunk/docs/license.html
kinterbasdb/trunk/docs/modindex.html
kinterbasdb/trunk/docs/objects.inv
kinterbasdb/trunk/docs/python-db-api-compliance.html
kinterbasdb/trunk/docs/search.html
kinterbasdb/trunk/docs/searchindex.js
kinterbasdb/trunk/docs/thread-safety-overview.html
kinterbasdb/trunk/docs/tutorial.html
kinterbasdb/trunk/sphinx/
kinterbasdb/trunk/sphinx/.static/
kinterbasdb/trunk/sphinx/.static/default.css
kinterbasdb/trunk/sphinx/.templates/
kinterbasdb/trunk/sphinx/Makefile
kinterbasdb/trunk/sphinx/Python-DB-API-2.0.txt
kinterbasdb/trunk/sphinx/beyond-python-db-api.txt
kinterbasdb/trunk/sphinx/changelog.txt
kinterbasdb/trunk/sphinx/concurrency.txt
kinterbasdb/trunk/sphinx/conf.py
kinterbasdb/trunk/sphinx/index.txt
kinterbasdb/trunk/sphinx/installation.txt
kinterbasdb/trunk/sphinx/license.txt
kinterbasdb/trunk/sphinx/links.txt
kinterbasdb/trunk/sphinx/python-db-api-compliance.txt
kinterbasdb/trunk/sphinx/thread-safety-overview.txt
kinterbasdb/trunk/sphinx/tutorial.txt
Removed Paths:
-------------
kinterbasdb/trunk/docs/changelog.txt
kinterbasdb/trunk/docs/firebird-client-library-thread-safety-overview.html
kinterbasdb/trunk/docs/global.css
kinterbasdb/trunk/docs/installation-binary.html
kinterbasdb/trunk/docs/installation-source.html
kinterbasdb/trunk/docs/license.txt
kinterbasdb/trunk/docs/usage.html
kinterbasdb/trunk/docs/w3c.png
Property Changed:
----------------
kinterbasdb/trunk/
Property changes on: kinterbasdb/trunk
___________________________________________________________________
Added: svn:ignore
+ dist
Modified: kinterbasdb/trunk/MANIFEST.in
===================================================================
--- kinterbasdb/trunk/MANIFEST.in 2009-01-10 14:07:07 UTC (rev 810)
+++ kinterbasdb/trunk/MANIFEST.in 2009-01-13 12:29:19 UTC (rev 811)
@@ -80,17 +80,47 @@
# documentation:
include README
-include docs/changelog.txt
-include docs/firebird-client-library-thread-safety-overview.html
-include docs/global.css
include docs/index.html
-include docs/installation-binary.html
-include docs/installation-source.html
-include docs/license.txt
+include docs/installation.html
+include docs/tutorial.html
+include docs/Python-DB-API-2.0.html
+include docs/python-db-api-compliance.html
+include docs/beyond-python-db-api.html
+include docs/concurrency.html
+include docs/thread-safety-overview.html
include docs/links.html
-include docs/Python-DB-API-2.0.html
-include docs/usage.html
-include docs/w3c.png
+include docs/changelog.html
+include docs/license.html
+include docs/genindex.html
+include docs/modindex.html
+include docs/objects.inv
+include docs/search.html
+include docs/searchindex.js
+include docs/_static/contents.png
+include docs/_static/default.css
+include docs/_static/doctools.js
+include docs/_static/file.png
+include docs/_static/jquery.js
+include docs/_static/minus.png
+include docs/_static/navigation.png
+include docs/_static/plus.png
+include docs/_static/pygments.css
+include docs/_static/rightsidebar.css
+include docs/_static/searchtools.js
+include docs/_static/sphinxdoc.css
+include docs/_static/stickysidebar.css
+include docs/_static/traditional.css
+include docs/_sources/index.txt
+include docs/_sources/installation.txt
+include docs/_sources/tutorial.txt
+include docs/_sources/Python-DB-API-2.0.txt
+include docs/_sources/python-db-api-compliance.txt
+include docs/_sources/beyond-python-db-api.txt
+include docs/_sources/concurrency.txt
+include docs/_sources/thread-safety-overview.txt
+include docs/_sources/links.txt
+include docs/_sources/changelog.txt
+include docs/_sources/license.txt
global-exclude CVS
Modified: kinterbasdb/trunk/PKG-INFO
===================================================================
--- kinterbasdb/trunk/PKG-INFO 2009-01-10 14:07:07 UTC (rev 810)
+++ kinterbasdb/trunk/PKG-INFO 2009-01-13 12:29:19 UTC (rev 811)
@@ -1,19 +1,20 @@
-Metadata-Version: 1.0
-Name: kinterbasdb
-Version: 3.3.0
-Summary: Python DB API 2.0 extension for Firebird and Interbase
-Home-page: http://kinterbasdb.sourceforge.net
-Author: Originally by Alexander Kuznetsov ;
- rewritten and expanded by David S. Rushby
- with contributions from several others
- (see docs/license.txt for details).
-Author-email: woo...@ro...
-License: see docs/license.txt
-Description: KInterbasDB implements Python Database API 2.0-compliant support
- for the open source relational database Firebird and some versions
- of its proprietary cousin Borland Interbase(R).
-
- In addition to the minimal feature set of the standard Python DB API,
- KInterbasDB also exposes nearly the entire native client API of the
- database engine.
-Platform: UNKNOWN
+Metadata-Version: 1.0
+Name: kinterbasdb
+Version: 3.3.0
+Summary: Python DB API 2.0 extension for Firebird and Interbase
+Home-page: http://www.firebirdsql.org
+Author: Originally by Alexander Kuznetsov ;
+ rewritten and expanded by David S. Rushby
+ with contributions from several others
+ (see docs/license.txt for details).
+ Current maintainer is Pavel Cisar
+Author-email: pc...@ib...
+License: see docs/license.txt
+Description: KInterbasDB implements Python Database API 2.0-compliant support
+ for the open source relational database Firebird and some versions
+ of its proprietary cousin Borland Interbase(R).
+
+ In addition to the minimal feature set of the standard Python DB API,
+ KInterbasDB also exposes nearly the entire native client API of the
+ database engine.
+Platform: UNKNOWN
Modified: kinterbasdb/trunk/__init__.py
===================================================================
--- kinterbasdb/trunk/__init__.py 2009-01-10 14:07:07 UTC (rev 810)
+++ kinterbasdb/trunk/__init__.py 2009-01-13 12:29:19 UTC (rev 811)
@@ -24,7 +24,7 @@
# underscore cannot be expected to have stable interfaces.
__version__ = (3, 3, 0, 'pre-alpha', 0)
-__timestamp__ = '2008.11.19.09.05.08.UTC'
+__timestamp__ = '2009.01.13.11.52.28.UTC'
import os, struct, sys
@@ -262,7 +262,7 @@
initialized = False
_guessTextualBlobEncodingWhenUsingFB20AndEarlier = False
-def init(type_conv=1, concurrency_level=_k.DEFAULT_CONCURRENCY_LEVEL):
+def init(type_conv=200, concurrency_level=_k.DEFAULT_CONCURRENCY_LEVEL):
global initialized, _MINIMAL_TYPE_TRANS_TYPES, \
_NORMAL_TYPE_TRANS_IN, _NORMAL_TYPE_TRANS_OUT, \
_guessTextualBlobEncodingWhenUsingFB20AndEarlier
Modified: kinterbasdb/trunk/__ki_platform_config.h
===================================================================
--- kinterbasdb/trunk/__ki_platform_config.h 2009-01-10 14:07:07 UTC (rev 810)
+++ kinterbasdb/trunk/__ki_platform_config.h 2009-01-13 12:29:19 UTC (rev 811)
@@ -7,19 +7,3 @@
#define ENABLE_FIELD_PRECISION_DETERMINATION
#define ENABLE_DB_ARRAY_SUPPORT
#define ENABLE_DB_SERVICES_API
-#define HAVE__isc_tpb_lock_timeout
-#define HAVE__isc_info_active_tran_count
-#define HAVE__isc_info_creation_date
-#define HAVE__isc_info_tra_oldest_interesting
-#define HAVE__isc_info_tra_oldest_snapshot
-#define HAVE__isc_info_tra_oldest_active
-#define HAVE__isc_info_tra_isolation
-#define HAVE__isc_info_tra_access
-#define HAVE__isc_info_tra_lock_timeout
-#define HAVE__isc_info_tra_consistency
-#define HAVE__isc_info_tra_concurrency
-#define HAVE__isc_info_tra_read_committed
-#define HAVE__isc_info_tra_no_rec_version
-#define HAVE__isc_info_tra_rec_version
-#define HAVE__isc_info_tra_readonly
-#define HAVE__isc_info_tra_readwrite
Modified: kinterbasdb/trunk/docs/Python-DB-API-2.0.html
===================================================================
--- kinterbasdb/trunk/docs/Python-DB-API-2.0.html 2009-01-10 14:07:07 UTC (rev 810)
+++ kinterbasdb/trunk/docs/Python-DB-API-2.0.html 2009-01-13 12:29:19 UTC (rev 811)
@@ -1,1005 +1,805 @@
-<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
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Python Database API Specification 2.0 — KInterbasDB v3.3.0 documentation</title>
+ <link rel="stylesheet" href="_static/default.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '3.3.0',
+ COLLAPSE_MODINDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="top" title="KInterbasDB v3.3.0 documentation" href="index.html" />
+ <link rel="next" title="Compliance to Python Database API 2.0" href="python-db-api-compliance.html" />
+ <link rel="prev" title="Quick-start Guide / Tutorial" href="tutorial.html" />
+ </head>
+ <body>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="modindex.html" title="Global Module Index"
+ accesskey="M">modules</a> |</li>
+ <li class="right" >
+ <a href="python-db-api-compliance.html" title="Compliance to Python Database API 2.0"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="tutorial.html" title="Quick-start Guide / Tutorial"
+ accesskey="P">previous</a> |</li>
+ <li><a href="index.html">KInterbasDB v3.3.0 documentation</a> »</li>
+ </ul>
+ </div>
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+ <div class="body">
+
+
+ <div class="section" id="python-database-api-specification-2-0">
+<h1>Python Database API Specification 2.0<a class="headerlink" href="#python-database-api-specification-2-0" title="Permalink to this headline">¶</a></h1>
+<p>KInterbasDB is the Python Database API 2.0 compliant driver
+for Firebird. The <cite>Reference / Usage Guide</cite> is therefore divided
+into three parts:</p>
+<blockquote>
+<ul class="simple">
+<li>Python Database API 2.0 specification</li>
+<li>KInterbasDB Compliance to Python DB 2.0 API specification.</li>
+<li>KInterbasDB features beyond Python DB 2.0 API specification.</li>
+</ul>
+</blockquote>
+<p>If you’re familiar to Python DB 2.0 API specification, you may skip
+directly to the next topic.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This is a local copy of the specification. The online source copy is
+available at <a class="reference external" href="http://www.python.org/topics/database/DatabaseAPI-2.0.html">http://www.python.org/topics/database/DatabaseAPI-2.0.html</a></p>
+</div>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<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>
+<ul class="simple">
+<li>Module Interface</li>
+<li>Connection Objects</li>
+<li>Cursor Objects</li>
+<li>Type Objects and Constructors</li>
+<li>Implementation Hints</li>
+<li>Major Changes from 1.0 to 2.0</li>
+</ul>
+<p>Comments and questions about this specification may be directed to the
+<a class="reference external" href="mailto:db-sig%40python.org">SIG for Database Interfacing with Python</a>.</p>
+<p>For more information on database interfacing with Python and available
+packages see the <a class="reference external" href="http://www.python.org/topics/database/">Database Topics Guide</a> on <a class="reference external" href="http://www.python.org/">www.python.org</a>.</p>
+<p>This document describes the Python Database API Specification 2.0. The
+previous <a class="reference external" 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>
+</div>
+<div class="section" id="module-interface">
+<h2>Module Interface<a class="headerlink" href="#module-interface" title="Permalink to this headline">¶</a></h2>
+<p>Access to the database is made available through connection objects.
+The module must provide the following constructor for these:</p>
+<dl class="function">
+<dt id="connect">
+<!--[connect]--><tt class="descname">connect</tt><big>(</big><em>parameters...</em><big>)</big><a class="headerlink" href="#connect" title="Permalink to this definition">¶</a></dt>
+<dd>Constructor for creating a connection to the database. Returns a Connection Object .
+It takes a number of parameters which are database dependent. <a class="footnote-reference" href="#f1" id="id1">[1]</a></dd></dl>
--->
+<p>These module globals must be defined:</p>
+<dl class="data">
+<dt id="apilevel">
+<!--[apilevel]--><tt class="descname">apilevel</tt><a class="headerlink" href="#apilevel" title="Permalink to this definition">¶</a></dt>
+<dd>String constant stating the supported DB API level.
+Currently only the strings <cite>‘1.0’</cite> and <cite>‘2.0’</cite> are allowed. If not
+given, a <a class="reference external" href="http://www.python.org/topics/database/DatabaseAPI-1.0.html">Database API 1.0</a> level
+interface should be assumed.</dd></dl>
-<title>Python Database API v2.0</title><meta name="description" content="Version 2.0 of the standard Python database interface."></head>
+<dl class="data">
+<dt id="threadsafety">
+<!--[threadsafety]--><tt class="descname">threadsafety</tt><a class="headerlink" href="#threadsafety" title="Permalink to this definition">¶</a></dt>
+<dd><p>Integer constant stating the level of thread safety the interface supports.
+Possible values are:</p>
+<blockquote>
+<blockquote>
+<ul class="simple">
+<li><cite>0</cite> = Threads may not share the module.</li>
+<li><cite>1</cite> = Threads may share the module, but not connections.</li>
+<li><cite>2</cite> = Threads may share the module and connections.</li>
+<li><cite>3</cite> = 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.</li>
+</ul>
+</blockquote>
+<p>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>
+</blockquote>
+</dd></dl>
-<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>
+<dl class="data">
+<dt id="paramstyle">
+<!--[paramstyle]--><tt class="descname">paramstyle</tt><a class="headerlink" href="#paramstyle" title="Permalink to this definition">¶</a></dt>
+<dd><p>String constant stating the type of parameter marker
+formatting expected by the interface. Possible values are <a class="footnote-reference" href="#f2" id="id2">[2]</a>:</p>
+<ul class="simple">
+<li><cite>‘qmark’</cite> = Question mark style, e.g. ‘...WHERE name=?’</li>
+<li><cite>‘numeric’</cite> = Numeric, positional style, e.g. ‘...WHERE name=:1’</li>
+<li><cite>‘named’</cite> = Named style, e.g. ‘...WHERE name=:name’</li>
+<li><cite>‘format’</cite> = ANSI C printf format codes, e.g. ‘...WHERE name=%s’</li>
+<li><cite>‘pyformat’</cite> = Python extended format codes, e.g. ‘...WHERE name=%(name)s’</li>
+</ul>
+</dd></dl>
- <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>The module should make all error information available through these
+exceptions or subclasses thereof:</p>
+<dl class="exception">
+<dt id="Warning">
+<!--[Warning]-->exception <tt class="descname">Warning</tt><a class="headerlink" href="#Warning" title="Permalink to this definition">¶</a></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).</dd></dl>
- </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>
+<dl class="exception">
+<dt id="Error">
+<!--[Error]-->exception <tt class="descname">Error</tt><a class="headerlink" href="#Error" title="Permalink to this definition">¶</a></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).</dd></dl>
- <p>
- Comments and questions about this specification may be directed
- to the <a href="mailto:db...@py...">SIG for Database
- Interfacing with Python</a>.
+<dl class="exception">
+<dt id="InterfaceError">
+<!--[InterfaceError]-->exception <tt class="descname">InterfaceError</tt><a class="headerlink" href="#InterfaceError" title="Permalink to this definition">¶</a></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.</dd></dl>
- </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>.
+<dl class="exception">
+<dt id="DatabaseError">
+<!--[DatabaseError]-->exception <tt class="descname">DatabaseError</tt><a class="headerlink" href="#DatabaseError" title="Permalink to this definition">¶</a></dt>
+<dd>Exception raised for errors that are related to the database. It must be a subclass
+of Error.</dd></dl>
- </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.
+<dl class="exception">
+<dt id="DataError">
+<!--[DataError]-->exception <tt class="descname">DataError</tt><a class="headerlink" href="#DataError" title="Permalink to this definition">¶</a></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.</dd></dl>
- </p><p>
+<dl class="exception">
+<dt id="OperationalError">
+<!--[OperationalError]-->exception <tt class="descname">OperationalError</tt><a class="headerlink" href="#OperationalError" title="Permalink to this definition">¶</a></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.</dd></dl>
- </p><hr>
+<dl class="exception">
+<dt id="IntegrityError">
+<!--[IntegrityError]-->exception <tt class="descname">IntegrityError</tt><a class="headerlink" href="#IntegrityError" title="Permalink to this definition">¶</a></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.</dd></dl>
- <a name="module"><h3>Module Interface</h3></a>
+<dl class="exception">
+<dt id="InternalError">
+<!--[InternalError]-->exception <tt class="descname">InternalError</tt><a class="headerlink" href="#InternalError" title="Permalink to this definition">¶</a></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.</dd></dl>
- <ul>
+<dl class="exception">
+<dt id="ProgrammingError">
+<!--[ProgrammingError]-->exception <tt class="descname">ProgrammingError</tt><a class="headerlink" href="#ProgrammingError" title="Permalink to this definition">¶</a></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.</dd></dl>
- <p>
- Access to the database is made available through connection
- objects. The module must provide the following constructor for
- these:
+<dl class="exception">
+<dt id="NotSupportedError">
+<!--[NotSupportedError]-->exception <tt class="descname">NotSupportedError</tt><a class="headerlink" href="#NotSupportedError" title="Permalink to this definition">¶</a></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.</dd></dl>
- </p><p>
+<p>This is the exception inheritance layout:</p>
+<div class="highlight-python"><pre> StandardError
+ |__Warning
+ |__Error
+ |__InterfaceError
+ |__DatabaseError
+ |__DataError
+ |__OperationalError
+ |__IntegrityError
+ |__InternalError
+ |__ProgrammingError
+ |__NotSupportedError
- </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>
+Note: The values of these exceptions are not defined. They should give
+the user a fairly good idea of what went wrong though.</pre>
+</div>
+</div>
+<div class="section" id="connection-objects">
+<h2>Connection Objects<a class="headerlink" href="#connection-objects" title="Permalink to this headline">¶</a></h2>
+<p>Connections Objects should respond to the following methods:</p>
+<dl class="class">
+<dt id="Connection">
+<!--[Connection]-->class <tt class="descname">Connection</tt><a class="headerlink" href="#Connection" title="Permalink to this definition">¶</a></dt>
+<dd><dl class="method">
+<dt id="Connection.close">
+<!--[Connection.close]--><tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#Connection.close" title="Permalink to this definition">¶</a></dt>
+<dd>Close the connection now (rather than whenever __del__ is called). The connection
+will be unusable from this point forward; an <cite>Error</cite> (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.</dd></dl>
- </p></dd></dl>
+<dl class="method">
+<dt id="Connection.commit">
+<!--[Connection.commit]--><tt class="descname">commit</tt><big>(</big><big>)</big><a class="headerlink" href="#Connection.commit" title="Permalink to this definition">¶</a></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.
+Database modules that do not support transactions should implement
+this method with void functionality.</dd></dl>
- <p>
- These module globals must be defined:
+<dl class="method">
+<dt id="Connection.rollback">
+<!--[Connection.rollback]--><tt class="descname">rollback</tt><big>(</big><big>)</big><a class="headerlink" href="#Connection.rollback" title="Permalink to this definition">¶</a></dt>
+<dd>This method is optional since not all databases
+provide transaction support. <a class="footnote-reference" href="#f3" id="id3">[3]</a> 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.</dd></dl>
- </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>
+<dl class="method">
+<dt id="Connection.cursor">
+<!--[Connection.cursor]--><tt class="descname">cursor</tt><big>(</big><big>)</big><a class="headerlink" href="#Connection.cursor" title="Permalink to this definition">¶</a></dt>
+<dd>Return a new Cursor Object 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 class="footnote-reference" href="#f4" id="id4">[4]</a></dd></dl>
- </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>
+</dd></dl>
- <td>= Threads may not share the module.</td>
+</div>
+<div class="section" id="cursor-objects">
+<h2>Cursor Objects<a class="headerlink" href="#cursor-objects" title="Permalink to this headline">¶</a></h2>
+<p>These objects represent a database cursor, which is used to manage the
+context of a fetch operation. Cursor Objects should respond to the
+following methods and attributes:</p>
+<dl class="class">
+<dt id="Cursor">
+<!--[Cursor]-->class <tt class="descname">Cursor</tt><a class="headerlink" href="#Cursor" title="Permalink to this definition">¶</a></dt>
+<dd><dl class="attribute">
+<dt id="Cursor.description">
+<!--[Cursor.description]--><tt class="descname">description</tt><a class="headerlink" href="#Cursor.description" title="Permalink to this definition">¶</a></dt>
+<dd>This read-only attribute is a sequence of 7-item
+sequences. Each of these sequences contains information describing one
+result column: <cite>(name, type_code, display_size, internal_size,
+precision, scale, null_ok)</cite>. This attribute will be <cite>None</cite> for
+operations that do not return rows or if the cursor has not had an
+operation invoked via the <cite>executeXXX()</cite> method yet. The <cite>type_code</cite>
+can be interpreted by comparing it to the Type Objects specified in
+the section below.</dd></dl>
- </tr><tr>
- <td><code>1</code></td>
+<dl class="attribute">
+<dt id="Cursor.rowcount">
+<!--[Cursor.rowcount]--><tt class="descname">rowcount</tt><a class="headerlink" href="#Cursor.rowcount" title="Permalink to this definition">¶</a></dt>
+<dd>This read-only attribute specifies the number of rows
+that the last <cite>executeXXX()</cite> produced (for DQL statements like select)
+or affected (for DML statements like update or insert ). The
+attribute is -1 in case no <cite>executeXXX()</cite> has been performed on the
+cursor or the rowcount of the last operation is not determinable by
+the interface. <a class="footnote-reference" href="#f7" id="id5">[7]</a></dd></dl>
- <td>= Threads may share the module, but not
- connections.</td>
+<dl class="method">
+<dt id="Cursor.callproc">
+<!--[Cursor.callproc]--><tt class="descname">callproc</tt><big>(</big><em>procname</em><span class="optional">[</span>, <em>parameters</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#Cursor.callproc" title="Permalink to this definition">¶</a></dt>
+<dd>This method is optional since not all databases provide stored procedures.
+<a class="footnote-reference" href="#f3" id="id6">[3]</a> 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. The procedure may also
+provide a result set as output. This must then be made available
+through the standard <cite>fetchXXX()</cite> methods.</dd></dl>
- </tr><tr>
- <td><code>2</code></td>
+<dl class="method">
+<dt id="Cursor.close">
+<!--[Cursor.close]--><tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#Cursor.close" title="Permalink to this definition">¶</a></dt>
+<dd>Close the cursor now (rather than whenever __del__ is
+called). The cursor will be unusable from this point forward; an
+<cite>Error</cite> (or subclass) exception will be raised if any operation is
+attempted with the cursor.</dd></dl>
- <td>= Threads may share the module and
- connections.</td>
+<dl class="method">
+<dt id="Cursor.execute">
+<!--[Cursor.execute]--><tt class="descname">execute</tt><big>(</big><em>operation</em><span class="optional">[</span>, <em>parameters</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#Cursor.execute" title="Permalink to this definition">¶</a></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 <cite>paramstyle</cite> attribute for details).
+<a class="footnote-reference" href="#f5" id="id7">[5]</a> 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). 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. 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: <cite>executemany()</cite> should be used instead.
+Return values are not defined.</dd></dl>
- </tr><tr>
- <td><code>3</code></td>
+<dl class="method">
+<dt id="Cursor.executemany">
+<!--[Cursor.executemany]--><tt class="descname">executemany</tt><big>(</big><em>operation</em>, <em>seq_of_parameters</em><big>)</big><a class="headerlink" href="#Cursor.executemany" title="Permalink to this definition">¶</a></dt>
+<dd>Prepare a database operation (query or command) and then execute it against all parameter
+sequences or mappings found in the sequence <cite>seq_of_parameters</cite>.
+Modules are free to implement this method using multiple calls to the
+<cite>execute()</cite> method or by using array operations to have the database
+process the sequence as a whole in one call. The same comments as for
+<cite>execute()</cite> also apply accordingly to this method. Return values are
+not defined.</dd></dl>
- <td>= Threads may share the module, connections and
- cursors.</td>
+<dl class="method">
+<dt id="Cursor.fetchone">
+<!--[Cursor.fetchone]--><tt class="descname">fetchone</tt><big>(</big><big>)</big><a class="headerlink" href="#Cursor.fetchone" title="Permalink to this definition">¶</a></dt>
+<dd>Fetch the next row of a query result set, returning
+a single sequence, or <cite>None</cite> when no more data is available. <a class="footnote-reference" href="#f6" id="id8">[6]</a> An
+<cite>Error</cite> (or subclass) exception is raised if the previous call to
+<cite>executeXXX()</cite> did not produce any result set or no call was issued yet.</dd></dl>
- </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>
+<dl class="method">
+<dt id="Cursor.fetchmany">
+<!--[Cursor.fetchmany]--><tt class="descname">fetchmany</tt><big>(</big><span class="optional">[</span><em>size=cursor.arraysize</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#Cursor.fetchmany" title="Permalink to this definition">¶</a></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. The number of rows to fetch per call is specified by the
+parameter. If it is not given, the cursor’s <cite>arraysize</cite> 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. An <cite>Error</cite> (or subclass) exception is raised if the previous
+call to <cite>executeXXX()</cite> did not produce any result set or no call was
+issued yet. 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 <cite>fetchmany()</cite> call to the next.</dd></dl>
- </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>
+<dl class="method">
+<dt id="Cursor.fetchall">
+<!--[Cursor.fetchall]--><tt class="descname">fetchall</tt><big>(</big><big>)</big><a class="headerlink" href="#Cursor.fetchall" title="Permalink to this definition">¶</a></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 <cite>arraysize</cite> attribute can affect the
+performance of this operation. An <cite>Error</cite> (or subclass) exception is
+raised if the previous call to <cite>executeXXX()</cite> did not produce any
+result set or no call was issued yet.</dd></dl>
- <td>= Question mark style, e.g. '...WHERE name=?'</td>
+<dl class="method">
+<dt id="Cursor.nextset">
+<!--[Cursor.nextset]--><tt class="descname">nextset</tt><big>(</big><big>)</big><a class="headerlink" href="#Cursor.nextset" title="Permalink to this definition">¶</a></dt>
+<dd>This method is optional since not all databases
+support multiple result sets. <a class="footnote-reference" href="#f3" id="id9">[3]</a> This method will make the cursor
+skip to the next available set, discarding any remaining rows from the
+current set. If there are no more sets, the method returns <cite>None</cite>.
+Otherwise, it returns a true value and subsequent calls to the fetch
+methods will return rows from the next result set. An <cite>Error</cite> (or
+subclass) exception is raised if the previous call to <cite>executeXXX()</cite>
+did not produce any result set or no call was issued yet.</dd></dl>
- </tr><tr>
- <td><code>'numeric'</code></td>
+<dl class="method">
+<dt id="Cursor.setinputsizes">
+<!--[Cursor.setinputsizes]--><tt class="descname">setinputsizes</tt><big>(</big><em>sizes</em><big>)</big><a class="headerlink" href="#Cursor.setinputsizes" title="Permalink to this definition">¶</a></dt>
+<dd>This can be used before a call to <cite>executeXXX()</cite> to predefine memory areas
+for the operation’s parameters. <cite>sizes</cite> 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 <cite>None</cite>, then no
+predefined memory area will be reserved for that column (this is
+useful to avoid predefined areas for large inputs). This method would
+be used before the <cite>executeXXX()</cite> method is invoked. Implementations
+are free to have this method do nothing and users are free to not use it.</dd></dl>
- <td>= Numeric, positional style, e.g. '...WHERE name=:1'</td>
+<dl class="method">
+<dt id="Cursor.setoutputsize">
+<!--[Cursor.setoutputsize]--><tt class="descname">setoutputsize</tt><big>(</big><em>size</em><span class="optional">[</span>, <em>column</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#Cursor.setoutputsize" title="Permalink to this definition">¶</a></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.
+This method would be used before the <cite>executeXXX()</cite> method is invoked.
+Implementations are free to have this method do nothing and users are
+free to not use it.</dd></dl>
- </tr><tr>
- <td><code>'named'</code></td>
+</dd></dl>
- <td>= Named style, e.g. '...WHERE name=:name'</td>
+</div>
+<div class="section" id="type-objects-and-constructors">
+<h2>Type Objects and Constructors<a class="headerlink" href="#type-objects-and-constructors" title="Permalink to this headline">¶</a></h2>
+<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
+<cite>executeXXX()</cite> 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. 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. A Cursor Object’s <cite>description</cite>
+attribute returns information about each of the result columns of a
+query. The <cite>type_code</cite> must compare equal 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 Implementation Hints below for details).
+The module exports the following constructors and singletons:</p>
+<dl class="function">
+<dt id="Date">
+<!--[Date]--><tt class="descname">Date</tt><big>(</big><em>year</em>, <em>month</em>, <em>day</em><big>)</big><a class="headerlink" href="#Date" title="Permalink to this definition">¶</a></dt>
+<dd>This function constructs an object holding a date value.</dd></dl>
- </tr><tr>
- <td><code>'format'</code></td>
+<dl class="function">
+<dt id="Time">
+<!--[Time]--><tt class="descname">Time</tt><big>(</big><em>hour</em>, <em>minute</em>, <em>second</em><big>)</big><a class="headerlink" href="#Time" title="Permalink to this definition">¶</a></dt>
+<dd>This function constructs an object holding a time value.</dd></dl>
- <td>= ANSI C printf format codes, e.g. '...WHERE name=%s'</td>
+<dl class="function">
+<dt id="Timestamp">
+<!--[Timestamp]--><tt class="descname">Timestamp</tt><big>(</big><em>year</em>, <em>month</em>, <em>day</em>, <em>hour</em>, <em>minute</em>, <em>second</em><big>)</big><a class="headerlink" href="#Timestamp" title="Permalink to this definition">¶</a></dt>
+<dd>This function constructs an object holding a time stamp value.</dd></dl>
- </tr><tr>
- <td><code>'pyformat'</code></td>
+<dl class="function">
+<dt id="DateFromTicks">
+<!--[DateFromTicks]--><tt class="descname">DateFromTicks</tt><big>(</big><em>ticks</em><big>)</big><a class="headerlink" href="#DateFromTicks" title="Permalink to this definition">¶</a></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 time module for details).</dd></dl>
- <td>= Python extended format codes, e.g. '...WHERE
- name=%(name)s'</td>
+<dl class="function">
+<dt id="TimeFromTicks">
+<!--[TimeFromTicks]--><tt class="descname">TimeFromTicks</tt><big>(</big><em>ticks</em><big>)</big><a class="headerlink" href="#TimeFromTicks" title="Permalink to this definition">¶</a></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 time module for details).</dd></dl>
- </tr></tbody></table>
- <p>
+<dl class="function">
+<dt id="TimestampFromTicks">
+<!--[TimestampFromTicks]--><tt class="descname">TimestampFromTicks</tt><big>(</big><em>ticks</em><big>)</big><a class="headerlink" href="#TimestampFromTicks" title="Permalink to this definition">¶</a></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 time module for details).</dd></dl>
- </p></dd></dl>
+<dl class="function">
+<dt id="Binary">
+<!--[Binary]--><tt class="descname">Binary</tt><big>(</big><em>string</em><big>)</big><a class="headerlink" href="#Binary" title="Permalink to this definition">¶</a></dt>
+<dd>This function constructs an object capable of holding a binary (long) string value.</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>
+<dl class="data">
+<dt id="STRING">
+<!--[STRING]--><tt class="descname">STRING</tt><a class="headerlink" href="#STRING" title="Permalink to this definition">¶</a></dt>
+<dd>This type object is used to describe columns in a database that are string-based
+(e.g. CHAR).</dd></dl>
- </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>
+<dl class="data">
+<dt id="BINARY">
+<!--[BINARY]--><tt class="descname">BINARY</tt><a class="headerlink" href="#BINARY" title="Permalink to this definition">¶</a></dt>
+<dd>This type object is used to describe (long) binary columns in a database
+(e.g. LONG, RAW, BLOBs).</dd></dl>
- </p></dd><dt> <b>Error</b>
+<dl class="data">
+<dt id="NUMBER">
+<!--[NUMBER]--><tt class="descname">NUMBER</tt><a class="headerlink" href="#NUMBER" title="Permalink to this definition">¶</a></dt>
+<dd>This type object is used to describe numeric columns in a database.</dd></dl>
- </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>
+<dl class="data">
+<dt id="DATETIME">
+<!--[DATETIME]--><tt class="descname">DATETIME</tt><a class="headerlink" href="#DATETIME" title="Permalink to this definition">¶</a></dt>
+<dd>This type object is used to describe date/time columns in a database.</dd></dl>
- </p></dd><dt> <b>InterfaceError</b>
+<dl class="data">
+<dt id="ROWID">
+<!--[ROWID]--><tt class="descname">ROWID</tt><a class="headerlink" href="#ROWID" title="Permalink to this definition">¶</a></dt>
+<dd>This type object is used to describe the “Row ID” column in a database.</dd></dl>
- </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>SQL NULL values are represented by the Python <cite>None</cite> singleton on
+input and output. Note: Usage of Unix ticks for database interfacing
+can cause troubles because of the limited date range they cover.</p>
+</div>
+<div class="section" id="implementation-hints">
+<h2>Implementation Hints<a class="headerlink" href="#implementation-hints" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>The preferred object types for the date/time objects are those
+defined in the <a class="reference external" href="http://starship.python.net/%7Elemburg/mxDateTime.html">mxDateTime</a> package. It
+provides all necessary constructors and methods both at Python and C
+level.</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 Include/bufferobject.h and
+Objects/bufferobject.c in the Python source distribution.</li>
+<li>Here is a sample implementation of the Unix ticks based constructors
+for date/time delegating work to the generic constructors:</li>
+</ul>
+<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">time</span>
- </p></dd><dt> <b>DatabaseError</b>
+<span class="k">def</span> <span class="nf">DateFromTicks</span><span class="p">(</span><span class="n">ticks</span><span class="p">):</span>
- </dt><dd>
- Exception raised for errors that are related to the
- database. It must be a subclass of Error.
- <p>
+ <span class="k">return</span> <span class="nb">apply</span><span class="p">(</span><span class="n">Date</span><span class="p">,</span><span class="n">time</span><span class="o">.</span><span class="n">localtime</span><span class="p">(</span><span class="n">ticks</span><span class="p">)[:</span><span class="mf">3</span><span class="p">])</span>
- </p></dd><dt> <b>DataError</b>
+<span class="k">def</span> <span class="nf">TimeFromTicks</span><span class="p">(</span><span class="n">ticks</span><span class="p">):</span>
- </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>
+ <span class="k">return</span> <span class="nb">apply</span><span class="p">(</span><span class="n">Time</span><span class="p">,</span><span class="n">time</span><span class="o">.</span><span class="n">localtime</span><span class="p">(</span><span class="n">ticks</span><span class="p">)[</span><span class="mf">3</span><span class="p">:</span><span class="mf">6</span><span class="p">])</span>
- </p></dd><dt> <b>OperationalError</b>
+<span class="k">def</span> <span class="nf">TimestampFromTicks</span><span class="p">(</span><span class="n">ticks</span><span class="p">):</span>
- </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>
+ <span class="k">return</span> <span class="nb">apply</span><span class="p">(</span><span class="n">Timestamp</span><span class="p">,</span><span class="n">time</span><span class="o">.</span><span class="n">localtime</span><span class="p">(</span><span class="n">ticks</span><span class="p">)[:</span><span class="mf">6</span><span class="p">])</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li>This Python class allows implementing the above type objects even
+though the description type code field yields multiple values for on
+type object:</li>
+</ul>
+<div class="highlight-python"><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
- </p></dd><dt> <b>IntegrityError</b>
+The resulting type object compares equal to all values passed to the
+constructor.</pre>
+</div>
+<ul class="simple">
+<li>Here is a snippet of Python code that implements the exception
+hierarchy defined above:</li>
+</ul>
+<div class="highlight-python"><pre> import exceptions
- </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>
+ class Error(exceptions.StandardError):
+ pass
- </p></dd><dt> <b>InternalError</b>
+ class Warning(exceptions.StandardError):
+ pass
- </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>
+ class InterfaceError(Error):
+ pass
- </p></dd><dt> <b>ProgrammingError</b>
+ class DatabaseError(Error):
+ pass
- </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>
+ class InternalError(DatabaseError):
+ pass
- </p></dd><dt> <b>NotSupportedError</b>
+ class OperationalError(DatabaseError):
+ pass
- </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>
+ class ProgrammingError(DatabaseError):
+ pass
- </p></dd></dl>
+ class IntegrityError(DatabaseError):
+ pass
- <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>
+ class DataError(DatabaseError):
+ pass
- </p></ul>
+ class NotSupportedError(DatabaseError):
+ pass
- <a name="connection"><h3>Connection Objects</h3></a>
+In C you can use the `PyErr_NewException(fullname, base, NULL)` API to
+create the exception objects.</pre>
+</div>
+</div>
+<div class="section" id="major-changes-from-version-1-0-to-version-2-0">
+<h2>Major Changes from Version 1.0 to Version 2.0<a class="headerlink" href="#major-changes-from-version-1-0-to-version-2-0" title="Permalink to this headline">¶</a></h2>
+<blockquote>
+<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 class="reference external" 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. These are the most important changes from 1.0 to 2.0:</p>
+<blockquote>
+<ul class="simple">
+<li>The need for a separate dbi module was dropped and the functionality
+merged into the module interface itself.</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.</li>
+<li>New constants (apilevel, threadlevel, paramstyle) and methods
+(executemany, nextset) were added to provide better database bindings.</li>
+<li>The semantics of .callproc() needed to call stored procedures are
+now clearly defined.</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.</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.</li>
+</ul>
+</blockquote>
+</blockquote>
+</div>
+<div class="section" id="open-issues">
+<h2>Open Issues<a class="headerlink" href="#open-issues" title="Permalink to this headline">¶</a></h2>
+<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>
+<ul class="simple">
+<li>Define a useful return value for .nextset() for the case where a new
+result set is available.</li>
+<li>Create a fixed point numeric type for use as loss-less monetary and
+decimal interchange format.</li>
+</ul>
+</div>
+<div class="section" id="footnotes">
+<h2>Footnotes<a class="headerlink" href="#footnotes" title="Permalink to this headline">¶</a></h2>
+<table class="docutils footnote" frame="void" id="f1" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>As a guideline the connection constructor parameters should be
+implemented as keyword parameters for more intuitive use and follow
+this order of parameters: <cite>dsn</cite> = Data source name as string <cite>user</cite> =
+User name as string (optional) <cite>password</cite> = Password as string
+(optional) <cite>host</cite> = Hostname (optional) <cite>database</cite> = Database name
+(optional) E.g. a connect could look like this:
+<cite>connect(dsn=’myhost:MYDB’,user=’guido’,password=‘234$?’)</cite></td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="f2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>Module implementors should prefer ‘numeric’, ‘named’ or ‘pyformat’
+over the other formats because these offer more clarity and
+flexibility.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="f3" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[3]</td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id6">2</a>, <a class="fn-backref" href="#id9">3</a>)</em> If the database does not support the functionality required by the
+method, the interface should throw an exception in case the method is
+used. The preferred approach is to not implement the method and thus
+have Python generate an <cite>AttributeError</cite> in case the method is
+requested. This allows the programmer to check for database
+capabilities using the standard <cite>hasattr()</cite> function. For some
+dynamically configured interfaces it may not be appropriate to require
+dynamically making the method available. These interfaces should then
+raise a <cite>NotSupportedError</cite> to indicate the non-ability to perform the
+roll back when the method is invoked.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="f4" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id4">[4]</a></td><td>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 <cite>.fetchXXX()</cite>
+methods.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="f5" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" hre...
[truncated message content] |
