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(firstweekday)

Задаёт день недели (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(width)

Возвращает заголовок с сокращёнными названиями дней недели. Параметр width задаёт ширину в символах для одного дня недели.

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(theyear, w=0, l=0, c=6, m=3)

Выводит календарь за весь год, возвращаемый функцией calendar().

calendar.calendar(theyear, 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

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

Изменено в версии 3.12: IllegalMonthError теперь также является подклассом ValueError. В новом коде следует избегать перехвата IndexError.

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