引言

此 API 的定义旨在鼓励用于访问数据库的 Python 模块之间保持相似性。通过这样做，我们希望实现一致性，从而产生更易于理解的模块、更易于跨数据库移植的代码以及更广泛的 Python 数据库连接范围。

此接口规范包含以下几项

• 模块接口
• 连接对象
• 游标对象
• DBI 辅助对象

有关此规范的评论和问题可发送至 Python 表格数据库特别兴趣小组 (https://pythonlang.cn/sigs/db-sig)。

本规范文档最后更新日期为：1996 年 4 月 9 日。它将被称为本规范的 1.0 版。

模块接口

数据库接口模块的名称通常应以 db 结尾。现有示例包括：oracledb、informixdb 和 pg95db。这些模块应导出以下几个名称

模块名(连接字符串)

用于创建数据库连接的构造函数。返回一个连接对象。

错误

数据库模块错误引发的异常。

连接对象

连接对象应响应以下方法

关闭()

立即关闭连接（而不是在调用 __del__ 时）。从此刻起，连接将无法使用；如果尝试对连接执行任何操作，将引发异常。

提交()

将任何待处理事务提交到数据库。

回滚()

将数据库回滚到任何待处理事务的开始。

游标()

返回一个新的游标对象。如果数据库不支持游标概念，可能会抛出异常。

调用过程([参数])

（注意：此方法尚未明确定义。）使用给定（可选）参数调用存储的数据库过程。返回存储过程的结果。

（所有游标对象属性和方法）

对于没有游标的数据库以及不需要游标复杂性的简单应用程序，连接对象应响应游标对象的每个属性和方法。具有游标的数据库可以通过使用隐式内部游标来实现这一点。

游标对象

这些对象代表一个数据库游标，用于管理获取操作的上下文。

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

数组大小

此读/写属性指定 fetchmany() 一次获取的行数。此值也用于一次插入多行时（将元组/元组列表/列表作为 params 值传递给 execute()）。此属性默认为单行。

请注意，arraysize 是可选的，仅用于提高数据库交互的性能。实现应在 fetchmany() 方法中遵守它，但可以自由地一次与数据库交互一行。

描述

此只读属性是一个由 7 元组组成的元组。每个 7 元组包含描述每个结果列的信息：（名称、类型代码、显示大小、内部大小、精度、比例、可空性）。对于不返回行的操作，或者游标尚未通过 execute() 方法调用操作时，此属性将为 None。

“type_code”是下面部分中指定的“dbi”值之一。

注意：这一点有点不稳定。通常，7 元组的前两个项目将始终存在；其他项目可能因数据库而异。

关闭()

立即关闭游标（而不是在调用 __del__ 时）。从此刻起，游标将无法使用；如果尝试对游标执行任何操作，将引发异常。

执行(操作 [,参数])

执行（准备）数据库操作（查询或命令）。可以提供参数（作为序列（例如元组/列表）），并将绑定到操作中的变量。变量以基于参数元组中索引（基于位置而非基于名称）的数据库特定表示法指定。

参数也可以指定为序列的序列（例如，元组列表），以在单个操作中插入多行。

游标将保留对操作的引用。如果再次传入相同的操作对象，则游标可以优化其行为。这对于使用相同操作但绑定不同参数（多次）的算法最有效。

为了在重用操作时实现最大效率，最好使用 setinputsizes() 方法提前指定参数类型和大小。参数与预定义信息不匹配是合法的；实现应进行补偿，可能会导致效率损失。

使用 SQL 术语，这些是 execute() 方法的可能结果值

• 如果语句是 DDL（例如 CREATE TABLE），则返回 1。
• 如果语句是 DML（例如 UPDATE 或 INSERT），则返回受影响的行数（0 或正整数）。
• 如果语句是 DQL（例如 SELECT），则返回 None，表示该语句在您使用其中一个“fetch”方法之前并未真正完成。

取一行()

获取查询结果的下一行，返回一个元组。

取多行([大小])

获取查询结果的下一组行，返回一个元组列表。当没有更多行可用时，返回一个空列表。要获取的行数由参数指定。如果它是 None，则游标的 arraysize 决定要获取的行数。

请注意，size 参数涉及性能考虑。为了获得最佳性能，通常最好使用 arraysize 属性。如果使用 size 参数，那么最好让它在一次 fetchmany() 调用到下一次调用之间保持相同的值。

取所有()

获取查询结果的所有行，返回一个元组列表。请注意，游标的 arraysize 属性可能会影响此操作的性能。

设置输入大小(大小)

（注意：此方法尚未明确定义。）这可以在调用 execute() 之前使用，以预定义操作参数的内存区域。sizes 指定为一个元组——每个输入参数一项。该项应该是一个与将使用的输入对应的 Type 对象，或者它应该是一个指定字符串参数最大长度的整数。如果该项是 None，则不会为该列保留预定义的内存区域（这对于避免为大型输入预定义区域很有用）。

此方法将在调用 execute() 方法之前使用。

请注意，此方法是可选的，仅用于提高数据库交互的性能。实现可以不做任何事情，用户也可以不使用它。

设置输出大小(大小 [,列])

（注意：此方法尚未明确定义。）

为获取大列（例如 LONG）设置列缓冲区大小。该列指定为结果元组中的索引。使用 None 列将为游标中的所有大列设置默认大小。

此方法将在调用 execute() 方法之前使用。

请注意，此方法是可选的，仅用于提高数据库交互的性能。实现可以不做任何事情，用户也可以不使用它。

DBI 辅助对象

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

为了克服这个问题，创建了“dbi”模块。这个模块指定了一些用于处理数据库的基本数据库接口类型。有两个类：“dbiDate”和“dbiRaw”。这些是封装值的简单容器类。当传递给数据库模块时，模块可以检测到输入参数 intended 是 DATE 还是 RAW。为了对称性，数据库模块将返回 DATE 和 RAW 列作为这些类的实例。

游标对象的“description”属性返回有关查询结果的每个列的信息。“type_code”被定义为该模块导出的五种类型之一：STRING、RAW、NUMBER、DATE 或 ROWID。

该模块导出以下名称

dbiDate(值)

此函数构造一个包含日期值的“dbiDate”实例。该值应指定为自“纪元”以来的秒数整数（例如 time.time()）。

dbiRaw(值)

此函数构造一个包含原始（二进制）值的“dbiRaw”实例。该值应指定为 Python 字符串。

字符串

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

原始

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

数字

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

日期

此对象用于描述数据库中的日期列。

行ID

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

致谢

非常感谢 Andrew Kuchling 于 2001 年将 Python 数据库 API 规范 1.0 从原始 HTML 格式转换为 PEP 格式。

Greg Stein 是 Python 数据库 API 规范 1.0 的原始作者。Marc-André 后来作为编辑继续维护该 API。

版权

本文档已置于公共领域。