Metadata-Version: 2.4
Name: ChinaHolidays
Version: 2026.2.16
Summary: 获取中国节假日信息
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: toml
Dynamic: license-file

# ChinaHolidays

#### 介绍
获取中国休息日，节假日安排来自官方渠道。
详情参考[official_info.toml](./src/ChinaHolidays/official_info.toml)

#### 安装与使用
* pip方式安装
```bash
pip install ChinaHolidays
```
* uv方式安装
```bash
uv pip install ChinaHolidays
```
```bash
uv add ChinaHolidays
```
* 使用
```python
from ChinaHolidays import (
    get_all_holidays,
    filter_holidays,
    date_range,
    ChinaHolidays
)
```

#### 功能
提供以下接口函数与类：
* date_range
```python
获取日期范围

    :param start_date: 开始日期
    :type start_date: datetime
    :param end_date: 结束日期（包含）
    :type end_date: datetime
    :return: 日期范围
    :rtype: set[datetime]
```
* get_all_holidays
```python
获取所有休息日（法定节假日+周末）

    :param year: 年份。默认为当前年份
    :type year: int
    :param consider_compensatory_workdays: 是否考虑调休工作日，默认为False
    :type consider_compensatory_workdays: bool
    :return: 休息日列表
    :rtype: set[datetime]
```
* filter_holidays
```python
筛掉休息日（法定节假日+周末）

    :param start_date: 开始日期
    :type start_date: datetime
    :param end_date: 结束日期（包含）
    :type end_date: datetime
    :param consider_compensatory_workdays: 是否考虑调休工作日，默认为False
    :type consider_compensatory_workdays: bool
    :return: 指定时间范围非休息日列表
    :rtype: set[datetime]
```
* ChinaHolidays
```python
class ChinaHolidays:
    """中国节假日"""

    def __init__(self, year: int):
        """初始化
        
        :param year: 年份
        :type year: int"""

    @property
    def festivals(self):
        """节假日

        :return: 节假日字典，键为节假日名称，值为日期集合
        :rtype: dict[str, set[datetime]]"""

    @property
    def festival_days(self):
        """节假日日期
        
        :return: 节假日日期集合
        :rtype: set[datetime]"""

    @property
    def compensatory_workdays(self):
        """调休工作日
        
        :return: 调休工作日集合
        :rtype: set[datetime]"""

    @property
    def weekends(self):
        """周末
        
        :return: 周末日期集合
        :rtype: set[datetime]"""
```
