calendar — 通用日历相关函数

源代码: Lib/calendar.py


此模块允许您输出类似 Unix cal 程序的日历,并提供与日历相关的其他有用函数。默认情况下,这些日历将星期一作为一周的第一天,星期日作为最后一天(欧洲惯例)。使用 setfirstweekday() 将一周的第一天设置为星期日 (6) 或任何其他工作日。指定日期的参数以整数形式给出。有关相关功能,另请参阅 datetimetime 模块。

此模块中定义的函数和类使用理想化的日历,即当前格里高利历在两个方向上无限延伸。这与 Dershowitz 和 Reingold 的著作《Calendrical Calculations》中“前摄格里高利”日历的定义相匹配,其中它是所有计算的基本日历。零年和负年按照 ISO 8601 标准的规定进行解释。0 年是公元前 1 年,-1 年是公元前 2 年,依此类推。

class calendar.Calendar(firstweekday=0)

创建一个 Calendar 对象。firstweekday 是一个整数,指定一周的第一天。MONDAY0 (默认值),SUNDAY6

Calendar 对象提供几个可用于准备格式化日历数据的方法。这个类本身不做任何格式化。这是子类的工作。

Calendar 实例具有以下方法

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 实例具有以下方法

formatweek(theweek, w=0)

以不带换行符的字符串形式返回单个星期。如果提供了w,则指定日期列的宽度,这些列是居中的。取决于构造函数中指定的或由 setfirstweekday() 方法设置的第一天是星期几。

formatmonth(theyear, themonth, w=0, l=0)

以多行字符串形式返回一个月的日历。如果提供了w,则指定日期列的宽度,这些列是居中的。如果提供了l,则指定每周将使用的行数。取决于构造函数中指定的或由 setfirstweekday() 方法设置的第一天是星期几。

prmonth(theyear, themonth, w=0, l=0)

打印由 formatmonth() 返回的月份日历。

formatyear(theyear, w=2, l=1, c=6, m=3)

以多行字符串形式返回整个年份的m列日历。可选参数wlc分别用于日期列宽度、每周行数和月份列之间的空格数。取决于构造函数中指定的或由 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为 true,则年份将包含在标题中,否则只使用月份名称。

formatyear(theyear, width=3)

以 HTML 表格形式返回一年的日历。width(默认为 3)指定每行中的月份数。

formatyearpage(theyear, width=3, css='calendar.css', encoding=None)

以完整的 HTML 页面形式返回一年的日历。width(默认为 3)指定每行中的月份数。css 是要使用的层叠样式表的名称。如果没有要使用的样式表,则可以传递 Noneencoding 指定要用于输出的编码(默认为系统默认编码)。

formatmonthname(theyear, themonth, withyear=True)

返回一个 HTML 表格行中的月份名称。如果 withyear 为 true,则该行将包含年份,否则只使用月份名称。

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 是星期日)。为了方便起见,提供了 MONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAYSUNDAY。 例如,要将第一个工作日设置为星期日

import calendar
calendar.setfirstweekday(calendar.SUNDAY)
calendar.firstweekday()

返回每周开始的工作日的当前设置。

calendar.isleap(year)

如果 year 是闰年,则返回 True,否则返回 False

calendar.leapdays(y1, y2)

返回从 y1y2(不包括 y2)范围内的闰年数,其中 y1y2 是年份。

此函数适用于跨越世纪变化的范围。

calendar.weekday(year, month, day)

返回 year (1970–…)、month (112)、day (131) 的星期几(0 是星期一)。

calendar.weekheader(n)

返回包含缩写工作日名称的标题。 n 指定一个工作日的字符宽度。

calendar.monthrange(year, month)

返回指定 yearmonth 的月份第一天的工作日和月份中的天数。

calendar.monthcalendar(year, month)

返回表示月份日历的矩阵。每一行代表一周;月份之外的日期用零表示。除非由 setfirstweekday() 设置,否则每周从星期一开始。

calendar.prmonth(theyear, themonth, w=0, l=0)

打印 month() 返回的月份日历。

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)

返回使用 formatyear() 方法的 TextCalendar 类生成的,包含整年日历的三列多行字符串。

calendar.timegm(tuple)

一个不相关但很方便的函数,它接受一个时间元组(例如由 gmtime() 函数在 time 模块中返回的),并返回相应的 Unix 时间戳值,假设 epoch 为 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

一个序列,表示当前语言环境下星期几的缩写,其中 Mon 为第 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

星期几的别名,其中 MONDAY0SUNDAY6

3.12 版本新增。

class calendar.Day

枚举,将星期几定义为整数常量。此枚举的成员以 MONDAYSUNDAY 的形式导出到模块范围。

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

月份的别名,其中 JANUARY1DECEMBER12

3.12 版本新增。

class calendar.Month

枚举,将月份定义为整数常量。此枚举的成员以 JANUARYDECEMBER 的形式导出到模块范围。

3.12 版本新增。

calendar 模块定义了以下异常

exception calendar.IllegalMonthError(month)

ValueError 的子类,当给定的月份数字超出 1-12(含)范围时引发。

month

无效的月份数字。

异常 calendar.IllegalWeekdayError(weekday)

当给定的工作日数字超出 0-6(含)范围时引发的 ValueError 的子类。

weekday

无效的工作日数字。

参见

模块 datetime

面向对象的日期和时间接口,功能类似于 time 模块。

模块 time

低级时间相关函数。

命令行用法

在 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

要打印日历的年份。默认为当前年份。

month

要打印日历的指定 year 的月份。必须是 1 到 12 之间的数字,并且只能在文本模式下使用。默认为打印全年的日历。

文本模式选项

--width WIDTH, -w WIDTH

终端列中日期列的宽度。日期在列中居中打印。任何低于 2 的值都将被忽略。默认为 2。

--lines LINES, -l LINES

终端行中每周的行数。日期顶部对齐打印。任何低于 1 的值都将被忽略。默认为 1。

--spacing SPACING, -s SPACING

列中月份之间的空格。任何低于 2 的值都将被忽略。默认为 6。

--months MONTHS, -m MONTHS

每行打印的月份数。默认为 3。

HTML 模式选项

--css CSS, -c CSS

用于日历的 CSS 样式表的路径。这必须是相对于生成的 HTML 的路径,或者是一个绝对 HTTP 或 file:/// URL。