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)

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

itermonthdays(year, month)

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

itermonthdays2(year, month)

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

itermonthdays3(year, month)

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

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

itermonthdays4(year, month)

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

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

monthdatescalendar(year, month)

Возвращает список недель в месяце месяц года год в виде полных недель. Недели представляют собой списки из семи объектов datetime.date.

monthdays2calendar(year, month)

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

monthdayscalendar(year, month)

Возвращает список недель в месяце месяц года год в виде полных недель. Недели - это список из семи чисел дней.

yeardatescalendar(year, width=3)

Возвращает данные за указанный год, готовые к форматированию. Возвращаемое значение представляет собой список строк месяцев. Каждая строка месяца содержит до ширины месяцев (по умолчанию 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 можно передать имя локали в конструкторе, и он будет возвращать названия месяцев и дней недели в указанной локали. Если эта локаль включает кодировку, все строки, содержащие названия месяцев и дней недели, будут возвращены в юникоде.

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

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

Примечание

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

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

calendar.setfirstweekday(weekday)

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

import calendar
calendar.setfirstweekday(calendar.SUNDAY)
calendar.firstweekday()

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

calendar.isleap(year)

Возвращает True, если год - високосный, иначе False.

calendar.leapdays(y1, y2)

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

Эта функция работает для диапазонов, охватывающих смену столетий.

calendar.weekday(year, month, day)

Возвращает день недели (0 - понедельник) для года (1970–…), месяца (1–12), дня (1–31).

calendar.weekheader(n)

Возвращает заголовок, содержащий сокращенные названия дней недели. n задает ширину в символах для одного дня недели.

calendar.monthrange(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.

См.также

Модуль datetime

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

Модуль time

Низкоуровневые функции, связанные с временем.

zoneinfo — Поддержка часовых поясов IANA
collections — Контейнерные типы данных
Вернуться на верх