کار با ماژول Calendar در پایتون

سطح مقدماتی (Beginner Level)

ماژول calendar در پایتون یکی از کتابخانه‌های استاندارد است که به شما اجازه می‌دهد تقویم‌های متنی یا HTML تولید کنید و محاسبات ساده‌ای مانند تشخیص سال کبیسه یا روز هفته را انجام دهید. برخلاف ماژول datetime که روی "زمان حال" یا "اختلاف زمانی" تمرکز دارد، این ماژول روی ساختار تقویم تمرکز دارد.

۱. نمایش سریع تقویم (سالانه و ماهانه)

ساده‌ترین کاربرد این ماژول، چاپ تقویم در خروجی استاندارد است.

مثال اول: چاپ تقویم یک ماه خاص

برای چاپ تقویم یک ماه، از تابع month() استفاده می‌کنیم که خروجی را به صورت رشته (String) برمی‌گرداند.

مثال دوم: چاپ کل تقویم سال

اگر بخواهید کل ۱۲ ماه سال را یکجا ببینید.

مثال سوم: چاپ مستقیم (بدون print)

توابع prmonth و prcal مستقیماً خروجی را چاپ می‌کنند و نیازی به تابع print ندارند.

۲. بررسی سال‌های کبیسه (Leap Years)

مدیریت سال‌های کبیسه (سالی که ۳۶۶ روز است) در محاسبات مالی و علمی بسیار مهم است.

مثال اول: بررسی یک سال خاص

تابع isleap() مقدار True یا False برمی‌گرداند.

مثال دوم: شمارش تعداد سال‌های کبیسه در یک بازه

تابع leapdays(y1, y2) تعداد سال‌های کبیسه را در بازه [y1, y2) (شامل اولی، بدون دومی) برمی‌گرداند.

۳. پیدا کردن روز هفته (Weekday)

برای اینکه بفهمید یک تاریخ خاص (مثلاً تاریخ تولد) چه روزی از هفته بوده است. در پایتون به صورت پیش‌فرض:

• 0 = دوشنبه (Monday)
• 6 = یکشنبه (Sunday)

مثال اول: روز هفته یک تاریخ خاص

مثال دوم: لیست کامل روزها

دسترسی به نام روزها و ماه‌ها برای بومی‌سازی یا نمایش.

سطح پیشرفته (Professional Level)

در سطح حرفه‌ای، ما به جای استفاده از توابع ساده، از کلاس‌ها (Classes) و Iterators موجود در ماژول calendar استفاده می‌کنیم تا داده‌ها را پردازش کنیم، خروجی HTML بسازیم یا سیستم‌های رزرو وقت (Booking Systems) ایجاد کنیم.

۱. کلاس TextCalendar و تغییر روز شروع هفته

در بسیاری از کشورها (مثل ایران یا آمریکا)، هفته با دوشنبه شروع نمی‌شود. کلاس TextCalendar به ما اجازه می‌دهد روز اول هفته را تعیین کنیم.

مثال اول: شروع هفته با یکشنبه (Sunday)

مثال دوم: شروع هفته با شنبه (برای تقویم‌های کاری خاص)

۲. دریافت داده‌های خام با monthrange

تابع monthrange(year, month) یکی از کاربردی‌ترین توابع برای برنامه‌نویسان است. این تابع یک تاپل برمی‌گرداند: (روز_اول_هفته, تعداد_کل_روزهای_ماه). از این تابع برای حلقه‌ها و اعتبارسنجی ورودی کاربر استفاده می‌شود.

مثال اول: اطلاعات ماه فوریه (بررسی کبیسه بودن غیرمستقیم)

مثال دوم: استفاده در منطق برنامه

فرض کنید می‌خواهید آخرین روز ماه را پیدا کنید.

# Static Snippet: Logic for getting last date
import calendar
from datetime import date

def get_last_day_of_month(year, month):
    _, last_day = calendar.monthrange(year, month)
    return date(year, month, last_day)

۳. پیمایش روزها (Iterating)

به جای چاپ تقویم، گاهی نیاز دارید روی روزها "لوپ" بزنید (مثلاً برای ساخت تقویم گرافیکی در Django یا Tkinter). متدهای itermonthdays و itermonthdates این کار را انجام می‌دهند.

مثال اول: itermonthdays (شامل روزهای 0)

این متد روزهای ماه را برمی‌گرداند. روزهایی که متعلق به ماه قبل یا بعد هستند (برای پر کردن هفته) را با 0 نمایش می‌دهد.

مثال دوم: itermonthdates (شیء datetime.date)

اگر به جای عدد، خودِ آبجکت تاریخ را بخواهید (برای مقایسه دقیق زمانی).

۴. تولید تقویم HTML

برای برنامه‌های تحت وب (مثل Flask یا Django)، کلاس HTMLCalendar می‌تواند مستقیماً کد جدول HTML تولید کند.

مثال اول: تولید جدول ساده

مثال دوم: سفارشی‌سازی CSS Class

شما می‌توانید متدهای این کلاس را بازنویسی (Override) کنید تا کلاس‌های CSS اختصاصی خود را اعمال کنید.

# Static: Customizing HTML Calendar
import calendar

class MyCustomCalendar(calendar.HTMLCalendar):
    def formatday(self, day, weekday):
        if day == 0:
            return '<td class="noday">&nbsp;</td>' # روز خالی
        else:
            return f'<td class="day-style">{day}</td>'

html_gen = MyCustomCalendar()
print(html_gen.formatmonth(2025, 1))