尧图网页设计 
文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载本指南讲解如何为 Python 内置sqlite3模块注册自定义 adapter让datetime对象在写入 SQLite 时被自动序列化为带毫秒的 ISO-8601 UTC 字符串如2026-08-28T18:15:27.213Z省去在每处写操作中手工调用datetime.isoformat()的重复劳动。读完本文你将掌握sqlite3.register_adapter()的用法、时区感知校验的实现要点以及 adapter 与连接上下文管理器组合的完整实战模式。本文内容源自仓库中的 register-sqlite-adapter-to-serialize-datetimes.md 一文。背景SQLite 没有原生 datetime 类型SQLite 本身并不提供datetime或timestamp数据类型。日期时间信息只能以两种形态落到存储层以text形式存储为格式化的字符串如 ISO-8601以int形式存储为 Unix 时间戳epoch seconds。这意味着在使用 Python 的sqlite3模块执行写操作时必须明确告诉数据库“一个datetime对象应该以什么形状写入”。这一点在仓库的另一篇笔记 experiment-with-sqlite-queries-in-memory.md 中也有体现——建表时默认值直接使用 SQLite 的datetime(now)函数生成文本串说明该仓库的 SQLite 实践是以text形态存时间的。问题场景手工转换 datetime 的繁琐与不足最直接的方案是在每个涉及写操作的地方手工把datetime值转换为字符串。例如向sessions表插入一条新会话记录时# Prepare sessions insert payload session_data { active: 1 if active else 0, project_id: project_id, start_time: datetime.isoformat(session.start_time), end_time: None, } if session.end_time: session_data[end_time] datetime.isoformat(session.end_time) # Insert the new active session cursor self.conn.execute( insert into sessions (active, project_id, start_time, end_time) values (:active, :project_id, :start_time, :end_time) returning id; , session_data, )这里使用了datetime.isoformat()它把datetime对象格式化为类似下面的样子 datetime.now().isoformat() 2026-08-28T11:52:04.709907这种写法有两个明显的痛点也正是原文档想要改进的两点格式不合预期默认的isoformat()输出不带时区指示naive且微秒段是 6 位.709907。期望的存储格式是带毫秒和 UTC 标识的2026-08-28T18:15:27.213Z即 3 位毫秒 Z后缀。处处重复每次写操作都要记得手工调用datetime.isoformat()一旦遗漏sqlite3就会尝试用默认方式处理datetime对象行为不可控。核心方案注册 adapter 实现自动序列化Python 的sqlite3模块提供了适配器adapter机制通过sqlite3.register_adapter(type, callable)注册一个可调用对象之后凡是把该类型的 Python 对象作为参数传给 SQL 语句时都会被自动转换为可存储的值。官方文档中将其称为 register adapter callablessqlite3注册适配器可调用对象它是解决上述两个痛点的关键。第一步定义转换函数首先定义一个执行datetime→str转换的函数。原文档作者选择把它放在db.py中与其它数据库相关的函数放在一起from datetime import datetime, timezone def to_db(dt: datetime) - str: if dt.tzinfo is None or dt.utcoffset() is None: raise ValueError(fUnable to store naive datetime: {dt!r}) dt dt.astimezone(timezone.utc) return f{dt:%Y-%m-%dT%H:%M:%S}.{dt.microsecond // 1000:03d}Z这个函数做了三件事时区感知校验通过dt.tzinfo is None or dt.utcoffset() is None拒绝 naive无时区信息的datetime。因为最终要写入的是 UTC 时间naive 对象没有明确的时区语义直接转换会丢失信息甚至产生歧义因此抛出ValueError并带上对象本身的repr便于定位问题。统一换算到 UTCdt.astimezone(timezone.utc)把任意时区感知的datetime换算到 UTC。这一点与仓库中的另一篇笔记 parse-relative-time-to-datetime-object.md 的思路一致——该笔记同样强调“存储层统一用 UTC展示层再通过astimezone转回本地时区”保证存储一致性。按目标格式格式化用格式字符串%Y-%m-%dT%H:%M:%S输出日期与时分秒dt.microsecond // 1000把微秒6 位截断为毫秒3 位并用:03d保证不足 3 位时补零最后拼上Z表示 UTC。这样datetime.now()的 6 位微秒709907会变成213毫秒截断整体输出形如2026-08-28T18:15:27.213Z。第二步注册 adapter在创建用于数据库交互的连接之前先注册 adapter。注册后连接上执行的写操作就会自动走该转换逻辑import sqlite3 from datetime import datetime from pathlib import Path from sqlite3 import Connection def initialize_conn(db_file: Path) - Connection: # register adapters sqlite3.register_adapter(datetime, to_db) conn: Connection sqlite3.connect(db_file) conn.row_factory sqlite3.Row return conn几个值得注意的细节sqlite3.register_adapter是模块级的注册作用于该进程内之后创建的所有连接因此只需注册一次。这里把它放在initialize_conn函数里、sqlite3.connect之前执行保证每个连接都生效。conn.row_factory sqlite3.Row让查询结果可按列名访问。仓库中的 access-sqlite-result-values-by-name-with-row-factory.md 专门讲解过这一点默认结果是 tuple只能按位置取值开启 Row Factory 后既可按位置也可按名称取值可读性更好。这是写入方向Python → SQLite的适配。与之相对的读取方向SQLite → Python则是sqlite3.register_converter配合detect_types使用本文不展开。第三步放心使用原生 datetime 写操作注册之后写操作中可以直接传入datetime对象无需任何手工转换with self.conn: query update sessions set active :active, end_time :end_time where active 1; self.conn.execute( query, {active: 0, end_time: session.end_time}, )session.end_time是一个datetime对象如果会话已结束它会被自动以2026-08-28T18:15:27.213Z的形态写入end_time列None则照常写入NULL。代码里再也不会出现datetime.isoformat(session.end_time)这类散落各处的转换调用。这里还体现了仓库中另一篇笔记 commit-writes-from-executed-sqlite-statements.md 推荐的连接上下文管理器用法with self.conn:块内自动管理事务正常结束即commit中途抛异常则rollback省去了手工处理事务的样板代码。小结三步完成 datetime 的自动化序列化回顾整个方案只需三步定义to_db(dt: datetime) - str转换函数——负责校验时区、换算 UTC、格式化输出在连接初始化时调用sqlite3.register_adapter(datetime, to_db)完成注册之后所有写操作直接传datetime对象交给 adapter 自动序列化。这样既统一了存储格式YYYY-MM-DDTHH:MM:SS.mmmZ又消除了手工转换带来的重复与遗漏风险。需要调整存储格式例如改用 Unix 时间戳时只需修改to_db一处所有写入点同步生效——这就是 adapter 注册机制相对于逐处手工转换的核心价值。如需查阅本文涉及的相关笔记可继续阅读仓库中的 access-sqlite-result-values-by-name-with-row-factory.md、commit-writes-from-executed-sqlite-statements.md 以及 experiment-with-sqlite-queries-in-memory.md。赞分享文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载相关推荐JavaScript 中 ISO-8601 格式日期被当作 UTC 时间解析的陷阱与应对JavaScript 中 ISO 8601 格式日期被当作 UTC 时间解析的陷阱与应对 在 JavaScript 中使用 new Date 或 Date.p文档教程知识库Luxon 格式化实战指南ISO 8601、toLocaleString 与 toFormat 自定义 Token 全解Luxon 格式化实战指南ISO 8601、toLocaleString 与 toFormat 自定义 Token 全解 导读 Luxon 提供了三套相互补充开发工具探索未来时间格式ISO 8601 的魅力探索未来时间格式ISO 8601 的魅力 在数字化世界中数据的准确性和标准化至关重要。当我们谈论日期和时间时没有比遵循国际标准更关键的事情了。ISO 86开发工具上一篇终极指南如何快速免费将CAJ文件转换为可搜索的PDF文档下一篇Catch2 Event Listeners 深度指南在测试进程中注入自定义行为的完整实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Python sqlite3 适配器注册：让 datetime 自动以 ISO-8601 UTC 格式序列化
文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载本指南讲解如何为 Python 内置sqlite3模块注册自定义 adapter让datetime对象在写入 SQLite 时被自动序列化为带毫秒的 ISO-8601 UTC 字符串如2026-08-28T18:15:27.213Z省去在每处写操作中手工调用datetime.isoformat()的重复劳动。读完本文你将掌握sqlite3.register_adapter()的用法、时区感知校验的实现要点以及 adapter 与连接上下文管理器组合的完整实战模式。本文内容源自仓库中的 register-sqlite-adapter-to-serialize-datetimes.md 一文。背景SQLite 没有原生 datetime 类型SQLite 本身并不提供datetime或timestamp数据类型。日期时间信息只能以两种形态落到存储层以text形式存储为格式化的字符串如 ISO-8601以int形式存储为 Unix 时间戳epoch seconds。这意味着在使用 Python 的sqlite3模块执行写操作时必须明确告诉数据库“一个datetime对象应该以什么形状写入”。这一点在仓库的另一篇笔记 experiment-with-sqlite-queries-in-memory.md 中也有体现——建表时默认值直接使用 SQLite 的datetime(now)函数生成文本串说明该仓库的 SQLite 实践是以text形态存时间的。问题场景手工转换 datetime 的繁琐与不足最直接的方案是在每个涉及写操作的地方手工把datetime值转换为字符串。例如向sessions表插入一条新会话记录时# Prepare sessions insert payload session_data { active: 1 if active else 0, project_id: project_id, start_time: datetime.isoformat(session.start_time), end_time: None, } if session.end_time: session_data[end_time] datetime.isoformat(session.end_time) # Insert the new active session cursor self.conn.execute( insert into sessions (active, project_id, start_time, end_time) values (:active, :project_id, :start_time, :end_time) returning id; , session_data, )这里使用了datetime.isoformat()它把datetime对象格式化为类似下面的样子 datetime.now().isoformat() 2026-08-28T11:52:04.709907这种写法有两个明显的痛点也正是原文档想要改进的两点格式不合预期默认的isoformat()输出不带时区指示naive且微秒段是 6 位.709907。期望的存储格式是带毫秒和 UTC 标识的2026-08-28T18:15:27.213Z即 3 位毫秒 Z后缀。处处重复每次写操作都要记得手工调用datetime.isoformat()一旦遗漏sqlite3就会尝试用默认方式处理datetime对象行为不可控。核心方案注册 adapter 实现自动序列化Python 的sqlite3模块提供了适配器adapter机制通过sqlite3.register_adapter(type, callable)注册一个可调用对象之后凡是把该类型的 Python 对象作为参数传给 SQL 语句时都会被自动转换为可存储的值。官方文档中将其称为 register adapter callablessqlite3注册适配器可调用对象它是解决上述两个痛点的关键。第一步定义转换函数首先定义一个执行datetime→str转换的函数。原文档作者选择把它放在db.py中与其它数据库相关的函数放在一起from datetime import datetime, timezone def to_db(dt: datetime) - str: if dt.tzinfo is None or dt.utcoffset() is None: raise ValueError(fUnable to store naive datetime: {dt!r}) dt dt.astimezone(timezone.utc) return f{dt:%Y-%m-%dT%H:%M:%S}.{dt.microsecond // 1000:03d}Z这个函数做了三件事时区感知校验通过dt.tzinfo is None or dt.utcoffset() is None拒绝 naive无时区信息的datetime。因为最终要写入的是 UTC 时间naive 对象没有明确的时区语义直接转换会丢失信息甚至产生歧义因此抛出ValueError并带上对象本身的repr便于定位问题。统一换算到 UTCdt.astimezone(timezone.utc)把任意时区感知的datetime换算到 UTC。这一点与仓库中的另一篇笔记 parse-relative-time-to-datetime-object.md 的思路一致——该笔记同样强调“存储层统一用 UTC展示层再通过astimezone转回本地时区”保证存储一致性。按目标格式格式化用格式字符串%Y-%m-%dT%H:%M:%S输出日期与时分秒dt.microsecond // 1000把微秒6 位截断为毫秒3 位并用:03d保证不足 3 位时补零最后拼上Z表示 UTC。这样datetime.now()的 6 位微秒709907会变成213毫秒截断整体输出形如2026-08-28T18:15:27.213Z。第二步注册 adapter在创建用于数据库交互的连接之前先注册 adapter。注册后连接上执行的写操作就会自动走该转换逻辑import sqlite3 from datetime import datetime from pathlib import Path from sqlite3 import Connection def initialize_conn(db_file: Path) - Connection: # register adapters sqlite3.register_adapter(datetime, to_db) conn: Connection sqlite3.connect(db_file) conn.row_factory sqlite3.Row return conn几个值得注意的细节sqlite3.register_adapter是模块级的注册作用于该进程内之后创建的所有连接因此只需注册一次。这里把它放在initialize_conn函数里、sqlite3.connect之前执行保证每个连接都生效。conn.row_factory sqlite3.Row让查询结果可按列名访问。仓库中的 access-sqlite-result-values-by-name-with-row-factory.md 专门讲解过这一点默认结果是 tuple只能按位置取值开启 Row Factory 后既可按位置也可按名称取值可读性更好。这是写入方向Python → SQLite的适配。与之相对的读取方向SQLite → Python则是sqlite3.register_converter配合detect_types使用本文不展开。第三步放心使用原生 datetime 写操作注册之后写操作中可以直接传入datetime对象无需任何手工转换with self.conn: query update sessions set active :active, end_time :end_time where active 1; self.conn.execute( query, {active: 0, end_time: session.end_time}, )session.end_time是一个datetime对象如果会话已结束它会被自动以2026-08-28T18:15:27.213Z的形态写入end_time列None则照常写入NULL。代码里再也不会出现datetime.isoformat(session.end_time)这类散落各处的转换调用。这里还体现了仓库中另一篇笔记 commit-writes-from-executed-sqlite-statements.md 推荐的连接上下文管理器用法with self.conn:块内自动管理事务正常结束即commit中途抛异常则rollback省去了手工处理事务的样板代码。小结三步完成 datetime 的自动化序列化回顾整个方案只需三步定义to_db(dt: datetime) - str转换函数——负责校验时区、换算 UTC、格式化输出在连接初始化时调用sqlite3.register_adapter(datetime, to_db)完成注册之后所有写操作直接传datetime对象交给 adapter 自动序列化。这样既统一了存储格式YYYY-MM-DDTHH:MM:SS.mmmZ又消除了手工转换带来的重复与遗漏风险。需要调整存储格式例如改用 Unix 时间戳时只需修改to_db一处所有写入点同步生效——这就是 adapter 注册机制相对于逐处手工转换的核心价值。如需查阅本文涉及的相关笔记可继续阅读仓库中的 access-sqlite-result-values-by-name-with-row-factory.md、commit-writes-from-executed-sqlite-statements.md 以及 experiment-with-sqlite-queries-in-memory.md。赞分享文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载相关推荐JavaScript 中 ISO-8601 格式日期被当作 UTC 时间解析的陷阱与应对JavaScript 中 ISO 8601 格式日期被当作 UTC 时间解析的陷阱与应对 在 JavaScript 中使用 new Date 或 Date.p文档教程知识库Luxon 格式化实战指南ISO 8601、toLocaleString 与 toFormat 自定义 Token 全解Luxon 格式化实战指南ISO 8601、toLocaleString 与 toFormat 自定义 Token 全解 导读 Luxon 提供了三套相互补充开发工具探索未来时间格式ISO 8601 的魅力探索未来时间格式ISO 8601 的魅力 在数字化世界中数据的准确性和标准化至关重要。当我们谈论日期和时间时没有比遵循国际标准更关键的事情了。ISO 86开发工具上一篇终极指南如何快速免费将CAJ文件转换为可搜索的PDF文档下一篇Catch2 Event Listeners 深度指南在测试进程中注入自定义行为的完整实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考