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

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

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

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

class calendar.Calendar(firstweekday=0)

Создаёт объект Calendar. firstweekday — целое число, задающее первый день недели. MONDAY — 0 (значение по умолчанию), SUNDAY — 6.

Объект Calendar предоставляет несколько методов, которые можно использовать для подготовки данных календаря к форматированию. Сам этот класс ничего не форматирует. Эту задачу выполняют подклассы.

Экземпляры Calendar имеют следующие методы и атрибуты:

firstweekday

Первый день недели в виде целого числа (0–6).

Это свойство также можно задавать и считывать с помощью методов setfirstweekday() и getfirstweekday() соответственно.

getfirstweekday()

Возвращает int, соответствующее текущему первому дню недели (0–6).

Эквивалентно чтению свойства firstweekday.

setfirstweekday(firstweekday)

Устанавливает первым днём недели firstweekday, переданный в виде int (0–6).

Эквивалентно заданию свойства firstweekday.

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 имеют следующие методы:

formatday(theday, weekday, width)

Возвращает строку, представляющую отдельный день и отформатированную с заданной шириной width. Если theday равен 0, возвращает строку пробелов заданной ширины, представляющую пустой день. Параметр weekday не используется.

formatweek(theweek, w=0)

Возвращает одну неделю в виде строки без символа новой строки. Если задан параметр w, он задаёт ширину столбцов дат, которые выравниваются по центру. Результат зависит от первого дня недели, заданного в конструкторе или методом setfirstweekday().

formatweekday(weekday, width)

Возвращает строку с названием одного дня недели, отформатированную с указанной шириной width. Параметр weekday — это целое число, представляющее день недели, где 0 — понедельник, а 6 — воскресенье.

formatweekheader(width)

Возвращает строку с заголовком, содержащим названия дней недели, отформатированным с заданной шириной width для каждого столбца. Названия зависят от настроек локали и дополняются пробелами до указанной ширины.

formatmonth(theyear, themonth, w=0, l=0)

Возвращает календарь месяца в виде многострочной строки. Если задан параметр w, он задаёт ширину столбцов дат, которые выравниваются по центру. Если задан параметр l, он задаёт число строк для каждой недели. Результат зависит от первого дня недели, заданного в конструкторе или методом setfirstweekday().

formatmonthname(theyear, themonth, width=0, withyear=True)

Возвращает строку с названием месяца, выровненным по центру в пределах указанной ширины width. Если withyear равен True, в вывод включается год. Параметры theyear и themonth задают соответственно год и месяц, название которых нужно отформатировать.

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 (не включая 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

Последовательность, представляющая дни недели в текущей локали, где понедельник имеет номер 0.

>>> import calendar
>>> list(calendar.day_name)
['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']

calendar.day_abbr

Последовательность, представляющая сокращённые названия дней недели в текущей локали, где понедельник имеет номер 0.

>>> import calendar
>>> list(calendar.day_abbr)
['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']

calendar.MONDAY

calendar.TUESDAY

calendar.WEDNESDAY

calendar.THURSDAY

calendar.FRIDAY

calendar.SATURDAY

calendar.SUNDAY

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

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

class calendar.Day

Перечисление, определяющее дни недели в виде целочисленных констант. Элементы этого перечисления экспортируются в пространство имён модуля как значения от MONDAY до SUNDAY.

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

calendar.month_name

Последовательность, представляющая месяцы года в текущей локали. Она соответствует обычному соглашению, согласно которому январь имеет номер 1, поэтому её длина равна 13, а month_name[0] — пустая строка.

>>> import calendar
>>> list(calendar.month_name)
['', 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']

calendar.month_abbr

Последовательность, представляющая сокращённые названия месяцев года в текущей локали. Она соответствует обычному соглашению, согласно которому январь имеет номер 1, поэтому её длина равна 13, а month_abbr[0] — пустая строка.

>>> import calendar
>>> list(calendar.month_abbr)
['', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

calendar.JANUARY

calendar.FEBRUARY

calendar.MARCH

calendar.APRIL

calendar.MAY

calendar.JUNE

calendar.JULY

calendar.AUGUST

calendar.SEPTEMBER

calendar.OCTOBER

calendar.NOVEMBER

calendar.DECEMBER

Псевдонимы месяцев года, где JANUARY — это 1, а DECEMBER — это 12.

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

class calendar.Month

Перечисление, определяющее месяцы года в виде целочисленных констант. Члены этого перечисления экспортируются в область видимости модуля как JANUARY — DECEMBER.

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

Модуль 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