calendar — General calendar-related functions常规日历相关功能

Source code: Lib/calendar.py

---

This module allows you to output calendars like the Unix cal program, and provides additional useful functions related to the calendar. 此模块允许您像Unix cal程序一样输出日历，并提供与日历相关的其他有用功能。By default, these calendars have Monday as the first day of the week, and Sunday as the last (the European convention). 默认情况下，这些日历将周一作为一周的第一天，周日作为最后一天（欧洲公约）。Use setfirstweekday() to set the first day of the week to Sunday (6) or to any other weekday. 使用setfirstweekday()将一周的第一天设置为星期日（6）或任何其他工作日。Parameters that specify dates are given as integers. 指定日期的参数以整数形式给出。For related functionality, see also the datetime and time modules.有关相关功能，请参阅datetime和time模块。

The functions and classes defined in this module use an idealized calendar, the current Gregorian calendar extended indefinitely in both directions. 本模块中定义的函数和类使用理想日历，当前的公历在两个方向上无限扩展。This matches the definition of the “proleptic Gregorian” calendar in Dershowitz and Reingold’s book “Calendrical Calculations”, where it’s the base calendar for all computations. 这与德肖维茨（Dershowitz）和莱因戈尔德的《历法计算》一书中“前公历”的定义相匹配，其中它是所有计算的基准日历。Zero and negative years are interpreted as prescribed by the ISO 8601 standard. Year 0 is 1 BC, year -1 is 2 BC, and so on.零年和负年按照ISO 8601标准的规定进行解释。第0年是公元前1年，第1年是公元前2年，依此类推。

classcalendar.Calendar(firstweekday=0)

Creates a Calendar object. 创建Calendar对象。firstweekday is an integer specifying the first day of the week. firstweekday是一个整数，指定一周的第一天。MONDAY is 0 (the default), SUNDAY is 6.MONDAY为0（默认值），SUNDAY为6。

A Calendar object provides several methods that can be used for preparing the calendar data for formatting. Calendar对象提供了几种方法，可用于准备要格式化的日历数据。This class doesn’t do any formatting itself. 这个类本身不做任何格式化。This is the job of subclasses.这是子类的工作。

Calendar instances have the following methods:实例有以下方法：

iterweekdays()

Return an iterator for the week day numbers that will be used for one week. 返回一个迭代器，用于一周内使用的周数。The first value from the iterator will be the same as the value of the firstweekday property.迭代器的第一个值将与firstweekday属性的值相同。

itermonthdates(year, month)

Return an iterator for the month month (1–12) in the year year. 返回一年year中月份month（1-12）的迭代器。This iterator will return all days (as datetime.date objects) for the month and all days before the start of the month or after the end of the month that are required to get a complete week.该迭代器将返回该月的所有天（作为datetime.date对象）以及获得完整一周所需的该月开始之前或结束之后的所有天。

itermonthdays(year, month)

Return an iterator for the month month in the year year similar to itermonthdates(), but not restricted by the datetime.date range. 返回年year中月份month的迭代器，类似于itermonthdates()，但不受datetime.date范围的限制。Days returned will simply be day of the month numbers. 返回的天数将仅为每月的第几天。For the days outside of the specified month, the day number is 0.对于指定月份以外的天数，天数为0。

itermonthdays2(year, month)

Return an iterator for the month month in the year year similar to itermonthdates(), but not restricted by the datetime.date range. 返回年year中月份month的迭代器，类似于itermonthdates()，但不受datetime.date范围的限制。Days returned will be tuples consisting of a day of the month number and a week day number.返回的天数将是元组，由一个月的一天数和一个星期的一天数组成。

itermonthdays3(year, month)

Return an iterator for the month month in the year year similar to itermonthdates(), but not restricted by the datetime.date range. 返回年year中月份month的迭代器，类似于itermonthdates()，但不受datetime.date范围的限制。Days returned will be tuples consisting of a year, a month and a day of the month numbers.返回的天数将是元组，由一年、一个月和一个月中的一天数字组成。

New in version 3.7.版本3.7中新增。

itermonthdays4(year, month)

Return an iterator for the month month in the year year similar to itermonthdates(), but not restricted by the datetime.date range. 返回年year中月份month的迭代器，类似于itermonthdates()，但不受datetime.date范围的限制。Days returned will be tuples consisting of a year, a month, a day of the month, and a day of the week numbers.返回的日期将是元组，由年、月、月中的一天和星期几数字组成。

New in version 3.7.版本3.7中新增。

monthdatescalendar(year, month)

Return a list of the weeks in the month month of the year as full weeks. 返回一年year中当月month的周列表，作为完整周。Weeks are lists of seven datetime.date objects.周是七个datetime.date对象的列表。

monthdays2calendar(year, month)

Return a list of the weeks in the month month of the year as full weeks. 返回一年year中当month的周列表，作为完整周。Weeks are lists of seven tuples of day numbers and weekday numbers.周是由日数和工作日数的七个元组组成的列表。

monthdayscalendar(year, month)

Return a list of the weeks in the month month of the year as full weeks. 返回一年year中当月month的周列表，作为完整周。Weeks are lists of seven day numbers.周是由七天的数字组成的列表。

yeardatescalendar(year, width=3)

Return the data for the specified year ready for formatting. 返回指定年份的数据，以便格式化。The return value is a list of month rows. 返回值是月份行的列表。Each month row contains up to width months (defaulting to 3). 每个月行包含最多width个月（默认为3个月）。Each month contains between 4 and 6 weeks and each week contains 1–7 days. 每月包含4到6周，每周包含1-7天。Days are datetime.date objects.天是datetime.date对象。

yeardays2calendar(year, width=3)

Return the data for the specified year ready for formatting (similar to yeardatescalendar()). 返回指定年份的数据以进行格式化（类似于yeardatescalendar()）。Entries in the week lists are tuples of day numbers and weekday numbers. 周列表中的条目是日数和工作日数的元组。Day numbers outside this month are zero.本月以外的天数为零。

yeardayscalendar(year, width=3)

Return the data for the specified year ready for formatting (similar to yeardatescalendar()). 返回指定年份的数据以进行格式化（类似于yeardatescalendar()）。Entries in the week lists are day numbers. 周列表中的条目是日数。Day numbers outside this month are zero.本月以外的天数为零。

classcalendar.TextCalendar(firstweekday=0)

This class can be used to generate plain text calendars.此类可用于生成纯文本日历。

TextCalendar instances have the following methods:实例有以下方法：

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

Return a month’s calendar in a multi-line string. 以多行字符串形式返回一个月的日历。If w is provided, it specifies the width of the date columns, which are centered. 如果提供了w，则指定日期列的宽度，这些列居中。If l is given, it specifies the number of lines that each week will use. 如果给定l，则指定每周使用的行数。Depends on the first weekday as specified in the constructor or set by the setfirstweekday() method.取决于构造函数中指定的第一个工作日或由setfirstweekday()方法设置的第一个工作日。

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

Print a month’s calendar as returned by formatmonth().打印由formatmonth()返回的月份日历。

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

Return a m-column calendar for an entire year as a multi-line string. 以多行字符串形式返回一整年的m列日历。Optional parameters w, l, and c are for date column width, lines per week, and number of spaces between month columns, respectively. 可选参数w、l和c分别用于日期列宽度、每周行数和月列之间的空格数。Depends on the first weekday as specified in the constructor or set by the setfirstweekday() method. 取决于构造函数中指定的第一个工作日或由setfirstweekday()方法设置的第一个工作日。The earliest year for which a calendar can be generated is platform-dependent.可以生成日历的最早年份取决于平台。

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

Print the calendar for an entire year as returned by formatyear().打印formatyear()返回的全年日历。

classcalendar.HTMLCalendar(firstweekday=0)

This class can be used to generate HTML calendars.此类可用于生成HTML日历。

HTMLCalendar instances have the following methods:实例有以下方法：

formatmonth(theyear, themonth, withyear=True)

Return a month’s calendar as an HTML table. 以HTML表格的形式返回一个月的日历。If withyear is true the year will be included in the header, otherwise just the month name will be used.如果withyear为true，则年份将包含在标题中，否则只使用月份名称。

formatyear(theyear, width=3)

Return a year’s calendar as an HTML table. 以HTML表格的形式返回一年的日历。width (defaulting to 3) specifies the number of months per row.width（默认为3）指定每行的月数。

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

Return a year’s calendar as a complete HTML page. 将一年的日历作为完整的HTML页面返回。width (defaulting to 3) specifies the number of months per row. width（默认为3）指定每行的月数。css is the name for the cascading style sheet to be used. css是要使用的级联样式表的名称。None can be passed if no style sheet should be used. 如果不应使用样式表，则可以传递None。encoding specifies the encoding to be used for the output (defaulting to the system default encoding).encoding指定用于输出的编码（默认为系统默认编码）。

HTMLCalendar has the following attributes you can override to customize the CSS classes used by the calendar:具有以下属性，您可以覆盖这些属性以自定义日历使用的CSS类：

cssclasses

A list of CSS classes used for each weekday. 每个工作日使用的CSS类的列表。The default class list is:默认类列表为：

cssclasses = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]

more styles can be added for each day:每天可以添加更多样式：

cssclasses = ["mon text-bold", "tue", "wed", "thu", "fri", "sat", "sun red"]

Note that the length of this list must be seven items.请注意，此列表的长度必须为七项。

cssclass_noday

The CSS class for a weekday occurring in the previous or coming month.上个月或下个月的工作日的CSS类。

New in version 3.7.版本3.7中新增。

cssclasses_weekday_head

A list of CSS classes used for weekday names in the header row. 标题行中用于工作日名称的CSS类列表。The default is the same as cssclasses.默认值与cssclasses相同。

New in version 3.7.版本3.7中新增。

cssclass_month_head

The month’s head CSS class (used by formatmonthname()). 月份的头CSS类（由formatmonthname()使用）。The default value is "month".默认值为"month"。

New in version 3.7.版本3.7中新增。

cssclass_month

The CSS class for the whole month’s table (used by formatmonth()). 整个月表的CSS类（由formatmonth()使用）。The default value is "month".默认值为"month"。

New in version 3.7.版本3.7中新增。

cssclass_year

The CSS class for the whole year’s table of tables (used by formatyear()). 全年表格的CSS类（由formatyear()使用）。The default value is "year".默认值为"year"。

New in version 3.7.版本3.7中新增。

cssclass_year_head

The CSS class for the table head for the whole year (used by formatyear()). 全年表头的CSS类（由formatyear()使用）。The default value is "year".默认值为"year"。

New in version 3.7.版本3.7中新增。

Note that although the naming for the above described class attributes is singular (e.g. cssclass_month cssclass_noday), one can replace the single CSS class with a space separated list of CSS classes, for example:注意，尽管上述类属性的命名是单数的（例如，cssclass_month cssclass_noday），但可以用空间分隔的CSS类列表替换单个CSS类，例如：

"text-bold text-red"

Here is an example how HTMLCalendar can be customized:下面是一个如何定制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"

classcalendar.LocaleTextCalendar(firstweekday=0, locale=None)

This subclass of TextCalendar can be passed a locale name in the constructor and will return month and weekday names in the specified locale. TextCalendar的这个子类可以在构造函数中传递区域设置名称，并将返回指定区域设置中的月份和工作日名称。If this locale includes an encoding all strings containing month and weekday names will be returned as unicode.如果此区域设置包含编码，则包含月份和工作日名称的所有字符串将以unicode格式返回。

classcalendar.LocaleHTMLCalendar(firstweekday=0, locale=None)

This subclass of HTMLCalendar can be passed a locale name in the constructor and will return month and weekday names in the specified locale. HTMLCalendar的这个子类可以在构造函数中传递区域设置名称，并将返回指定区域设置中的月份和工作日名称。If this locale includes an encoding all strings containing month and weekday names will be returned as unicode.如果此区域设置包含编码，则包含月份和工作日名称的所有字符串将以unicode格式返回。

Note

The formatweekday() and formatmonthname() methods of these two classes temporarily change the current locale to the given locale. 这两个类的formatweekday()和formatmonthname()方法临时将当前区域设置更改为给定locale。Because the current locale is a process-wide setting, they are not thread-safe.因为当前区域设置是进程范围的设置，所以它们不是线程安全的。

For simple text calendars this module provides the following functions.对于简单文本日历，此模块提供以下功能。

calendar.setfirstweekday(weekday)

Sets the weekday (0 is Monday, 6 is Sunday) to start each week. 将工作日（0为周一，6为周日）设置为每周开始。The values MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, and SUNDAY are provided for convenience. 为了方便起见，提供了MONDAY、TUESDAY、WEDNESDAY、THURSDAY、FRIDAY、SATURDAY和SUNDAY的值。For example, to set the first weekday to Sunday:例如，要将第一个工作日设置为周日：

import calendar
calendar.setfirstweekday(calendar.SUNDAY)

calendar.firstweekday()

Returns the current setting for the weekday to start each week.返回每周开始的工作日的当前设置。

calendar.isleap(year)

Returns True if year is a leap year, otherwise False.如果year是闰年，则返回True，否则返回False。

calendar.leapdays(y1, y2)

Returns the number of leap years in the range from y1 to y2 (exclusive), where y1 and y2 are years.返回从y1到y2（不包括）范围内的闰年数，其中y1和y2是年。

This function works for ranges spanning a century change.该函数适用于跨越世纪变化的范围。

calendar.weekday(year, month, day)

Returns the day of the week (0 is Monday) for year (1970–…), month (1–12), day (1–31).返回year（1970-…）、month（1-12）、day（1-31）的星期几（0是星期一）。

calendar.weekheader(n)

Return a header containing abbreviated weekday names. 返回包含缩写工作日名称的标题。n specifies the width in characters for one weekday.n指定一个工作日的宽度（以字符为单位）。

calendar.monthrange(year, month)

Returns weekday of first day of the month and number of days in month, for the specified year and month.返回指定year和month的月份第一天的工作日和月份天数。

calendar.monthcalendar(year, month)

Returns a matrix representing a month’s calendar. 返回表示一个月日历的矩阵。Each row represents a week; days outside of the month are represented by zeros. 每行代表一周；月外的天数用零表示。Each week begins with Monday unless set by setfirstweekday().每周从星期一开始，除非由setfirstweekday()设置。

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

Prints a month’s calendar as returned by month().打印month()返回的月份日历。

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

Returns a month’s calendar in a multi-line string using the formatmonth() of the TextCalendar class.使用TextCalendar类的formatmonth()以多行字符串形式返回一个月的日历。

calendar.prcal(year, w=0, l=0, c=6, m=3)

Prints the calendar for an entire year as returned by calendar().打印calendar()返回的全年日历。

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

Returns a 3-column calendar for an entire year as a multi-line string using the formatyear() of the TextCalendar class.使用TextCalendar类的formatyear()以多行字符串形式返回全年的3列日历。

calendar.timegm(tuple)

An unrelated but handy function that takes a time tuple such as returned by the gmtime() function in the time module, and returns the corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX encoding. 一个不相关但方便的函数，它接受时间元组，如time模块中的gmtime()函数返回的时间元组，并返回相应的Unix时间戳值（假设历元为1970）和POSIX编码。In fact, time.gmtime() and timegm() are each others’ inverse.事实上，time.gmtime()和timegm()是彼此的反比。

The calendar module exports the following data attributes:calendar模块导出以下数据属性：

calendar.day_name

An array that represents the days of the week in the current locale.表示当前区域设置中每周几天的数组。

calendar.day_abbr

An array that represents the abbreviated days of the week in the current locale.一个数组，表示当前区域设置中一周中的缩短天数。

calendar.month_name

An array that represents the months of the year in the current locale. 表示当前区域设置中一年中月份的数组。This follows normal convention of January being month number 1, so it has a length of 13 and month_name[0] is the empty string.这遵循了通常的约定，一月是第1个月，因此它的长度为13，month_name[0]是空字符串。

calendar.month_abbr

An array that represents the abbreviated months of the year in the current locale. 表示当前区域设置中一年中缩写月份的数组。This follows normal convention of January being month number 1, so it has a length of 13 and month_abbr[0] is the empty string.这遵循了1月为第1个月的正常约定，因此其长度为13，month_abbr[0]是空字符串。

calendar.MONDAY

calendar.TUESDAY

calendar.WEDNESDAY

calendar.THURSDAY

calendar.FRIDAY

calendar.SATURDAY

calendar.SUNDAY

Aliases for day numbers, where MONDAY is 0 and SUNDAY is 6.日数的别名，其中MONDAY为0，SUNDAY为6。

See also

Module 单元datetime

Object-oriented interface to dates and times with similar functionality to the time module.面向对象的日期和时间接口，具有与time模块类似的功能。

Module 单元time

Low-level time related functions.低级时间相关功能。