Metadata-Version: 2.1
Name: weekday
Version: 0.1.1
Summary: 一个获取当天或指定日期是星期几的 Python 库
Home-page: https://github.com/zhenzi0322-package/weekday
Author: zhenzi0322
Author-email: zhenzi0322 <82131529@qq.com>
License: MIT
Requires-Python: >=3.8
description-content-type: text/markdown
Description:
 # weekday
 
 一个轻量级的 Python 库，用于获取当天或指定日期是星期几。支持中英文输出，提供丰富的判断函数，**支持中国法定节假日和调休判断**。
 
 ## 安装
 
 ```bash
 pip install weekday
 ```
 
 ## 快速开始
 
 ```python
 from weekday import today, today_name, weekday, weekday_name
 from weekday import is_workday, is_restday, is_holiday
 
 # 获取今天是星期几
 today()           # 返回 0-6（0=周一，6=周日）
 today_name()      # '星期六'
 today_name(lang="en")  # 'Saturday'
 
 # 获取指定日期是星期几
 weekday("2024-01-01")   # 0（星期一）
 weekday_name("2024-01-01")  # '星期一'
 
 # 判断是否需要上班（考虑节假日和调休）
 is_workday("2024-02-04")  # True（周日，但是春节调休）
 is_workday("2024-02-10")  # False（周六，春节假期）
 
 # 判断是否法定节假日
 is_holiday("2024-01-01")  # True（元旦）
 ```
 
 ## API 参考
 
 ### 基础函数
 
 #### `today() -> int`
 
 获取今天是星期几。
 
 **返回值：** `int` - 0-6，0 表示星期一，6 表示星期日。
 
 ```python
 from weekday import today
 
 today()  # 例如：5（表示星期六）
 ```
 
 ---
 
 #### `today_name(lang="zh") -> str`
 
 获取今天是星期几的名称。
 
 **参数：**
 - `lang` (str): 语言，`"zh"` 返回中文，`"en"` 返回英文。默认 `"zh"`。
 
 **返回值：** `str` - 星期名称字符串。
 
 ```python
 from weekday import today_name
 
 today_name()            # '星期六'
 today_name(lang="en")   # 'Saturday'
 ```
 
 ---
 
 #### `weekday(d=None) -> int`
 
 获取指定日期是星期几。
 
 **参数：**
 - `d` (date | datetime | str | None): 日期，可以是 `date`、`datetime` 或字符串（格式 `YYYY-MM-DD`）。如果不传，则使用今天的日期。
 
 **返回值：** `int` - 0-6，0 表示星期一，6 表示星期日。
 
 **异常：**
 - `ValueError`: 字符串格式不正确时抛出。
 - `TypeError`: 传入不支持的类型时抛出。
 
 ```python
 from datetime import date, datetime
 from weekday import weekday
 
 weekday("2024-01-01")       # 0（星期一）
 weekday("2024-01-05")       # 4（星期五）
 weekday("2024-01-06")       # 5（星期六）
 weekday(date(2024, 1, 1))   # 0
 weekday(datetime(2024, 1, 5, 12, 30))  # 4
 weekday()                   # 返回今天的星期值
 ```
 
 ---
 
 #### `weekday_name(d=None, lang="zh", abbr=False) -> str`
 
 获取指定日期是星期几的名称。
 
 **参数：**
 - `d` (date | datetime | str | int | None): 日期或星期值（0-6）。如果不传，则使用今天的日期。
 - `lang` (str): 语言，`"zh"` 返回中文，`"en"` 返回英文。默认 `"zh"`。
 - `abbr` (bool): 是否使用英文缩写（仅 `lang="en"` 时有效）。默认 `False`。
 
 **返回值：** `str` - 星期名称字符串。
 
 ```python
 from weekday import weekday_name
 
 weekday_name("2024-01-01")                  # '星期一'
 weekday_name("2024-01-01", lang="en")       # 'Monday'
 weekday_name("2024-01-06", lang="en", abbr=True)  # 'Sat'
 weekday_name(0)                             # '星期一'
 weekday_name(6, lang="en")                  # 'Sunday'
 ```
 
 ---
 
 ### 判断函数
 
 #### `is_weekday(d=None) -> bool`
 
 判断指定日期是否为工作日（周一至周五）。
 
 ```python
 from weekday import is_weekday
 
 is_weekday("2024-01-01")  # True（星期一）
 is_weekday("2024-01-06")  # False（星期六）
 is_weekday()              # 判断今天是否为工作日
 ```
 
 ---
 
 #### `is_weekend(d=None) -> bool`
 
 判断指定日期是否为周末（周六或周日）。
 
 ```python
 from weekday import is_weekend
 
 is_weekend("2024-01-06")  # True（星期六）
 is_weekend("2024-01-07")  # True（星期日）
 is_weekend("2024-01-01")  # False（星期一）
 ```
 
 ---
 
 ### 具体星期判断函数
 
 以下函数用于判断指定日期是否为特定的星期几：
 
 | 函数 | 说明 |
 |------|------|
 | `is_monday(d=None)` | 判断是否为星期一 |
 | `is_tuesday(d=None)` | 判断是否为星期二 |
 | `is_wednesday(d=None)` | 判断是否为星期三 |
 | `is_thursday(d=None)` | 判断是否为星期四 |
 | `is_friday(d=None)` | 判断是否为星期五 |
 | `is_saturday(d=None)` | 判断是否为星期六 |
 | `is_sunday(d=None)` | 判断是否为星期日 |
 
 **参数：**
 - `d` (date | datetime | str | None): 日期，格式同 `weekday()` 函数。
 
 **返回值：** `bool` - 是指定星期几返回 `True`，否则返回 `False`。
 
 ```python
 from weekday import is_monday, is_friday, is_saturday
 
 is_monday("2024-01-01")    # True
 is_friday("2024-01-05")    # True
 is_saturday("2024-01-06")  # True
 is_monday("2024-01-05")    # False
 ```
 
 ---
 
 ### 工作日、休息日、节假日和调休
 
 以下函数用于判断指定日期是否需要上班，考虑中国法定节假日和调休安排。
 
 #### `is_workday(d=None) -> bool`
 
 判断指定日期是否需要上班（考虑节假日和调休）。
 
 - **工作日**包括：正常的周一至周五 + 调休工作日（周末但要上班）
 - **非工作日**包括：正常的周末 + 法定节假日
 
 ```python
 from weekday import is_workday
 
 # 普通工作日
 is_workday("2024-01-02")  # True（周二）
 
 # 普通周末
 is_workday("2024-01-06")  # False（周六）
 
 # 节假日（放假）
 is_workday("2024-01-01")  # False（元旦）
 is_workday("2024-02-10")  # False（春节，虽然是周六）
 
 # 调休工作日（周末但要上班）
 is_workday("2024-02-04")  # True（周日，春节调休）
 is_workday("2024-05-11")  # True（周六，劳动节调休）
 ```
 
 ---
 
 #### `is_restday(d=None) -> bool`
 
 判断指定日期是否休息（考虑节假日和调休）。
 
 - **休息日**包括：正常的周末 + 法定节假日
 - **非休息日**包括：正常的工作日 + 调休工作日
 
 ```python
 from weekday import is_restday
 
 is_restday("2024-01-06")  # True（周六）
 is_restday("2024-02-10")  # True（春节假期）
 is_restday("2024-02-04")  # False（周日，但是调休工作日）
 ```
 
 ---
 
 #### `is_holiday(d=None) -> bool`
 
 判断指定日期是否为法定节假日。
 
 ```python
 from weekday import is_holiday
 
 is_holiday("2024-01-01")  # True（元旦）
 is_holiday("2024-02-10")  # True（春节）
 is_holiday("2024-01-06")  # False（普通周六，不是节假日）
 ```
 
 ---
 
 #### `is_adjustment_workday(d=None) -> bool`
 
 判断指定日期是否为调休工作日（周末但要上班）。
 
 ```python
 from weekday import is_adjustment_workday
 
 is_adjustment_workday("2024-02-04")  # True（周日，春节调休）
 is_adjustment_workday("2024-05-11")  # True（周六，劳动节调休）
 is_adjustment_workday("2024-01-06")  # False（普通周末）
 ```
 
 ---
 
 #### `get_day_type(d=None) -> DayType`
 
 获取指定日期的详细类型。
 
 **返回值：** `DayType` 枚举值：
 - `DayType.WORKDAY` - 正常工作日
 - `DayType.WEEKEND` - 正常周末
 - `DayType.HOLIDAY` - 法定节假日
 - `DayType.ADJUSTMENT_WORKDAY` - 调休工作日
 
 ```python
 from weekday import get_day_type, DayType
 
 get_day_type("2024-01-02")  # DayType.WORKDAY
 get_day_type("2024-01-06")  # DayType.WEEKEND
 get_day_type("2024-01-01")  # DayType.HOLIDAY（元旦）
 get_day_type("2024-02-04")  # DayType.ADJUSTMENT_WORKDAY（春节调休）
 ```
 
 ---
 
 #### `get_holiday_name(d=None) -> str | None`
 
 获取指定日期对应的节假日名称。
 
 **返回值：** `str` 或 `None` - 节假日名称，如果不是节假日返回 `None`。
 
 ```python
 from weekday import get_holiday_name
 
 get_holiday_name("2024-01-01")  # '元旦'
 get_holiday_name("2024-02-10")  # '春节'
 get_holiday_name("2024-10-01")  # '国庆节'
 get_holiday_name("2024-01-02")  # None（普通工作日）
 ```
 
 ---
 
 #### `get_adjustment_name(d=None) -> str | None`
 
 获取指定日期对应的调休名称。
 
 **返回值：** `str` 或 `None` - 调休名称（如"春节调休"），如果不是调休工作日返回 `None`。
 
 ```python
 from weekday import get_adjustment_name
 
 get_adjustment_name("2024-02-04")  # '春节调休'
 get_adjustment_name("2024-05-11")  # '劳动节调休'
 get_adjustment_name("2024-01-02")  # None（普通工作日）
 ```
 
 ---
 
 ### 已支持的节假日年份
 
 目前内置了以下年份的中国法定节假日数据：
 
 - **2024 年**：元旦、春节、清明节、劳动节、端午节、中秋节、国庆节
 - **2025 年**：元旦、春节、清明节、劳动节、端午节、国庆节
 
 ### 添加其他年份的节假日数据
 
 中国的节假日安排每年年底由国务院发布，如需添加其他年份的数据，可以使用以下函数：
 
 #### `register_holidays(year, holidays, adjustments=None)`
 
 注册指定年份的节假日和调休数据。
 
 ```python
 from weekday import register_holidays
 
 # 注册 2026 年国庆节
 register_holidays(
     2026,
     holidays={
         "2026-10-01": "国庆节",
         "2026-10-02": "国庆节",
         "2026-10-03": "国庆节",
         "2026-10-04": "国庆节",
         "2026-10-05": "国庆节",
         "2026-10-06": "国庆节",
         "2026-10-07": "国庆节",
     },
     adjustments={
         "2026-09-27": "国庆节调休",  # 周日上班
         "2026-10-10": "国庆节调休",  # 周六上班
     }
 )
 
 # 现在可以使用 2026 年的节假日判断了
 is_holiday("2026-10-01")  # True
 is_workday("2026-09-27")  # True（调休工作日）
 ```
 
 其中的`holidays`是放真正放假的日期，`adjustments`是放周末但要上班的日子。
 
 ---
 
 #### `register_holiday_range(start_date, end_date, name, adjustments=None, adjustment_name=None)`
 
 注册一个连续的节假日区间，更方便。
 
 ```python
 from weekday import register_holiday_range
 
 # 注册 2026 年国庆节 10月1日-7日
 register_holiday_range(
     "2026-10-01", "2026-10-07",
     "国庆节",
     adjustments=["2026-09-27", "2026-10-10"],
     adjustment_name="国庆节调休"
 )
 ```
 
 ---
 
 #### `get_supported_years() -> list`
 
 获取已支持节假日数据的年份列表。
 
 ```python
 from weekday import get_supported_years
 
 get_supported_years()  # [2024, 2025, 2026]
 ```
 
 ---
 
 #### `has_year_data(year) -> bool`
 
 检查指定年份是否有节假日数据。
 
 ```python
 from weekday import has_year_data
 
 has_year_data(2024)  # True
 has_year_data(2030)  # False
 ```
 
 ---
 
 ## 日期格式支持
 
 所有接受日期参数的函数都支持以下格式：
 
 - **字符串**：`"YYYY-MM-DD"` 格式，如 `"2024-01-01"`
 - **date 对象**：`datetime.date(2024, 1, 1)`
 - **datetime 对象**：`datetime.datetime(2024, 1, 1, 12, 30)`
 - **不传参**：默认使用今天的日期
 
 ## 星期值说明
 
 本库使用 0-6 表示星期几，遵循 ISO 标准：
 
 | 值 | 中文 | 英文 |
 |----|------|------|
 | 0 | 星期一 | Monday |
 | 1 | 星期二 | Tuesday |
 | 2 | 星期三 | Wednesday |
 | 3 | 星期四 | Thursday |
 | 4 | 星期五 | Friday |
 | 5 | 星期六 | Saturday |
 | 6 | 星期日 | Sunday |
 
 ## 许可证
 
 MIT License
 

