Holidays：工作日、节假日管理

原创

luckpunk

发布于 2025-01-15 12:51:59

14200

代码可运行

文章被收录于专栏：Python每日一库Python每日一库

运行总次数：0

代码可运行

在处理日期相关的编程任务时，我们经常需要判断某一天是否为法定节假日、调休日或工作日。传统方法需要手动维护日期列表，不仅繁琐还容易出错。直到遇见了holidays这个神奇的库，它完美解决了这个痛点，让日期处理变得轻而易举。

去年在一个跨国企业项目中，我们需要处理来自不同国家的假期安排。最初团队打算自己维护一个假期数据库，但很快发现这个方案难以持续。holidays库的出现拯救了我们，它内置了超过100个国家的节假日数据，而且保持实时更新。

安装和配置

安装holidays库非常简单：

pip install holidays

对于国内用户，建议使用清华镜像源加速安装：

pip install holidays -i https://pypi.tuna.tsinghua.edu.cn/simple

基本用法

holidays库的使用方式极其优雅。以下是几个基本示例：

import holidays
import datetime

# 获取中国2024年的所有节假日
cn_holidays = holidays.CN(years=2024)

# 判断某天是否为节假日
date = datetime.date(2024, 1, 1)
print(f"2024年1月1日是否为节假日: {date in cn_holidays}")
print(f"节日名称: {cn_holidays.get(date)}")

# 获取某个月份的所有节假日
jan_holidays = {date: name for date, name in cn_holidays.items() 
                if date.month == 1}
for date, name in jan_holidays.items():
    print(f"{date}: {name}")

进阶技巧

holidays库还支持自定义节假日，这在处理公司特殊假期时特别有用：

from holidays.holiday_base import HolidayBase

class CompanyHolidays(HolidayBase):
    def _populate(self, year):
        # 添加公司年会日期
        self[datetime.date(year, 1, 15)] = "公司年会"
        # 添加司庆日
        self[datetime.date(year, 6, 18)] = "公司成立纪念日"
        
# 合并公司假期和国家法定节假日
company_cn = holidays.CN() + CompanyHolidays()

一个鲜为人知的特性是holidays库支持工作日偏移计算：

from datetime import date
from holidays.utils import find_next_working_day

cn_holidays = holidays.CN()
current_date = date(2024, 1, 1)

# 查找下一个工作日
next_working_day = find_next_working_day(
    current_date, 
    holidays_obj=cn_holidays
)
print(f"下一个工作日是: {next_working_day}")

实战案例

这里展示一个实用的员工休假管理系统：

class VacationPlanner:
    def __init__(self, country='CN'):
        self.holidays = getattr(holidays, country)()
        
    def is_valid_vacation(self, start_date, days):
        """检查请假时间是否合理"""
        current = start_date
        working_days = 0
        
        for _ in range(days):
            if current.weekday() < 5 and current not in self.holidays:
                working_days += 1
            current += datetime.timedelta(days=1)
            
        return working_days <= days
    
    def calculate_return_date(self, start_date, days):
        """计算实际返岗日期"""
        current = start_date
        working_days = 0
        
        while working_days < days:
            current += datetime.timedelta(days=1)
            if current.weekday() < 5 and current not in self.holidays:
                working_days += 1
                
        return current

planner = VacationPlanner()
vacation_start = datetime.date(2024, 1, 15)
vacation_days = 5

if planner.is_valid_vacation(vacation_start, vacation_days):
    return_date = planner.calculate_return_date(vacation_start, vacation_days)
    print(f"请假开始日期: {vacation_start}")
    print(f"返岗日期: {return_date}")