后端【免费下载链接】pendulumPython datetimes made easy项目地址https://gitcode.com/gh_mirrors/pe/pendulum点击查看免费下载导读Duration是 Pendulum 中用于表达时间差time difference的核心类它继承自 Python 原生datetime.timedelta但在此基础上实现了直观归一化intuitive normalization、年/月单位支持、丰富的属性分解与多语言文字化输出等能力。本文以 docs/docs/duration.md 为主线结合 src/pendulum/duration.py 源码与 tests/duration/ 测试用例完整讲解 Duration 的创建、属性语义、单位换算方法与本地化输出帮助你在实际项目中安全、精准地使用 Pendulum 处理时间差。一、Duration 是什么继承 timedelta 的增强时间差类在 Python 标准库中两个datetime对象相减会得到一个timedelta它只有days、seconds、microseconds三个字段且会自动进行进位归一化。Pendulum 的Duration类直接继承自timedelta见 duration.py却在行为上做了重要改进。1.1 直观归一化不再自动进位原生timedelta会把负的时间差统一表示为负天数 正秒数的形式阅读起来很不直观 import pendulum import datetime d1 datetime.datetime(2012, 1, 1, 1, 2, 3, tzinfodatetime.UTC) d2 datetime.datetime(2011, 12, 31, 22, 2, 3, tzinfodatetime.UTC) delta d2 - d1 delta.days -1 delta.seconds 75600而 Pendulum 会保留每个单位的符号保持各分量直接相减的直觉语义 d1 pendulum.datetime(2012, 1, 1, 1, 2, 3) d2 pendulum.datetime(2011, 12, 31, 22, 2, 3) delta d2 - d1 delta.days 0 delta.hours -3从源码看这一逻辑在Duration.__new__中完成先把所有输入折算为秒再分别拆出_microseconds、_seconds、_days、_remaining_days、_weeks等内部字段duration.py负值通过符号位m保持各分量方向一致。二、实例化pendulum.duration()帮助函数创建Duration实例最直接的方式是使用pendulum.duration()帮助函数定义于 src/pendulum/init.py import pendulum it pendulum.duration(days1177, seconds7284, microseconds1234)2.1 完整的构造参数Duration.__new__与duration()帮助函数接受的参数完全一致所有参数默认值为0且顺序无关全部以关键字形式传入参数含义默认值days天数0seconds秒数0microseconds微秒数0milliseconds毫秒数0minutes分钟数0hours小时数0weeks周数0years年数必须为整数0months月数必须为整数0其中milliseconds会被换算并合并进微秒源码在记录_signature时使用microseconds milliseconds * 1000duration.py与原生timedelta的换算规则一致。2.2 支持 years 与 monthstimedelta 不具备的能力原生timedelta无法直接表达2 年 3 个月而Duration可以 import pendulum it pendulum.duration(years2, months3)注意两个限制均有源码与测试佐证years与months必须是整数传入浮点数会抛出ValueError(Float year and months are not supported)duration.py对应测试见 test_construct.py由于timedelta内部没有年/月字段Duration采用固定近似1 年 365 天1 个月 30 天见 duration.py 中的days years * 365 months * 30。因此为了维持与原生类的兼容days、total_seconds()等原生属性/方法在包含年/月时会使用上述近似值 it.days 820 it.total_seconds() 70848000.0该近似行为同样被测试锁定例如duration(years2).days 730、duration(months3).days 90test_construct.py。三、属性体系细粒度分解每个时间单位原生timedelta只有days、seconds、microseconds三个属性Duration则提供了一套完整的分解属性。以下沿用文档示例 import pendulum it pendulum.duration( ... years2, months3, ... days1177, seconds7284, microseconds1234 ... ) it.years 2 it.months 33.1 天与周的分解# Weeks 基于总天数计算不计入 years 和 months it.weeks 168 # days 与 timedelta 语义一致表示时长内的总天数 # 若指定了 years 和/或 months则使用近似值 it.days 1997 # 不足一整周的天数 it.remaining_days 1对应源码中的拆分逻辑为_weeks abs(_days) // 7、_remaining_days abs(_days) % 7duration.py即days是年×365 月×30 实际天数的累计总量而weeks/remaining_days只基于实际传入的天数部分拆分。3.2 时、分、秒与微秒 # 各单位的剩余值 it.hours 2 it.minutes 1 # seconds 与 days 一样属于特殊情形 # 为兼容 timedelta默认属性返回剩余秒数的整体值 it.seconds 7284 # 若想获取未计入小时和分钟的秒数 it.remaining_seconds 24 it.microseconds 1234从实现看hours与minutes由_seconds逐级取模而来abs(seconds) // 3600 % 24、abs(seconds) // 60 % 60见 duration.py并通过缓存字段_h、_i避免重复计算remaining_seconds则是abs(seconds) % 60duration.py。上述属性都对应了测试 test_construct.py 中的断言。四、单位换算total_xxx()与in_xxx()当需要把时长整体换算成某个单位时Duration提供两组方法。4.1total_xxx()返回浮点数与原生total_seconds()返回浮点数的语义一致每个total_xxx()都返回该单位下的完整时长保留小数 it.total_weeks() 168.15490079569113 it.total_days() 1177.0843055698379 it.total_hours() 28250.02333367611 it.total_minutes() 1695001.4000205665 it.total_seconds() 101700084.001234源码实现非常直白全部基于total_seconds()除以对应常量折算常量定义于 constants.pySECONDS_PER_MINUTE、SECONDS_PER_HOUR、SECONDS_PER_DAY例如total_hours()即self.total_seconds() / SECONDS_PER_HOURduration.py。4.2in_xxx()返回截断整数in_xxx()系列则对total_xxx()的结果做int()截断返回整数 it.in_weeks() 168 it.in_days() 1997 it.in_hours() 28250 it.in_minutes() 1695001 it.in_seconds() 101700084实现上即int(self.total_weeks())等一行转换duration.py相关断言见 tests/duration/test_in_methods.py。五、文字化输出in_words()与多语言支持in_words()是Duration最实用的方法之一它决定时长被打印时的呈现形式并且内置多语言本地化支持。其签名与核心逻辑在 duration.pydef in_words(self, locale: str | None None, separator: str ) - strlocale指定语言环境默认使用pendulum.get_locale()的当前 localeseparator各单位之间的分隔符默认单个空格。 import pendulum pendulum.set_locale(fr) it pendulum.duration(days1177, seconds7284, microseconds1234) it.in_words() 168 semaines 1 jour 2 heures 1 minute 24 secondes print(it) 168 semaines 1 jour 2 heures 1 minute 24 secondes it.in_words(localede) 168 Wochen 1 Tag 2 Stunden 1 Minute 24 Sekunden5.1 实现要点输出单位顺序固定为year → month → week → dayremaining_days→ hour → minute → secondremaining_seconds对应 duration.py 的intervals列表复数处理通过loaded_locale.plural(count)选择单复数词形再用translation.format(interval_count)填充数字__str__复用Duration.__str__直接返回self.in_words()duration.py所以print(it)与it.in_words()结果一致零值兜底当所有单位均为 0 时若存在微秒则输出0.12 seconds这类亚秒形式否则输出0 microseconds对应测试 test_in_words.py__repr__则输出结构化的构造参数形式如Duration(years2, months3, weeks168, days1, hours2, minutes1, seconds25)duration.py测试见 test_in_words.py。5.2 分隔符与负值 pendulum.duration(days1177, seconds7284, microseconds1000000) pi.in_words(separator, ) 168 weeks, 1 day, 2 hours, 1 minute, 25 seconds pendulum.duration(days-1).in_words() -1 day多语言词形取自 src/pendulum/locales/ 下各语言包的units翻译表测试覆盖了法文等场景test_in_words.py。六、进阶能力算术运算、转换与类常量6.1 算术运算Duration重载了原生timedelta的算术协议duration.py加减__add__/__sub__支持与任意timedelta含Duration运算结果基于total_seconds()重新构造乘法__mul__/__rmul__支持整数与浮点数整数乘法会保留 years/months 并按比例放大浮点乘法内部用_divide_and_round做银行家舍入除法__truediv__、__floordiv__、__mod__、__divmod__同样可用除以timedelta返回倍数除以标量返回新的Duration取负__neg__对各分量取反负值时长可通过invert属性判断total_seconds() 0。对应测试见 tests/duration/test_arithmetic.py乘法、除法、整除的年份/月份保留行为与 test_construct.pyinvert判定。6.2 与原生类型互转 pi pendulum.duration(seconds3456.123456) delta pi.as_timedelta() # 返回原生 datetime.timedelta isinstance(delta, timedelta) True delta.total_seconds() 3456.123456as_timedelta()通过timedelta(secondsself.total_seconds())完成转换duration.py测试见 test_construct.py。6.3 类常量与AbsoluteDurationDuration还定义了与timedelta对齐的类常量duration.pyDuration.min # Duration(days-999999999) Duration.max # Duration(days999999999, hours23, minutes59, seconds59, microseconds999999) Duration.resolution # Duration(microseconds1)此外同文件还定义了内部使用的AbsoluteDuration子类duration.py它把所有分量归一为绝对值表达total_seconds()恒为非负并额外提供invert标记原始方向用于 Pendulum 内部如Interval的绝对差值表达。七、实践建议与注意事项优先用pendulum.duration()帮助函数创建实例它透传全部 9 个关键字参数可读性最好年份/月份是近似值1 年按 365 天、1 月按 30 天折算。涉及days、total_seconds()等原生语义时务必记住这一点跨时区或跨闰年的精确日历差值请改用Interval见 docs/docs/interval.md区分days与remaining_days、seconds与remaining_seconds前者是与timedelta兼容的累计/整体值后者才是扣除更大单位后的余量这是 Duration 属性体系中最容易混淆的一对概念in_xxx()是截断而非四舍五入int(total_xxx())直接丢弃小数部分需要四舍五入时请自行使用round()多语言输出直接依赖pendulum.set_locale()或in_words(locale...)参数中文可传zh词形数据位于 src/pendulum/locales/zh/print()即in_words()__str__委托给in_words()因此直接打印对象即可获得本地化的自然语言时长描述。结语Duration是 Pendulum 时间体系的基石之一它以继承timedelta的方式保持生态兼容又以直观归一化、年/月支持和细粒度属性分解补足了原生类的短板配合in_words()的多语言输出能力让计算时间差并呈现给人看这件事变得简单而可靠。无论是编写调度逻辑、统计耗时还是生成人类可读的时长文案Duration都值得作为你的默认选择。赞分享后端【免费下载链接】pendulumPython datetimes made easy项目地址https://gitcode.com/gh_mirrors/pe/pendulum点击查看免费下载相关推荐Jenkins Job DSL安全最佳实践保护你的CI/CD管道Jenkins Job DSL安全最佳实践保护你的CI/CD管道 Jenkins Job DSL是一种基于Groovy的领域特定语言用于以编程方式定义JenPendulum Duration类详解精确时间间隔计算的终极指南Pendulum Duration类详解精确时间间隔计算的终极指南 在Python日期时间处理中Pendulum Duration类提供了比标准库更强大和直后端Pendulum 属性与特性详解超越标准 datetime 的日期时间属性Pendulum 属性与特性详解超越标准 datetime 的日期时间属性 Pendulum 在标准库 datetime 基础上提供了一组更丰富的属性与特性后端上一篇Cilium 的 cilium-dbg map events 实战指南深入剖析 BPF Map 事件缓冲与事件流下一篇基于 Zeek dns.log 的 DNS 数据外泄检测实战熵分析、长标签与查询量异常识别创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考