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

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

Этот модуль позволяет выводить календари, как программа cal в Unix, и предоставляет дополнительные полезные функции, связанные с календарем. По умолчанию в этих календарях первый день недели – понедельник, а последний – воскресенье (европейская конвенция). Используйте 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 позволяет передать имя локали в конструктор и будет возвращать названия месяцев и дней недели на указанной локали. Если локаль включает кодировку, все строки, содержащие названия месяцев и дней недели, будут возвращены в Юникоде.

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

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

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

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)¶

Возвращает календарь на весь год из трёх колонок в виде многострочной строки, используя метод 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] – пустая строка.