Использование модуля calendar в Python

Краткое введение

Модуль calendar прост в использовании. Он входит в стандартную поставку Python, поэтому ничего дополнительно устанавливать не нужно. Внутри модуля есть функции и классы для работы с днями недели, месяцами и годами — текстовые представления календарей, утилиты для проверки високосных лет и многое другое.

Определение: високосный год — год, содержащий 29 февраля.

Как начать: импорт и базовый пример

Откройте ваш .py-файл и импортируйте модуль:

import calendar

Теперь можно вызывать функции модуля напрямую.

Показать дни недели

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

Пример: короткие двухсимвольные аббревиатуры:

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))  # использовать трёхсимвольные аббревиатуры

Ожидаемый вывод:

Sun Mon Tue Wed Thu Fri Sat

Важно: setfirstweekday меняет глобальное состояние модуля в рамках текущего интерпретатора.

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

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

import calendar
print(calendar.isleap(2023))  # проверяем 2023 год

Ожидаемый вывод:

False

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

Функция leapdays(y1, y2) считает количество високосных годов в полуоткрытом диапазоне [y1, y2). Параметры — целые годы, где y1 включается, а y2 — нет.

Пример: количество високосных годов с 2022 по 2029 включительно (вызовем с 2022,2030):

import calendar
checkleap = calendar.leapdays(2022, 2030)
print("There are {} leap days between 2022 and 2030".format(checkleap))

Ожидаемый вывод:

There are 2 leap days between 2022 and 2030

Узнать индекс первого дня недели и номер дня

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

import calendar
print(calendar.firstweekday())

Ожидаемый вывод (по умолчанию):

0

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

import calendar
# пример: первый день сентября 2021 года
print(calendar.weekday(2021, 9, 1))  # принимает год, месяц, число

Ожидаемый вывод:

2

Значение 2 означает среду (по нумерации 0=понедельник).

Также полезна функция monthrange(year, month), которая возвращает кортеж (weekday_of_first_day, number_of_days_in_month):

import calendar
print(calendar.monthrange(2021, 9))

Ожидаемый вывод:

(2, 30)

Первое значение — индекс дня недели для 1-го числа месяца, второе — количество дней в месяце.

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

Функция month(theyear, themonth, w=0, l=0) возвращает текстовый календарь для указанного месяца. Параметры w и l — опциональные: w контролирует ширину колонки, l — число строк на день.

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

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

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

Функция calendar(year, w=2, l=1, c=6, m=3) возвращает строку с календарём на весь год. Параметры:

• w — ширина столбца (символов);
• l — высота строки для даты (число строк на день);
• c — число строк блоков месяцев (количество строк по вертикали при группировке месяцев);
• m — число столбцов блоков месяцев (сколько месяцев в строке).

Пример:

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

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

Практическая шпаргалка (cheat sheet)

• calendar.weekheader(width) — строка заголовков дней.
• calendar.setfirstweekday(calendar.SUNDAY) — установить воскресенье как первый день.
• calendar.firstweekday() — вернуть индекс первого дня.
• calendar.isleap(year) — True, если год високосный.
• calendar.leapdays(y1, y2) — число високосных годов в диапазоне [y1, y2).
• calendar.weekday(y, m, d) — индекс дня недели для даты.
• calendar.monthrange(y, m) — (weekday_of_first_day, days_in_month).
• calendar.month(y, m, w=…, l=…) — текстовый календарь месяца.
• calendar.calendar(y, w=…, l=…, c=…, m=…) — текстовый календарь года.

Альтернативные подходы и когда модуль calendar не подходит

• Если вам нужен более мощный парсинг дат, работа с часовыми поясами и человеко-понятные методы, используйте сторонние библиотеки: dateutil, Pendulum или Arrow.
• Для веб‑интерфейсов стоит генерировать HTML-календарь и стилизовать его — модуль calendar поддерживает HTML-форматирование через HTMLCalendar.
• Модуль calendar не хранит события и не подходит для управления расписаниями приложений. Для этого используйте базы данных и специализированные библиотеки (например, icalendar).

Мини‑методология: как быстро сделать CLI-календарь

1. Определите входы: год, месяц (опционально), формат вывода (текст/HTML).
2. Проверка валидности: год — целое положительное, месяц — 1..12.
3. Используйте calendar.month() или calendar.calendar() для формирования строки.
4. Добавьте параметры форматирования (w, l, c, m) как опции CLI.
5. Тестируйте на пограничных датах: февраль невисокосного и високосного года.

Ролевые чек‑листы

Для разработчика:

• Проверить поведение при смене первого дня недели.
• Убедиться, что вывод корректно кодируется (UTF-8).
• Добавить тесты на leap years и monthrange.

Для преподавателя:

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

Для изучающего:

• Попробовать изменить параметры w и l и посмотреть, как меняется формат.
• Сравнить calendar.isleap с собственной функцией на основе правил високосного года.

Тестовые сценарии / критерии приёмки

• Для 2020 года isleap(2020) возвращает True.
• monthrange(2021, 2) возвращает (x, 28) для невисокосного года и (x, 29) для високосного.
• При setfirstweekday(calendar.SUNDAY) weekheader(3) начинается с Sun.
• calendar.calendar(2000) успешно возвращает строку и содержит 12 заголовков месяцев.

Подсказки по безопасности и приватности

Модуль calendar не работает с личными данными сам по себе. Однако при визуализации событий убедитесь, что конфиденциальные метаданные не попадают в лог-файлы и что права доступа к файлам вывода настроены корректно.

Часто задаваемые вопросы

Как вывести календарь в HTML?

Модуль предоставляет HTMLCalendar. Создайте экземпляр calendar.HTMLCalendar(firstweekday) и вызовите method formatmonth(year, month) или formatyear(year).

Можно ли получить локализованные названия дней недели?

Библиотека calendar использует английские сокращения по умолчанию. Для локализованных названий применяйте модуль locale и дополнительные форматирование через datetime.strftime.

Как получить список дат выходных в месяце?

Используйте monthrange(), а затем обходите числа от 1 до days_in_month и проверяйте calendar.weekday(year, month, day) на значения индексов выходных (например, 5 и 6 для субботы/воскресенья).

Ключевые выводы

• Модуль calendar прост и полезен для форматированного текстового вывода календарей.
• Он хорош для скриптов, анализа дат и быстрой генерации календарей, но не для управления событиями.
• Для расширенных задач рассмотрите dateutil, Pendulum или интеграцию с базой данных.

Спасибо за внимание и удачного кодинга!