calendar --- 通用日历相关函数¶
源代码： Lib/calendar.py
该模块可以让你像 Unix cal 程序一样输出日历，并提供了其他与日历相关的实用函数。默认情况下，这些日历以星期一为一周的第一天，星期日为一周的最后一天（欧洲惯例）。可以使用 setfirstweekday() 将一周的第一天设置为星期日（6）或任何其他工作日。指定日期的形参以整数形式给出。对于相关的功能，另请参阅 datetime 和 time 模块。
该模块中定义的函数和类使用一个理想化的日历，即当前格列高利历在两个方向上无限延伸。这与 Dershowitz 和 Reingold 的著作《Calendrical Calculations》中“proleptic Gregorian”日历的定义相匹配，在该书中，它是所有计算的基础日历。零和负数年份的解释遵循 ISO 8601 标准。0 年是公元前 1 年，-1 年是公元前 2 年，以此类推。
- class calendar.Calendar(firstweekday=0)¶
创建一个
Calendar对象。firstweekday 是一个指定一周第一天的整数。MONDAY是0（默认值），SUNDAY是6。一个
Calendar对象提供了几种可用于准备日历数据以进行格式化的方法。这个类本身不做任何格式化。这是子类的工作。Calendar实例拥有以下方法和属性：- firstweekday¶
作为整数的一周的第一天 (0–6)。
此属性也可以分别使用
setfirstweekday()和getfirstweekday()来设置和读取。
- getfirstweekday()¶
返回当前一周第一天的
int值 (0–6)。与读取
firstweekday属性相同。
- setfirstweekday(firstweekday)¶
将一周的第一天设置为以
int(0–6) 形式传入的 firstweekday。与设置
firstweekday属性相同。
- iterweekdays()¶
返回一周内将要使用的星期几数字的迭代器。迭代器的第一个值将与
firstweekday属性的值相同。
- itermonthdates(year, month)¶
返回 year 年 month 月（1-12）的迭代器。这个迭代器将返回该月的所有日期（作为
datetime.date对象），以及该月开始前或结束后为构成完整一周所需的所有日期。
- itermonthdays(year, month)¶
返回 year 年 month 月的迭代器，类似于
itermonthdates()，但不受datetime.date范围的限制。返回的日期将只是月份中的天数。对于指定月份之外的日期，天数为0。
- itermonthdays2(year, month)¶
返回 year 年 month 月的迭代器，类似于
itermonthdates()，但不受datetime.date范围的限制。返回的日期将是由月份中的天数和星期几数字组成的元组。
- itermonthdays3(year, month)¶
返回 year 年 month 月的迭代器，类似于
itermonthdates()，但不受datetime.date范围的限制。返回的日期将是由年份、月份和月份中的天数组成的元组。在 3.7 版本加入。
- itermonthdays4(year, month)¶
返回 year 年 month 月的迭代器，类似于
itermonthdates()，但不受datetime.date范围的限制。返回的日期将是由年份、月份、月份中的天数和星期几数字组成的元组。在 3.7 版本加入。
- monthdatescalendar(year, month)¶
返回 year 年 month 月的周列表，这些周都是完整的。周是由七个
datetime.date对象组成的列表。
- monthdays2calendar(year, month)¶
返回 year 年 month 月的周列表，这些周都是完整的。周是由七个日期和星期几组成的元组列表。
- monthdayscalendar(year, month)¶
返回 year 年 month 月的周列表，这些周都是完整的。周是由七个日期数字组成的列表。
- yeardatescalendar(year, width=3)¶
返回指定年份的数据，以便进行格式化。返回值是一个月行的列表。每个月行最多包含 width 个月（默认为 3）。每个月包含 4 到 6 周，每周包含 1-7 天。天是
datetime.date对象。
- yeardays2calendar(year, width=3)¶
返回指定年份的数据，以便进行格式化（类似于
yeardatescalendar()）。周列表中的条目是由日期和星期几组成的元组。本月之外的日期为零。
- yeardayscalendar(year, width=3)¶
返回指定年份的数据，以便进行格式化（类似于
yeardatescalendar()）。周列表中的条目是日期。本月之外的日期为零。
- class calendar.TextCalendar(firstweekday=0)¶
此类可用于生成纯文本日历。
TextCalendar实例具有以下方法：- formatday(theday, weekday, width)¶
返回一个表示单个日期的字符串，其格式化宽度为给定的 width。如果 theday 为
0，则返回一个指定宽度的空格字符串，表示一个空日期。weekday 参数未使用。
- formatweek(theweek, w=0)¶
返回一个不带换行符的单周字符串。如果提供了 w，它指定了日期列的宽度，日期列会居中显示。这取决于构造函数中指定的或通过
setfirstweekday()方法设置的第一天。
- formatweekday(weekday, width)¶
返回一个表示单个工作日名称的字符串，其格式化宽度为指定的 width。weekday 参数是一个表示星期几的整数，其中
0是星期一，6是星期日。
- formatweekheader(width)¶
返回一个包含星期几名称的标题行的字符串，每列的格式化宽度为给定的 width。名称取决于区域设置，并会填充到指定的宽度。
- formatmonth(theyear, themonth, w=0, l=0)¶
以多行字符串的形式返回一个月的日历。如果提供了 w，它指定了日期列的宽度，日期列会居中显示。如果给定了 l，它指定了每周将使用的行数。这取决于构造函数中指定的或通过
setfirstweekday()方法设置的第一天。
- formatmonthname(theyear, themonth, width=0, withyear=True)¶
返回一个表示月份名称的字符串，该字符串在指定的 width 内居中。如果 withyear 为
True，则在输出中包含年份。theyear 和 themonth 参数分别指定了要格式化的名称的年份和月份。
- prmonth(theyear, themonth, w=0, l=0)¶
打印由
formatmonth()返回的一个月的日历。
- formatyear(theyear, w=2, l=1, c=6, m=3)¶
以多行字符串的形式返回一个 m 列的全年日历。可选参数 w、l 和 c 分别用于日期列宽、每周行数和月份列之间的空格数。这取决于构造函数中指定的或通过
setfirstweekday()方法设置的第一天。可以生成日历的最早年份取决于平台。
- pryear(theyear, w=2, l=1, c=6, m=3)¶
打印由
formatyear()返回的全年日历。
- class calendar.HTMLCalendar(firstweekday=0)¶
此类可用于生成 HTML 日历。
HTMLCalendar实例具有以下方法：- formatmonth(theyear, themonth, withyear=True)¶
以 HTML 表格的形式返回一个月的日历。如果 withyear 为真，则年份将包含在标题中，否则只使用月份名称。
- formatyear(theyear, width=3)¶
以 HTML 表格的形式返回一年的日历。width（默认为 3）指定每行的月份数。
- formatyearpage(theyear, width=3, css='calendar.css', encoding=None)¶
以完整的 HTML 页面形式返回一年的日历。width（默认为 3）指定每行的月份数。css 是要使用的级联样式表的名称。如果不需要使用样式表，可以传递
None。encoding 指定用于输出的编码（默认为系统默认编码）。
- formatmonthname(theyear, themonth, withyear=True)¶
以 HTML 表格行的形式返回月份名称。如果 withyear 为真，则年份将包含在行中，否则只使用月份名称。
HTMLCalendar具有以下属性，您可以覆盖这些属性来自定义日历使用的 CSS 类：- cssclasses¶
用于每个工作日的 CSS 类列表。默认类列表为：
cssclasses = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
可以为每天添加更多样式：
cssclasses = ["mon text-bold", "tue", "wed", "thu", "fri", "sat", "sun red"]
请注意，此列表的长度必须为七项。
- cssclass_noday¶
上一个月或下一个月中出现的工作日的 CSS 类。
在 3.7 版本加入。
- cssclasses_weekday_head¶
用于标题行中工作日名称的 CSS 类列表。默认值与
cssclasses相同。在 3.7 版本加入。
- cssclass_month_head¶
月份头部的 CSS 类（由
formatmonthname()使用）。默认值为"month"。在 3.7 版本加入。
- cssclass_month¶
整个月表格的 CSS 类（由
formatmonth()使用）。默认值为"month"。在 3.7 版本加入。
- cssclass_year¶
整个年度表格的 CSS 类（由
formatyear()使用）。默认值为"year"。在 3.7 版本加入。
- cssclass_year_head¶
全年表格头部的 CSS 类（由
formatyear()使用）。默认值为"year"。在 3.7 版本加入。
请注意，尽管上述类属性的命名是单数形式（例如
cssclass_month、cssclass_noday），但可以将单个 CSS 类替换为以空格分隔的 CSS 类列表，例如："text-bold text-red"以下是一个如何自定义
HTMLCalendar的示例：class CustomHTMLCal(calendar.HTMLCalendar): cssclasses = [style + " text-nowrap" for style in calendar.HTMLCalendar.cssclasses] cssclass_month_head = "text-center month-head" cssclass_month = "text-center month" cssclass_year = "text-italic lead"
- class calendar.LocaleTextCalendar(firstweekday=0, locale=None)¶
这个
TextCalendar的子类可以在构造函数中传递一个区域设置名称，并会返回指定区域设置的月份和星期几名称。
- class calendar.LocaleHTMLCalendar(firstweekday=0, locale=None)¶
这个
HTMLCalendar的子类可以在构造函数中传递一个区域设置名称，并会返回指定区域设置的月份和星期几名称。
备注
这两个类的构造函数、formatweekday() 和 formatmonthname() 方法会临时将 LC_TIME 区域设置更改为给定的 locale。由于当前区域设置是进程范围的设置，它们不是线程安全的。
对于简单的文本日历，本模块提供以下函数。
- calendar.setfirstweekday(weekday)¶
设置每周开始的星期（
0为星期一，6为星期日）。为方便起见，提供了MONDAY、TUESDAY、WEDNESDAY、THURSDAY、FRIDAY、SATURDAY和SUNDAY的值。例如，要将每周的第一天设置为星期日：import calendar calendar.setfirstweekday(calendar.SUNDAY)
- calendar.firstweekday()¶
返回每周开始日的当前设置。
- calendar.leapdays(y1, y2)¶
返回从 y1 到 y2（不含）范围内的闰年数，其中 y1 和 y2 是年份。
该函数适用于跨越世纪变化的范围。
- calendar.weekday(year, month, day)¶
返回 year（
1970–…）、month（1–12）、day（1–31）的星期几（0为星期一）。
- calendar.weekheader(n)¶
返回一个包含缩写星期名称的标题。n 指定了一个星期的字符宽度。
- calendar.monthrange(year, month)¶
对于指定的 year 和 month，返回该月第一天的星期几和该月的天数。
- calendar.monthcalendar(year, month)¶
返回一个表示月份日历的矩阵。每一行代表一周；月份之外的日期由零表示。除非由
setfirstweekday()设置，否则每周从星期一开始。
- calendar.month(theyear, themonth, w=0, l=0)¶
使用
TextCalendar类的formatmonth()方法，以多行字符串的形式返回一个月的日历。
- calendar.prcal(year, w=0, l=0, c=6, m=3)¶
打印由
calendar()返回的全年日历。
- calendar.calendar(year, w=2, l=1, c=6, m=3)¶
使用
TextCalendar类的formatyear()方法，以多行字符串的形式返回一个3列的全年日历。
- calendar.timegm(tuple)¶
一个不相关但很方便的函数，它接受一个时间元组（例如由
time模块中的gmtime()函数返回的时间元组），并返回相应的 Unix 时间戳值，假设纪元为 1970 年，并使用 POSIX 编码。实际上，time.gmtime()和timegm()互为逆函数。
calendar 模块导出以下数据属性：
- calendar.day_name¶
一个表示当前区域设置中一周中各天的序列，其中星期一为第 0 天。
>>> import calendar >>> list(calendar.day_name) ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']
- calendar.day_abbr¶
一个表示当前区域设置中一周中各天缩写的序列，其中星期一为第 0 天。
>>> import calendar >>> list(calendar.day_abbr) ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
- calendar.MONDAY¶
- calendar.TUESDAY¶
- calendar.WEDNESDAY¶
- calendar.THURSDAY¶
- calendar.FRIDAY¶
- calendar.SATURDAY¶
- calendar.SUNDAY¶
一周中各天的别名，其中
MONDAY是0，SUNDAY是6。3.12 新版功能.
- calendar.month_name¶
一个表示当前区域设置中一年中各个月份的序列。这遵循一月为第 1 个月的正常惯例，因此其长度为 13，并且
month_name[0]是空字符串。>>> import calendar >>> list(calendar.month_name) ['', 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
- calendar.month_abbr¶
一个表示当前区域设置中一年中各个月份缩写的序列。这遵循一月为第 1 个月的正常惯例，因此其长度为 13，并且
month_abbr[0]是空字符串。>>> import calendar >>> list(calendar.month_abbr) ['', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
- calendar.JANUARY¶
- calendar.FEBRUARY¶
- calendar.MARCH¶
- calendar.APRIL¶
- calendar.MAY¶
- calendar.JUNE¶
- calendar.JULY¶
- calendar.AUGUST¶
- calendar.SEPTEMBER¶
- calendar.OCTOBER¶
- calendar.NOVEMBER¶
- calendar.DECEMBER¶
一年中各个月份的别名，其中
JANUARY是1，DECEMBER是12。3.12 新版功能.
calendar 模块定义了以下异常：
- exception calendar.IllegalMonthError(month)¶
ValueError的子类，当给定的月份编号超出 1-12（含）范围时引发。- month¶
无效的月份编号。
- exception calendar.IllegalWeekdayError(weekday)¶
ValueError的子类，当给定的星期几编号超出 0-6（含）范围时引发。- weekday¶
无效的星期几编号。
命令行用法¶
在 2.5 版本中新增。
calendar 模块可以作为脚本从命令行执行，以交互方式打印日历。
python -m calendar [-h] [-L LOCALE] [-e ENCODING] [-t {text,html}]
[-w WIDTH] [-l LINES] [-s SPACING] [-m MONTHS] [-c CSS]
[-f FIRST_WEEKDAY] [year] [month]
例如，要打印 2000 年的日历：
$ python -m calendar 2000
2000
January February March
Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1 2 1 2 3 4 5 6 1 2 3 4 5
3 4 5 6 7 8 9 7 8 9 10 11 12 13 6 7 8 9 10 11 12
10 11 12 13 14 15 16 14 15 16 17 18 19 20 13 14 15 16 17 18 19
17 18 19 20 21 22 23 21 22 23 24 25 26 27 20 21 22 23 24 25 26
24 25 26 27 28 29 30 28 29 27 28 29 30 31
31
April May June
Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1 2 1 2 3 4 5 6 7 1 2 3 4
3 4 5 6 7 8 9 8 9 10 11 12 13 14 5 6 7 8 9 10 11
10 11 12 13 14 15 16 15 16 17 18 19 20 21 12 13 14 15 16 17 18
17 18 19 20 21 22 23 22 23 24 25 26 27 28 19 20 21 22 23 24 25
24 25 26 27 28 29 30 29 30 31 26 27 28 29 30
July August September
Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1 2 1 2 3 4 5 6 1 2 3
3 4 5 6 7 8 9 7 8 9 10 11 12 13 4 5 6 7 8 9 10
10 11 12 13 14 15 16 14 15 16 17 18 19 20 11 12 13 14 15 16 17
17 18 19 20 21 22 23 21 22 23 24 25 26 27 18 19 20 21 22 23 24
24 25 26 27 28 29 30 28 29 30 31 25 26 27 28 29 30
31
October November December
Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1 1 2 3 4 5 1 2 3
2 3 4 5 6 7 8 6 7 8 9 10 11 12 4 5 6 7 8 9 10
9 10 11 12 13 14 15 13 14 15 16 17 18 19 11 12 13 14 15 16 17
16 17 18 19 20 21 22 20 21 22 23 24 25 26 18 19 20 21 22 23 24
23 24 25 26 27 28 29 27 28 29 30 25 26 27 28 29 30 31
30 31
接受以下选项
- --help, -h¶
显示帮助信息并退出。
- --locale LOCALE, -L LOCALE¶
用于月份和星期几名称的区域设置。默认为英语。
- --encoding ENCODING, -e ENCODING¶
用于输出的编码。如果设置了
--locale，则必须使用--encoding。
- --type {text,html}, -t {text,html}¶
将日历打印到终端，可以是文本形式或 HTML 文档形式。
- --first-weekday FIRST_WEEKDAY, -f FIRST_WEEKDAY¶
每周开始的星期几。必须是 0（星期一）到 6（星期日）之间的数字。默认为 0。
在 3.13 版本加入。
- year¶
要打印日历的年份。默认为当前年份。
文本模式选项
- --width WIDTH, -w WIDTH¶
日期列在终端列中的宽度。日期在列中居中打印。任何小于 2 的值都将被忽略。默认为 2。
- --lines LINES, -l LINES¶
每周在终端行中的行数。日期顶部对齐打印。任何小于 1 的值都将被忽略。默认为 1。
- --spacing SPACING, -s SPACING¶
月份之间的列间距。任何小于 2 的值都将被忽略。默认为 6。
- --months MONTHS, -m MONTHS¶
每行打印的月份数。默认为 3。
在 3.14 版本发生变更: 默认情况下，今天的日期会以颜色高亮显示，并可以通过环境变量进行控制。
HTML 模式选项
- --css CSS, -c CSS¶
用于日历的 CSS 样式表的路径。此路径必须是相对于生成的 HTML 的相对路径，或者是绝对的 HTTP 或
file:///URL。