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

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

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