calendar — Общие функции, связанные с календарём

Исходный код: Lib/calendar.py

Этот модуль позволяет выводить календари, подобные программе Unix cal, и предоставляет дополнительные полезные функции, связанные с календарём. По умолчанию в этих календарях понедельник является первым днём недели, а воскресенье — последним (европейская конвенция). Используйте setfirstweekday(), чтобы установить первый день недели на воскресенье (6) или любой другой день недели. Параметры, определяющие даты, задаются как целые числа. Для связанной функциональности также см. модули datetime и time.

Большинство этих функций и классов полагаются на модуль datetime, который использует идеализированный календарь, текущий григорианский календарь, расширенный в обоих направлениях. Это соответствует определению «пролептического григорианского» календаря в книге Дершовица и Рейнгольда «Вычисления календаря», где он является базовым календарём для всех вычислений.

class calendar.Calendar(firstweekday=0)

Создаёт объект Calendar. firstweekday — целое число, определяющее первый день недели. 0 — понедельник (по умолчанию), 6 — воскресенье.

Объект Calendar предоставляет несколько методов, которые могут использоваться для подготовки данных календаря для форматирования. Этот класс сам по себе не выполняет форматирование. Это задача подклассов.

Экземпляры Calendar имеют следующие методы:

iterweekdays()

Возвращает итератор для номеров дней недели, которые будут использоваться для одной недели. Первое значение из итератора будет таким же, как значение свойства firstweekday.

itermonthdates(year, month)

Возвращает итератор для месяца month (1–12) в году year. Этот итератор вернёт все дни (как объекты datetime.date) для месяца и все дни до начала месяца или после окончания месяца, которые необходимы для получения полной недели.

itermonthdays2(year, month)

Возвращает итератор для месяца month в году year, аналогичный itermonthdates(). Возвращаемые дни будут кортежами, состоящими из номера дня и номера дня недели.

itermonthdays(year, month)

Возвращает итератор для месяца month в году year, аналогичный itermonthdates(). Возвращаемые дни будут просто номерами дней.

monthdatescalendar(year, month)

Возвращает список недель в месяце month года year в виде полных недель. Недели являются списками из семи объектов datetime.date.

monthdays2calendar(year, month)

Возвращает список недель в месяце month года year в виде полных недель. Недели являются списками из семи кортежей, содержащих номера дня и дня недели.

monthdayscalendar(year, month)

Возвращает список недель в месяце month года year в виде полных недель. Недели являются списками из семи номеров дней.

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 имеют следующие методы:

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 столбцах в виде строки с несколькими строками. Необязательные параметры 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 имеет значение true, год будет включён в заголовок, в противном случае будет использовано только название месяца.

formatyear(theyear, width=3)

Возвращает календарь на весь год в виде HTML-таблицы. width (по умолчанию 3) задаёт количество месяцев в строке.

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

Возвращает календарь на весь год в виде полной HTML-страницы. width (по умолчанию 3) задаёт количество месяцев в строке. css — имя используемого каскадного таблицы стилей. None можно передать, если не использовать таблицу стилей. encoding задаёт используемую кодировку вывода (по умолчанию — системная кодировка).

class calendar.LocaleTextCalendar(firstweekday=0, locale=None)

Этот подкласс TextCalendar может принимать имя локали в конструкторе и возвращать названия месяцев и дней недели в указанной локали. Если эта локаль включает кодировку, все строки, содержащие названия месяцев и дней недели, будут возвращаться в виде unicode.

class calendar.LocaleHTMLCalendar(firstweekday=0, locale=None)

Этот подкласс HTMLCalendar может принимать имя локали в конструкторе и возвращать названия месяцев и дней недели в указанной локали. Если эта локаль включает кодировку, все строки, содержащие названия месяцев и дней недели, будут возвращаться в виде unicode.

Для простых текстовых календарей в этом модуле предоставляются следующие функции.

calendar.setfirstweekday(weekday)

Устанавливает день недели (0 — понедельник, 6 — воскресенье) для начала каждой недели. Значения MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, и SUNDAY предоставляются для удобства. Например, чтобы установить первый день недели на воскресенье:

import calendar
calendar.setfirstweekday(calendar.SUNDAY)

calendar.firstweekday()

Возвращает текущую установку для дня недели, с которого начинается каждая неделя.

calendar.isleap(year)

Возвращает True, если year — високосный год, иначе False.

calendar.leapdays(y1, y2)

Возвращает количество високосных лет в диапазоне от y1 до y2 (исключая), где y1 и y2 — годы.

Эта функция работает для диапазонов, охватывающих смену столетия.

calendar.weekday(year, month, day)

Возвращает день недели (0 — понедельник) для year (1970–…), month (1–12), day (1–31).

calendar.weekheader(n)

Возвращает заголовок, содержащий сокращённые названия дней недели. n задаёт ширину в символах для одного дня недели.

calendar.monthrange(year, month)

Возвращает день недели первого дня месяца и количество дней в месяце для указанного year и month.

calendar.monthcalendar(year, month)

Возвращает матрицу, представляющую календарь месяца. Каждая строка представляет неделю; дни вне месяца отображаются нулями. Каждая неделя начинается с понедельника, если не установлено иначе с помощью setfirstweekday().

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

Выводит календарь месяца, возвращённый month().

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

Возвращает календарь месяца в строке с несколькими строками, используя formatmonth() класса TextCalendar.

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

Выводит календарь на весь год, как возвращает calendar().

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

Возвращает календарь на весь год в 3 колонках в строке с несколькими строками, используя formatyear() класса TextCalendar.

calendar.timegm(tuple)

Функция, не связанная с другими, но полезная для преобразования кортежа времени, такого как возвращаемый функцией gmtime() в модуле time, в соответствующее значение Unix-временной метки, предполагая эпоху 1970 года и кодировку POSIX. Фактически, time.gmtime() и timegm() являются взаимными обратными операциями.

Модуль calendar экспортирует следующие атрибуты данных:

calendar.day_name

Массив, представляющий дни недели в текущем локали.

calendar.day_abbr

Массив, представляющий сокращённые названия дней недели в текущем локали.

calendar.month_name

Массив, представляющий месяцы года в текущем локали. Следуя общепринятой конвенции, январь имеет номер 1, поэтому его длина равна 13, и month_name[0] — пустая строка.

calendar.month_abbr

Массив, представляющий сокращённые названия месяцев года в текущем локали. Следуя общепринятой конвенции, январь имеет номер 1, поэтому его длина равна 13, и month_abbr[0] — пустая строка.