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

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

Последовательность, представляющая сокращенные названия дней недели в текущей локали, где Mon имеет номер дня 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]
                   [-f FIRST_WEEKDAY] [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