Skip to content

📓 python农历&节日工具库 - 中文数字/设计模式/树形结构

License

Notifications You must be signed in to change notification settings

kinegratii/borax

Repository files navigation

Borax - python农历&节日工具库 - 中文数字/设计模式/树形结构

PyPI PyPI - Python Version Python package Codecov GitHub license borax

概述 (Overview)

github https://github.com/kinegratii/borax

gitee https://gitee.com/kinegratii/borax

Borax 是一个Python3工具集合库。包括了以下几个话题:

话题(Topics) 内容
Borax.LunarDate 1900-2100年的中国农历日期库
Borax.Festivals 实现常见节日(公历、农历、星期、节气)的工具库
Borax.Choices 声明式的选项类。适用于Django.models.choices 定义。
Borax.Datasets 记录型数据操作库,包括连结(Join)、列选择(fetch)等
Borax.DataStuctures 树形结构,json数据
Borax.Numbers 数字库。包括中文数字、百分数等。
Borax.Patterns 设计模式。包括单例模式、代理对象、延迟对象。

安装 (Installation)

Borax 的 python 版本要求如下

borax 版本 python版本 维护状态
4.1.x 3.9+ 维护开发
4.0.0 3.7+ 维护至2024年12月31日
3.x 3.5+ 不再维护

可以通过 pip 安装 :

$ pip install borax

版本 (Version)

Borax的版本符合 语义化版本 ,格式为 <主版本号>.<副版本号>.<修正版本号>, 推荐使用下面方式定义Borax的依赖版本号。

borax~=4.1

使用示例 (Usage)

Borax.LunarDate: 中国农历日期

一个支持1900-2100年的农历日期工具库。

本模块的数据和算法参考自项目 jjonline/calendar.js ,部分算法和数据有所修改。

创建日期,日期推算

from datetime import timedelta
from borax.calendars import LunarDate

# 获取今天的农历日期(农历二〇一八年七月初一)
print(LunarDate.today()) # LunarDate(2018, 7, 1, 0)

# 将公历日期转化为农历日期
ld = LunarDate.from_solar_date(2018, 8, 11)
print(ld) # LunarDate(2018, 7, 1, 0)

# 日期推算,返回10天后的农历日期
print(ld.after(10)) # LunarDate(2018, 7, 11, 0)

# 可以直接与 datetime.timedelta 直接相加减
print(ld + timedelta(days=10)) # LunarDate(2018, 7, 11, 0)

格式化字符串

today = LunarDate.today()
print(today.strftime('%Y年%L%M月%D')) # '二〇一八年六月廿六'
print(today.strftime('今天的干支表示法为:%G')) # '今天的干支表示法为:戊戌年庚申月辛未日'

Borax.Festival: 国内外节日

创建春节(每年正月初一)对应的节日对象

from borax.calendars.festivals2 import LunarFestival

festival = LunarFestival(month=1, day=1)
print(festival.description) # '农历每年正月初一'

# 下一次春节的具体日期以及距离天数
print(festival.countdown()) # (273, <WrappedDate:2022-02-01(二〇二二年正月初一)>)

# 接下来5个春节的日期 ['2022-02-01(二〇二二年正月初一)', '2023-01-22(二〇二三年正月初一)', '2024-02-10(二〇二四年正月初一)', '2025-01-29(二〇二五年正月初一)', '2026-02-17(二〇二六年正月初一)']
print([str(wd) for wd in festival.list_days(start_date=date.today(), count=5)])

可支持的节日类型

节日 表示法 规范化描述
元旦 SolarFestival(month=1, day=1) 农历每年正月初一
中秋节 LunarFestival(month=8, day=15) 农历每年八月十五
母亲节(每年5月第二个周日) WeekFestival(month=5, index=2, week=calendar.SUNDAY) 公历每年5月第2个星期日
除夕 LunarFestival(day=-1) 农历每年最后一天
程序员节 SolarFestival(freq=FreqConst.YEARLY,day=256) 公历每年第256天
清明节 TemFestival(name="清明") 公历每年清明
每月5日 SolarFestival(freq=FreqConst.MONTHLY, day=5) 公历每月5日
国际麻风节 WeekFestival(month=1, index=-1, week=calendar.SUNDAY) 公历1月倒数第1个星期日
每月最后一个周日 WeekFestival(month=0, index=-1, week=calendar.SUNDAY) 公历每月倒数第1个星期日
初伏 TemFestival('夏至', nth=3, day_gz='庚') 公历每年夏至起第三个庚日

Borax.FestivalLibrary:内置节日库

基本使用示例

from datetime import date
from borax.calendars.festivals2 import FestivalLibrary, WrappedDate

library = FestivalLibrary.load_builtin()

# 2020年国庆节和中秋节是同一天
names = library.get_festival_names(date(2020, 10, 1))
print(names) # ['国庆节', '中秋节']

# 2021年七夕
festival = library.get_festival('七夕')
print(festival.description) # '农历每年七月初七'
print(WrappedDate(festival.at(year=2021))) # '2021-08-14(二〇二一年七月初七)'

计算节日及其距离今天(2021年5月4日)的天数

from borax.calendars.festivals2 import FestivalLibrary

library = FestivalLibrary.load_builtin()
for ndays, wd, festival in library.list_days_in_countdown(countdown=365):
    print(f'{ndays:>3d} {wd} {festival.name}')

输出结果

  0 2022-05-04(四月初四) 青年节
  4 2022-05-08(四月初八) 母亲节
  8 2022-05-12(四月十二) 护士节
...
332 2023-04-01(闰二月十一) 愚人节
336 2023-04-05(闰二月十五) 清明
362 2023-05-01(三月十二) 劳动节

Borax.Numbers: 中文数字处理

不同形式的中文数字

from borax.numbers import ChineseNumbers

# 小写、计量
print(ChineseNumbers.measure_number(204)) # '二百零四'
# 小写、编号
print(ChineseNumbers.order_number(204)) # '二百〇四'
# 大写、计量
print(ChineseNumbers.measure_number(204, upper=True)) # '贰佰零肆'
# 大写、编号
print(ChineseNumbers.order_number(204, upper=True)) # '贰佰〇肆'

财务金额

import decimal

from borax.numbers import FinanceNumbers

decimal.getcontext().prec = 2

print(FinanceNumbers.to_capital_str(100000000)) # '壹亿元整'
print(FinanceNumbers.to_capital_str(4578442.23)) # '肆佰伍拾柒万捌仟肆佰肆拾贰元贰角叁分'
print(FinanceNumbers.to_capital_str(107000.53)) # '壹拾万柒仟元伍角叁分'
print(FinanceNumbers.to_capital_str(decimal.Decimal(4.50))) # '肆元伍角零分'

更多模块功能参见文档。

文档 (Document)

文档由 Material for MkDocs 构建 ,另外备用文档使用 docsify 构建

2024年1月起,仅保留 Read the Docs 文档源。

网址
read-the-docs https://borax.readthedocs.io/zh_CN/latest/
github(已废弃) https://kinegratii.github.io/borax
gitee(已废弃) https://kinegratii.gitee.io/borax

开发特性和规范 (Development Features)

项目构建 (Project Build)

从4.1.0 开始,borax 使用 pyproject.toml 作为项目构建的配置文件,使用以下命令构建 wheel 发行包。

python -m build -w

开源协议 (License)

The MIT License (MIT)