中国节假日日历库 chinese-calendar 完全指南

chinese-calendar 是一个专业的 Python 库，专门用于判断中国法定节假日和工作日。该库支持从 2004 年至 2026 年的完整节假日数据，包括 2020 年春节延长假期等特殊情况的精准识别。

快速安装部署

基础安装方法

使用 pip 命令即可快速安装最新版本：

pip install chinesecalendar

年度数据更新

由于节假日安排依赖国务院发布的最新通知，建议每年 11 月前后执行版本升级：

pip install -U chinesecalendar

核心功能详解

基础日期类型判断

import datetime
from chinese_calendar import is_holiday, is_workday

# 判断 2018年4月30号 是不是节假日
april_last = datetime.date(2018, 4, 30)
assert is_workday(april_last) is False
assert is_holiday(april_last) is True

节假日详细信息获取

import chinese_calendar as calendar

# 在判断的同时获取节日名称
on_holiday, holiday_name = calendar.get_holiday_detail(april_last)
assert on_holiday is True
assert holiday_name == calendar.Holiday.labour_day.value

调休日智能识别

import chinese_calendar

# 判断法定节假日是否为调休
assert chinese_calendar.is_in_lieu(datetime.date(2006, 2, 1)) is False
assert chinese_calendar.is_in_lieu(datetime.date(2006, 2, 2)) is True

完整节假日类型覆盖

库中支持的主要节假日类型包括：

• 元旦 (New Year's Day) - 1天假期
• 春节 (Spring Festival) - 3天法定节假日
• 清明节 (Tomb-sweeping Day) - 1天假期
• 劳动节 (Labour Day) - 1天假期
• 端午节 (Dragon Boat Festival) - 1天假期
• 国庆节 (National Day) - 3天法定节假日
• 中秋节 (Mid-autumn Festival) - 1天假期

高级功能应用

时间段节假日统计

from chinese_calendar import get_holidays, get_workdays

start_date = datetime.date(2024, 1, 1)
end_date = datetime.date(2024, 12, 31)

# 获取2024年所有节假日（包含周末）
all_holidays = get_holidays(start_date, end_date, include_weekends=True)

# 获取2024年所有工作日（不包含周末）
workdays_only = get_workdays(start_date, end_date, include_weekends=False)

工作日智能查找

from chinese_calendar import find_workday

# 查找下一个工作日
next_workday = find_workday(delta_days=1)

# 查找上一个工作日
previous_workday = find_workday(delta_days=-1)

项目架构说明

chinese-calendar 项目采用清晰的模块化设计：

chinese_calendar/
├── __init__.py          # 主模块入口，导出所有公共接口
├── constants.py         # 生成的节假日常量数据定义
├── scripts/
│   ├── __init__.py     # 脚本模块初始化
│   └── data.py         # 节假日数据定义和生成逻辑
├── solar_terms.py      # 24节气计算相关功能
└── utils.py           # 工具函数和辅助方法

数据来源与权威性

该库的所有节假日数据均来源于国务院办公厅发布的官方节假日安排通知，确保数据的准确性和时效性。每年根据最新的国务院通知及时更新数据源，保证节假日判断的权威性。

主要应用场景

chinese-calendar 库适用于多种业务场景：

1. 企业考勤系统 - 自动判断工作日和节假日，实现考勤自动化
2. 财务计算应用 - 准确计算工作日相关的利息和费用
3. 项目管理系统 - 科学排除节假日，优化项目排期
4. 日程安排工具 - 智能避开法定节假日，提升用户体验

使用注意事项

1. 时间范围限制：该库仅支持 2004 年至 2026 年的节假日数据
2. 政策依赖性：节假日安排以国务院最新通知为基准
3. 版本更新建议：建议定期升级以获取最新的节假日数据
4. 调休规则注意：每年的调休安排可能有所不同，需要特别关注

技术特点

• 轻量级设计：库文件体积小，依赖简单
• 高性能计算：采用优化的算法实现快速日期判断
• 易于集成：提供简洁的 API 接口，便于快速集成到现有项目中

通过使用 chinese-calendar 库，开发者可以轻松地在应用程序中集成中国法定节假日的智能判断功能，显著提升开发效率和系统准确性。