"sqlite3" --- SQLite 数据库 DB-API 2.0 接口模块
***********************************************

**原始碼：**Lib/sqlite3/

SQLite 是一个C语言库，它可以提供一种轻量级的基于磁盘的数据库，这种数据
库不需要独立的服务器进程，也允许需要使用一种非标准的 SQL 查询语言来访
问它。一些应用程序可以使用 SQLite 作为内部数据存储。可以用它来创建一个
应用程序原型，然后再迁移到更大的数据库，比如 PostgreSQL 或 Oracle。

"sqlite3" 模块由Gerhard Häring编写。它提供了 **PEP 249** 所描述的符合
DB-API 2.0 规范的 SQL 接口，并要求使用 SQLite 3.7.15 或更新的版本。

本文档包括了四个主要部分：

* 教程 将教你如何使用 "sqlite3" 模块。

* 参考 描述了该模块定义的类与函数。

* 常用方案指引 详细介绍了如何处理一些特定的任务。

* 解釋 提供了关于事务控制（transaction control）的更深一步的背景。

也參考:

  https://www.sqlite.org
     SQLite的主页；它的文档详细描述了它所支持的 SQL 方言的语法和可用的
     数据类型。

  https://www.w3schools.com/sql/
     学习 SQL 语法的教程、参考和例子。

  **PEP 249** - DB-API 2.0 规范
     PEP 由 Marc-André Lemburg 撰寫。


教程
====

在本篇教程中，你将会使用 "sqlite3" 模块的基本功能创建一个存储 Monty
Python 的电影作品信息的数据库。本篇教程假定您在阅读前对于数据库的基本
概念有所了解，例如 cursors  与  transactions  。

首先，我们需要创建一个新的数据库并打开一个数据库连接以允许 "sqlite3"
通过它来动作。 调用 "sqlite3.connect()" 来创建与当前工作目录下
"tutorial.db" 数据库的连接，如果它不存在则会隐式地创建它:

   import sqlite3
   con = sqlite3.connect("tutorial.db")

上面的代码中，返回的 "Connection" 对象 "con" 代表一个与在磁盘上的数据
库（on-disk databse）的连接。

为了执行 SQL 语句并且从 SQL 查询中取得结果，我们需要使用游标 (cursor)
。在下面的代码中，我们调用函数 "con.cursor()" 创建了一个游标
("Cursor") ：

   cur = con.cursor()

通过上面的操作，我们已经得到了与数据库的连接 (connection) 与游标
(cursor) ，现在我们便可以在数据库中创建一张名为 "movie" 的表了，它包括
电影名 （title，在下方代码中对应“title”）、上映年份（release year，在
下方代码中对应“year”）以及电影评分（review score，在下方代码中对应
“score”）这三列。在本篇教程中，出于简洁的考虑，我们在创建表的 SQL 语句
声明中只列出表头名 (column names) ，而没有像一般的 SQL 语句那样同时声
明数据列的对应数据类型 —— 这一点得益于 SQLite 的 flexible typing 特性
，它使得我们在使用 SQLite 时，指明数据类型这一项工作时可选的。如下面的
代码所示，我们通过调用函数 "cur.excute(...)" 执行创建表格的 "CREATE
TABLE" 语句：

   cur.execute("CREATE TABLE movie(title, year, score)")

我们可以通过查询 SQLite 内置的 "sqlite_matser" 表以验证新表是否已经创
建，本例中，此时该表应该已经包括了一条 "movie" 的表定义（更多内容请参
考 The Schema Table ）。下面的代码将通过调用函数 "cur.excute(...)" 执
行查询，把结果赋给 "res" ，而后调用 "res.fetchone()" 获取结果行：

   >>> res = cur.execute("SELECT name FROM sqlite_master")
   >>> res.fetchone()
   ('movie',)

在上面的代码中，我们可以看到表格已经被创建，因为查询结果返回了一个包含
表格名的元组 ("tuple") 。倘若我们在 "sqlite_master" 表中查询一个并不存
在的表 "spam" ，那么 "res.fetchone()" 将会返回 "None" ：

   >>> res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")
   >>> res.fetchone() is None
   True

现在，让我们再次调用 "cur.execute(...)" 去添加由 SQL 字面量 (literals)
提供的两行数据：

   cur.execute("""
       INSERT INTO movie VALUES
           ('Monty Python and the Holy Grail', 1975, 8.2),
           ('And Now for Something Completely Different', 1971, 7.5)
   """)

"INSERT" 语句将隐式地创建一个事务 (transaction) ，事务需要在将更改保存
到数据库前提交（更多细节请参考 事务控制 ）。我们通过在一个连接对象（本
例中为 "con"）上调用 "con.commit()" 提交事务：

   con.commit()

我们可以通过执行一个 "SELECT" 查询以验证数据是否被正确地插入表中。下面
的代码中，我们使用我们已经很熟悉的函数 "cur.execute(...)" 将查询结果赋
给 "res" ，而后调用 "res.fetchall()" 返回所有的结果行：

   >>> res = cur.execute("SELECT score FROM movie")
   >>> res.fetchall()
   [(8.2,), (7.5,)]

上面的代码中，结果是一个包含了两个元组 ("tuple") 的列表 ("list") ，其
中每一个元组代表一个数据行，每个数据行都包括该行的 "score" 值。

现在，让我们调用 "cur.executemany(...)" 再插入三行数据：

   data = [
       ("Monty Python Live at the Hollywood Bowl", 1982, 7.9),
       ("Monty Python's The Meaning of Life", 1983, 7.5),
       ("Monty Python's Life of Brian", 1979, 8.0),
   ]
   cur.executemany("INSERT INTO movie VALUES(?, ?, ?)", data)
   con.commit()  # Remember to commit the transaction after executing INSERT.

请注意，占位符 (placeholders) "?" 是用来在查询中绑定数据 "data" 的。在
绑定 Python 的值到 SQL 语句中时，请使用占位符取代格式化字符串 (string
formatting ) 以避免 SQL 注入攻击 （更多细节请参见 如何在 SQL 查询中使
用占位符来绑定值 ）。

同样的，我们可以通过执行 "SELECT" 查询验证新的数据行是否已经插入表中，
这一次我们将迭代查询的结果：

   >>> for row in cur.execute("SELECT year, title FROM movie ORDER BY year"):
   ...     print(row)
   (1971, 'And Now for Something Completely Different')
   (1975, 'Monty Python and the Holy Grail')
   (1979, "Monty Python's Life of Brian")
   (1982, 'Monty Python Live at the Hollywood Bowl')
   (1983, "Monty Python's The Meaning of Life")

如上可见，每一行都是包括 "(year,title)" 这两个元素的元组 ("tuple" ) ，
它与我们查询中选中的数据列相匹配。

最后，让我们先通过调用 "con.close()" 关闭现存的与数据库的连接，而后打
开一个新的连接、创建一个新的游标、执行一个新的查询以验证我们是否将数据
库写入到了本地磁盘上：

   >>> con.close()
   >>> new_con = sqlite3.connect("tutorial.db")
   >>> new_cur = new_con.cursor()
   >>> res = new_cur.execute("SELECT title, year FROM movie ORDER BY score DESC")
   >>> title, year = res.fetchone()
   >>> print(f'The highest scoring Monty Python movie is {title!r}, released in {year}')
   The highest scoring Monty Python movie is 'Monty Python and the Holy Grail', released in 1975

现在您已经成功地使用模块 "sqlite3" 创建了一个 SQLite 数据库，并且学会
了以多种方式往其中插入数据与检索值。

也參考:

  * 阅读 常用方案指引 以获取更多信息：

       * 如何在 SQL 查询中使用占位符来绑定值

       * 如何将自定义 Python 类型适配到 SQLite 值

       * 如何将 SQLite 值转换为自定义 Python 类型

       * 如何使用连接上下文管理器

       * 如何创建并使用行工厂对象

  * 参阅 解釋 以获取关于事务控制的更深一步的背景。


参考
====


模块函数
--------

sqlite3.connect(database, timeout=5.0, detect_types=0, isolation_level='DEFERRED', check_same_thread=True, factory=sqlite3.Connection, cached_statements=100, uri=False)

   打开一个与 SQLite 数据库的连接。

   參數:
      * **database** (*path-like object*) -- 数据库文件所在的路径。传
        入 "":memory:"" 将会打开一个与在计算机内存 (RAM) 中的数据库连
        接，而不是打开与在本地磁盘 (disk) 上储存的数据库的连接。

      * **timeout** (*float*) -- 当一个表被锁定时连接在最终引发
        "OperationalError" 之前应该等待多少秒。 如果另一个链接开启了一
        个事务来修改一个表，该表将被锁定直到该事务完成提交。 默认值为
        五秒。

      * **detect_types** (*int*) -- 控制是否以及如何使用由
        "register_converter()" 注册的转换器将并非由 SQLite 原生支持的
        数据类型转换为 Python 类型。 将它设置为 "PARSE_DECLTYPES" 和
        "PARSE_COLNAMES" 的任意组合 (使用 "|"，即按位或) 来启动它。 如
        果两个旗标都被设置则列名将优先于声明的类型。 即使设置了
        *detect_types*，依然无法对生成的字段 (例如 "max(data)") 进行类
        型检测；此时它将改为返回 "str"。 当使用默认值 ("0") 时，类型检
        测将被禁用。

      * **isolation_level** (*str | None*) -- 该参数代表数据库连接的事
        务控制级别 ("isolation_level")，它将控制数据库事务
        (transactions) 是否以及如何隐式创建。它的可取值为 ""DEFERRED""
        （默认值），""EXCLUSIVE""，""IMMEDIATE"" 或 "None" （取用该值
        将禁止事务的隐式创建）。请参阅 事务控制 以获取更多信息。

      * **check_same_thread** (*bool*) -- 如果为 "True" (默认)，则
        "ProgrammingError" 将在数据库连接被它的创建者以外的线程使用时
        被引发。 如果为 "False"，则连接可以在多个线程中被访问；写入操
        作需要由用户者进行序列化以避免数据损坏。 请参阅 "threadsafety"
        了解详情。

      * **factory** (*Connection*) -- 如果您不想使用默认的
        "Connection" 类创建连接，那么您可以通过传入一个自定义的
        "Connection" 类的子类给该参数以创建连接。

      * **cached_statements** (*int*) -- "sqlite3" 应当为该连接进行内
        部缓存以避免解析开销的语句数量。 在默认情况下为 100 条语句。

      * **uri** (*bool*) -- 如果将该参数的值设置为 "True"，参数
        *database* 将会被解释为一个由文件路径与可选的查询字符串组成的
        URI (Uniform Resource Identifier) 链接。链接的前缀协议部分
        (schema part) *必需* 是 ""file:"" ，后面的文件路径可以是相对路
        径或绝对路径。查询字符串允许向 SQLite 传递参数，以实现不同的
        如何使用 SQLite URI。

   傳回型態:
      Connection

   使用它将引发一个附带参数 "database" 的 审计事件 (auditing event)
   "sqlite3.connect" 。

   使用它将引发一个附带参数 "connection_handle" 的 审计事件
   "sqlite3.connect/handle" 。

   3.4 版新加入: *uri* 參數。

   3.7 版更變: *database* 现在可以是一个 *path-like object* 对象了，而
   不仅仅是字符串。

   3.10 版新加入: 审计事件 "sqlite3.connect/handle" 。

sqlite3.complete_statement(statement)

   如果传入的字符串语句 (statement) 看起来像是包括一条或多条完整的 SQL
   语句，那么该函数将返回 "True" 。请注意，除了检查未封闭的字符串字面
   (unclosed string literals) 以及语句是否以分号结束外，它不会执行任何
   的语法检查 (syntactic verification) 与语法解析 (synatatic parsing)
   。

   範例：

      >>> sqlite3.complete_statement("SELECT foo FROM bar;")
      True
      >>> sqlite3.complete_statement("SELECT foo")
      False

   该函数可能在这样的情形下非常有用：在通过命令行 (command-line) 输入
   数据时，可使用该函数判断输入文本是否可以构成一个完成的 SQL 语句，或
   者判断在调用函数 "execute()" 前是否还需要额外的输入。

sqlite3.enable_callback_tracebacks(flag, /)

   是否启用回调回溯 (callback tracebacks) 。默认情况下，在 SQLite 中，
   您不会在用户定义的函数、聚合函数 (aggregates) 、转换函数
   (converters) 、验证回调函数 (authorizer callbacks) 等中得到任何回溯
   信息。如果您想调试它们，您可以在将形式参数 *flag* 设置为 "True" 的
   情况下调用该函数。之后您便可以从 "sys.stderr" 的回调中得到回溯信息
   。使用 "False" 将再次禁用该功能。

sqlite3.register_adapter(type, adapter, /)

   注册一个可调用的适配器 (adapter) 以将一个 Python 类型适配为一个
   SQLite 类型。适配器应该以一个类型为 *type* 的 Python 对象作为它的唯
   一参数传入调用，并且必需返回能被 SQLite 原生支持的类型的一个值 。

sqlite3.register_converter(typename, converter, /)

   注册一个可调用的转换器 (converter) ，它能够将 SQLite 对象转换为一个
   特定类型的 Python 对象。转换器将会对所有类型为 *typename* 的 SQLite
   值进行调用；它会被传递给一个 "bytes" 对象并且应该返回一个所需的
   Python 类型的对象。您可以参考函数 "connect()" 的形式参数
   *detect_types* 的文档，以了解关于类型检测 (detection works) 是如何
   工作的详细信息。

   注：*typename* 以及您在查询中使用的类型名是不大小写敏感的。


模块常量
--------

sqlite3.PARSE_COLNAMES

   将这个旗标值传递给 "connect()" 的 *detect_types* 形参，以使用从查询
   列名解析的类型名作为转换器字典键来查找转换器函数。类型名称必须用方
   括号（"[]"）括起来。

      SELECT p as "p [point]" FROM test;  ! will look up converter "point"

   此旗标可以使用 "|" （位或）运算符与 "PARSE_DECLTYPES" 组合。

sqlite3.PARSE_DECLTYPES

   将这个旗标值传递给 "connect()" 的 *detect_types* 形参，以使用创建数
   据库表时为每列声明的类型的查找转换器函数。"sqlite3" 将使用声明类型
   的第一个单词作为转换字典键来查找转换函数。例如：

      CREATE TABLE test(
         i integer primary key,  ! will look up a converter named "integer"
         p point,                ! will look up a converter named "point"
         n number(10)            ! will look up a converter named "number"
       )

   此旗标可以使用 "|" （位或）运算符与 "PARSE_COLNAMES" 组合。

sqlite3.SQLITE_OK
sqlite3.SQLITE_DENY
sqlite3.SQLITE_IGNORE

   作为传递给函数 "Connection.set_authorizer()" 的形式参数
   *authorizer_callback* 的回调函数应该返回的标志 (flags) ，以表明是否
   ：

   * 访问被允许（"SQLITE_OK"）。

   * SQL语句伴异常的执行失败（"SQLITE_DENY"）。

   * 该列应被视为NULL（"SQLITE_IGNORE"）。

sqlite3.apilevel

   指明所支持的 DB-API 级别的字符串常量。 根据 DB-API 的需要设置。 硬
   编码为 ""2.0""。

sqlite3.paramstyle

   指明 "sqlite3" 模块所预期的形参标记格式化类型。 根据 DB-API 的需要
   设置。 硬编码为 ""qmark""。

   備註:

     "named" DB-API 形参风格也受到支持。

sqlite3.sqlite_version

   以 "字符串" 表示的运行时 SQLite 库版本号。

sqlite3.sqlite_version_info

   以 "整数" "tuple" 表示的运行时. SQLite 库版本号。

sqlite3.threadsafety

   由 DB-API 所需要的整数常量，指明 "sqlite3" 模块支持的线程安全
   (thread safety) 等级。目前硬编码为 "1"，表示 *线程可能会分享模块
   (module) ，但不会分享连接 (connections)* 。然而，这可能不会总是正确
   的，即它无法完全确保它所指明的情况总是为真。您可以通过使用以下查询
   以检查底层的 SQLite 库在编译时的线程模式 (threaded mode) ：

      import sqlite3
      con = sqlite3.connect(":memory:")
      con.execute("""
          select * from pragma_compile_options
          where compile_options like 'THREADSAFE=%'
      """).fetchall()

   注意 SQLITE_THREADSAFE 级别 与 DB-API 2.0 "threadsafety" 级别不一致
   。

sqlite3.version

   此模块 "字符串" 形式的版本号。 这不是 SQLite 库的版本号。

sqlite3.version_info

   此模块 "整数" "tuple" 形式的版本号。 这不是 SQLite 库的版本号。
   library.


连接对象
--------

class sqlite3.Connection

   每个打开的 SQLite 数据库均以 "Connection" 对象来表示，这种对象是使
   用 "sqlite3.connect()" 创建的。 它们的主要目的是创建 "Cursor" 对象
   ，以及 事务控制。

   也參考:

     * 如何使用连接快捷方法

     * 如何使用连接上下文管理器

   SQLite 数据库连接对象有如下的属性和方法：

   cursor(factory=Cursor)

      创建并返回一个 "Cursor" 对象。该方法接受一个可选的形式参数
      *factory* 。如果要提供该参数，请确保该参数是一个能够返回从属于
      "Cursor" 类或其子类的实例的可调用参数。

   commit()

      向数据库提交任何未决事务 (pending transaction) 。如果不存在打开
      的事务，那么该方法便没有作用。

   rollback()

      回滚到任何未决事务 (pending transaction) 的起点处。如果不存在打
      开的事务，那么该方法便没有作用。

   close()

      关闭数据库连接。任何未决事务 (pending transaction) 都不会被隐式
      提交，即所有未提交的事务都会丢失。请确保您在关闭数据库连接前调用
      方法 "commit()" ，以避免丢失任何挂起 (pending) 的更改。

   execute(sql, parameters=(), /)

      创建一个新的 "Cursor" 对象，并在其上使用给出的 *sql* 和
      *parameters* 调用 "execute()"。 返回新的游标对象。

   executemany(sql, parameters, /)

      创建一个新的 "Cursor" 对象，并在其上使用给出的 *sql* 和
      *parameters* 调用 "executemany()"。 返回新的游标对象。

   executescript(sql_script, /)

      创建一个新的 "Cursor" 对象，并在其上使用给出的 *sql_script* 调用
      "executescript()"。 返回新的游标对象。

   create_function(name, narg, func, *, deterministic=False)

      创建或移除用户定义的 SQL 函数。

      參數:
         * **name** (*str*) -- SQL 函数的名称。

         * **narg** (*int*) -- SQL 函数可接受的参数数量，如果是 "-1"，
           则该函数可以接受任意数量的参数。

         * **func** (*callback* | None) -- 当 SQL 函数被调用时，所唤起
           的一个可调用对象 (callable) 。该可调用对象应该返回 一个
           SQLite 原生支持的类型 。如果将它设置为 "None" ，那么将会移
           除一个现存的 SQL 函数。

         * **deterministic** (*bool*) -- 如为 "True"，创建的 SQL 函数
           将被标记为 deterministic，这允许 SQLite 执行额外的优化。

      丟出:
         **NotSupportedError** -- 如果 *deterministic* 在早于 SQLite
         3.8.3 的版本上使用。

      3.8 版新加入: 新增 *deterministic* 參數。

      範例：

         >>> import hashlib
         >>> def md5sum(t):
         ...     return hashlib.md5(t).hexdigest()
         >>> con = sqlite3.connect(":memory:")
         >>> con.create_function("md5", 1, md5sum)
         >>> for row in con.execute("SELECT md5(?)", (b"foo",)):
         ...     print(row)
         ('acbd18db4cc2f85cedef654fccc4a4d8',)

   create_aggregate(name, /, n_arg, aggregate_class)

      创建或移除用户自定义的 SQL 聚合函数。

      參數:
         * **name** (*str*) -- SQL 聚合函数的名称。

         * **n_arg** (*int*) -- SQL 聚合函数可接受的参数数量。 如为
           "-1"，则可以接受任意数量的参数。

         * **aggregate_class** (*class* | None) -- 一个类必须实现下列
           方法:  * "step()": 向聚合添加一行。 * "finalize()": 将聚合
           的最终结果作为 一个 SQLite 原生支持的类型 返回。 "step()"
           方法需要接受的参数数量是由 *n_arg* 控制的。 设为 "None" 将
           移除现有的 SQL 聚合函数。

      範例：

         class MySum:
             def __init__(self):
                 self.count = 0

             def step(self, value):
                 self.count += value

             def finalize(self):
                 return self.count

         con = sqlite3.connect(":memory:")
         con.create_aggregate("mysum", 1, MySum)
         cur = con.execute("CREATE TABLE test(i)")
         cur.execute("INSERT INTO test(i) VALUES(1)")
         cur.execute("INSERT INTO test(i) VALUES(2)")
         cur.execute("SELECT mysum(i) FROM test")
         print(cur.fetchone()[0])

         con.close()

   create_collation(name, callable)

      使用排序函数 *callable* 创建一个名为 *name* 的排序规则。
      *callable* 被传递给两个 "字符串" 参数，并且它应该返回一个 "整数"
      。

      * 如果前者的排序高于后者则为 "1"

      * 如果前者的排序低于于后者则为 "-1"

      * 如果它们的顺序相同则为 "0"

      下面的例子显示了一个反向排序的排序方法:

         def collate_reverse(string1, string2):
             if string1 == string2:
                 return 0
             elif string1 < string2:
                 return 1
             else:
                 return -1

         con = sqlite3.connect(":memory:")
         con.create_collation("reverse", collate_reverse)

         cur = con.execute("CREATE TABLE test(x)")
         cur.executemany("INSERT INTO test(x) VALUES(?)", [("a",), ("b",)])
         cur.execute("SELECT x FROM test ORDER BY x COLLATE reverse")
         for row in cur:
             print(row)
         con.close()

      通过将 *callable* 设为 "None" 来移除一个排序规则函数。

   interrupt()

      从其他的线程调用此方法以中止可能正在连接上执行的任何查询。 被中
      止的查询将引发 "OperationalError"。

   set_authorizer(authorizer_callback)

      注册可调用的 *authorizer_callback* 回调函数，它将在每次试图访问
      数据库中的表的某一列被调用。回调函数应该返回常量 "SQLITE_OK"、
      "SQLITE_DENY"、"SQLITE_IGNORE" 中的任意一个，以表明对该列的访问
      应该由底层 SQLite 库进行怎样的处理。

      该回调的第一个参数指明哪种操作将被授权。 第二个和第三个参数根据
      第一个参数的具体值将为传给操作的参数或为 "None"。 第四个参数如果
      适用则为数据库名称（"main", "temp" 等）。 第五个参数是负责尝试访
      问的最内层触发器或视图的名称或者如果该尝试访问是直接来自输入的
      SQL 代码的话则为 "None"。

      请参阅 SQLite 文档了解第一个参数可能的值以及依赖于第一个参数的第
      二个和第三个参数的含义。 所有必需的常量均在 "sqlite3" 模块中可用
      。

   set_progress_handler(progress_handler, n)

      注册可调用的 *progress_handler* 函数，它将在 SQLite 虚拟机
      (SQLite virtual machine) 的每 *n* 条指令中被调用。如果您向在长期
      运行的操作中得到 SQLite 的调用，例如更新GUI，那么这个函数将非常
      有用。

      如果你想清除任何先前安装的进度处理句柄，可在调用该方法时传入
      "None" 作为 *progress_handler*。

      从处理函数返回非零值将终止当前正在执行的查询并导致它引发
      "OperationalError" 异常。

   set_trace_callback(trace_callback)

      注册可调用的 *trace_callback* 追踪回调函数，它将在 SQLite后端
      (SQLite backend) 执行每一条 SQL 语句时被调用。

      传给该回调的唯一参数是被执行的语句 (作为 "str")。 回调的返回值将
      被忽略。 请注意后端不仅会运行传给 "Cursor.execute()" 方法的语句
      。 其他来源还包括 "sqlite3" 模块的 事务管理 以及在当前数据库中定
      义的触发器的执行。

      传入 "None" 作为 *trace_callback* 将禁用追踪回调。

      備註:

        在跟踪回调中产生的异常不会被传播。作为开发和调试的辅助手段，使
        用 "enable_callback_tracebacks()" 来启用打印跟踪回调中产生的异
        常的回调。

      3.3 版新加入.

   enable_load_extension(enabled, /)

      如果 *enabled* 为 "True" 则允许 SQLite 从共享库加载 SQLite 扩展
      ；否则，不允许加载 SQLite 扩展。 SQLite 扩展可以定义新的函数、聚
      合或全新的虚拟表实现。 一个知名的扩展是与随同 SQLite 一起分发的
      全文搜索扩展。

      備註:

        在默认情况下 "sqlite3" 模块的构建没有附带可加载扩展支持，因为
        某些平台（主要是 macOS）上的 SQLite 库在编译时未启用此特性。
        要获得可加载扩展支持，你必须将 "--enable-loadable-sqlite-
        extensions" 选项传给 **configure**。

      引发一个 审计事件 "sqlite3.enable_load_extension"，附带参数
      "connection", "enabled"。

      3.2 版新加入.

      3.10 版更變: 增加了 "sqlite3.enable_load_extension" 审计事件。

         con.enable_load_extension(True)

         # Load the fulltext search extension
         con.execute("select load_extension('./fts3.so')")

         # alternatively you can load the extension using an API call:
         # con.load_extension("./fts3.so")

         # disable extension loading again
         con.enable_load_extension(False)

         # example from SQLite wiki
         con.execute("CREATE VIRTUAL TABLE recipe USING fts3(name, ingredients)")
         con.executescript("""
             INSERT INTO recipe (name, ingredients) VALUES('broccoli stew', 'broccoli peppers cheese tomatoes');
             INSERT INTO recipe (name, ingredients) VALUES('pumpkin stew', 'pumpkin onions garlic celery');
             INSERT INTO recipe (name, ingredients) VALUES('broccoli pie', 'broccoli cheese onions flour');
             INSERT INTO recipe (name, ingredients) VALUES('pumpkin pie', 'pumpkin sugar flour butter');
             """)
         for row in con.execute("SELECT rowid, name, ingredients FROM recipe WHERE name MATCH 'pie'"):
             print(row)

         con.close()

   load_extension(path, /)

      从指定路径 *path* 的共享库中加载一个 SQLite 扩展。请您在调用该方
      法前，确保您已经使用 "enable_load_extension()" 方法启用了拓展的
      加载。

      引发一个 审计事件 "sqlite3.load_extension"，附带参数
      "connection", "path"。

      3.2 版新加入.

      3.10 版更變: 增加了 "sqlite3.load_extension" 审计事件。

   iterdump()

      返回一个 *iterator* 用来将数据库转储为 SQL 源代码。 在保存内存数
      据库以便将来恢复时很有用处。 类似于 **sqlite3** shell 中的
      ".dump" 命令。

      範例：

         # Convert file example.db to SQL dump file dump.sql
         con = sqlite3.connect('example.db')
         with open('dump.sql', 'w') as f:
             for line in con.iterdump():
                 f.write('%s\n' % line)
         con.close()

   backup(target, *, pages=- 1, progress=None, name='main', sleep=0.250)

      创建 SQLite 数据库的备份。

      即使数据库是通过其他客户端访问或通过同一连接并发访问也是有效的。

      參數:
         * **target** (*Connection*) -- 用于保存备份的数据库连接。

         * **pages** (*int*) -- 每次要拷贝的页数。 如果小于等于 "0"，
           则一次性拷贝整个数据库。 默认为 "-1"。

         * **progress** (*callback* | None) -- 如果将它设置为一个可调
           用的回调函数 (callable) ，那么它会在每次备份迭代 (backup
           iteration) 时被调用，并且带有以下三个整数参数：最近一次迭代
           的的状态（形式参数 *status*），需要复制的剩余页数（形式参数
           *remaining*）以及总页数（形式参数 *total*）。默认值为
           "None"。

         * **name** (*str*) -- 要备份的数据库名称。 可能为代表主数据库
           的 ""main"" (默认值)，代表临时数据库的 ""temp""，或者使用
           "ATTACH DATABASE" SQL 语句所附加的自定义数据库名称。

         * **sleep** (*float*) -- 连续尝试备份剩余页所要间隔的休眠秒数
           。

      示例 1，将现有数据库拷贝至另一个数据库:

         def progress(status, remaining, total):
             print(f'Copied {total-remaining} of {total} pages...')

         src = sqlite3.connect('example.db')
         dst = sqlite3.connect('backup.db')
         with dst:
             src.backup(dst, pages=1, progress=progress)
         dst.close()
         src.close()

      示例 2，将现有数据库拷贝至一个临时副本:

         src = sqlite3.connect('example.db')
         dst = sqlite3.connect(':memory:')
         src.backup(dst)

      3.7 版新加入.

   in_transaction

      这个只读属性对应于低层级的 SQLite autocommit mode。

      如果一个事务处于活动状态（有未提交的更改）则为 "True"，否则为
      "False"。

      3.2 版新加入.

   isolation_level

      该属性控制由 "sqlite3" 模块执行的 事务处理 。如果将该属性设置为
      "None" ，那么事务将永远不会被隐式地打开。如果将它设置为
      ""DEFERRED"" 、 ""IMMEDIATE"" 、 ""EXCLUSIVE"" 中的任意一个，那
      么 事务管理 (transaction management) 将会隐式地根据其对应的
      SQLite transaction behaviour 执行。

      如果未被 "connect()" 的 *isolation_level* 形参覆盖，则默认为
      """"，这是 ""DEFERRED"" 的一个别名。

   row_factory

      针对从该连接创建的 "Cursor" 对象的初始 "row_factory"。 为该属性
      赋值不会影响属于该连接的现有游标的 "row_factory"，只影响新的游标
      。 默认为 "None"，表示将每一行作为 "tuple" 返回。

      详情参见 如何创建并使用行工厂对象。

   text_factory

      一个可调用对象 (callable) ，它接受一个 "bytes" 作为形式参数并且
      返回该参数的文本表示。该调用对象将为数据类型为 "TEXT" 的 SQLite
      值调用。默认情况下，该属性将被设置为 "str" ，这意味着它总是返回
      一个字符串。如果您想返回 *bytes* ，请将*text_factory*设置为
      `bytes`。

      範例：

         con = sqlite3.connect(":memory:")
         cur = con.cursor()

         AUSTRIA = "Österreich"

         # by default, rows are returned as str
         cur.execute("SELECT ?", (AUSTRIA,))
         row = cur.fetchone()
         assert row[0] == AUSTRIA

         # but we can make sqlite3 always return bytestrings ...
         con.text_factory = bytes
         cur.execute("SELECT ?", (AUSTRIA,))
         row = cur.fetchone()
         assert type(row[0]) is bytes
         # the bytestrings will be encoded in UTF-8, unless you stored garbage in the
         # database ...
         assert row[0] == AUSTRIA.encode("utf-8")

         # we can also implement a custom text_factory ...
         # here we implement one that appends "foo" to all strings
         con.text_factory = lambda x: x.decode("utf-8") + "foo"
         cur.execute("SELECT ?", ("bar",))
         row = cur.fetchone()
         assert row[0] == "barfoo"

         con.close()

   total_changes

      返回自打开数据库连接以来已修改、插入或删除的数据库行的总数。


游标对象
--------

   一个代表被用于执行 SQL 语句，并管理获取操作的上下文的 database
   cursor 的 "Cursor" 对象。 游标对象是使用 "Connection.cursor()"，或
   是通过使用任何 连接快捷方法 来创建的。

   Cursor 对象属于 *迭代器*，这意味着如果你通过 "execute()" 来执行
   "SELECT" 查询，你可以简单地迭代游标来获取结果行:

      for row in cur.execute("SELECT t FROM data"):
          print(row)

class sqlite3.Cursor

   "Cursor" 游标实例具有以下属性和方法。

   execute(sql, parameters=(), /)

      执行一条 SQL 语句，可以选择使用 占位符 来绑定 Python 值。

      參數:
         * **sql** (*str*) -- 一条 SQL 语句。

         * **parameters** ("dict" | *sequence*) -- 要绑定到 *sql* 中占
           位符的 Python 值。 如果使用命名占位符则会使用 "dict"。 如果
           使用非命名占位符则会使用 *sequence*。 参见 如何在 SQL 查询
           中使用占位符来绑定值。

      丟出:
         **Warning** -- 如果 *sql* 包含多条 SQL 语句。

      如果属性 "isolation_level" 的值不是 "None"，并且*sql* 是一个
      "INSERT"、"UPDATE"、 "DELETE"、 或 "REPLACE" 语句，并且现在没有
      打开的事务 (transaction) ，那么在执行 *sql* 语句前将会隐式打开一
      个事务。

      使用 "executescript()" 来执行多条 SQL 语句。statements.

   executemany(sql, parameters, /)

      对于在 *parameters* 中的每一项，重复执行已经 参数化 了的 SQL 语
      句 *sql*。

      使用与 "execute()" 相同的隐式事务处理。

      參數:
         * **sql** (*str*) -- 一条 SQL DML (Data Manipulation
           Language) 语句。

         * **parameters** (*iterable*) -- 一个用来绑定到 *sql* 中的占
           位符的形参的 *iterable*。 参见 如何在 SQL 查询中使用占位符
           来绑定值。

      丟出:
         * **ProgrammingError** -- 如果 *sql* 不是一条 DML 语句。

         * **Warning** -- 如果 *sql* 包含多条 SQL 语句。

      範例：

         rows = [
             ("row1",),
             ("row2",),
         ]
         # cur is an sqlite3.Cursor object
         cur.executemany("INSERT INTO data VALUES(?)", rows)

   executescript(sql_script, /)

      执行形式参数 *sql_script* 中的 SQL 语句。如果在执行时仍有一个未
      决事务 (pending transaction) ，那么首先会隐式地执行一个 "COMMIT"
      语句。请注意，除此之外，它不会执行任何隐式的事务控制；因此，任何
      关于事务控制的内容都应添加到 *sql_script* 中。

      *sql_script* 必须为 "字符串"。

      範例：

         # cur is an sqlite3.Cursor object
         cur.executescript("""
             BEGIN;
             CREATE TABLE person(firstname, lastname, age);
             CREATE TABLE book(title, author, published);
             CREATE TABLE publisher(name, address);
             COMMIT;
         """)

   fetchone()

      如果 "row_factory" 为 "None"，则将下一行查询结果集作为 "tuple"
      返回。 否则，将其传给指定的行工厂函数并返回函数结果。 如果没有更
      多可用数据则返回 "None"。

   fetchmany(size=cursor.arraysize)

      将下一个多行查询结果集作为 "list" 返回。 如果没有更多可用行时则
      返回一个空列表。

      每次调用要获取的行数是由 *size* 形参指定的。 如果未指定 *size*，
      则由 "arraysize" 确定要获取的行数。 如果可用的行少于 *size*，则
      返回可用的行数。

      请注意 *size* 形参会涉及到性能方面的考虑。为了获得优化的性能，通
      常最好是使用 arraysize 属性。 如果使用 *size* 形参，则最好在从一
      个 "fetchmany()" 调用到下一个调用之间保持相同的值。

   fetchall()

      将全部（剩余的）查询结果行作为 "list" 返回。 如果没有可用的行则
      返回空列表。 请注意 "arraysize" 属性可能会影响此操作的性能。

   close()

      立即关闭 cursor（而不是在当 "__del__" 被调用的时候）。

      从这一时刻起该 cursor 将不再可用，如果再尝试用该 cursor 执行任何
      操作将引发 "ProgrammingError" 异常。

   setinputsizes(sizes, /)

      DB-API 要求的方法。 在 "sqlite3" 不做任何事情。

   setoutputsize(size, column=None, /)

      DB-API 要求的方法。 在 "sqlite3" 不做任何事情。

   arraysize

      用于控制 "fetchmany()" 返回行数的可读取/写入属性。 该属性的默认
      值为 1，表示每次调用将获取单独一行。

   connection

      提供属于该游标的 SQLite "Connection" 的只读属性。 通过调用
      "con.cursor()" 创建的 "Cursor" 对象将具有一个指向 *con* 的
      "connection" 属性:

         >>> con = sqlite3.connect(":memory:")
         >>> cur = con.cursor()
         >>> cur.connection == con
         True

   description

      提供上一次查询的列名称的只读属性。 为了与 Python DB API 保持兼容
      ，它会为每个列返回一个 7 元组，每个元组的最后六个条目均为 "None"
      。

      对于没有任何匹配行的 "SELECT" 语句同样会设置该属性。

   lastrowid

      提供上一次插入的行的行 ID 的只读属性。 它只会在使用 "execute()"
      方法的 "INSERT" 或 "REPLACE" 语句成功后被更新。 对于其他语句，则
      在 "executemany()" 或 "executescript()"，或者如果插入失败，
      "lastrowid" 的值将保持不变。 "lastrowid" 的初始值为 "None"。

      備註:

        对 "WITHOUT ROWID" 表的插入不被记录。

      3.6 版更變: 新增 "REPLACE" 陳述式的支援。

   rowcount

      这是一个只读属性。对于语句 "INSERT"、"DELETE"、"REPLACE" ，它将
      提供这些语句所修改的行数；对于其他语句，包括 CTE (Common Table
      Expression) 查询，它的值将会是 "-1"。它的值只会在执行方法
      "execute()" 与方法 "executemany()" 时发生更新。

   row_factory

      控制从该 "Cursor" 获取的行的表示形式。 如为 "None"，一行将表示为
      一个 "tuple"。可设置形式包括 "sqlite3.Row"；或者接受两个参数的
      *callable*，一个 "Cursor" 对象和由行内所有值组成的 "tuple"，以及
      返回代表一个 SQLite 行的自定义对象。

      默认为当 "Cursor" 被创建时设置的 "Connection.row_factory"。 对该
      属性赋值不会影响父连接的 "Connection.row_factory"。

      详情参见 如何创建并使用行工厂对象。


Row 对象
--------

class sqlite3.Row

   一个被用作 "Connection" 对象的高度优化的 "row_factory" 的 "Row" 实
   例。 它支持迭代、相等性检测、"len()" 以及基于列名称的 *mapping* 访
   问和数字序列。

   两个 "Row" 对象如果具有相同的列名称和值则比较结果相等。

   详情参见 如何创建并使用行工厂对象。

   keys()

      在一次查询之后，立即将由列名称组成的 "list" 作为 "字符串" 返回，
      它是 "Cursor.description" 中每个元组的第一个成员。

   3.5 版更變: 添加了对切片操作的支持。


PrepareProtocol 对象
--------------------

class sqlite3.PrepareProtocol

   PrepareProtocol 类型的唯一目的是作为 **PEP 246** 风格的适配协议让对
   象能够 将自身适配 为 原生 SQLite 类型。


例外
----

异常层次是由 DB-API 2.0 (**PEP 249**) 定义的。

exception sqlite3.Warning

   当 SQL 查询不是一个 "字符串" 或多个语句被传递给了方法 "execute()"
   或方法 "executemany()" 时由模块 "sqlite3" 引发的异常。"Warning" 是
   "Exception" 的子类。

exception sqlite3.Error

   本模块中其他异常的基类。使用它来捕捉所有的错误，只需一条 "except"
   语句。 "Error" 是 "Exception" 的子类。

exception sqlite3.InterfaceError

   当跨越回滚 (rollback) 获取数据或模块 "sqlite3" 无法绑定参数时引发的
   异常。"InterfaceError" 是 "Error" 的子类。

exception sqlite3.DatabaseError

   对与数据库有关的错误引发的异常。它作为几种数据库错误的基础异常。它
   只通过专门的子类隐式引发。 "DatabaseError" 是 "Error" 的一个子类。

exception sqlite3.DataError

   由于处理的数据有问题而产生的异常，比如数字值超出范围，字符串太长。
   "DataError" 是 "DatabaseError" 的子类。

exception sqlite3.OperationalError

   与数据库操作有关的错误而引发的异常，不一定在程序员的控制之下。例如
   ，数据库路径没有找到，或者一个事务无法被处理。 "OperationalError"
   是 "DatabaseError" 的子类。

exception sqlite3.IntegrityError

   当数据库的关系一致性受到影响时引发的异常。 例如外键检查失败等。 它
   是 "DatabaseError" 的子类。

exception sqlite3.InternalError

   当 SQLite 遇到一个内部错误时引发的异常。如果它被引发，可能表明运行
   中的 SQLite 库有问题。  "InternalError" 是 "DatabaseError" 的子类。

exception sqlite3.ProgrammingError

   由 "sqlite3" API 编程错误引发的异常。例如，您尝试对一个已经关闭的
   "Connection" 对象进行操作，或试图通过方法 "executemany()" 执行非DML
   语句  (non-DML statements) ，这些行为都会引发该异常。
   "ProgrammingError" 是 "DatabaseError" 的子类。

exception sqlite3.NotSupportedError

   在下层的 SQLite 库不支持某个方法或数据库 API 的情况下引发的异常。
   例如，在 "create_function()" 中把 *deterministic* 设为 "True"，而下
   层的 SQLite 库不支持确定性函数的时候。 "NotSupportedError" 是
   "DatabaseError" 的一个子类。


SQLite 与 Python 类型
---------------------

SQLite 原生支持如下的类型： "NULL"，"INTEGER"，"REAL"，"TEXT"，"BLOB"
。

因此可以将以下Python类型发送到SQLite而不会出现任何问题：

+---------------------------------+---------------+
| Python 类型                     | SQLite 类型   |
|=================================|===============|
| "None"                          | "NULL"        |
+---------------------------------+---------------+
| "int"                           | "INTEGER"     |
+---------------------------------+---------------+
| "float"                         | "REAL"        |
+---------------------------------+---------------+
| "str"                           | "TEXT"        |
+---------------------------------+---------------+
| "bytes"                         | "BLOB"        |
+---------------------------------+---------------+

这是SQLite类型默认转换为Python类型的方式：

+---------------+------------------------------------------------+
| SQLite 类型   | Python 类型                                    |
|===============|================================================|
| "NULL"        | "None"                                         |
+---------------+------------------------------------------------+
| "INTEGER"     | "int"                                          |
+---------------+------------------------------------------------+
| "REAL"        | "float"                                        |
+---------------+------------------------------------------------+
| "TEXT"        | 取决于 "text_factory" , 默认为 "str"           |
+---------------+------------------------------------------------+
| "BLOB"        | "bytes"                                        |
+---------------+------------------------------------------------+

"sqlite3" 模块的类型系统可通过两种方式来扩展：你可以通过 对象适配器 将
额外的 Python 类型保存在 SQLite 数据库中，你也可以让 "sqlite3" 模块通
过 转换器 将 SQLite 类型转换为不同的 Python 类型。types via.


默认适配器和转换器
------------------

对于 datetime 模块中的 date 和 datetime 类型已提供了默认的适配器。 它
们将会以 ISO 日期/ISO 时间戳的形式发给 SQLite。

默认转换器使用的注册名称是针对 "datetime.date" 的 "date" 和针对
"datetime.datetime" 的 "timestamp"。

通过这种方式，你可以在大多数情况下使用 Python 的 date/timestamp 对象而
无须任何额外处理。 适配器的格式还与实验性的 SQLite date/time 函数兼容
。

下面的示例演示了这一点。

   import sqlite3
   import datetime

   con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
   cur = con.cursor()
   cur.execute("create table test(d date, ts timestamp)")

   today = datetime.date.today()
   now = datetime.datetime.now()

   cur.execute("insert into test(d, ts) values (?, ?)", (today, now))
   cur.execute("select d, ts from test")
   row = cur.fetchone()
   print(today, "=>", row[0], type(row[0]))
   print(now, "=>", row[1], type(row[1]))

   cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"')
   row = cur.fetchone()
   print("current_date", row[0], type(row[0]))
   print("current_timestamp", row[1], type(row[1]))

   con.close()

如果存储在 SQLite 中的时间戳的小数位多于 6 个数字，则时间戳转换器会将
该值截断至微秒精度。

備註:

  默认的 "时间戳" 转换器忽略了数据库中的 UTC 偏移，总是返回一个原生的
  "datetime.datetime" 对象。要在时间戳中保留 UTC 偏移，可以不使用转换
  器，或者用 "register_converter()" 注册一个偏移感知的转换器。


常用方案指引
============


如何在 SQL 查询中使用占位符来绑定值
-----------------------------------

SQL 操作通常会需要使用来自 Python 变量的值。 不过，请谨慎使用 Python
的字符串操作来拼装查询，因为这样易受 SQL injection attacks。 例如，攻
击者可以简单地添加结束单引号并注入 "OR TRUE" 来选择所有的行:

   >>> # Never do this -- insecure!
   >>> symbol = input()
   ' OR TRUE; --
   >>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol
   >>> print(sql)
   SELECT * FROM stocks WHERE symbol = '' OR TRUE; --'
   >>> cur.execute(sql)

请改用 DB-API 的形参替换。 要将变量插入到查询字符串中，可在字符串中使
用占位符，并通过将实际值作为游标的 "execute()" 方法的第二个参数以由多
个值组成的 "tuple" 形式提供给查询来替换它们。

一条SQL语句可能使用这两种占位符中的一种：? 标记（或称问号标记风格
qmark style）或具名占位符（或称具名风格 named style）。对于问号标记风
格，*parameters* 必须是一个长度与 ? 标记 的数量匹配的序列 (*sequence*)
，否则将会抛出 "ProgrammingError" 错误。 对于具名风格，*parameters* 必
须是一个 "dict" 或是其子类的实例，同时该实例必须包括所有具名占位符所对
应的键。 其中，该实例中不为具名占位符所对应的键将会被忽略。这里是上述
两种风格的示例：

   con = sqlite3.connect(":memory:")
   cur = con.execute("CREATE TABLE lang(name, first_appeared)")

   # This is the named style used with executemany():
   data = (
       {"name": "C", "year": 1972},
       {"name": "Fortran", "year": 1957},
       {"name": "Python", "year": 1991},
       {"name": "Go", "year": 2009},
   )
   cur.executemany("INSERT INTO lang VALUES(:name, :year)", data)

   # This is the qmark style used in a SELECT query:
   params = (1972,)
   cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
   print(cur.fetchall())

備註:

  **PEP 249** 数字占位符已经 *不再* 被支持。 如果使用，它们将被解读为
  命名占位符。


如何将自定义 Python 类型适配到 SQLite 值
----------------------------------------

SQLite 仅支持一个原生数据类型的有限集。 要在 SQLite 数据库中存储自定义
Python 类型，请将它们 *适配* 到 SQLite 原生可识别的 Python 类型 之一。

有两种方式可将 Python 对象适配到 SQLite 类型：让你的对象自行适配，或是
使用 *适配器可调用对象*。 后者将优先于前者发挥作用。 对于导出自定义类
型的库，启用该类型的自行适配可能更为合理。 而作为一名应用程序开发者，
通过注册自定义适配器函数进行直接控制可能更为合理。


如何编写可适配对象
~~~~~~~~~~~~~~~~~~

假设我们有一个代表笛卡尔坐标系中的坐标值对 "Point"，"x" 和 "y" 的类，
该坐标值在数据库中将存储为一个文本字符串。 这可以通过添加一个返回已适
配值的 "__conform__(self, protocol)" 方法来实现。 传给 *protocol* 的对
象将为 "PrepareProtocol" 类型。

   class Point:
       def __init__(self, x, y):
           self.x, self.y = x, y

       def __conform__(self, protocol):
           if protocol is sqlite3.PrepareProtocol:
               return f"{self.x};{self.y}"

   con = sqlite3.connect(":memory:")
   cur = con.cursor()

   cur.execute("SELECT ?", (Point(4.0, -3.2),))
   print(cur.fetchone()[0])


如何注册适配器可调用对象
~~~~~~~~~~~~~~~~~~~~~~~~

另一种可能的方式是创建一个将 Python 对象转换为 SQLite 兼容类型的函数。
随后可使用 "register_adapter()" 来注册该函数。

   class Point:
       def __init__(self, x, y):
           self.x, self.y = x, y

   def adapt_point(point):
       return f"{point.x};{point.y}"

   sqlite3.register_adapter(Point, adapt_point)

   con = sqlite3.connect(":memory:")
   cur = con.cursor()

   cur.execute("SELECT ?", (Point(1.0, 2.5),))
   print(cur.fetchone()[0])


如何将 SQLite 值转换为自定义 Python 类型
----------------------------------------

编写适配器使你可以将 *from* 自定义 Python 类型转换为 *to* SQLite 值。
为了能将 *from* SQLite 值转换为 *to* 自定义 Python 类型，我们可使用
*converters*。

让我们回到 "Point" 类。 我们以以分号分隔的字符串形式在 SQLite 中存储了
x 和 y 坐标值。

首先，我们将定义一个转换器函数，它接受这样的字符串作为形参并根据该参数
构造一个 "Point" 对象。

備註:

  转换器函数 **总是** 接受传入一个 "bytes" 对象，无论下层的 SQLite 数
  据类型是什么。

   def convert_point(s):
       x, y = map(float, s.split(b";"))
       return Point(x, y)

我们现在需要告诉 "sqlite3" 何时应当转换一个给定的 SQLite 值。 这是在连
接到一个数据库时完成的，使用 "connect()" 的 *detect_types* 形参。 有三
个选项:

* 隐式: 将 *detect_types* 设为 "PARSE_DECLTYPES"

* 显式: 将 *detect_types* 设为 "PARSE_COLNAMES"

* 同时: 将 *detect_types* 设为 "sqlite3.PARSE_DECLTYPES |
  sqlite3.PARSE_COLNAMES"。 列名的优先级高于声明的类型。

下面的示例演示了隐式和显式的方法:

   class Point:
       def __init__(self, x, y):
           self.x, self.y = x, y

       def __repr__(self):
           return f"Point({self.x}, {self.y})"

   def adapt_point(point):
       return f"{point.x};{point.y}"

   def convert_point(s):
       x, y = list(map(float, s.split(b";")))
       return Point(x, y)

   # Register the adapter and converter
   sqlite3.register_adapter(Point, adapt_point)
   sqlite3.register_converter("point", convert_point)

   # 1) Parse using declared types
   p = Point(4.0, -3.2)
   con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
   cur = con.execute("CREATE TABLE test(p point)")

   cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
   cur.execute("SELECT p FROM test")
   print("with declared types:", cur.fetchone()[0])
   cur.close()
   con.close()

   # 2) Parse using column names
   con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
   cur = con.execute("CREATE TABLE test(p)")

   cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
   cur.execute('SELECT p AS "p [point]" FROM test')
   print("with column names:", cur.fetchone()[0])


适配器和转换器范例程序
----------------------

本小节显示了通用适配器和转换器的范例程序。

   import datetime
   import sqlite3

   def adapt_date_iso(val):
       """Adapt datetime.date to ISO 8601 date."""
       return val.isoformat()

   def adapt_datetime_iso(val):
       """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
       return val.isoformat()

   def adapt_datetime_epoch(val):
       """Adapt datetime.datetime to Unix timestamp."""
       return int(val.timestamp())

   sqlite3.register_adapter(datetime.date, adapt_date_iso)
   sqlite3.register_adapter(datetime.datetime, adapt_datetime_iso)
   sqlite3.register_adapter(datetime.datetime, adapt_datetime_epoch)

   def convert_date(val):
       """Convert ISO 8601 date to datetime.date object."""
       return datetime.date.fromisoformat(val.decode())

   def convert_datetime(val):
       """Convert ISO 8601 datetime to datetime.datetime object."""
       return datetime.datetime.fromisoformat(val.decode())

   def convert_timestamp(val):
       """Convert Unix epoch timestamp to datetime.datetime object."""
       return datetime.datetime.fromtimestamp(int(val))

   sqlite3.register_converter("date", convert_date)
   sqlite3.register_converter("datetime", convert_datetime)
   sqlite3.register_converter("timestamp", convert_timestamp)


如何使用连接快捷方法
--------------------

通过使用 "Connection" 类的 "execute()", "executemany()" 与
"executescript()" 方法，您可以简化您的代码，因为无需再显式创建 （通常
是多余的） "Cursor" 对象。此时 "Cursor" 对象会被隐式创建并且由这些快捷
方法返回。这样一来，您仅需在 "Connection" 对象上调用一次方法就可以执行
"SELECT" 语句，并对其进行迭代。

   # Create and fill the table.
   con = sqlite3.connect(":memory:")
   con.execute("CREATE TABLE lang(name, first_appeared)")
   data = [
       ("C++", 1985),
       ("Objective-C", 1984),
   ]
   con.executemany("INSERT INTO lang(name, first_appeared) VALUES(?, ?)", data)

   # Print the table contents
   for row in con.execute("SELECT name, first_appeared FROM lang"):
       print(row)

   print("I just deleted", con.execute("DELETE FROM lang").rowcount, "rows")

   # close() is not a shortcut method and it's not called automatically;
   # the connection object should be closed manually
   con.close()


如何使用连接上下文管理器
------------------------

一个 "Connection" 对象可以像一个上下文管理器 (context manager) 那般被
使用，在这种情况下当离开上下文管理器的主体时，将会自动提交或回滚打开的
事务。如果 "with" 语句的主体在没有异常的情况下完成，那么事务便会被提交
；如果提交失败，或者 "with" 语句的主体引发了一个未被捕获异常，那么事务
将会回滚。

如果在离开 "with" 语句的主体时没有打开的事务，那么上下文管理器是无用的
。

備註:

  此上下文管理器不会隐式地开启新事务也不会关闭连接。

   con = sqlite3.connect(":memory:")
   con.execute("CREATE TABLE lang(id INTEGER PRIMARY KEY, name VARCHAR UNIQUE)")

   # Successful, con.commit() is called automatically afterwards
   with con:
       con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))

   # con.rollback() is called after the with block finishes with an exception,
   # the exception is still raised and must be caught
   try:
       with con:
           con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))
   except sqlite3.IntegrityError:
       print("couldn't add Python twice")

   # Connection object used as context manager only commits or rollbacks transactions,
   # so the connection object should be closed manually
   con.close()


如何使用 SQLite URI
-------------------

一些有用的 URI 技巧包括:

* 以只读模式打开一个数据库:

   >>> con = sqlite3.connect("file:tutorial.db?mode=ro", uri=True)
   >>> con.execute("CREATE TABLE readonly(data)")
   Traceback (most recent call last):
   OperationalError: attempt to write a readonly database

* 如果一个数据库尚不存在则不会隐式地新建数据库；如果无法新建数据库则将
  引发 "OperationalError":

   >>> con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
   Traceback (most recent call last):
   OperationalError: unable to open database file

* 创建一个名为 shared 的内存数据库:

   db = "file:mem1?mode=memory&cache=shared"
   con1 = sqlite3.connect(db, uri=True)
   con2 = sqlite3.connect(db, uri=True)
   with con1:
       con1.execute("CREATE TABLE shared(data)")
       con1.execute("INSERT INTO shared VALUES(28)")
   res = con2.execute("SELECT data FROM shared")
   assert res.fetchone() == (28,)

关于此特性的更多信息，包括可用的形参列表，可以在 SQLite URI
documentation 中找到。


如何创建并使用行工厂对象
------------------------

在默认情况下，"sqlite3" 会以 "tuple" 来表示每一行。 如果 "tuple" 不适
合你的需求，你可以使用 "sqlite3.Row" 类或自定义的 "row_factory"。

虽然 "row_factory" 同时作为 "Cursor" 和 "Connection" 的属性存在，但推
荐设置 "Connection.row_factory"，这样在该连接上创建的所有游标都将使用
同一个行工厂对象。

"Row" 提供了针对列的序列方式和大小写不敏感的名称方式访问，具有优于
"tuple" 的最小化内存开销和性能影响。 要使用 "Row" 作为行工厂对象，请将
其赋值给 "row_factory" 属性:

   >>> con = sqlite3.connect(":memory:")
   >>> con.row_factory = sqlite3.Row

现在查询将返回 "Row" 对象:

   >>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius")
   >>> row = res.fetchone()
   >>> row.keys()
   ['name', 'radius']
   >>> row[0]         # Access by index.
   'Earth'
   >>> row["name"]    # Access by name.
   'Earth'
   >>> row["RADIUS"]  # Column names are case-insensitive.
   6378

你可以创建自定义 "row_factory" 用来返回 "dict" 形式的行，将列名映射到
相应的值。

   def dict_factory(cursor, row):
       fields = [column[0] for column in cursor.description]
       return {key: value for key, value in zip(fields, row)}

使用它，现在查询将返回 "dict" 而不是 "tuple":

   >>> con = sqlite3.connect(":memory:")
   >>> con.row_factory = dict_factory
   >>> for row in con.execute("SELECT 1 AS a, 2 AS b"):
   ...     print(row)
   {'a': 1, 'b': 2}

以下行工厂函数将返回一个 *named tuple*:

   from collections import namedtuple

   def namedtuple_factory(cursor, row):
       fields = [column[0] for column in cursor.description]
       cls = namedtuple("Row", fields)
       return cls._make(row)

"namedtuple_factory()" 可以像下面这样使用:

   >>> con = sqlite3.connect(":memory:")
   >>> con.row_factory = namedtuple_factory
   >>> cur = con.execute("SELECT 1 AS a, 2 AS b")
   >>> row = cur.fetchone()
   >>> row
   Row(a=1, b=2)
   >>> row[0]  # Indexed access.
   1
   >>> row.b   # Attribute access.
   2

经过一些调整，上面的范例程序可以被适配为使用 "dataclass"，或任何其他自
定义类，而不是 "namedtuple"。


解釋
====


事务控制
--------

"sqlite3" 模块并不遵守 **PEP 249** 所推荐的事务控制规范。

如果连接的属性 "isolation_level" 不为 "None"，新的事务会在 "execute()"
和 "executemany()" 执行 "INSERT", "UPDATE", "DELETE" 或 "REPLACE" 语句
之前隐式地开启；对于其他语句，则不会执行隐式的事务处理。 可分别使用
"commit()" 和 "rollback()" 方法提交和回滚未应用的事务。 你可以通过
"isolation_level" 属性来选择下层的 SQLite transaction behaviour — 也就
是说，"sqlite3" 是否要隐式地执行以及执行何种类型的 "BEGIN" 语句

如果 "isolation_level" 被设为 "None"，则完全不会隐式地开启任何事务。
这将使下层 SQLite 库处于 自动提交模式，但也允许用户使用显式 SQL 语句执
行他们自己的事务处理。 下层 SQLite 库的自动提交模式可使用
"in_transaction" 属性来查询。

"executescript()" 方法会在执行给定的 SQL 脚本之前隐式地提交任何挂起的
事务，无论 "isolation_level" 的值是什么。

3.6 版更變: 在以前 "sqlite3" 会在 DDL 语句之前隐式地提交已开启的事务。
现存则不会再这样做。
