{"id":24073782,"url":"https://github.com/kinegratii/borax","last_synced_at":"2025-10-08T18:03:10.530Z","repository":{"id":31785436,"uuid":"126959349","full_name":"kinegratii/borax","owner":"kinegratii","description":":notebook: python农历\u0026节日工具库 - 中文数字/设计模式/树形结构","archived":false,"fork":false,"pushed_at":"2025-03-18T13:30:10.000Z","size":1927,"stargazers_count":78,"open_issues_count":3,"forks_count":10,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T19:06:55.505Z","etag":null,"topics":["chinese-festivals","chinese-lunar-calendar","datastructures","festivals","lunar-calendar","python3","utils"],"latest_commit_sha":null,"homepage":"https://borax.readthedocs.io/zh_CN/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kinegratii.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-27T09:07:08.000Z","updated_at":"2025-03-19T08:38:24.000Z","dependencies_parsed_at":"2023-12-23T12:20:11.968Z","dependency_job_id":"b2e9b050-145a-45c8-961e-0fb88cd290d8","html_url":"https://github.com/kinegratii/borax","commit_stats":{"total_commits":399,"total_committers":3,"mean_commits":133.0,"dds":0.07268170426065168,"last_synced_commit":"06407958a6ba3115d783ed6457c2e7355a3f237c"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinegratii%2Fborax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinegratii%2Fborax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinegratii%2Fborax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinegratii%2Fborax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kinegratii","download_url":"https://codeload.github.com/kinegratii/borax/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247242678,"owners_count":20907134,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chinese-festivals","chinese-lunar-calendar","datastructures","festivals","lunar-calendar","python3","utils"],"created_at":"2025-01-09T17:56:49.042Z","updated_at":"2025-10-08T18:03:05.497Z","avatar_url":"https://github.com/kinegratii.png","language":"Python","funding_links":[],"categories":["📂 按分类"],"sub_categories":["📅 农历日历"],"readme":"# Borax - python农历\u0026节日工具库 - 中文数字/设计模式/树形结构\n\n\n[![PyPI](https://img.shields.io/pypi/v/borax.svg)](https://pypi.org/project/borax) \n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/borax.svg)](https://pypi.org/project/borax)\n![Python package](https://github.com/kinegratii/borax/workflows/Python%20package/badge.svg)\n![Codecov](https://codecov.io/github/kinegratii/borax/coverage.svg)\n![GitHub license](https://img.shields.io/github/license/kinegratii/borax)\n[![borax](https://snyk.io/advisor/python/borax/badge.svg)](https://snyk.io/advisor/python/borax)\n\n\n## 概述 (Overview)\n\n\u003e 代码主仓库 github  https://github.com/kinegratii/borax\n\u003e\n\u003e 备份仓库(仅版本发布时同步代码) gitee  https://gitee.com/kinegratii/borax\n\n\n\nBorax 是一个Python3工具集合库。包括了以下几个话题：\n\n| 话题（Topics）      | 内容                                                  |\n| ------------------- | ----------------------------------------------------- |\n| Borax.LunarDate     | 1900-2100年的中国农历日期库                           |\n| Borax.Festivals     | 实现常见节日（公历、农历、星期、节气）的工具库                           |\n| Borax.Choices       | 声明式的选项类。适用于Django.models.choices 定义。    |\n| Borax.Datasets      | 记录型数据操作库，包括连结（Join）、列选择（fetch）等 |\n| Borax.DataStuctures | 树形结构，json数据                                    |\n| Borax.Numbers       | 数字库。包括中文数字、百分数等。                      |\n| Borax.Patterns      | 设计模式。包括单例模式、代理对象、延迟对象。          |\n\n## 安装 (Installation)\n\nBorax 的 python 版本要求如下\n\n| borax 版本 | python版本 | 维护状态 |\n| ------ | ------ | ------ |\n| 4.1.x | 3.9+ | 维护开发 |\n| 4.0.0 | 3.7+ | 不再维护 |\n| 3.x | 3.5+ | 不再维护 |\n\n可以通过 *pip* 安装 ：\n\n```shell\n$ pip install borax\n```\n\n## 版本 (Version)\n\nBorax的版本符合 [语义化版本](https://semver.org/lang/zh-CN/) ，格式为 `\u003c主版本号\u003e.\u003c副版本号\u003e.\u003c修正版本号\u003e`， 推荐使用下面方式定义Borax的依赖版本号。\n\n```text\nborax~=4.1\n```\n\n## 使用示例 (Usage)\n\n### Borax.LunarDate: 中国农历日期\n\n一个支持1900-2100年的农历日期工具库。\n\n\u003e 本模块的数据和算法参考自项目 [jjonline/calendar.js](https://github.com/jjonline/calendar.js)  ，部分算法和数据有所修改。\n\n创建日期，日期推算\n\n```python\nfrom datetime import timedelta\nfrom borax.calendars import LunarDate\n\n# 获取今天的农历日期（农历二〇一八年七月初一）\nprint(LunarDate.today()) # LunarDate(2018, 7, 1, 0)\n\n# 将公历日期转化为农历日期\nld = LunarDate.from_solar_date(2018, 8, 11)\nprint(ld) # LunarDate(2018, 7, 1, 0)\n\n# 日期推算，返回10天后的农历日期\nprint(ld.after(10)) # LunarDate(2018, 7, 11, 0)\n\n# 可以直接与 datetime.timedelta 直接相加减\nprint(ld + timedelta(days=10)) # LunarDate(2018, 7, 11, 0)\n```\n\n格式化字符串\n\n```python\ntoday = LunarDate.today()\nprint(today.strftime('%Y年%L%M月%D')) # '二〇一八年六月廿六'\nprint(today.strftime('今天的干支表示法为：%G')) # '今天的干支表示法为：戊戌年庚申月辛未日'\n```\n\n### Borax.Festival: 国内外节日\n\n创建春节（每年正月初一）对应的节日对象\n\n```python\nfrom borax.calendars.festivals2 import LunarFestival\n\nfestival = LunarFestival(month=1, day=1)\nprint(festival.description) # '农历每年正月初一'\n\n# 下一次春节的具体日期以及距离天数\nprint(festival.countdown()) # (273, \u003cWrappedDate:2022-02-01(二〇二二年正月初一)\u003e)\n\n# 接下来5个春节的日期 ['2022-02-01(二〇二二年正月初一)', '2023-01-22(二〇二三年正月初一)', '2024-02-10(二〇二四年正月初一)', '2025-01-29(二〇二五年正月初一)', '2026-02-17(二〇二六年正月初一)']\nprint([str(wd) for wd in festival.list_days(start_date=date.today(), count=5)])\n```\n\n### 可支持的节日类型\n\n| 节日                          | 表示法                                                | 规范化描述                |\n| ----------------------------- | ----------------------------------------------------- | ------------------------- |\n| 元旦                          | SolarFestival(month=1, day=1)                         | 农历每年正月初一          |\n| 中秋节                        | LunarFestival(month=8, day=15)                        | 农历每年八月十五          |\n| 母亲节（每年5月第二个周日）   | WeekFestival(month=5, index=2, week=calendar.SUNDAY)  | 公历每年5月第2个星期日    |\n| 除夕             | LunarFestival(day=-1)                                 | 农历每年最后一天          |\n| 程序员节                      | SolarFestival(freq=FreqConst.YEARLY，day=256)         | 公历每年第256天           |\n| 清明节                        | TemFestival(name=\"清明\")                              | 公历每年清明              |\n| 每月5日                       | SolarFestival(freq=FreqConst.MONTHLY， day=5)         | 公历每月5日               |\n| 国际麻风节       | WeekFestival(month=1, index=-1, week=calendar.SUNDAY) | 公历1月倒数第1个星期日    |\n| 每月最后一个周日 | WeekFestival(month=0, index=-1, week=calendar.SUNDAY) | 公历每月倒数第1个星期日   |\n| 初伏 | TemFestival('夏至', nth=3, day_gz='庚') | 公历每年夏至起第三个庚日   |\n\n### Borax.FestivalLibrary：内置节日库\n\n基本使用示例\n\n```python\nfrom datetime import date\nfrom borax.calendars.festivals2 import FestivalLibrary, WrappedDate\n\nlibrary = FestivalLibrary.load_builtin()\n\n# 2020年国庆节和中秋节是同一天\nnames = library.get_festival_names(date(2020, 10, 1))\nprint(names) # ['国庆节', '中秋节']\n\n# 2021年七夕\nfestival = library.get_festival('七夕')\nprint(festival.description) # '农历每年七月初七'\nprint(WrappedDate(festival.at(year=2021))) # '2021-08-14(二〇二一年七月初七)'\n```\n\n计算节日及其距离今天（2021年5月4日）的天数\n\n```python\n\nfrom borax.calendars.festivals2 import FestivalLibrary\n\nlibrary = FestivalLibrary.load_builtin()\nfor ndays, wd, festival in library.list_days_in_countdown(countdown=365):\n    print(f'{ndays:\u003e3d} {wd} {festival.name}')\n```\n\n输出结果\n\n```\n  0 2022-05-04(四月初四) 青年节\n  4 2022-05-08(四月初八) 母亲节\n  8 2022-05-12(四月十二) 护士节\n...\n332 2023-04-01(闰二月十一) 愚人节\n336 2023-04-05(闰二月十五) 清明\n362 2023-05-01(三月十二) 劳动节\n\n```\n\n\n### Borax.Numbers: 中文数字处理\n\n\n不同形式的中文数字\n\n```python\nfrom borax.numbers import ChineseNumbers\n\n# 小写、计量\nprint(ChineseNumbers.measure_number(204)) # '二百零四'\n# 小写、编号\nprint(ChineseNumbers.order_number(204)) # '二百〇四'\n# 大写、计量\nprint(ChineseNumbers.measure_number(204, upper=True)) # '贰佰零肆'\n# 大写、编号\nprint(ChineseNumbers.order_number(204, upper=True)) # '贰佰〇肆'\n```\n\n财务金额\n\n```python\nimport decimal\n\nfrom borax.numbers import FinanceNumbers\n\ndecimal.getcontext().prec = 2\n\nprint(FinanceNumbers.to_capital_str(100000000)) # '壹亿元整'\nprint(FinanceNumbers.to_capital_str(4578442.23)) # '肆佰伍拾柒万捌仟肆佰肆拾贰元贰角叁分'\nprint(FinanceNumbers.to_capital_str(107000.53)) # '壹拾万柒仟元伍角叁分'\nprint(FinanceNumbers.to_capital_str(decimal.Decimal(4.50))) # '肆元伍角零分'\n```\n\n更多模块功能参见文档。\n\n## 文档 (Document)\n\n文档由 [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) 构建。\n\n| 源 | 网址 |\n| ---- | ---- |\n| read-the-docs | [https://borax.readthedocs.io/zh_CN/latest/](https://borax.readthedocs.io/zh_CN/latest/) |\n\n## 开发特性和规范 (Development Features)\n\n- [x] [Typing Hints](https://www.python.org/dev/peps/pep-0484/)\n- [x] [Flake8 Code Style](http://flake8.pycqa.org/en/latest/)\n- [x] [nose2](https://pypi.org/project/nose2/) | [pytest](https://docs.pytest.org/en/latest/)\n- [x] [Github Action](https://github.com/kinegratii/borax/actions)\n- [x] [Code Coverage](https://codecov.io/)\n- [x] [pyproject.toml build tools](https://packaging.python.org/)\n\n## 单元测试 (Unittests)\n\n支持 unitests 和 nose2 测试框架。\n\nunittest\n\n```shell\npython -m unittest\n```\n\nnose2\n\n```shell\nnose2 tests\n```\n\n\n\n## 项目构建 (Project Build)\n\n从4.1.0 开始，borax 使用 *pyproject.toml* 作为项目构建的配置文件，使用以下命令构建 wheel 发行包。\n\n```shell\npython -m build -w\n```\n\n## 开源协议 (License)\n\nThe MIT License (MIT)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkinegratii%2Fborax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkinegratii%2Fborax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkinegratii%2Fborax/lists"}