jdatetime：Python 环境的波斯日历库

jdatetime 在 GitHub 上已经拿到 388 Star 了。

它是 Python 标准库 datetime 模块的 Jalali（波斯历）实现。伊朗、阿富汗等地区日常使用波斯历，年份与公历相差约 621 年。涉及这些地区的业务系统需要处理日期转换，但 Python 生态里长期缺少一个接口风格一致且开箱即用的库。jdatetime 直接复刻了 datetime 的 API 设计，替换 import 语句即可上手。

1、 这库是干嘛的

让 Python 开发者用标准 datetime 的写法操作波斯历。

jdatetime 提供两个核心类：jdatetime.date 和 jdatetime.datetime，分别对标标准库的 date 和 datetime。now、strftime、timedelta 运算、时区处理等操作全部保留。熟悉标准库 datetime 的人不需要学习新概念。

2、 公历与波斯历互转

核心方法有两个。fromgregorian 将公历日期转为波斯历，togregorian 将波斯日期转为公历。

fromgregorian 支持两种传参方式：

jdatetime.date.fromgregorian(day=X, month=X, year=X)
jdatetime.date.fromgregorian(date=datetime.date)

也支持直接从 datetime.datetime 对象转换：

jdatetime.datetime.fromgregorian(datetime=datetime.datetime)

日期格式化与标准库完全一致。设置波斯语后的输出效果：

>>> jdatetime.datetime.now().strftime("%a, %d %b %Y %H:%M:%S")
u'Wed, 08 Ord 1395 20:47:32'

闰年判断也内置了，算法基于波斯历规则。

3、 本地化

设置 FA_LOCALE 即可切换为波斯语输出，星期和月份名称自动变为波斯语。

语言设定支持两种方式：实例化时通过 locale 参数指定，或通过 set_locale 设置全局默认。线程和 greenlet 环境各自独立，适合在一个进程内处理多语言的场景。

4、 安装

pip install jdatetime

一行命令完成安装，没有第三方依赖。

5、 开发与贡献

项目通过 tox 管理多版本 Python 测试。fork 后提交 PR，运行 tox 验证测试全部通过即可。发布采用语义版本号，GitHub Action 自动构建并部署到 PyPI。

运行 tox 验证测试全部通过即可。发布采用语义版本号，GitHub Action 自动构建并部署到 PyPI。