Python: как использовать модуль calendar для создания календаря

Введение

Python содержит стандартный модуль calendar, который позволяет программно получать данные календаря, печатать текстовые варианты месяцев и годов, а также выполнять служебные проверки (високосный год, количество дней и т. п.). Поскольку модуль встроен, дополнительная установка не требуется.

Ниже — практическое руководство с примерами и пояснениями, подходящее для начинающих и для быстрого справочного просмотра.

Быстрый старт с модулем calendar

Импортировать модуль просто:

import calendar

Обратите внимание: в примерах ниже используются стандартные функции модуля. Код можно запускать в интерпретаторе Python 3.

Вывести дни недели в виде заголовков

По умолчанию неделя начинается с понедельника. Функция weekheader(width) возвращает строку с сокращёнными названиями дней недели; параметр width задаёт длину сокращения (число символов).

Пример — установить длину сокращения 2:

import calendar
print(calendar.weekheader(2))  # сокращения по 2 символа
# Вывод: Mo Tu We Th Fr Sa Su

Если вы хотите, чтобы неделя начиналась с воскресенья, используйте setfirstweekday:

import calendar
calendar.setfirstweekday(calendar.SUNDAY)
print(calendar.weekheader(3))  # сокращения по 3 символа
# Вывод: Sun Mon Tue Wed Thu Fri Sat

Важно: setfirstweekday меняет глобальное состояние модуля для текущего процесса. Если вы используете calendar в большом приложении, учитывайте побочные эффекты.

Проверка, является ли год високосным

Функция isleap(year) возвращает True, если год високосный, иначе False:

import calendar
print(calendar.isleap(2023))
# Вывод: False

Подсчёт високосных дней в диапазоне лет

Функция leapdays(y1, y2) возвращает количество високосных дней между годами y1 и y2 (y1 включён, y2 не включён). Например:

import calendar
count = calendar.leapdays(2022, 2030)
print(f"Между 2022 и 2030 годами {count} високосных лет")
# Вывод: Между 2022 и 2030 годами 2 високосных лет

Первый день недели и индекс дня

Модуль использует индексацию дней недели: 0 — понедельник, 1 — вторник, …, 6 — воскресенье (при стандартной настройке).

import calendar
print(calendar.firstweekday())  # стандартно 0
# Вывод: 0

Функция weekday(year, month, day) возвращает индекс дня недели для конкретной даты:

import calendar
print(calendar.weekday(2021, 9, 1))  # год, месяц, число
# Вывод: 2

Здесь 2 соответствует среде (Wednesday) при стандартной индексации.

Функция monthrange(year, month) возвращает кортеж (weekday, days) — индекс первого дня месяца и число дней в месяце:

import calendar
print(calendar.monthrange(2021, 9))
# Вывод: (2, 30)

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

Функция month(year, month, w=0, l=0) возвращает строковое представление месяца. Параметры w и l задают ширину и высоту поля вывода для дат — их можно менять для форматирования вывода.

import calendar
print(calendar.month(theyear=2021, themonth=9, w=4, l=2))

Результат выглядит как текстовый календарь месяца.

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

Функция calendar(year, w=2, l=1, c=2, m=3) возвращает строковое представление всего года; параметры w, l управляют форматированием, c — число столбцов блоков месяцев, m — число месяцев в строке при печати (иногда используют m для макета).

import calendar
print(calendar.calendar(2022, w=2, l=1, c=2, m=6))

Попробуйте менять w, l, c и m, чтобы получить разные раскладки годового календаря.

Полезные приёмы и паттерны

• Локализованные заголовки дней: calendar.LocaleTextCalendar и calendar.LocaleHTMLCalendar позволяют получать названия дней и месяцев в нужной локали.
• Получение матриц месяца: метод monthcalendar(year, month) возвращает список недель, каждая — список из 7 чисел (0 для пустых дней). Удобно для построения пользовательских интерфейсов.

Пример использования monthcalendar:

import calendar
cal = calendar.monthcalendar(2021, 9)
for week in cal:
    print(week)
# Возможный вывод: [0, 0, 1, 2, 3, 4, 5] и т. п.

Этот формат хорошо подходит для отображения календаря в таблице: нули обозначают дни вне месяца.

Когда модуль calendar не подходит

Важно понимать ограничения:

• Для сложной локализации и работы с временными зонами лучше использовать библиотеки datetime + pytz/zoneinfo или более высокоуровневые библиотеки, такие как dateutil или Pendulum.
• Для веб-интерфейсов с интерактивностью или для мобильных приложений удобнее использовать готовые виджеты/календарные компоненты фреймворков (React DatePicker, FullCalendar и т. п.).
• Для генерации красиво стилизованных HTML-календарей может потребоваться подключать CSS/JS, calendar предлагает базовые HTML-генераторы, но они минимальны.

Альтернативные подходы

• dateutil — продвинутые расчёты дат (рецидивы, удобная работа с интервалами).
• pandas — если вы строите временные ряды и нужны мощные операции с датами.
• Pendulum — более удобный интерфейс для дат и временных зон по сравнению со стандартным datetime.

Быстрая методика (mini-methodology) для создания текстового календаря в приложении

1. Определите требуемую локаль и начало недели.
2. Выберите формат вывода: текст, HTML, матрица для UI.
3. Используйте monthcalendar для получения недель в виде списков.
4. Отформатируйте вывод (шаблонизатор/строки) и примените стили при необходимости.
5. Покройте тестами ключевые сценарии (январь/февраль, високосный год, переходы года).

Примеры тестовых случаев и критерии приёмки

Критерии приёмки:

• Корректный первый день недели для заданной локали.
• Правильное число дней в каждом месяце (включая февраль в високосных годах).
• Отображение пустых ячеек до и после месяца (нулевые значения в monthcalendar).

Тестовые случаи:

• monthrange(2020, 2) должно показать 29 дней.
• monthcalendar для марта 2021 не должно содержать отрицательных чисел.
• calendar.weekday возвращает 0–6 в ожидаемом диапазоне.

Короткий глоссарий

• monthcalendar: список недель месяца, каждая неделя — список из 7 чисел (0 = пустой слот).
• monthrange: (индекс первого дня, число дней) в месяце.
• isleap: проверяет високосный год.
• weekheader: строка с заголовками дней, ширина задаётся параметром.

Риски и рекомендации по безопасности

Модуль работает с локальными датами и не хранит чувствительные данные. Тем не менее:

• Если вы используете календарь для планирования событий с пользовательскими данными, валидируйте входные даты.
• При генерации HTML-календаря экранируйте пользовательские строки, чтобы избежать XSS.

Заключение

Модуль calendar полезен для быстрой генерации текстовых и базовых HTML-календарей, проверки високосных годов и получения структуры месяца. Для простых скриптов и утилит он часто закрывает задачу полностью; для сложных задач — комбинируйте с dateutil, pandas или библиотеками для временных зон.

Важно: экспериментируйте с параметрами форматирования (w, l, c, m) и используйте monthcalendar для интеграции с собственными интерфейсами. Удачной практики и счастливого кодинга!