简介

定义此 API 的目的是鼓励使用 Python 访问数据库的模块之间的相似性。通过这样做，我们希望实现一致性，从而使模块更容易理解，代码在数据库之间更便携，并扩展 Python 对数据库连接的覆盖范围。

有关此规范的意见和问题可以发送到 Python 数据库接口 SIG。

有关使用 Python 进行数据库接口和可用软件包的更多信息，请参阅 数据库主题指南。

本文档描述了 Python 数据库 API 规范 2.0 和一组常见的可选扩展。之前的版本 1.0 版本仍然可用作参考，在 PEP 248 中。鼓励软件包编写者使用此规范版本作为新接口的基础。

模块接口

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

连接对象

连接对象应该响应以下方法。

游标对象

这些对象表示数据库游标，它用于管理提取操作的上下文。从同一个连接创建的游标不是隔离的，即，一个游标对数据库所做的任何更改都会立即被其他游标看到。从不同连接创建的游标可以或不可以被隔离，具体取决于事务支持是如何实现的（另请参阅连接的 .rollback() 和 .commit() 方法）。

游标对象应该响应以下方法和属性。

类型对象和构造函数

许多数据库需要将输入以特定格式绑定到操作的输入参数。例如，如果输入是针对 DATE 列，则必须以特定字符串格式绑定到数据库。类似的问题存在于“行 ID”列或大型二进制项（例如 blob 或 RAW 列）中。这给 Python 带来问题，因为 .execute*() 方法的参数是无类型的。当数据库模块看到一个 Python 字符串对象时，它不知道它应该将其绑定为一个简单的 CHAR 列，作为原始 BINARY 项目，还是作为 DATE。

为了克服这个问题，模块必须提供下面定义的构造函数来创建可以保存特殊值的 对象。当传递给游标方法时，模块随后可以检测输入参数的正确类型并相应地绑定它。

Cursor 对象的 description 属性返回有关查询的每个结果列的信息。 type_code 必须与下面定义的类型对象之一相等。类型对象可能等于多个类型代码（例如，DATETIME 可能等于日期、时间和时间戳列的类型代码；有关详细信息，请参阅下面的 实现提示）。

该模块导出以下构造函数和单例

Date(year, month, day)

此函数构造一个保存日期值的 对象。

Time(hour, minute, second)

此函数构造一个保存时间的 对象。

Timestamp(year, month, day, hour, minute, second)

此函数构造一个保存时间戳值的 对象。

DateFromTicks(ticks)

此函数从给定的滴答值（自纪元以来的秒数；有关详细信息，请参阅 标准 Python 时间模块 的文档）构造一个保存日期值的 对象。

TimeFromTicks(ticks)

此函数从给定的滴答值（自纪元以来的秒数；有关详细信息，请参阅标准 Python 时间模块的文档）构造一个保存时间的 对象。

TimestampFromTicks(ticks)

此函数从给定的滴答值（自纪元以来的秒数；有关详细信息，请参阅标准 Python 时间模块的文档）构造一个保存时间戳值的 对象。

Binary(string)

此函数构造一个能够保存二进制（长）字符串值的 对象。

STRING 类型

此类型对象用于描述数据库中基于字符串的列（例如 CHAR）。

BINARY 类型

此类型对象用于描述数据库中（长）二进制列（例如 LONG、RAW、BLOB）。

NUMBER 类型

此类型对象用于描述数据库中的数字列。

DATETIME 类型

此类型对象用于描述数据库中的日期/时间列。

ROWID 类型

此类型对象用于描述数据库中的“行 ID”列。

SQL NULL 值在输入和输出中由 Python None 单例表示。

模块作者的实现提示

• 日期/时间对象可以实现为 Python datetime 模块 对象（自 Python 2.3 起可用，自 2.4 起提供 C API）或使用 mxDateTime 包（自 1.5.2 起适用于所有 Python 版本）。它们都以 Python 和 C 级别提供了所有必要的构造函数和方法。
• 以下是对 Unix 滴答基于构造函数的示例实现，将工作委托给通用构造函数

  import time
  
  def DateFromTicks(ticks):
      return Date(*time.localtime(ticks)[:3])
  
  def TimeFromTicks(ticks):
      return Time(*time.localtime(ticks)[3:6])
  
  def TimestampFromTicks(ticks):
      return Timestamp(*time.localtime(ticks)[:6])
  

• 对于二进制对象，首选的对象类型是标准 Python 中从版本 1.5.2 开始提供的缓冲区类型。有关详细信息，请参阅 Python 文档。有关 C 接口的信息，请查看 Python 源代码分发中的 Include/bufferobject.h 和 Objects/bufferobject.c。
• 此 Python 类允许实现上述类型对象，即使描述类型代码字段对一个类型对象产生多个值。

  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
  

  生成的类型对象与传递给构造函数的所有值相等。

• 以下是用 Python 代码实现上述异常层次结构的示例 [10]

  class Error(Exception):
      pass
  
  class Warning(Exception):
      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
  

  在 C 中，您可以使用 PyErr_NewException(fullname, base, NULL) API 创建异常对象。

可选的 DB API 扩展

在 DB API 2.0 的生命周期中，模块作者经常将其实现扩展到 DB API 规范要求的范围之外。为了增强兼容性并为未来版本的规范提供清晰的升级路径，本节定义了一组对核心 DB API 2.0 规范的常见扩展。

与所有 DB API 可选功能一样，数据库模块作者可以自由地不实现这些额外的属性和方法（使用它们会导致 AttributeError），或者在只有在运行时才能检查可用性时，抛出 NotSupportedError。

有人建议通过 Python 警告框架发出 Python 警告，让程序员可以选择性地查看这些扩展的使用情况。为了使此功能有用，必须标准化警告消息，以便能够屏蔽它们。以下将这些标准消息称为警告消息。

Cursor.rownumber

此只读属性应提供游标在结果集中的当前 0 索引，如果无法确定索引，则应提供 None。

索引可以看作游标在序列（结果集）中的索引。下一个获取操作将获取该序列中由 .rownumber 索引的行。

警告消息：“使用了 DB-API 扩展 cursor.rownumber”

Connection.Error，Connection.ProgrammingError 等。

DB API 标准定义的所有异常类都应作为属性暴露在 Connection 对象上（除了在模块范围内可用）。

这些属性简化了多连接环境中的错误处理。

警告消息：“使用了 DB-API 扩展 connection.<exception>”

Cursor.connection

此只读属性返回对创建游标的 Connection 对象的引用。

此属性简化了在多连接环境中编写多态代码。

警告消息：“使用了 DB-API 扩展 cursor.connection”

Cursor.scroll(value [, mode=’relative’ ])

根据mode，将游标在结果集中滚动到新的位置。

如果 mode 为 relative（默认），则 value 被视为结果集中当前位置的偏移量；如果设置为 absolute，则 value 表示绝对目标位置。

如果滚动操作将超出结果集，则应抛出 IndexError。在这种情况下，游标位置将被置为未定义状态（理想情况下是不移动游标）。

注意

此方法应使用本机可滚动游标（如果可用），或者对于仅向前可滚动游标，回退到仿真。此方法可能会抛出 NotSupportedError 来表示数据库不支持特定操作（例如，向后滚动）。

警告消息：“使用了 DB-API 扩展 cursor.scroll()”

Cursor.messages

这是一个 Python 列表对象，接口将所有来自底层数据库的此游标的消息（异常类、异常值）以元组形式追加到该列表中。

所有标准游标方法调用（在执行调用之前）都会清除该列表，除了 .fetch*() 调用会自动清除，以避免过度使用内存，也可以通过执行 del cursor.messages[:] 来清除该列表。

数据库生成的的所有错误和警告消息都将放入此列表中，因此检查此列表允许用户验证方法调用的正确操作。

此属性的目的是消除对 Warning 异常的需要，因为 Warning 异常通常会造成问题（一些警告实际上只具有信息性字符）。

警告消息：“使用了 DB-API 扩展 cursor.messages”

Connection.messages

与 Cursor.messages 相同，只是列表中的消息是面向连接的。

所有标准连接方法调用（在执行调用之前）都会自动清除该列表，以避免过度使用内存，也可以通过执行 del connection.messages[:] 来清除该列表。

警告消息：“使用了 DB-API 扩展 connection.messages”

Cursor.next()

使用与 .fetchone() 相同的语义，从当前正在执行的 SQL 语句中返回下一行。当结果集耗尽时，对于 Python 版本 2.2 及更高版本，将抛出 StopIteration 异常。早期版本没有 StopIteration 异常，因此该方法应改为抛出 IndexError。

警告消息：“使用了 DB-API 扩展 cursor.next()”

Cursor.__iter__()

返回 self，使游标与迭代协议兼容 [8]。

警告消息：“使用了 DB-API 扩展 cursor.__iter__()”

Cursor.lastrowid

此只读属性提供最后修改行的 rowid（大多数数据库仅在执行单个 INSERT 操作时返回 rowid）。如果操作未设置 rowid 或数据库不支持 rowid，则此属性应设置为 None。

如果最后执行的语句修改了不止一行（例如，使用 INSERT 与 .executemany()），则 .lastrowid 的语义将被定义为未定义。

警告消息：“使用了 DB-API 扩展 cursor.lastrowid”

Connection.autocommit

用于查询和设置连接的自动提交模式的属性。

如果连接以自动提交（非事务性）模式运行，则返回 True。如果连接以手动提交（事务性）模式运行，则返回 False。

将该属性设置为 True 或 False 将相应地调整连接的模式。

将设置从 True 更改为 False（禁用自动提交）将使数据库离开自动提交模式并启动一个新的事务。从 False 更改为 True（启用自动提交）在处理挂起的事务时具有依赖于数据库的语义。 [12]

弃用通知：即使几个数据库模块同时实现了此属性的读和写特性，通过写入属性来设置自动提交模式已弃用，因为这可能会导致 I/O 和相关异常，从而难以在异步上下文中实现。 [13]

警告消息：“使用了 DB-API 扩展 connection.autocommit”

可选的错误处理扩展

核心 DB API 规范只介绍了一组异常，这些异常可以抛出以向用户报告错误。在某些情况下，异常可能会对程序的流程造成太大干扰，甚至可能导致执行无法进行。

为了处理这些情况，并为了简化处理数据库时的错误处理，数据库模块作者可以选择实现用户定义的错误处理程序。本节描述了一种定义这些错误处理程序的标准方法。

Connection.errorhandler，Cursor.errorhandler

读写属性，引用在遇到错误情况时要调用的错误处理程序。

处理程序必须是 Python 可调用对象，它接受以下参数

errorhandler(connection, cursor, errorclass, errorvalue)

其中 connection 是对游标操作的连接的引用，cursor 是对游标的引用（如果错误不适用于游标，则为 None），errorclass 是要使用 errorvalue 作为构造参数来实例化的错误类。

标准错误处理程序应将错误信息添加到相应的 .messages 属性中（Connection.messages 或 Cursor.messages），并抛出由给定的 errorclass 和 errorvalue 参数定义的异常。

如果没有设置 .errorhandler（该属性为 None），则应应用上述标准错误处理方案。

警告消息：“使用了 DB-API 扩展 .errorhandler”

游标应在游标创建时从其连接对象继承 .errorhandler 设置。

可选的两阶段提交扩展

许多数据库支持两阶段提交 (TPC)，它允许跨多个数据库连接和其他资源管理事务。

如果数据库后端提供了对两阶段提交的支持，并且数据库模块作者希望公开这种支持，则应实现以下 API。如果只有在运行时才能检查数据库后端对两阶段提交的支持，则应抛出 NotSupportedError。

常见问题解答

数据库 SIG 通常会看到关于 DB API 规范的重复问题。本节介绍了人们有时对规范会遇到的一些问题。

问题

如何从 .fetch*() 返回的元组构造字典？

答案

有几个现有的工具可以提供用于此任务的帮助程序。它们中的大多数使用将游标属性 .description 中定义的列名用作行字典中键的基础的方法。

请注意，没有将 DB API 规范扩展到也支持 .fetch*() 方法的字典返回值的原因是，这种方法有几个缺点

• 一些数据库不支持区分大小写的列名，或自动将它们转换为全小写或全大写字符。
• 结果集中的由查询生成的列（例如，使用 SQL 函数）不映射到表列名，并且数据库通常以非常数据库特定的方式为这些列生成名称。

因此，通过字典键访问列在数据库之间有所不同，并使编写可移植代码变得不可能。

与版本 1.0 相比，版本 2.0 的主要变化

Python 数据库 API 2.0 与 1.0 版本相比引入了一些重大更改。由于其中一些更改会导致现有的基于 DB API 1.0 的脚本中断，因此主版本号已调整以反映此更改。

以下是 1.0 到 2.0 的最重要更改

• 对单独的 dbi 模块的需求已被删除，其功能已合并到模块接口本身。
• 为日期/时间值添加了新的构造函数和 类型对象，RAW 类型对象已重命名为 BINARY。结果集应该涵盖现代 SQL 数据库中常见的全部基本数据类型。
• 添加了新的常量（apilevel、threadsafety、paramstyle）和方法（.executemany()、.nextset()）以提供更好的数据库绑定。
• 调用存储过程所需的 .callproc() 的语义现在已明确定义。
• .execute() 返回值的定义已更改。以前，返回值是基于 SQL 语句类型（这很难正确实现）——它现在未定义；改用更灵活的 .rowcount 属性。模块可以自由地返回旧样式的返回值，但这些不再由规范强制执行，应被视为数据库接口依赖项。
• 基于类的 异常 已合并到规范中。模块实现者可以自由地通过对定义的异常类进行子类化来扩展本规范中定义的异常布局。

发布后对 DB API 2.0 规范的补充

• 指定了对核心功能集的额外可选 DB API 扩展。

未解决问题

尽管 2.0 版规范澄清了 1.0 版中遗留的许多问题，但仍有一些遗留问题需要在将来的版本中解决

• 为 .nextset() 定义一个有用的返回值，用于有新结果集可用的情况。
• 集成 decimal 模块 Decimal 对象，以用作无损货币和十进制交换格式。

脚注

鸣谢

衷心感谢 Andrew Kuchling，他在 2001 年将 Python 数据库 API 规范 2.0 从最初的 HTML 格式转换为 PEP 格式。

衷心感谢 James Henstridge，他在 2008 年领导了关于标准化两阶段提交 API 扩展的讨论。

衷心感谢 Daniele Varrazzo，他在 2012 年将规范从文本 PEP 格式转换为 ReST PEP 格式，这使得可以链接到各种部分。

版权

本文件已置于公共领域。