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

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

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

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

class calendar.Calendar([firstweekday])

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

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

В версии 2.5.

Экземпляры 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])

Возвращает данные для указанного года, готовые к форматированию. Возвращаемое значение — список строк месяца. Каждая строка месяца содержит до width месяцев (по умолчанию 3). Каждый месяц содержит от 4 до 6 недель, и каждая неделя содержит от 1 до 7 дней. Дни являются объектами datetime.date.

yeardays2calendar(year[, width])

Возвращает данные для указанного года, готовые к форматированию (аналогично yeardatescalendar()). Элементы в списках недель являются кортежами номеров дней и номеров дней недели. Номера дней за пределами этого месяца равны нулю.

yeardayscalendar(year[, width])

Возвращает данные для указанного года, готовые к форматированию (аналогично yeardatescalendar()). Элементы в списках недель являются номерами дней. Номера дней за пределами этого месяца равны нулю.

class calendar.TextCalendar([firstweekday])

Этот класс может использоваться для генерации текстовых календарей.

В версии 2.5.

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

formatmonth(theyear, themonth[, w[, l]])

Возвращает календарь месяца в строке с несколькими строками. Если w указано, оно задаёт ширину столбцов даты, которые центрируются. Если l задано, оно задаёт количество строк, которые будет использовать каждая неделя. Зависит от первого дня недели, указанного в конструкторе или установленного методом setfirstweekday().

prmonth(theyear, themonth[, w[, l]])

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

formatyear(theyear[, w[, l[, c[, m]]]])

Возвращает календарь на весь год с m столбцами в строке с несколькими строками. Необязательные параметры w, l и c предназначены для ширины столбца даты, строк на неделю и количества пробелов между столбцами месяцев соответственно. Зависит от первого дня недели, указанного в конструкторе или установленного методом setfirstweekday(). Самый ранний год, для которого может быть сгенерирован календарь, зависит от платформы.

pryear(theyear[, w[, l[, c[, m]]]])

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

class calendar.HTMLCalendar([firstweekday])

Этот класс может использоваться для генерации календарей в формате HTML.

В версии 2.5.

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

formatmonth(theyear, themonth[, withyear])

Возвращает календарь месяца в виде HTML-таблицы. Если withyear — true, год будет включён в заголовок, в противном случае будет использоваться только название месяца.

formatyear(theyear[, width])

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

formatyearpage(theyear[, width[, css[, encoding]]])

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

class calendar.LocaleTextCalendar([firstweekday[, locale]])

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

В версии 2.5.

class calendar.LocaleHTMLCalendar([firstweekday[, locale]])

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

В версии 2.5.

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

calendar.setfirstweekday(weekday)

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

import calendar
calendar.setfirstweekday(calendar.SUNDAY)

Новая в версии 2.0.

calendar.firstweekday()

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

Новая в версии 2.0.

calendar.isleap(year)

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

calendar.leapdays(y1, y2)

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

Изменено в версии 2.0: В Python 1.5.2 эта функция не работала для диапазонов, охватывающих смену столетия.

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[, l]])

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

calendar.month(theyear, themonth[, w[, l]])

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

Новая в версии 2.0.

calendar.prcal(year[, w[, l[c]]])

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

calendar.calendar(year[, w[, l[c]]])

Возвращает календарь на весь год в виде трёхколоночной таблицы в виде многострочной строки, используя формат TextCalendar класса.

Новая в версии 2.0.

calendar.timegm(tuple)

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

Новая в версии 2.0.

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

calendar.day_name

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

calendar.day_abbr

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

calendar.month_name

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

calendar.month_abbr

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