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

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

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

Функции и классы, определённые в этом модуле, используют идеализированный календарь, текущий григорианский календарь, продолженный неопределённо в обоих направлениях. Это соответствует определению «пролептического григорианского» календаря в книге Дершовица и Рейнголда «Расчёты по календарю», где это базовый календарь для всех вычислений. Годы 0 и отрицательные интерпретируются в соответствии со стандартом 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.

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

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 timestamp, предполагая эпоху 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] — пустая строка.