calendar – Общие функции работы с календарём¶calendar – General calendar-related functions

Исходный код: 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 (не включая), где 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 и 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