Park Lam's 每日分享

Python实用工具：holidays库详解——轻松处理节假日数据

作者：

Park Lam

在

Python作为一门跨领域的编程语言，其生态系统的丰富性是支撑其广泛应用的核心因素之一。从Web开发中Django、Flask框架的高效构建，到数据分析领域Pandas、NumPy的强大处理能力；从机器学习中TensorFlow、PyTorch的深度学习支持，到自动化领域PyAutoGUI、Selenium的桌面与网页操控，Python几乎覆盖了技术领域的各个角落。在这些场景中，处理时间相关的数据是常见需求，而节假日作为时间维度的重要节点，其数据的获取与分析往往影响着业务逻辑的设计。本文将聚焦于Python生态中专门用于处理节假日数据的holidays库，深入解析其功能特性与实际应用。

一、holidays库概述：用途、原理与特性

1. 核心用途

holidays库是一个轻量级的Python工具，主要用于快速获取全球多个国家和地区的节假日数据。其应用场景广泛，例如：

  • 日程管理系统：在预约、任务调度功能中排除节假日；
  • 金融数据分析：分析股市、外汇市场在节假日的休市规律；
  • 电商运营分析：对比节假日与非节假日的销售数据差异；
  • 国际化应用开发：为多国家用户提供本地化的日期提示。

2. 工作原理

该库通过内置的国家/地区代码映射表与节假日生成逻辑实现数据获取：

  • 数据来源：核心数据基于pandas-holiday项目，并结合各国家官方假期规则维护；
  • 动态加载：首次调用时自动加载对应国家的节假日数据，支持按年份、地区筛选；
  • 更新机制：通过版本迭代更新节假日规则，用户也可自定义扩展数据。

3. 优缺点分析

优点：

  • 极简易用：无需复杂配置，一行代码即可获取节假日列表；
  • 高覆盖性：支持超过300个国家和地区（含美国各州、加拿大各省）；
  • 灵活性强：支持按年份过滤、自定义节假日、处理地区差异。

局限性：

  • 数据延迟：部分小众国家或年度新增假期可能存在更新不及时；
  • 依赖时区：默认返回UTC时间，需结合pytz等库处理时区转换；
  • 轻量级设计：不包含节假日类型（如公共假期、宗教节日）的细分标签。

4. 开源协议

holidays库基于MIT License开源，允许商业使用、修改和再分发，但需保留原作者声明。

二、holidays库基础使用指南

1. 安装与环境配置

安装命令

pip install holidays

验证安装

import holidays
print(holidays.__version__)  # 输出版本号，如'0.13.3'

2. 基础用法：获取默认国家节假日

逻辑说明

未指定国家时，库默认使用系统 locale（通常为操作系统语言对应的国家）。若需显式指定，可传入国家代码（如US、CN）。

代码示例

# 获取默认国家节假日（若系统 locale 为中文，可能默认中国）
default_holidays = holidays.Holidays()
print(f"默认国家：{default_holidays.country}")  # 输出国家代码，如'CN'

# 显式指定国家（以美国为例）
us_holidays = holidays.Holidays(country='US')
print(f"美国2023年节假日数量：{len(us_holidays.get_holidays(2023))}")  # 输出具体数值

3. 按国家/地区获取节假日

国家代码列表

支持的国家代码可通过holidays.countries属性查看，例如：

print(holidays.countries['CN'])  # 输出'China'
print(holidays.countries['JP'])  # 输出'Japan'

地区细分（以美国为例）

部分国家支持地区参数（如美国各州），通过subdiv参数指定：

# 获取纽约州节假日
ny_holidays = holidays.Holidays(country='US', subdiv='NY')
print("纽约州2023年元旦：", ny_holidays.get('2023-01-01'))  # 输出节假日名称

4. 按年份过滤数据

单一年份获取

# 获取中国2024年节假日
cn_2024 = holidays.China(years=2024)
for date, name in cn_2024.items():
    print(f"{date.strftime('%Y-%m-%d')}: {name}")

多年份批量获取

# 获取2023-2025年美国节假日
us_multi_years = holidays.US(years=[2023, 2024, 2025])
print(f"总节假日数：{len(us_multi_years)}")

5. 自定义节假日

临时添加单个节假日

# 创建自定义节假日实例
custom_holidays = holidays.Holidays(country='CN')
# 添加2024年公司年会（12月31日）
custom_holidays['2024-12-31'] = "公司年会"
print("自定义后节假日：", '2024-12-31' in custom_holidays)  # 输出True

批量导入自定义数据

# 从字典批量添加
additional_holidays = {
    '2025-01-15': "年度总结日",
    '2025-06-01': "儿童福利日"
}
custom_holidays.update(additional_holidays)

6. 数据结构与遍历

字典结构

holidays对象本质是字典，键为datetime.date类型，值为节假日名称：

us_holidays = holidays.US(years=2023)
first_holiday = next(iter(us_holidays.items()))
print(f"首个节假日：{first_holiday[0].strftime('%Y-%m-%d')} - {first_holiday[1]}")

按月份分组

# 按月份统计节假日数量
from collections import defaultdict
monthly_holidays = defaultdict(int)
for date in us_holidays:
    monthly_holidays[date.month] += 1
print("各月节假日数量：", dict(monthly_holidays))

7. 性能优化：缓存机制

原理说明

重复获取同一国家/地区的节假日时，启用缓存可避免重复计算。通过holidays.Cache类实现：

代码示例

from holidays import Cache

# 创建缓存实例（有效期默认30天）
cache = Cache()
us_holidays_cached = cache.get('US', years=2023)
print("缓存中的节假日数：", len(us_holidays_cached))

三、复杂场景应用：处理地区差异与数据整合

1. 多地区对比分析

需求场景

对比中国、美国、日本三国2023年节假日分布差异。

实现代码

countries = ['CN', 'US', 'JP']
for country in countries:
    hols = holidays.CountryHoliday(country, years=2023)
    print(f"\n{country}节假日分布：")
    for month in range(1, 13):
        monthly_hols = [d for d in hols if d.month == month]
        print(f"{month}月：{len(monthly_hols)}天")

输出示例

CN节假日分布：
1月：2天
2月：3天
...
10月：3天

US节假日分布：
1月：1天
2月：1天
...
12月：1天

2. 与Pandas结合进行数据分析

场景说明

假设存在销售数据集sales.csv，包含date和revenue字段，需标记节假日并分析销售额变化。

步骤1：读取数据并添加节假日标签

import pandas as pd
import holidays

# 读取数据
df = pd.read_csv('sales.csv', parse_dates=['date'])

# 创建中国节假日对象
cn_hols = holidays.China(years=df['date'].dt.year.unique())

# 添加标签列
df['is_holiday'] = df['date'].apply(lambda d: d in cn_hols)
df['holiday_name'] = df['date'].apply(lambda d: cn_hols.get(d, ''))

步骤2：统计节假日与非节假日销售额

# 分组统计
grouped = df.groupby('is_holiday')['revenue'].agg(['mean', 'sum', 'count'])
print("节假日销售统计：")
print(grouped.loc[True])
print("\n非节假日销售统计：")
print(grouped.loc[False])

3. 处理时区转换

需求场景

将UTC时间的节假日转换为北京时间（UTC+8）。

实现代码

from datetime import datetime
import pytz

# 获取UTC时间的节假日
utc_hols = holidays.US(years=2023, tz='UTC')
# 转换为北京时间
bj_tz = pytz.timezone('Asia/Shanghai')
bj_hols = {date.astimezone(bj_tz): name for date, name in utc_hols.items()}

# 示例：查看元旦对应的北京时间
jan_1_utc = next(iter(utc_hols.keys()))
jan_1_bj = jan_1_utc.astimezone(bj_tz)
print(f"UTC时间：{jan_1_utc}, 北京时间：{jan_1_bj}")

四、实际案例：生成年度节假日日历

需求描述

为某跨国公司生成2024年主要国家的节假日日历，以Excel格式保存，包含日期、国家、节假日名称。

实现步骤

1. 定义目标国家列表

target_countries = ['CN', 'US', 'JP', 'DE', 'FR']  # 中国、美国、日本、德国、法国

2. 批量获取节假日数据

all_holidays = []
for country_code in target_countries:
    # 获取国家全称
    country_name = holidays.countries[country_code]
    # 获取2024年节假日
    hols = holidays.CountryHoliday(country_code, years=2024)
    for date, name in hols.items():
        all_holidays.append({
            '日期': date.strftime('%Y-%m-%d'),
            '国家': country_name,
            '节假日名称': name
        })

3. 保存为Excel文件

import pandas as pd

# 创建DataFrame
df = pd.DataFrame(all_holidays)
# 按国家和日期排序
df = df.sort_values(by=['国家', '日期'])
# 保存为Excel
df.to_excel('2024年国际节假日日历.xlsx', index=False)

4. 验证结果

打开生成的Excel文件，可见类似以下内容：

日期国家节假日名称
2024-01-01China元旦
2024-02-10China春节
2024-01-01United States元旦
………

五、资源获取与扩展学习

1. 官方资源

  • Pypi地址：https://pypi.org/project/holidays/
  • Github仓库：https://github.com/darioagliardi/holidays
  • 官方文档：https://holidays.readthedocs.io/en/latest/

2. 扩展工具推荐

  • 时区处理：pytz、zoneinfo库；
  • 日历生成：calendar库、python-pptx生成PPT日历；
  • 数据可视化：结合matplotlib或seaborn绘制节假日分布图表。

结语

holidays库以其轻量、灵活的特性，成为Python生态中处理节假日数据的首选工具。无论是基础的日期标记，还是复杂的多地区数据分析，它都能高效满足需求。通过结合Pandas、NumPy等数据处理库，以及时区转换工具，开发者可进一步拓展其应用场景。建议在实际项目中根据业务需求，合理利用缓存机制优化性能，并定期更新库版本以获取最新节假日数据。如需处理更精细化的节假日类型（如宗教节日、地方性节日），可参考库的源代码结构，自定义扩展数据规则。

关注我，每天分享一个实用的Python自动化工具。

更多文章