8.2. calendar – Общие функции для работы с календарем¶calendar – General calendar-related functions

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

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

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

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 (не включая), где 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]])¶

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

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

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

Выводит календарь на целый год, возвращаемый функцией calendar().

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

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

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

calendar.timegm(tuple)¶

Не связанная напрямую, но удобная функция, которая принимает кортеж времени, например возвращаемый функцией gmtime() из модуля time, и возвращает соответствующее значение метки времени Unix, предполагая эпоху 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] – пустая строка.