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

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

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

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

class calendar.Calendar(firstweekday=0)

Создаёт объект Calendar. firstweekday — целое число, определяющее первый день недели. MONDAY — 0 (значение по умолчанию), SUNDAY — 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.

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

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

calendar.MONDAY

calendar.TUESDAY

calendar.WEDNESDAY

calendar.THURSDAY

calendar.FRIDAY

calendar.SATURDAY

calendar.SUNDAY

Псевдонимы для номеров дней, где MONDAY — это 0 и SUNDAY — это 6.