引言

定义此 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”列或大型二进制项（例如 blobs 或 RAW 列）也存在类似问题。这给 Python 带来了问题，因为 .execute*() 方法的参数是无类型的。当数据库模块看到 Python 字符串对象时，它不知道是应该将其绑定为简单的 CHAR 列、作为原始 BINARY 项，还是作为 DATE。

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

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

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

Date(year, month, day)

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

Time(hour, minute, second)

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

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

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

DateFromTicks(ticks)

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

TimeFromTicks(ticks)

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

TimestampFromTicks(ticks)

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

Binary(string)

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

STRING 类型

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

BINARY 类型

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

NUMBER 类型

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

DATETIME 类型

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

ROWID 类型

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

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

模块作者的实现提示

• 日期/时间对象可以作为Python datetime 模块对象（Python 2.3 开始可用，2.4 开始提供 C API）或使用 mxDateTime 包（Python 1.5.2 及更高版本均可用）实现。它们都提供了 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 警告，使这些扩展的使用对程序员可选可见。为了使此功能有用，警告消息必须标准化，以便能够屏蔽它们。这些标准消息在下文中称为 Warning Message。

Cursor.rownumber

此只读属性应提供游标在结果集中的当前 0-based 索引，如果无法确定索引，则为 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__()

返回自身以使游标与迭代协议兼容 [8]。

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

Cursor.lastrowid

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

如果上次执行的语句修改了多行（例如，使用 .executemany() 进行 INSERT），则 .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 格式，从而允许链接到各个部分。

版权

本文档已置于公共领域。