> **Источник:** https://python-all.ru/3.1/library/calendar.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# 8.2. `calendar` – Общие функции для работы с календарем

Этот модуль позволяет выводить календари, как программа **cal** в Unix, и предоставляет дополнительные полезные функции, связанные с календарем. По умолчанию в этих календарях первый день недели – понедельник, а последний – воскресенье (европейская конвенция). Используйте [`setfirstweekday()`](https://python-all.ru/3.1/library/calendar.html#calendar.setfirstweekday), чтобы установить первым днём недели воскресенье (6) или любой другой день недели. Параметры, задающие даты, передаются как целые числа. За дополнительными возможностями обращайтесь также к модулям [`datetime`](https://python-all.ru/3.1/library/datetime.html#module-datetime) и [`time`](https://python-all.ru/3.1/library/time.html#module-time).

Большинство этих функций и классов используют модуль [`datetime`](https://python-all.ru/3.1/library/datetime.html#module-datetime), который работает с идеализированным календарем – текущим григорианским календарем, неограниченно расширенным в обе стороны. Это соответствует определению «пролептического григорианского» календаря в книге Дершовица и Рейнгольда «Календарные вычисления», где он является базовым для всех расчётов.

#### `class calendar.Calendar(firstweekday=0)`

Создаёт объект [`Calendar`](https://python-all.ru/3.1/library/calendar.html#calendar.Calendar). *firstweekday* – целое число, задающее первый день недели. `0` – понедельник (по умолчанию), `6` – воскресенье.

Объект [`Calendar`](https://python-all.ru/3.1/library/calendar.html#calendar.Calendar) предоставляет несколько методов, которые можно использовать для подготовки данных календаря к форматированию. Этот класс сам не выполняет форматирование. Это задача подклассов.

Экземпляры [`Calendar`](https://python-all.ru/3.1/library/calendar.html#calendar.Calendar) имеют следующие методы:

#### `iterweekdays()`

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

[`firstweekday`](https://python-all.ru/3.1/library/calendar.html#calendar.firstweekday)

.

#### `itermonthdates(year, month)`

Возвращает итератор для месяца

*month*

(1-12) в году

*year*

. Этот итератор возвращает все дни (как объекты

[`datetime.date`](https://python-all.ru/3.1/library/datetime.html#datetime.date)

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

#### `itermonthdays2(year, month)`

Возвращает итератор для месяца

*month*

в году

*year*

, аналогично

[`itermonthdates()`](https://python-all.ru/3.1/library/calendar.html#calendar.Calendar.itermonthdates)

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

#### `itermonthdays(year, month)`

Возвращает итератор для месяца

*month*

в году

*year*

, аналогично

[`itermonthdates()`](https://python-all.ru/3.1/library/calendar.html#calendar.Calendar.itermonthdates)

. Возвращаемые дни – это просто номера дней.

#### `monthdatescalendar(year, month)`

Возвращает список недель в месяце

*month*

года

*year*

в виде полных недель. Недели представляют собой списки из семи объектов

[`datetime.date`](https://python-all.ru/3.1/library/datetime.html#datetime.date)

.

#### `monthdays2calendar(year, month)`

Возвращает список недель в месяце

*month*

года

*year*

в виде полных недель. Каждая неделя – это список из семи кортежей с номером дня и номером дня недели.

#### `monthdayscalendar(year, month)`

Возвращает список недель в месяце

*month*

года

*year*

в виде полных недель. Каждая неделя – это список из семи номеров дней.

#### `yeardatescalendar(year, width=3)`

Возвращает данные для указанного года, готовые к форматированию. Возвращаемое значение – это список строк месяцев. Каждая строка месяца содержит до

*width*

месяцев (по умолчанию 3). Каждый месяц содержит от 4 до 6 недель, и каждая неделя содержит от 1 до 7 дней. Дни – это объекты

[`datetime.date`](https://python-all.ru/3.1/library/datetime.html#datetime.date)

.

#### `yeardays2calendar(year, width=3)`

Возвращает данные для указанного года, готовые к форматированию (аналогично

[`yeardatescalendar()`](https://python-all.ru/3.1/library/calendar.html#calendar.Calendar.yeardatescalendar)

). Записи в списках недель – это кортежи номеров дней и номеров дней недели. Номера дней вне этого месяца равны нулю.

#### `yeardayscalendar(year, width=3)`

Возвращает данные для указанного года, готовые к форматированию (аналогично

[`yeardatescalendar()`](https://python-all.ru/3.1/library/calendar.html#calendar.Calendar.yeardatescalendar)

). Записи в списках недель – это номера дней. Номера дней вне этого месяца равны нулю.

#### `class calendar.TextCalendar(firstweekday=0)`

Этот класс можно использовать для создания текстовых календарей.

Экземпляры [`TextCalendar`](https://python-all.ru/3.1/library/calendar.html#calendar.TextCalendar) имеют следующие методы:

#### `formatmonth(theyear, themonth, w=0, l=0)`

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

*w*

, он задаёт ширину столбцов с датами, которые выравниваются по центру. Если указан

*l*

, он задаёт количество строк, которое будет использоваться для каждой недели. Зависит от первого дня недели, указанного в конструкторе или установленного методом

[`setfirstweekday()`](https://python-all.ru/3.1/library/calendar.html#calendar.setfirstweekday)

.

#### `prmonth(theyear, themonth, w=0, l=0)`

Выводит календарь месяца, возвращаемый методом

[`formatmonth()`](https://python-all.ru/3.1/library/calendar.html#calendar.TextCalendar.formatmonth)

.

#### `formatyear(theyear, w=2, l=1, c=6, m=3)`

Возвращает календарь на целый год с

*m*

столбцами в виде многострочной строки. Необязательные параметры

*w*

,

*l*

и

*c*

задают ширину столбца дат, количество строк на неделю и количество пробелов между столбцами месяцев соответственно. Зависит от первого дня недели, указанного в конструкторе или заданного методом

[`setfirstweekday()`](https://python-all.ru/3.1/library/calendar.html#calendar.setfirstweekday)

. Самый ранний год, для которого можно сгенерировать календарь, зависит от платформы.

#### `pryear(theyear, w=2, l=1, c=6, m=3)`

Выводит календарь на целый год, возвращённый методом

[`formatyear()`](https://python-all.ru/3.1/library/calendar.html#calendar.TextCalendar.formatyear)

.

#### `class calendar.HTMLCalendar(firstweekday=0)`

Этот класс можно использовать для создания HTML-календарей.

Экземпляры [`HTMLCalendar`](https://python-all.ru/3.1/library/calendar.html#calendar.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`](https://python-all.ru/3.1/library/constants.html#None)

можно передать, если таблицу стилей использовать не нужно.

*encoding*

задаёт кодировку для вывода (по умолчанию используется системная кодировка).

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

Этот подкласс

[`TextCalendar`](https://python-all.ru/3.1/library/calendar.html#calendar.TextCalendar)

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

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

Этот подкласс

[`HTMLCalendar`](https://python-all.ru/3.1/library/calendar.html#calendar.HTMLCalendar)

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

> **Примечание**
>
> Методы `formatweekday()` и `formatmonthname()` этих двух классов временно меняют текущую локаль на заданную *locale*. Поскольку текущая локаль является общепроцессной настройкой, эти методы не являются потокобезопасными.

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

#### `calendar.setfirstweekday(weekday)`

Устанавливает день недели, с которого начинается каждая неделя (`0` – понедельник, `6` – воскресенье). Константы `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY` и `SUNDAY` предусмотрены для удобства. Например, чтобы установить первый день недели на воскресенье:

```python
import calendar
calendar.setfirstweekday(calendar.SUNDAY)
```

#### `calendar.firstweekday()`

Возвращает текущую настройку дня недели, с которого начинается каждая неделя.

#### `calendar.isleap(year)`

Возвращает

[`True`](https://python-all.ru/3.1/library/constants.html#True)

, если

*year*

– високосный год, иначе

[`False`](https://python-all.ru/3.1/library/constants.html#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()`](https://python-all.ru/3.1/library/calendar.html#calendar.setfirstweekday)

.

#### `calendar.prmonth(theyear, themonth, w=0, l=0)`

Выводит календарь на месяц, возвращённый методом

[`month()`](https://python-all.ru/3.1/library/calendar.html#calendar.month)

.

#### `calendar.month(theyear, themonth, w=0, l=0)`

Возвращает календарь на месяц в виде многострочной строки с помощью метода

`formatmonth()`

класса

[`TextCalendar`](https://python-all.ru/3.1/library/calendar.html#calendar.TextCalendar)

.

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

Печатает календарь на весь год, как возвращается функцией

[`calendar()`](https://python-all.ru/3.1/library/calendar.html#calendar.calendar)

.

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

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

`formatyear()`

класса

[`TextCalendar`](https://python-all.ru/3.1/library/calendar.html#calendar.TextCalendar)

.

#### `calendar.timegm(tuple)`

Независимая, но полезная функция, которая принимает кортеж времени, например возвращаемый функцией

`gmtime()`

в модуле

[`time`](https://python-all.ru/3.1/library/time.html#module-time)

, и возвращает соответствующее значение метки времени Unix, предполагая эпоху 1970 и кодировку POSIX. Фактически,

[`time.gmtime()`](https://python-all.ru/3.1/library/time.html#time.gmtime)

и

[`timegm()`](https://python-all.ru/3.1/library/calendar.html#calendar.timegm)

являются обратными друг другу.

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

#### `calendar.day_name`

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

#### `calendar.day_abbr`

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

#### `calendar.month_name`

Массив, представляющий месяцы года в текущей локали. Следует стандартному соглашению: январь – месяц номер 1, поэтому длина массива равна 13, и

`month_name[0]`

– пустая строка.

#### `calendar.month_abbr`

Массив, представляющий сокращённые названия месяцев года в текущей локали. Следует стандартному соглашению: январь – месяц номер 1, поэтому длина массива равна 13, и

`month_abbr[0]`

– пустая строка.

> **См. также**
>
> **Модуль [`datetime`](https://python-all.ru/3.1/library/datetime.html#module-datetime)**
>
> Объектно-ориентированный интерфейс для дат и времени с функциональностью, аналогичной модулю
>
> [`time`](https://python-all.ru/3.1/library/time.html#module-time)
>
> .
>
> **Модуль [`time`](https://python-all.ru/3.1/library/time.html#module-time)**
>
> Низкоуровневые функции для работы со временем.