calendar — Календарные функции


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

Функции и классы, определенные в этом модуле, используют идеализированный календарь, нынешний григорианский календарь расширен бесконечно в обоих направлениях. Это соответствует определению «пролептического григорианского» календаря в книге Dershowitz и Reingold’а «Календарные вычисления», где базовый календарь для всех вычислений. Нулевые и отрицательные годы интерпретируются как определено стандартом 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 истинно, год будет включен в заголовок, иначе будет использоваться только название месяца.

formatyear(theyear, width=3)

Возвращает календарь года в виде HTML-таблицы. width (по умолчанию 3) указывает количество месяцев в строке.

formatyearpage(theyear, width=3, css='calendar.css', encoding=None)

Возвращает календарь года в виде полной HTML-страницы. width (по умолчанию 1) указывает количество месяцев в строке. 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() методы данных двух классов временно изменяют текущую локаль на переданную 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 (112), day (131).

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] является пустой строка.

См.также

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