Python 库手册：calendar 日历模块

calendar 是 Python 的标准库模块之一，用于处理历法计算、生成日历表、判断闰年等操作。它封装了对阳历（格里历）的常见操作，便于开发中生成结构化日历、查询日期分布等。

常见应用场景：

（1）打印整月或整年的日历（控制排版格式）。

（2）查询某天是星期几。

（3）判断某年是否为闰年。

（4）获取某月有多少天。

（5）生成嵌套结构用于 GUI 日历、数据标注日历等.

◆ ◆ ◆

核心概念

1、Python 中的星期起始日默认为星期一（0）。

2、calendar 支持自定义星期起始日（如设置为星期天）。

3、模块中的 TextCalendar 和 HTMLCalendar 类提供了两种输出格式（纯文本与 HTML）。

4、所有月份按数字（1 ~ 12）处理，星期也为数字（0 ~ 6）。

◆ ◆ ◆

应用举例

例 1： 打印指定年份的年历（文本格式）

import calendar

print(calendar.calendar(2025))

例 2：打印指定月份的月历

import calendar

print(calendar.month(2025, 7))

例 3：获取一个月的所有星期分布（用于数据展示）

import calendar

cal = calendar.Calendar(firstweekday=0)  # 星期一为起始
for week in cal.monthdayscalendar(2025, 7):
    print(week)
    
# 每周是一个列表，0 表示该位置不是当月的有效日期（用于对齐）

例 4：判断闰年与获取每月天数

import calendar

print("2024 是闰年吗？", calendar.isleap(2024))  # True
print("2025 年 7 月有几天？", calendar.monthrange(2025, 7)[1])  # 31

例 5：查询某天是星期几

import calendar

# 返回值范围 0~6，表示星期一到星期日
day_of_week = calendar.weekday(2025, 7, 15)
print("2025-07-15 是星期：", day_of_week)  # 输出 1，即星期二

◆ ◆ ◆

常用函数速览

calendar.calendar(year, w=2, l=1, c=6)

返回整年日历的多行字符串表示。

参数：

year：年份

w：每个日期字段宽度

l：每周所占行数

c：每个月之间的间距

返回：字符串（适合打印）

calendar.firstweekday()

返回当前设置的星期起始日。默认 0 表示星期一。

calendar.isleap(year)

判断给定年份是否为闰年。

参数：year 整数年份

返回：布尔值（True 或 False）

calendar.leapdays(y1, y2)

计算从年份 y1（含）到 y2（不含）之间的闰年数。

calendar.month(year, month, w=2, l=1)

返回指定月份的日历字符串表示。

参数：

year：年份

month：月份

w：日期宽度

l：行距

返回：字符串（适合打印）

calendar.monthcalendar(year, month)

返回一个嵌套列表，表示该月日历的每周安排。

每周是一个包含 7 个元素的列表，0 表示该位置无效（不是该月的日期）。

返回：List[List[int]]

calendar.monthrange(year, month)

返回该月的起始星期与天数。

返回： (weekday, num_days)，比如：(2, 31) 表示该月从星期三开始，有 31 天

calendar.setfirstweekday(weekday)

设置星期的起始日（0=周一，6=周日）。

参数：weekday 为整数

返回：None

calendar.weekday(year, month, day)

返回指定日期是星期几（0=周一，6=周日）。

calendar.TextCalendar

该类用于以纯文本格式生成日历，可自定义起始星期，适合在命令行界面、日志、控制台等环境展示。

构造方法：

calendar.TextCalendar(firstweekday=0)
# 参数 firstweekday：设置每周的起始日（0 表示星期一，6 表示星期日）
# 默认值为 0，即以周一开始

常用方法：

（1）formatmonth(year, month, w=2, l=1)

返回指定年月的文本格式月历字符串。

from calendar import TextCalendar
tc = TextCalendar()
print(tc.formatmonth(2025, 7))

（2）formatyear(year, w=2, l=1, c=6, m=3)

返回整年文本格式日历，按列排布。

（3）prmonth(year, month)

直接打印某月日历（等同于 print(formatmonth(...))）。

（4）pryear(year)

直接打印整年日历。

calendar.HTMLCalendar

该类用于以 HTML 表格格式生成日历，适用于 Web 前端展示、日报系统、数据标注平台等。

构造方法：

calendar.HTMLCalendar(firstweekday=0)

与 TextCalendar 相同，设置每周起始日。

常用方法：

（1）formatmonth(year, month)

返回 HTML 表格代码，表示指定月历。

from calendar import HTMLCalendar

hc = HTMLCalendar()
html_code = hc.formatmonth(2025, 7)
print(html_code)

（2）formatyear(year, width=3)

返回整年 HTML 日历代码，width 表示每行显示几个月（默认 3）。

（3）子类可重写的方法（高级定制）

你可以继承 HTMLCalendar 类，重写以下方法以定制样式或内容：

formatday(day, weekday)

formatweek(theweek)

formatmonthname(year, month, withyear=True)

这在自定义工作日高亮、节假日标记等方面非常有用。

◆ ◆ ◆

使用建议

1、日历数据展示推荐用 monthcalendar() 或 Calendar().monthdayscalendar() 输出结构化信息。

2、打印格式可用 calendar.month() 或 TextCalendar 控制样式。

3、若需要国际化日历、支持节假日，建议结合 datetime 或第三方库 holidays。

“点赞有美意，赞赏是鼓励”