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

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

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

Функции и классы, определённые в этом модуле, используют идеализированный календарь – текущий григорианский календарь, неограниченно расширенный в обоих направлениях. Это соответствует определению «пролептического григорианского» календаря из книги Дершовица и Рейнгольда «Calendrical Calculations», где он является базовым для всех вычислений. Нулевые и отрицательные годы интерпретируются в соответствии со стандартом ISO 8601. Год 0 соответствует 1 году до н.э., год -1 – 2 году до н.э. и так далее.

class calendar.Calendar(firstweekday=0)¶

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

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

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

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

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

itermonthdays(year, month)¶: Возвращает итератор для месяца month года year, аналогично itermonthdates(), но без ограничения по диапазону datetime.date. Возвращаемые дни – просто номера дней месяца. Для дней за пределами указанного месяца номер дня равен 0.

itermonthdays2(year, month)¶: Возвращает итератор для месяца month года year, аналогичный itermonthdates(), но не ограниченный datetime.date диапазоном. Возвращаемые дни – кортежи, состоящие из номера дня в месяце и номера дня недели.

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

Добавлено в версии 3.7.

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

Добавлено в версии 3.7.

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 задает кодировку для вывода (по умолчанию используется системная кодировка).

HTMLCalendar имеет следующие атрибуты, которые можно переопределить для настройки CSS-классов, используемых календарем:

cssclasses¶

Список CSS-классов, используемых для каждого дня недели. Список классов по умолчанию:

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

для каждого дня можно добавить больше стилей:

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

Обратите внимание, что длина этого списка должна быть равна семи элементам.

cssclass_noday¶: CSS-класс для дня недели, приходящегося на предыдущий или следующий месяц.

Добавлено в версии 3.7.

cssclasses_weekday_head¶: Список CSS-классов, используемых для названий дней недели в строке заголовка. По умолчанию такой же, как cssclasses.

Добавлено в версии 3.7.

cssclass_month_head¶: CSS-класс заголовка месяца (используется formatmonthname()). Значение по умолчанию – "month".

Добавлено в версии 3.7.

cssclass_month¶: CSS-класс для таблицы целого месяца (используется formatmonth()). Значение по умолчанию – "month".

Добавлено в версии 3.7.

cssclass_year¶: CSS-класс для таблицы таблиц всего года (используется formatyear()). Значение по умолчанию – "year".

Добавлено в версии 3.7.

cssclass_year_head¶: CSS-класс для заголовка таблицы всего года (используется formatyear()). Значение по умолчанию – "year".

Добавлено в версии 3.7.

Обратите внимание, что, хотя названия описанных выше атрибутов классов стоят в единственном числе (например, cssclass_month cssclass_noday), можно заменить одиночный CSS-класс на список CSS-классов, разделенных пробелами, например:

"text-bold text-red"

Вот пример того, как можно настроить 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"

class calendar.LocaleTextCalendar(firstweekday=0, locale=None)¶: Этот подкласс TextCalendar может принимать название локали в конструкторе и возвращать названия месяцев и дней недели в указанной локали. Если эта локаль включает кодировку, все строки, содержащие названия месяцев и дней недели, будут возвращены в виде Unicode.

class calendar.LocaleHTMLCalendar(firstweekday=0, locale=None)¶: Этот подкласс HTMLCalendar может принимать название локали в конструкторе и возвращать названия месяцев и дней недели в указанной локали. Если эта локаль включает кодировку, все строки, содержащие названия месяцев и дней недели, будут возвращены в виде Unicode.

Примечание

Методы formatweekday() и formatmonthname() этих двух классов временно изменяют текущую локаль на указанную locale. Поскольку текущая локаль является общепроцессной настройкой, они не являются потокобезопасными.

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

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] – пустая строка.

См. также

Модуль datetime: Объектно-ориентированный интерфейс для работы с датами и временем, предоставляющий функциональность, аналогичную модулю time.
Модуль time: Низкоуровневые функции для работы со временем.

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

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