后端【免费下载链接】pendulumPython datetimes made easy项目地址https://gitcode.com/gh_mirrors/pe/pendulum点击查看免费下载本指南围绕 Pendulum 的差值计算体系展开深入讲解diff()如何返回表示两个时刻总时长的Interval对象、如何通过in_*系列方法按指定单位年/月/周/天/时/分/秒表达截断后的差值以及diff_for_humans()如何输出 1 day ago、3 weeks from now 等人类可读的文案并支持多语言本地化。读完本文你将掌握 Pendulum 中日期差值计算的完整 API、正负号与绝对值的控制方式、截断不四舍五入的边界行为以及本地化定制的方法并能直接迁移到评论时间、内容时效等真实业务场景。一、diff()两个时间点之间的总时长diff()是 Pendulum 计算两个时刻差值的入口方法。它返回一个 Interval 实例该实例表示两个DateTime之间的总时长。例如 import pendulum dt_ottawa pendulum.datetime(2000, 1, 1, tzAmerica/Toronto) dt_vancouver pendulum.datetime(2000, 1, 1, tzAmerica/Vancouver) dt_ottawa.diff(dt_vancouver).in_hours() 3两个城市同刻跨时区比较diff()返回的是真实的 3 小时时差而不是简单的本地时间相减。1.1 参数签名与语义从源码看DateTime.diff()的定义位于 src/pendulum/datetime.pydef diff(self, dt: datetime.datetime | None None, abs: bool True) - Interval[datetime.datetime]: if dt is None: dt self.now(self.tz) return Interval(self, dt, absoluteabs)两个参数的完整语义如下参数默认值说明dtNone要与之比较的DateTime实例传入None时使用now()并沿用当前实例的时区self.tzabsTrue是否返回绝对值。True时始终返回正数False时返回带正负号的相对值若传入的日期早于当前实例则带-号1.2 正负号absolute 参数的实战效果abs参数决定了差值的符号方向文档示例清楚地展示了这一点 dt_ottawa.diff(dt_vancouver).in_hours() 3 dt_ottawa.diff(dt_vancouver, False).in_hours() 3 dt_vancouver.diff(dt_ottawa, False).in_hours() -3当absTrue默认时无论谁先谁后结果都是正数 3当absFalse时以调用者为基准dt_ottawa.diff(dt_vancouver, False)表示渥太华相对温哥华Ottawa 更早但二者相减符号随内部方向而dt_vancouver.diff(dt_ottawa, False)返回-3明确表达出温哥华在渥太华之前 3 小时这一方向性信息。从 src/pendulum/interval.py 的实现可以看到Interval.__new__在absoluteTrue且start end时会自动交换起止点end, start start, end从而保证绝对值的语义同时Interval.__init__中通过self._invert start end记录方向供后续格式化使用。1.3 返回值类型Intervaldiff()返回的不是普通的timedelta而是Interval。Interval继承自Duration见 src/pendulum/interval.py并额外携带start、end两个端点属性支持in_words()、range()、迭代与成员判断in运算符等高级能力。关于 Interval 的更多用法可参考 Interval 文档。二、in_* 方法以指定单位表达总差值diff()返回的 Interval 可以通过一系列in_*方法把总时长折算为任意单位。这些方法永远返回以指定时间单位表达的完整总差值所有值都是截断truncate而非四舍五入round。2.1 可用方法一览Interval及父类 Duration提供的单位方法定义在 src/pendulum/duration.pydef in_weeks(self) - int: return int(self.total_weeks()) def in_days(self) - int: return int(self.total_days()) def in_hours(self) - int: return int(self.total_hours()) def in_minutes(self) - int: return int(self.total_minutes()) def in_seconds(self) - int: return int(self.total_seconds())Interval 还在 src/pendulum/interval.py 中补充了in_years()返回整年数、in_months()years * 12 months的完整月数、in_weeks()与in_days()等语义。所有方法都以int(...)截断小数部分因此 59 秒的差值用in_minutes()表达就是 0而 60 秒就是 1。2.2 截断语义的文档示例文档用一组精确的例子验证了截断而非四舍五入的规则 dt pendulum.datetime(2012, 1, 31, 0) dt.diff(dt.add(months1)).in_days() 29 dt.diff(dt.subtract(months1), False).in_days() -31 dt pendulum.datetime(2012, 4, 30, 0) dt.diff(dt.add(months1)).in_days() 30 dt.diff(dt.add(weeks1)).in_days() 7 dt pendulum.datetime(2012, 1, 1, 0) dt.diff(dt.add(seconds59)).in_minutes() 0 dt.diff(dt.add(seconds60)).in_minutes() 1 dt.diff(dt.add(seconds119)).in_minutes() 1 dt.diff(dt.add(seconds120)).in_minutes() 2这些示例蕴含两个关键事实月份长度按真实日历计算1 月 31 日加一个月到达 2 月 29 日2012 为闰年差值 29 天4 月 30 日加一个月到达 5 月 30 日差值 30 天。diff()的月差基于精确的日历日期差而非固定 30 天。严格向下截断119 秒 1 分 59 秒in_minutes()返回 1120 秒 2 分钟返回 2。任何小于整单位的部分都被丢弃。2.3 底层精确差值计算Interval 内部的精确差值由precise_diff()完成src/pendulum/interval.py 中self._delta: PreciseDiff precise_diff(_start, _end)。precise_diff在 src/pendulum/helpers.py 中按环境动态加载当PENDULUM_EXTENSIONS环境变量为1默认且平台为 64 位时优先使用 Rust 扩展实现pendulum._pendulum.precise_diff否则回退到 Python 实现pendulum._helpers.precise_diff。这也是 Interval 能精确拆解出years / months / weeks / days / hours / minutes / seconds / remaining_*等结构化字段的原因。2.4 测试用例佐证仓库测试 tests/datetime/test_diff.py 覆盖了所有单位的正负、跨年、跨时区场景例如dt.diff(dt.subtract(years1), False).in_years() -1相对值带符号dt.diff(dt.add(days1).add(hours13)).in_days() 1截断dt.diff(dt.add(seconds1.9)).in_seconds() 1小数秒截断dt_ottawa.diff(dt_vancouver).in_seconds() 3 * 60 * 60跨时区精确换算三、diff_for_humans()人性化差值文案diff_for_humans()在差值数值后附加一个短语把天数翻译成自然语言表达。它根据比较对象是否为 now以及方向过去/未来共有 4 种输出模式比较场景输出模式示例过去的值 vs 默认 nowago1 hour ago、5 months ago未来的值 vs 默认 nowfrom now1 hour from now、5 months from now过去的值 vs 另一个值before1 hour before、5 months before未来的值 vs 另一个值after1 hour after、5 months after3.1 基本用法示例 import pendulum # 最典型的场景评论时间对比当前 now() pendulum.now().subtract(days1).diff_for_humans() 1 day ago pendulum.now().diff_for_humans(pendulum.now().subtract(years1)) 1 year after dt pendulum.datetime(2011, 8, 1) dt.diff_for_humans(dt.add(months1)) 1 month before dt.diff_for_humans(dt.subtract(months1)) 1 month after pendulum.now().add(seconds5).diff_for_humans() 5 seconds from now pendulum.now().subtract(days24).diff_for_humans() 3 weeks ago注意最后一行24 天被智能地折叠为3 weeks而非24 days——这体现了diff_for_humans()的近似取整策略见下文 4.2 节。3.2 absolute 参数去掉修饰语传入True作为第 2 个参数可以移除ago、from now、before、after等修饰语只保留纯数值 pendulum.now().subtract(days24).diff_for_humans(absoluteTrue) 3 weeks3.3 源码调用链DateTime.diff_for_humans()的实现位于 src/pendulum/datetime.pydef diff_for_humans(self, otherNone, absoluteFalse, localeNone) - str: is_now other is None if is_now: other self.now() diff self.diff(other) return pendulum.format_diff(diff, is_now, absolute, locale)核心逻辑委托给pendulum.format_diff()最终由DifferenceFormattersrc/pendulum/formatting/difference_formatter.py完成文案生成。is_now标志决定使用ago / from now还是before / after分支方向由 Interval 的invert属性差值为负时为真决定使用未来future还是过去past的翻译键。Date与Time类型同样提供diff()与diff_for_humans()实现分别位于 src/pendulum/date.py 与 src/pendulum/time.py未传参时默认与today()/ 当前时间比较。四、本地化全局与单次调用4.1 两种设置方式差值文案的本地化支持两种方式全局设置在调用diff_for_humans()之前调用pendulum.set_locale(fr)或单次调用传参通过locale关键字参数。后者优先级更高且不会影响全局状态 import pendulum pendulum.set_locale(de) pendulum.now().add(years1).diff_for_humans() in 1 Jahr pendulum.now().add(years1).diff_for_humans(localefr) dans 1 an示例中全局 locale 为德语de但单次调用指定localefr后输出法语二者互不干扰。完整的本地化机制与可用语言列表可参考 Localization 文档仓库中 src/pendulum/locales 目录下按语言de、fr、zh、ja等组织 locale 数据DifferenceFormatter通过Locale.load(locale)加载对应语言包并利用 CLDRUnicode 通用语言环境数据仓库中的translations.relative与translations.units数据进行翻译与复数规则匹配。4.2 近似取整规则从源码看文案逻辑diff_for_humans()的输出不是简单的单位换算而是遵循DifferenceFormatter.format()中定义的阈值近似规则src/pendulum/formatting/difference_formatter.py阈值常量值含义DAYS_THRESHOLD_FOR_HALF_WEEK3剩余天数 3 天时周数 1约半周DAYS_THRESHOLD_FOR_HALF_MONTH15剩余天数 15 天时月数 1MONTHS_THRESHOLD_FOR_HALF_YEAR6剩余月数 6 个月时年数 1HOURS_IN_NEARLY_A_DAY22小时 ≥ 22 时天数 1接近一天DAYS_IN_NEARLY_A_MONTH27折算天数 ≥ 27 时月数 1接近一月MONTHS_IN_NEARLY_A_YEAR1111 个月 足够天数时进位为 1 年FEW_SECONDS_MAX10剩余秒数 ≤ 10 时优先使用 a few seconds 等自定义单位这解释了24 天 → 3 weeks24 天 3 周 3 天剩余未超过半周阈值3 天因此保持 3 周。格式化同时会依据 locale 的复数规则locale.plural(count)选择单复数形式例如英语的 1 day ago 与 2 days ago。五、实际应用与注意事项5.1 典型业务场景评论/帖子时间戳pendulum.now().subtract(days1).diff_for_humans()输出 1 day ago是社交产品最典型的用法事件方向提示dt.diff_for_humans(other)输出 before / after 指明先后关系无修饰的纯时长diff_for_humans(absoluteTrue)用于表格、标签等不强调方向的界面精确计算需要精确时长时使用diff().in_*()它严格截断适合倒计时、统计等场景。5.2 边界与陷阱时区参与计算diff()对带时区的实例执行的是真实时刻差跨时区比较会自动换算如本文开篇渥太华与温哥华的 3 小时示例Interval.__new__还会对 offset-naive 与 offset-aware 混用的情况抛出TypeError见 src/pendulum/interval.py。截断非取整in_minutes()对 119 秒返回 1、in_days()对 1 天 13 小时返回 1这是文档与测试共同确认的行为做倒计时逻辑时需自行处理余数。月份差异依赖日历add(months1)后的实际天数随起止月份变化1 月末加 1 月是 29 天4 月末加 1 月是 30 天不要假设固定 30 天/月。人性化文案是近似值diff_for_humans()的输出经过阈值四舍五入式的折叠如 24 天显示为 3 周适合展示而不适合精确计算。仓库中 tests/datetime/test_diff.py 与 tests/date/test_diff.py 提供了大量可直接对照的断言用例可作为理解截断、符号与文案规则的活文档。六、小结Pendulum 的差值体系由三层构成diff()负责产出携带端点与方向的Intervalin_*系列负责把总时长严格截断到目标单位diff_for_humans()负责把差值折叠为符合人类阅读习惯、且支持复数规则与多语言本地化的自然语言文案。掌握abs正负号、absolute去修饰语与locale本地化三个开关以及截断不取整近似折叠两条核心规则即可在真实业务中正确、优雅地处理所有时间差需求。赞分享后端【免费下载链接】pendulumPython datetimes made easy项目地址https://gitcode.com/gh_mirrors/pe/pendulum点击查看免费下载相关推荐Pendulum时间差计算终极指南从秒到年的精确时间间隔管理Pendulum时间差计算终极指南从秒到年的精确时间间隔管理 Pendulum是Python中一个强大的日期时间处理库专门为解决标准datetime模块在处后端PlayIntegrityFix社区贡献指南如何参与项目开发和问题解决PlayIntegrityFix社区贡献指南如何参与项目开发和问题解决 PlayIntegrityFix是一个开源的Android Magisk模块专门用于Perfetto Data Explorer Interval Intersect 节点多源时间区间交集计算实战指南Perfetto Data Explorer Interval Intersect 节点多源时间区间交集计算实战指南 Interval Intersect 是可观测性后端开发工具前端数据可视化上一篇Switch终极音乐播放方案TriPlayer完整使用教程与技巧下一篇TIDAL无损音乐下载终极指南24-bit/192kHz母带级音质免费保存创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考