说到 Python 里处理日期和时间，大多数人第一时间想到的都是datetime和time这两个模块。但有一个模块往往被低估了，它就是calendar。这个模块从 Python 早期版本就存在，历经多年迭代依然稳如磐石，却很少有人真正把它用到位。今天我们就好好聊聊这个“老朋友”。
它到底是什么
calendar是 Python 标准库中专门处理日历相关逻辑的模块。它跟datetime最大的区别在于：datetime关注的是“某个时刻”或“某个时间点”，而calendar关注的是“一段日期范围”的规律——比如某个月有多少天，某个月份的星期分布是怎样的，或者某个日期是星期几。
打个比方：如果你要安排一场发生在“每个月第一个星期一”的会议，用datetime逐个计算就很麻烦，但用calendar就能直接定位到这种规律性的日期。它其实是一套基于格里高利历的日期规则引擎，只是大多数人只知道用它打印日历。
它能做什么
calendar的核心能力可以分为几个大类：
第一类是日期推算——比如计算某个月的天数、确定某个日期是星期几、判断闰年。这些功能表面上看datetime也能做，但calendar做起来更直接。比如calendar.isleap(2024)直接返回True，而用datetime就要绕个弯去处理2月29日。
第二类是日历数据的结构化——这是calendar最独特的价值所在。calendar.monthcalendar(2024, 3)返回的是一个二维列表，每一行代表一周，每列的值为0表示这一天不属于本月。这种数据结构非常适合做排班系统、考勤统计、课程表的底层计算。
第三类是日历的可视化输出——calendar.TextCalendar和calendar.HTMLCalendar可以直接生成文本或HTML格式的日历。虽然实际项目里很少直接用这个做前端展示，但用来做命令行工具或者快速生成报表视图还是挺顺手的。
第四类是日期迭代器——calendar.Calendar对象提供了itermonthdates、itermonthdays等迭代方法，能按月逐日遍历。这在写时间序列分析或者生成月度报表时会省下不少代码量。
怎么使用
先看最基础的东西。判断闰年、获取月份天数，这些属于常规操作：
importcalendarprint(calendar.isleap(2024))# Trueprint(calendar.monthrange(2024,2))# (3, 29) 第一天是星期四，有29天monthrange返回的元组很实用：第一个值是月份第一天是星期几（0代表周一），第二个值是当月总天数。这个函数在写日期计算逻辑时是个很趁手的工具。
再看一个实际点的例子。假设要找出某个月份里所有的工作日（周一至周五）：
defget_weekdays_in_month(year,month):cal=calendar.Calendar()# itermonthdays返回的是日期数字，非本月的天返回0days=[dayfordayincal.itermonthdays(year,month)ifday!=0]weekdays=[]fordayindays:weekday=calendar.weekday(year,month,day)ifweekday<5:# 周一到周五weekdays.append(day)returnweekdays这个例子结合了Calendar的迭代器和weekday函数。其实也可以用itermonthdays2，它直接返回(日期, 星期数)的元组，代码会更简洁。
再说说更深入的东西。calendar其实支持定制每周的第一天。通过setfirstweekday或者实例化时传入参数，可以改变一周从周一开始还是从周日开始。这个细节在实际开发中经常踩坑——比如做国际化的项目，不同地区对一周起始的定义不同，而calendar在处理这种差异时特别自然。
最佳实践
第一，别把calendar当datetime用。有些新手用calendar的timegm函数来转换时间戳，其实datetime有更优雅的方式。calendar的优势在于处理周期性的日期规律，而不是做精确的时间计算。
第二，合理使用Calendar子类。TextCalendar和HTMLCalendar提供了格式化输出能力，但真正有价值的是LocaleTextCalendar和locale模块的结合。如果你需要做本地化的日历展示（比如显示中文的星期几），用locale.setlocale配合LocaleTextCalendar会比手动映射中文更可靠。
第三，善用monthdatescalendar方法。这个方法返回的是本月所有周的列表，每行是7个日期对象。在处理课表、演出排期这类按周切分的需求时，它比手动计算边界要简洁得多。
第四，注意性能。calendar的迭代器方法在处理大跨度时间范围时会生成很多对象。如果你只需要判断某个月有多少个星期五，用monthcalendar提取第一列的数据做简单数学推算，比遍历每一天要快很多。比如要算某个月有几个星期五，可以这样：
defcount_fridays(year,month):weeks=calendar.monthcalendar(year,month)returnsum(1forweekinweeksifweek[4]!=0)# 假设一周从周一开始这个思路利用了月份日历矩阵中每列固定是一个星期几的规律，比用条件判断循环快一个数量级。
和同类技术对比
跟calendar最常被放在一起比较的是dateutil的rrule模块和pandas的日期处理功能。
dateutil.rrule擅长处理复杂的周期规则——比如“每月的第二个星期二”这种不规则重复模式。而calendar的优势在于处理静态的日历结构：给定一个月份，它能立刻告诉你日历矩阵是什么样子的。如果你的需求是“计算未来两年的所有周五”，用rrule更合适；但你的需求是“生成2024年3月的工作日日历表”，calendar的monthcalendar效率更高。
pandas的date_range和calendar的迭代器有一部分功能重叠。pandas在大规模时间序列处理和灵活的偏移量计算上完胜，但它需要额外的依赖。如果你的项目已经用了pandas，处理日历逻辑时直接沿用pandas的数据结构会更一致；反之，为了一个简单的日历计算引入pandas就不太划算——calendar作为标准库成员，零依赖且性能也不差。
还有一个很容易被忽略的点：calendar的底层实现完全基于算法计算，不依赖任何外部数据文件。而某些流行的日历库（比如workalendar）需要加载节假日数据文件。如果你的应用场景只是计算日期规律、不涉及法定假日的判断，calendar提供的工具已经完全够用了。
最后想说，很多开发者在项目中几乎不用calendar，遇到日期间隔问题就用datetime加timedelta硬算。其实换一个角度想，calendar提供的是“从月份看日期”的视角，而datetime是“从日期看时间”的视角。当你需要从月份或年份的尺度来观察日期分布时，calendar往往能给出更简洁的解法。
