NEP 4 解读NumPy datetime64 与 timedelta64 日期时间类型的设计提案与现代实现【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址: https://gitcode.com/gh_mirrors/nu/numpy导读NEP 4全称A (third) proposal for implementing some date/time types in NumPy是 2008 年由 Francesc Alted i Abad 与 Ivan Vilata i Balaguer 提交的第三版日期时间类型提案它为 NumPy 引入了如今广为人知的datetime64与timedelta64两大核心 dtype 的原始设计蓝图。本文以该提案文档为主体逐节还原其设计动机、类型语义、时间单位体系、算术运算与转换规则并结合当前仓库中的官方参考文档、C 源码与测试用例对照说明这套设计如何最终落地为 NumPy 1.7 起的原生日期时间功能。读完本文你将掌握datetime64/timedelta64的内部表示int64 时间单位元数据、NaT 哨兵值的语义、单位表与取值/设值方式以及绝对时间与相对时间之间的运算规则。背景为什么 NumPy 需要自己的日期时间类型提案在 Executive summary 中指出日期/时间标记是许多处理数据集场景中的常见需求然而在 2008 年时Python 虽有datetime标准库模块与第三方mx.DateTime等类型NumPy 本身却长期缺少原生的日期时间类型。NEP 4 提出的新类型需要满足两个核心要求运算速度快fast to operate with尽可能与 Python 内置datetime模块兼容as compatible as possible。正是这两条约束决定了后续所有设计决策——用整数计数时间、用时间单位作为元数据、用微秒作为与 Pythondatetime对接的基准精度。双类型设计datetime64 与 timedelta64提案开篇即承认几乎不可能用单一类型满足所有使用场景因此设计了两个互补类型名称在当时是暂定的如今已成为标准类型语义内部实现datetime64绝对时间absolute非相对int64以 POSIX epoch 为基准timedelta64相对时间relative即时间差int64关键设计原则提案中以 Important 标注时间单位被视作补充 dtype 的元数据metadata不改变底层类型本身——它描述的是存储数值的含义而非数值的结构。因此datetime64[us]与datetime64[ns]共享同一底层 int64 存储与同一套运算逻辑区别只在于单位元数据。datetime64绝对时间的表示datetime64表示绝对时间点内部用int64实现基准epoch为 POSIX epoch且与 POSIX 一致地不把闰秒计入日期表示。单位转换与时间表示不包括其他时间计算中值-2**63即0x8000000000000000int64 最小值被解释为无效或未知日期即NaTNot a Time。这一哨兵值设计在现代实现中得到保留见 ndarraytypes.h 中#define NPY_DATETIME_NAT NPY_MIN_INT64。timedelta64相对时间的表示timedelta64表示相对时间时间间隔同样用int64实现同样以-2**63作为 NaT 哨兵。与绝对时间不同它没有 epoch 概念值本身就是所选单位下的整数个数。时间单位体系提案为两种类型各列出了一张时间单位表。时间单位决定了可表示的取值范围——因为内部是 64 位整数单位越细可表示的时间跨度越窄这正是 官方参考文档 中time span概念的来源跨度长度 64 位整数范围 × 单位长度。datetime64支持的单位与绝对时间跨度代码含义时间跨度年Yyear[9.2e18 BC, 9.2e18 AD]Mmonth[7.6e17 BC, 7.6e17 AD]Wweek[1.7e17 BC, 1.7e17 AD]Bbusiness day[3.5e16 BC, 3.5e16 AD]Dday[2.5e16 BC, 2.5e16 AD]hhour[1.0e15 BC, 1.0e15 AD]mminute[1.7e13 BC, 1.7e13 AD]ssecond[ 2.9e9 BC, 2.9e9 AD]msmillisecond[ 2.9e6 BC, 2.9e6 AD]usmicrosecond[290301 BC, 294241 AD]c#ticks (100ns)[ 2757 BC, 31197 AD]nsnanosecond[ 1678 AD, 2262 AD]timedelta64支持的单位与相对时间跨度代码含义时间跨度Yyear- 9.2e18 yearsMmonth- 7.6e17 yearsWweek- 1.7e17 yearsBbusiness day- 3.5e16 yearsDday- 2.5e16 yearshhour- 1.0e15 yearsmminute- 1.7e13 yearsssecond- 2.9e12 yearsmsmillisecond- 2.9e9 yearsusmicrosecond- 2.9e6 yearsc#ticks (100ns)- 2.9e4 yearsnsnanosecond- 292 yearspspicosecond- 106 daysfsfemtosecond- 2.6 hoursasattosecond- 9.2 seconds两个细节值得注意工作日B计数跳过周末datetime64按工作日计数时周六、周日被直接忽略——第 3 个工作日不是 1970-01-03周六而是 1970-01-05周一。ps/fs/as 只出现在 timedelta64 单位表中绝对时间用亚纳秒单位没有实用意义但相对时间如高性能计时可以现代实现同样如此见 ndarraytypes.h 中NPY_DATETIMEUNIT枚举自NPY_FR_Y0一直到NPY_FR_as13的完整单位定义。现代实现还引入了提案未涉及的**通用单位generic unit**概念NPY_FR_GENERIC 14即NPY_DATETIME_DEFAULTUNIT不带单位的 dtype 可在创建时根据输入自动推断单位。这一特性在 NumPy 2.5 起已被弃用官方建议显式指定具体单位详见 迁移指南。构建 datetime64 / timedelta64 dtype提案规定了两种 dtype 构造写法这一 API 沿用至今datetime64np.dtype(datetime64[us]) # 长字符串写法 np.dtype(M8[us]) # 短字符串写法M8 datetime64不指定单位时默认为微秒因此M8等价于M8[us]。timedelta64np.dtype(timedelta64[us]) # 长字符串写法 np.dtype(m8[us]) # 短字符串写法m8 timedelta64同样m8默认等价于m8[us]。提案中的c#100ns ticks单位最终未进入现代实现当前实现的完整单位集Y/M/W/D/h/m/s/ms/us/ns/ps/fs/as在 官方文档单位表 中有与提案几乎一一对应的跨度数据例如微秒绝对跨度同为 [290301 BC, 294241 AD]。设置与获取值datetime64 的赋值与读取提案给出的设值示例datetime64[s]数组t numpy.ones(3, dtypeM8[s]) t[0] 1199164176 # 整数1970 起的秒数即 2008-07-30 17:31:00 t[1] datetime.datetime(2008, 7, 30, 17, 31, 1) # Python datetime 对象 t[2] 2008-07-30T17:31:02 # ISO 8601 字符串对应的读取形式str(t[0]) -- 2008-07-30T17:31:00 repr(t[1]) -- datetime64(1199164177, s) str(t[0].item()) -- 2008-07-30 17:31:00 # Python datetime 对象 repr(t[0].item()) -- datetime.datetime(2008, 7, 30, 17, 31) str(t) -- [2008-07-30T17:31:00 2008-07-30T17:31:01 2008-07-30T17:31:02] repr(t) -- array([1199164176, 1199164177, 1199164178], dtypedatetime64[s])可见标量的str()走 ISO 8601 字符串表示repr()展示内部 int64 计数值与单位.item()则转换回 Python 对象——这正是提案与 Pythondatetime兼容目标的直接体现。timedelta64 的赋值与读取t numpy.ones(3, dtypem8[ms]) t[0] 12 # 12 ms t[1] datetime.timedelta(0, 0, 13000) # 13 ms t[2] 0:00:00.014 # 14 ms字符串形式读取形式str(t[0]) -- 0:00:00.012 repr(t[1]) -- timedelta64(13, ms) str(t[0].item()) -- 0:00:00.012000 # Python timedelta repr(t[0].item()) -- datetime.timedelta(0, 0, 12000) str(t) -- [0:00:00.012 0:00:00.014 0:00:00.014] repr(t) -- array([12, 13, 14], dtypetimedelta64[ms])现代实现的扩展now / today / NaT现代 官方文档 在提案基础上丰富了字符串输入datetime64接受NAT任意大小写组合表示 Not A Timenow返回当前 UTC 时间默认秒精度可用单位参数截断today返回当前 UTC 日期天精度 np.datetime64(nat, D) np.datetime64(NaT, D) np.datetime64(now) # 结果取决于当前时间 np.datetime64(2025-08-05T02:22:14) np.datetime64(now, ms) np.datetime64(2025-08-05T02:22:14.000)比较运算提案明确了比较运算的三种形态数组对数组、标量广播、字符串广播。datetime64比较numpy.array([1980], M8[Y]) numpy.array([1979], M8[Y]) # -- [False] # 标量广播 numpy.array([1979, 1980], M8[Y]) numpy.datetime64(1980, Y) # -- [False, True] # 字符串广播右侧可广播为 2 元素的 M8[Y] 数组 numpy.array([1979, 1980], M8[Y]) 1980-01-01 # -- [False, True]timedelta64比较numpy.array([12, 13, 14], m8[ms]) numpy.array([12, 13, 13], m8[ms]) # -- [True, True, False] numpy.array([12, 13, 14], m8[ms]) numpy.timedelta64(13, ms) # -- [False, True, False] numpy.array([12, 13, 14], m8[ms]) 0:00:00.012 # -- [True, False, False]与 Python datetime 的兼容边界提案明确给出了兼容性承诺的边界datetime64仅在使用**微秒us**单位时与 Pythondatetime.datetime完全兼容其他单位在转换时会有精度损失或溢出。与datetime对象的双向转换不考虑闰秒。timedelta64同样仅在使用微秒单位时与 Pythontimedelta完全兼容。现代实现延续了这一约定并进一步形式化为 转换协议表datetime64在 μs/ms/s/m/h 单位下.item()返回datetime.datetimeD/W 单位返回datetime.datens/ps/fs/as 返回intNaT 返回Nonetimedelta64在 μs 及以上单位返回datetime.timedeltaY/M 单位返回int。另一个重要背景现代datetime64采用格里高利历无限前推proleptic Gregorian calendar并支持公元前日期按天文年编号公元前 2 年记为 -1公元前 1 年记为 0每天固定 86400 秒、无时区概念naive time——这些约定与 Pythondatetime、POSIX 时间一致也因此共享其已知局限例如无法解析正闰秒时刻2016-12-31 23:59:60.450 UTC详见官方文档的 shortcomings 一节。日期时间数组的运算规则datetime64 与 datetime64只允许相减绝对时间之间唯一允许的算术运算是减法结果得到timedelta64numpy.ones(3, M8[s]) - numpy.zeros(3, M8[s]) -- array([1, 1, 1], dtypetimedelta64[s])相加则报错TypeError: unsupported operand type(s) for 。比较运算是允许的。Casting 规则两个不同单位的绝对时间相减会直接抛异常提案设想为numpy.IncompatibleUnitError因为不同单位的时间跨度差异巨大难以替用户决定结果单位numpy.ones(3, dtypeM8[Y]) - numpy.zeros(3, dtypeM8[Y]) # -- array([1, 1, 1], dtypetimedelta64[Y]) # 允许 numpy.ones(3, dtypeM8[Y]) - numpy.zeros(3, dtypeM8[ns]) # -- raise IncompatibleUnitError # 不允许该选哪个单位datetime64 与 timedelta64绝对时间 ± 相对时间绝对时间可以加减相对时间numpy.zeros(5, M8[Y]) numpy.ones(5, m8[Y]) -- array([1971, 1971, 1971, 1971, 1971], dtypedatetime64[Y]) numpy.ones(5, M8[Y]) - 2 * numpy.ones(5, m8[Y]) -- array([1969, 1969, 1969, 1969, 1969], dtypedatetime64[Y])但相乘如M8[Y] * m8[Y]会报TypeError。Casting 规则此类运算中绝对时间拥有单位决定优先权——结果沿用 datetime 的单位这最符合用户直觉series numpy.array([1970-01-01, 1970-02-01, 1970-09-01], dtypedatetime64[D]) series2 series numpy.timedelta(1, Y) # 加 1 个相对年 # -- array([1972-01-01, 1972-02-01, 1972-09-01], dtypedatetime64[D]) # 结果保留 D 单位timedelta64 与 timedelta64如同 int64 一样运算相对时间之间可以像普通 int64 dtype 一样运算只要结果能转换回timedelta64numpy.ones(3, m8[M]) 2) ** 3 -- array([27, 27, 27], dtypetimedelta64[M])若结果无法转换如与复数运算则报错TypeError: the result cannot be converted into a timedelta64。Casting 规则两个不同单位的timedelta64运算结果取较短更精细的单位keep the precision 规则numpy.ones(3, m8[s]) numpy.ones(3, m8[m]) -- array([61, 61, 61], dtypetimedelta64[s])但相对年Y或相对月M无法与更细单位直接混合因为其确切时长不确定一年不等于固定天数numpy.ones(3, m8[Y]) numpy.ones(3, m8[D]) -- raise IncompatibleUnitError # 相对年如何换算成天现代实现对此的处理是Y/M 到 D 的转换只允许通过unsafe规则强制转换按 400 年闰年周期的平均值计算直接标量转换会报TypeError: Cannot cast ... according to the rule same_kind见官方文档示例。提案中的 change_timeunit 辅助函数为化解上述相对年/月无法换算的难题提案设想了一个新函数change_timeunit(time_object, new_unit, reference)time_object要改变单位的时间对象new_unit目标时间单位reference一个绝对日期datetime64标量作为不确定时长单位相对年/月换算的参照点。用法示例以2001-01-01为参照把 1 个相对年换算成 366 天t_years numpy.ones(3, m8[Y]) t_days numpy.change_timeunit(t_years, D, 2001-01-01) t_days numpy.ones(3, m8[D]) -- array([366, 366, 366], dtypetimedelta64[D])这一函数最终没有以同名 API 落地——现代 NumPy 中由.astype()配合 unsafe casting 承担了类似的单位转换职责但以参照日期换算相对年/月的思想在datetime_busdaycal.c等业务日实现中仍有体现业务日换算同样依赖具体日历参照。dtype 与时间单位转换astype提案主张用.astype()完成日期时间 dtype 转换主要用于改变时间单位# 绝对时间秒 → 天 t1 numpy.zeros(5, dtypedatetime64[s]) t1.astype(datetime64[D]) # -- array([1970-01-01, ...], dtypedatetime64[D]) # 相对时间秒 → 毫秒数值随之放大 t1 numpy.ones(5, dtypetimedelta64[s]) t1.astype(timedelta64[ms]) # -- [1000 1000 1000 1000 1000]两个重要限制绝对/相对之间不可直接互转numpy.zeros(5, dtypedatetime64[s]).astype(timedelta64)会报TypeError: data type cannot be converted to the desired type。这一约束在现代实现中依然成立——绝对时间与相对时间是语义不同的两个世界只能通过加减运算相互联系。工作日转换可能产生 NaT工作日不覆盖连续时间线周末有间隙从普通时间转换到工作日时落在周末的原始时刻无法表示结果即为 NaT而 NaT 反转换回普通天数时保持 NaT 不变所有单位转换中 NaT 均原样保留t1 numpy.arange(5, dtypedatetime64[D]) # -- [1970-01-01 1970-01-02 1970-01-03 1970-01-04 1970-01-05] t2 t1.astype(datetime64[B]) # 1970 年从周四开始 # -- [1970-01-01 1970-01-02 NaT NaT 1970-01-05]现代 NumPy 将工作日从一种 dtype 单位NPY_FR_B在 ndarraytypes.h 中已因 1.6 ABI 兼容留下空位演进为一整套独立的 busday 工具函数实现在 datetime_busday.c包括busday_offset按工作日偏移支持forward/backward滚动规则、is_busday、busday_count以及优化的busdaycalendar对象并支持自定义 weekmask7 个布尔标志与节假日列表详见 官方文档 business day 一节。提案中的设计取舍为什么去掉 origin 元数据提案早期讨论中曾设想为datetime64增加origin元数据来补充绝对时间的定义。作者最终认为绝对datetime64 相对timedelta64的组合已经能提供等价功能无需额外元数据因此从提案中移除。这一决定奠定了今天两种类型、一种 epoch1970-01-01T00:00 UTC的简洁模型。为什么没有 quarter 单位提案解释了三层理由quarter属于派生单位提案聚焦最常用单位集合quarter通常需要支持从任意月份起算而提案不引入origin元数据无法支撑该需求若加入quarter用户难免期待biweekly、semester、biyearly等更多派生单位对提案而言负担过重。混合单位的总体原则提案在Final considerations中总结同一 dtype、不同单位之间的运算应当被支持例如秒级与微秒级时间差相加并产生恰当的结果单位具体语义由各小节 Casting rules 定义。由于工作日的特殊性工作日与其他单位混算很可能不被允许。从提案到现实NEP 4 与当前实现的对照NEP 4 状态为Deferred搁置但它提出的核心 API 与语义几乎全部成为现实。当前仓库中可以找到的落地证据类型与 NaT 哨兵NPY_DATETIME_NAT NPY_MIN_INT64见 ndarraytypes.h单位枚举NPY_DATETIMEUNIT完整定义自NPY_FR_Y至NPY_FR_as及NPY_FR_GENERIC见 ndarraytypes.h核心实现日期时间核心逻辑在 numpy/_core/src/multiarray/ 下的datetime.c、字符串解析在datetime_strings.c、工作日功能在datetime_busday.c与datetime_busdaycal.c官方文档Datetimes and timedeltas 是面向用户的完整参考测试覆盖test_datetime.py 包含大量针对构造、转换、运算、工作日与 NaT 语义的测试用例。对照之下两者的主要差异集中在现代实现新增了now/today字符串、通用单位自动推断2.5 起弃用、亚纳秒单位ps/fs/as、完整的 busday 工具集并明确了 UTC/闰秒相关的局限性而提案中的c#ticks 单位与change_timeunit函数未直接落地。从源码结构看可以说 NEP 4 为 NumPy 日期时间功能提供了 90% 以上的设计骨架后续演进均是在这一骨架上补充工程细节。总结NEP 4 用int64 计数值 时间单位元数据的极简模型同时满足了性能与 Python 兼容性两大诉求datetime64管绝对时间、timedelta64管相对时间二者通过减法/加减运算互通NaT 哨兵统一表达缺失值。它确立的单位表、dtype 构造语法M8[us]/m8[us]、casting 规则绝对时间优先、相对时间保精度、Y/M 需参照日期至今仍是 NumPy 日期时间功能的基石。对于希望深入理解numpy.datetime64内部语义或追溯其设计来源的开发者这份提案文档与本文梳理的仓库实现线索构成了从设计意图到工程实现的完整链条。【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址: https://gitcode.com/gh_mirrors/nu/numpy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考