中国节假日日历库 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. 对于调休日的判断需要特别注意，因为调休规则每年可能有所不同

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