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

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

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

Большинство этих функций и классов полагаются на модуль datetime, который использует идеализированный календарь, текущий григорианский календарь, расширенный в обоих направлениях. Это соответствует определению «пролептического григорианского» календаря в книге Дершовица и Рейнгольда «Расчёты календарных дат», где он является базовым календарём для всех вычислений.

class calendar.Calendar(firstweekday=0)

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

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

Примеры объектов Calendar имеют следующие методы:

iterweekdays()

Возвращает итератор для номеров дней недели, которые будут использоваться для одной недели. Первое значение из итератора будет таким же, как значение свойства firstweekday.

itermonthdates(year, month)

Возвращает итератор для месяца month (1–12) в году year. Этот итератор вернёт все дни (в виде объектов datetime.date) для месяца и все дни до начала месяца или после конца месяца, которые необходимы для получения полной недели.

itermonthdays2(year, month)

Возвращает итератор для месяца month в году year, аналогично itermonthdates(). Возвращаемые дни будут кортежами, состоящими из номера дня и номера дня недели.

itermonthdays(year, month)

Возвращает итератор для месяца month в году year, аналогично itermonthdates(). Возвращаемые дни будут просто номерами дней.

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 истинно, год будет включён в заголовок, в противном случае будет использоваться только имя месяца.

formatyear(theyear, width=3)

Возвращает календарь года в виде HTML-таблицы. width (по умолчанию 3) задаёт количество месяцев в строке.

formatyearpage(theyear, width=3, css='calendar.css', encoding=None)

Возвращает календарь года в виде полной HTML-страницы. width (по умолчанию 3) задаёт количество месяцев в строке. css — имя используемого каскадного стилевого листа. None может быть передано, если не нужно использовать стилевой лист. encoding задаёт кодировку, используемую для вывода (по умолчанию — системная кодировка).

class calendar.LocaleTextCalendar(firstweekday=0, locale=None)

Этот подкласс TextCalendar может принимать имя локали в конструкторе и возвращать имена месяцев и дней недели в указанной локали. Если эта локаль включает кодировку, все строки, содержащие имена месяцев и дней недели, будут возвращены как unicode.

class calendar.LocaleHTMLCalendar(firstweekday=0, locale=None)

Этот подкласс HTMLCalendar может принимать имя локали в конструкторе и возвращать имена месяцев и дней недели в указанной локали. Если эта локаль включает кодировку, все строки, содержащие имена месяцев и дней недели, будут возвращены как unicode.

Для простых текстовых календарей в этом модуле представлены следующие функции.

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)

Возвращает календарь месяца в многострочном строковом представлении, используя метод TextCalendar класса.

calendar.prcal(year, w=0, l=0, c=6, m=3)

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

calendar.calendar(year, w=2, l=1, c=6, m=3)

Возвращает календарь на весь год в трех столбцах в виде многострочной строки, используя метод TextCalendar класса.

calendar.timegm(tuple)

Не относящаяся к этому, но полезная функция, которая принимает кортеж времени, такой как возвращается функцией gmtime() в модуле time, и возвращает соответствующее значение Unix timestamp, предполагая эпоху 1970 и кодировку POSIX. Фактически, time.gmtime() и timegm() являются взаимными обратными функциями.

Модуль calendar экспортирует следующие атрибуты данных:

calendar.day_name

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

calendar.day_abbr

Массив, представляющий сокращенные дни недели в текущем локали.

calendar.month_name

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

calendar.month_abbr

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