Python calendar.itermonthdays(): Generate Month Calendar Grids

The calendar.Calendar().itermonthdays(year, month) method returns an iterator yielding day numbers for an entire calendar month. Days that fall outside the specified month (belonging to the previous or next month) are returned as 0 to pad full 7-day calendar weeks.

Parent Guide: To explore formatting full HTML tables, leap years, and weekday constants, visit the Python Calendar Module guide.

Show Table of Contents ↓

Syntax & Parameters 🔝

The itermonthdays() method is an instance method of the calendar.Calendar class:

import calendar

cal = calendar.Calendar(firstweekday=0)
day_iterator = cal.itermonthdays(year, month)

Parameter	Type	Required?	Description
`year`	`int`	Yes	The four-digit year (e.g. `2026`).
`month`	`int`	Yes	The month number (integer from `1` to `12`).

Return Value: Returns an iterator that yields integers. Each integer represents a day of the month (1–31), or 0 if the day belongs to the preceding or succeeding month to complete a full 7-day week row.

Why Are Days Outside the Month Padded with 0? 🔝

In standard wall calendars and scheduling user interfaces, a month is displayed as a grid with 7 columns (Sunday through Saturday, or Monday through Sunday). Because months rarely start on the very first column or end cleanly on the last column, the grid needs filler cells.

itermonthdays() yields 0 for these filler positions. When rendering a web UI, Tkinter window, or console table, any day equal to 0 can be rendered as an empty cell or a muted gray date.

Basic Example: Iterating Over a Month 🔝

Let's inspect the days returned for October 2026 (a month with 31 days starting on a Thursday):

import calendar

# Default Calendar starts with Monday (firstweekday=0)
cal = calendar.Calendar()
days = list(cal.itermonthdays(2026, 10))

print("Total entries yielded:", len(days))
print("All values:", days)

Expected Output

Total entries yielded: 35
All values: [0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 0]

Notice the three leading zeros: October 1, 2026 is a Thursday, so Monday, Tuesday, and Wednesday of that first week are represented by 0. The trailing zero pads the final week up to Sunday.

Configuring the First Day of the Week 🔝

By default, calendar.Calendar() starts weeks on Monday (0). You can configure it to start on Sunday (6) or any other weekday by passing firstweekday to the class constructor:

import calendar

# Configure Sunday as the start of the week
cal_sunday = calendar.Calendar(firstweekday=calendar.SUNDAY)
days_sun = list(cal_sunday.itermonthdays(2026, 10))

print("Sunday-first first week:", days_sun[:7])

Expected Output

Sunday-first first week: [0, 0, 0, 0, 1, 2, 3]

Chunking Days into 7-Day Calendar Rows 🔝

Because the total count of returned days is guaranteed to be a multiple of 7, you can cleanly slice the iterator into 7-day weekly rows:

import calendar

cal = calendar.Calendar(firstweekday=calendar.SUNDAY)
days = list(cal.itermonthdays(2026, 10))

# Split into 7-day chunks
weeks = [days[i:i + 7] for i in range(0, len(days), 7)]

print("Su Mo Tu We Th Fr Sa")
for week in weeks:
    print(" ".join(f"{d:2d}" if d > 0 else "  " for d in week))

Expected Output

Su Mo Tu We Th Fr Sa
             1  2  3
 4  5  6  7  8  9 10
11 12 13 14 15 16 17
18 19 20 21 22 23 24
25 26 27 28 29 30 31

The itermonthdays Family Comparison 🔝

Python's Calendar class provides several sibling iterator methods. Choose the one that matches your desired data structure:

Method	Yielded Item Type	Sample Yielded Value	Padding for Outside Days
`itermonthdays()`	`int`	`15`	`0`
`itermonthdays2()`	`tuple[int, int]`	`(15, 3)` (day, weekday)	`(0, weekday)`
`itermonthdays3()`	`tuple[int, int, int]`	`(2026, 10, 15)` (year, month, day)	Actual dates of outside month
`itermonthdays4()`	`tuple[int, int, int, int]`	`(2026, 10, 15, 3)`	Actual dates + weekday
`itermonthdates()`	`datetime.date`	`date(2026, 10, 15)`	Actual `date` objects of outside month

Hands-on Exercise: HTML/Table Calendar Grid Generator with Assertions 🔝

Let's construct a calendar grid generator function that takes a year and month, divides the days into 7-day rows, and returns a verified matrix structure with self-checking assertions:

Python Exercise: Month Calendar Matrix Generator

import calendar

def generate_calendar_matrix(year, month, sunday_start=True):
    start_weekday = calendar.SUNDAY if sunday_start else calendar.MONDAY
    cal = calendar.Calendar(firstweekday=start_weekday)
    
    days_list = list(cal.itermonthdays(year, month))
    # Group into 7-day week sublists
    weeks_matrix = [days_list[i:i + 7] for i in range(0, len(days_list), 7)]
    return weeks_matrix

# Test October 2026 (starts on Thursday)
oct_matrix = generate_calendar_matrix(2026, 10, sunday_start=True)

# Unit Assertions
assert len(oct_matrix) == 5  # 5 full weeks
assert len(oct_matrix[0]) == 7
assert oct_matrix[0] == [0, 0, 0, 0, 1, 2, 3]  # Thu=1, Fri=2, Sat=3
assert oct_matrix[-1][0] == 25                     # Final Sunday is 25
assert oct_matrix[-1][6] == 31                     # Final Saturday is 31

print("Generated Matrix Rows:", len(oct_matrix))
print("All calendar matrix unit assertions passed successfully!")

Practice in Google Colab & GitHub 🔝

Open in Google Colab View on GitHub

Run all itermonthdays() examples interactively, test different firstweekday configurations, and verify the calendar grid generator with unit assertions directly in Google Colab.

Python Calendar Module Overview — Complete guide to calendars, leap years, and month formatting.
itermonthdays2() Method — Return day numbers paired with weekday index tuples.
itermonthdates() Method — Yield full datetime.date objects for calendar months.
calendar.firstweekday() Function — Query and set the starting day of the week.
Python datetime Module — Working with dates, times, and timedeltas in Python.

Calendar Module itermonthdays2() itermonthdates() Python Tutorials

Subhendu Mohapatra

Author & Instructor at plus2net

I write and maintain practical tutorials on Python, PHP, SQL, JavaScript, HTML, jQuery, and web development at plus2net. The tutorials focus on clear explanations, working examples, and code that readers can test and adapt while learning.

About the author Watch on YouTube

Connect: