Python 中国节假日库 chinese-calendar 使用指南

调休日精准识别

中国节假日安排中经常出现的调休情况，该库也能准确识别：

from chinese_calendar import is_in_lieu

# 判断是否为调休日
is_compensated_rest = is_in_lieu(datetime.date(2024, 2, 4))
print(f"是否为调休日：{is_compensated_rest}")

实际业务应用场景

考勤系统集成案例

from chinese_calendar import get_workdays, is_workday
import datetime

class AttendanceSystem:
    def __init__(self):
        self.workday_cache = {}

    def calculate_workdays(self, start_date, end_date):
        """计算指定时间段内的工作日数量"""
        workdays_list = get_workdays(start_date, end_date, include_weekends=False)
        return len(workdays_list)

    def is_valid_work_date(self, check_date):
        """验证日期是否为有效工作日"""
        return is_workday(check_date)

# 使用示例
attendance = AttendanceSystem()
workday_count = attendance.calculate_workdays(
    datetime.date(2024, 1, 1),
    datetime.date(2024, 12, 31)
)
print(f"2024 年工作日总数：{workday_count}")

财务计算应用

from chinese_calendar import find_workday
import datetime

def calculate_interest(principal, rate, start_date, days):
    """按工作日计算利息"""
    current_date = start_date
    workday_count = 0
    for i in range(days):
        if is_workday(current_date):
            workday_count += 1
        current_date += datetime.timedelta(days=1)
    interest = principal * rate * workday_count / 365
    return interest

# 计算下一个工作日
next_business_day = find_workday(delta_days=1)
print(f"下一个工作日是：{next_business_day}")

高级功能与技巧

节假日统计分析

from chinese_calendar import get_holidays
import datetime

def analyze_holiday_pattern(year):
    """分析指定年份的节假日分布"""
    start_date = datetime.date(year, 1, 1)
    end_date = datetime.date(year, 12, 31)
    # 获取所有节假日（包含周末）
    all_holidays = get_holidays(start_date, end_date, include_weekends=True)
    # 获取法定节假日（不包含周末）
    legal_holidays = get_holidays(start_date, end_date, include_weekends=False)
    return {
        'total_holidays': len(all_holidays),
        'legal_holidays': len(legal_holidays),
        'holiday_distribution': [h.strftime('%Y-%m-%d') for h in legal_holidays]
    }

# 分析 2024 年节假日
holiday_analysis = analyze_holiday_pattern(2024)
print(holiday_analysis)

24 节气支持

除了法定节假日，chinese-calendar 还提供了 24 节气的计算功能：

from chinese_calendar import get_solar_terms

# 获取 2024 年所有节气
solar_terms_2024 = get_solar_terms(
    datetime.date(2024, 1, 1),
    datetime.date(2024, 12, 31)
)

完整节假日类型覆盖

chinese-calendar 库支持的中国法定节假日包括：

• 元旦 (1 月 1 日) - 1 天假期
• 春节 (农历正月初一) - 3 天法定节假日
• 清明节 (4 月 4 日 -6 日之间) - 1 天假期
• 劳动节 (5 月 1 日) - 1 天假期
• 端午节 (农历五月初五) - 1 天假期
• 中秋节 (农历八月十五) - 1 天假期
• 国庆节 (10 月 1 日) - 3 天法定节假日

使用注意事项

数据范围限制

• 支持年份：2004 年至 2026 年
• 数据来源：官方通知
• 更新频率：每年 11 月前后发布新版本

版本更新建议

# 每年年底更新以获取最新节假日数据
pip install -U chinesecalendar

常见问题解答

Q: 为什么需要每年更新库版本？ A: 因为中国的节假日安排每年由官方发布，存在变动可能，更新版本确保数据准确性。

Q: 如何处理超出支持年份的日期？ A: 库会自动抛出 NotImplementedError 异常，建议在代码中进行范围检查。

Q: 是否支持其他国家或地区的节假日？ A: 当前版本专注于中国法定节假日，不支持其他地区。

Q: 如何获取特定年份的所有节假日列表？ A: 使用 get_holidays() 函数，指定起始和结束日期。

最佳实践建议

1. 版本管理：在生产环境中固定版本号，避免自动更新导致意外变化
2. 异常处理：对日期范围进行验证，捕获可能的 NotImplementedError
3. 缓存策略：对于频繁查询的日期，可以考虑本地缓存结果
4. 测试覆盖：针对关键节假日和调休日编写测试用例

未来发展方向

chinese-calendar 库作为中国节假日计算的标准解决方案，将继续：

• 扩展支持年份范围
• 增加更多实用功能
• 提升性能和稳定性
• 完善文档和社区支持

通过使用 chinese-calendar 库，开发者可以轻松解决中国节假日计算的复杂问题，显著提升开发效率和系统准确性。无论是企业级应用还是个人项目，这个库都能提供可靠的技术支持。