weekday

一个轻量级的 Python 库，用于获取当天或指定日期是星期几。支持中英文输出，提供丰富的判断函数，支持中国法定节假日和调休判断。

安装

pip install weekday

快速开始

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 表示星期日。

from weekday import today

today()  # 例如：5（表示星期六）

today_name(lang="zh") -> str

获取今天是星期几的名称。

参数：

• lang (str): 语言，"zh" 返回中文，"en" 返回英文。默认 "zh"。

返回值： str - 星期名称字符串。

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: 传入不支持的类型时抛出。

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 - 星期名称字符串。

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

判断指定日期是否为工作日（周一至周五）。

from weekday import is_weekday

is_weekday("2024-01-01")  # True（星期一）
is_weekday("2024-01-06")  # False（星期六）
is_weekday()              # 判断今天是否为工作日

is_weekend(d=None) -> bool

判断指定日期是否为周末（周六或周日）。

from weekday import is_weekend

is_weekend("2024-01-06")  # True（星期六）
is_weekend("2024-01-07")  # True（星期日）
is_weekend("2024-01-01")  # False（星期一）

具体星期判断函数

以下函数用于判断指定日期是否为特定的星期几：

参数：

• d (date | datetime | str | None): 日期，格式同 weekday() 函数。

返回值： bool - 是指定星期几返回 True，否则返回 False。

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

判断指定日期是否需要上班（考虑节假日和调休）。

• 工作日包括：正常的周一至周五 + 调休工作日（周末但要上班）
• 非工作日包括：正常的周末 + 法定节假日

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

判断指定日期是否休息（考虑节假日和调休）。

• 休息日包括：正常的周末 + 法定节假日
• 非休息日包括：正常的工作日 + 调休工作日

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

判断指定日期是否为法定节假日。

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

判断指定日期是否为调休工作日（周末但要上班）。

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 - 调休工作日

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。

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。

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)

注册指定年份的节假日和调休数据。

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)

注册一个连续的节假日区间，更方便。

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

获取已支持节假日数据的年份列表。

from weekday import get_supported_years

get_supported_years()  # [2024, 2025, 2026]

has_year_data(year) -> bool

检查指定年份是否有节假日数据。

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 标准：

许可证

MIT License