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

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

formatmonthname(theyear, themonth, withyear=True)

Возвращает имя месяца в виде строки HTML-таблицы. Если withyear равно True, год будет включён в строку, в противном случае будет использовано только название месяца.

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 может принимать имя локали в конструкторе и возвращать имена месяцев и дней недели в указанной локали.

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

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

calendar.MONDAY

calendar.TUESDAY

calendar.WEDNESDAY

calendar.THURSDAY

calendar.FRIDAY

calendar.SATURDAY

calendar.SUNDAY

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

Модуль calendar определяет следующие исключения:

exception calendar.IllegalMonthError(month)

Подкласс исключения ValueError, который поднимается, когда заданный номер месяца находится вне диапазона от 1 до 12 (включительно).

month

Некорректный номер месяца.

exception calendar.IllegalWeekdayError(weekday)

Подкласс исключения ValueError, который поднимается, когда заданный номер дня недели находится вне диапазона от 0 до 6 (включительно).

weekday

Некорректный номер дня недели.

python -m calendar [-h] [-L LOCALE] [-e ENCODING] [-t {text,html}]
                   [-w WIDTH] [-l LINES] [-s SPACING] [-m MONTHS] [-c CSS]
                   [year] [month]

$ python -m calendar 2000
                                  2000

      January                   February                   March
Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
                1  2          1  2  3  4  5  6             1  2  3  4  5
 3  4  5  6  7  8  9       7  8  9 10 11 12 13       6  7  8  9 10 11 12
10 11 12 13 14 15 16      14 15 16 17 18 19 20      13 14 15 16 17 18 19
17 18 19 20 21 22 23      21 22 23 24 25 26 27      20 21 22 23 24 25 26
24 25 26 27 28 29 30      28 29                     27 28 29 30 31
31

       April                      May                       June
Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
                1  2       1  2  3  4  5  6  7                1  2  3  4
 3  4  5  6  7  8  9       8  9 10 11 12 13 14       5  6  7  8  9 10 11
10 11 12 13 14 15 16      15 16 17 18 19 20 21      12 13 14 15 16 17 18
17 18 19 20 21 22 23      22 23 24 25 26 27 28      19 20 21 22 23 24 25
24 25 26 27 28 29 30      29 30 31                  26 27 28 29 30

        July                     August                  September
Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
                1  2          1  2  3  4  5  6                   1  2  3
 3  4  5  6  7  8  9       7  8  9 10 11 12 13       4  5  6  7  8  9 10
10 11 12 13 14 15 16      14 15 16 17 18 19 20      11 12 13 14 15 16 17
17 18 19 20 21 22 23      21 22 23 24 25 26 27      18 19 20 21 22 23 24
24 25 26 27 28 29 30      28 29 30 31               25 26 27 28 29 30
31

      October                   November                  December
Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
                   1             1  2  3  4  5                   1  2  3
 2  3  4  5  6  7  8       6  7  8  9 10 11 12       4  5  6  7  8  9 10
 9 10 11 12 13 14 15      13 14 15 16 17 18 19      11 12 13 14 15 16 17
16 17 18 19 20 21 22      20 21 22 23 24 25 26      18 19 20 21 22 23 24
23 24 25 26 27 28 29      27 28 29 30               25 26 27 28 29 30 31
30 31