calendar.Calendar.itermonthdays3(year, month) produces an iterator of tuples containing (year, month, day). It includes dates from the previous and next months when needed to complete the first and last calendar weeks. Unlike itermonthdays() and itermonthdays2(), these tuples have actual dates for the adjacent-month slots, not zeros.
For example, July 2020 starts on a Wednesday. A Monday-first calendar therefore begins with (2020, 6, 29) and (2020, 6, 30) before reaching July 1.
import calendar
my_cal= calendar.Calendar()
for x in my_cal.itermonthdays3(2020,7):
print(x)
Output excerpt:
(2020, 6, 29)
(2020, 6, 30)
(2020, 7, 1)
(2020, 7, 2)
(2020, 7, 3)
(2020, 7, 4)
(2020, 7, 5)
(2020, 7, 6)
(2020, 7, 7)
... (middle rows omitted) ...
(2020, 7, 30)
(2020, 7, 31)
(2020, 8, 1)
(2020, 8, 2)
The iterator starts on Monday, June 29, 2020 and ends on Sunday, August 2. Each value is a three-item tuple ordered as (year, month, day); this example preserves the original tutorial demonstration.
Run the July 2020 examples, change the first weekday, unpack the three-value tuples and solve date-grid exercises.
Uses only Python's standard library. Publish the notebook to GitHub before deploying these links.
Create a calendar.Calendar() instance and call itermonthdays3(year, month). The order is year first, month second. Week layout is controlled by firstweekday on the Calendar object. The method was introduced in Python 3.7.
| Parameter or value | Meaning | Example |
|---|---|---|
year | The requested calendar year | 2020 |
month | Month number from 1 through 12 | 7 |
firstweekday | Starting weekday of each displayed week; Monday = 0, Sunday = 6 | Calendar(firstweekday=3) |
| Returned value | A tuple of three integers: year, month, day | (2020, 7, 1) |
import calendar
items = calendar.Calendar().itermonthdays3(2020, 7)
first = next(items)
print(type(first).__name__)
print(first)
print('Year:', first[0], 'Month:', first[1], 'Day:', first[2])
Output:
tuple
(2020, 6, 29)
Year: 2020 Month: 6 Day: 29
You can access tuple items using indexes 0, 1, and 2 (year, month, day), although unpacking into named variables is often clearer.
The original lesson uses firstweekday=3, meaning Thursday. It changes the boundaries and the number of full-week rows without changing which date each tuple represents. See how to set the first weekday.
import calendar
my_cal= calendar.Calendar(firstweekday=3)
for x in my_cal.itermonthdays3(2020,7):
print(x)
Output excerpt:
(2020, 6, 25)
(2020, 6, 26)
(2020, 6, 27)
(2020, 6, 28)
(2020, 6, 29)
(2020, 6, 30)
(2020, 7, 1)
(2020, 7, 2)
(2020, 7, 3)
... (middle rows omitted) ...
(2020, 8, 2)
(2020, 8, 3)
(2020, 8, 4)
(2020, 8, 5)
The Thursday-first view begins on Thursday, June 25, and ends on Wednesday, August 5. It covers six complete weeks (42 date tuples).
This preserves the original example that reads the three tuple positions individually. The output uses commas because print() separates its arguments with spaces.
import calendar
my_cal= calendar.Calendar(firstweekday=3)
for x in my_cal.itermonthdays3(2020,7):
print('Year:',x[0],', Month : ',x[1],', Day : ',x[2])
Output excerpt:
Year: 2020 , Month : 6 , Day : 25
Year: 2020 , Month : 6 , Day : 26
Year: 2020 , Month : 6 , Day : 27
Year: 2020 , Month : 6 , Day : 28
Year: 2020 , Month : 6 , Day : 29
Year: 2020 , Month : 6 , Day : 30
Year: 2020 , Month : 7 , Day : 1
Year: 2020 , Month : 7 , Day : 2
Year: 2020 , Month : 7 , Day : 3
... (middle rows omitted) ...
Year: 2020 , Month : 8 , Day : 2
Year: 2020 , Month : 8 , Day : 3
Year: 2020 , Month : 8 , Day : 4
Year: 2020 , Month : 8 , Day : 5
The values are integers, so you can work with them directly rather than parsing text.
Python lets you unpack a three-item tuple into three variables. This reads more naturally than x[0], x[1], and x[2].
import calendar
cal = calendar.Calendar()
for year, month, day in cal.itermonthdays3(2020, 7):
if month == 7 and day <= 5:
print(f'{year}-{month:02d}-{day:02d}')
Output:
2020-07-01
2020-07-02
2020-07-03
2020-07-04
2020-07-05
Unlike itermonthdays2(), which uses zero placeholders for adjacent-month dates, this method gives the actual month and year for each surrounding date. You can distinguish them by comparing the tuple with the requested year and month.
import calendar
slots = list(calendar.Calendar().itermonthdays3(2020, 7))
other_months = [(y, m, d) for y, m, d in slots if (y, m) != (2020, 7)]
print(other_months)
print('Adjacent-month slots:', len(other_months))
Output:
[(2020, 6, 29), (2020, 6, 30), (2020, 8, 1), (2020, 8, 2)]
Adjacent-month slots: 4
Filter by both year and month. Checking the month alone can be misleading when a calendar spans a year boundary.
import calendar
slots = calendar.Calendar().itermonthdays3(2020, 7)
july_dates = [(y, m, d) for y, m, d in slots if (y, m) == (2020, 7)]
print('Number of July dates:', len(july_dates))
print('First date:', july_dates[0])
print('Last date:', july_dates[-1])
Output:
Number of July dates: 31
First date: (2020, 7, 1)
Last date: (2020, 7, 31)
The iterator is a flat sequence whose length is divisible by seven. Convert it to a list, then slice groups of seven to build calendar rows.
import calendar
slots = list(calendar.Calendar().itermonthdays3(2020, 7))
weeks = [slots[i:i + 7] for i in range(0, len(slots), 7)]
for number, week in enumerate(weeks, start=1):
print(f'Week {number}: {week[0]} to {week[-1]}')
Output:
Week 1: (2020, 6, 29) to (2020, 7, 5)
Week 2: (2020, 7, 6) to (2020, 7, 12)
Week 3: (2020, 7, 13) to (2020, 7, 19)
Week 4: (2020, 7, 20) to (2020, 7, 26)
Week 5: (2020, 7, 27) to (2020, 8, 2)
The tuple consists of integers. Use formatted strings to display the month and day with leading zeros, which is useful for schedules and filenames.
import calendar
slots = calendar.Calendar().itermonthdays3(2020, 7)
for year, month, day in slots:
if month == 7 and day <= 3:
print(f'{year:04d}-{month:02d}-{day:02d}')
Output:
2020-07-01
2020-07-02
2020-07-03
For dates within the supported datetime.date range (years 1–9999), use tuple unpacking with date(*entry) to access date arithmetic and formatting methods. The iterator itself returns integer tuples, not date objects.
import calendar
from datetime import date
slots = list(calendar.Calendar().itermonthdays3(2020, 7))
first_date = date(*slots[0])
last_date = date(*slots[-1])
print(first_date, 'to', last_date)
print('Calendar span:', (last_date - first_date).days + 1, 'days')
Output:
2020-06-29 to 2020-08-02
Calendar span: 35 days
Use date.weekday() and calendar.day_name to give a weekday name to the returned date tuples. Weekday numbering remains Monday = 0 through Sunday = 6 regardless of the calendar’s first weekday.
import calendar
from datetime import date
for year, month, day in calendar.Calendar().itermonthdays3(2020, 7):
if month == 7 and 1 <= day <= 5:
weekday_name = calendar.day_name[date(year, month, day).weekday()]
print(day, weekday_name)
Output:
1 Wednesday
2 Thursday
3 Friday
4 Saturday
5 Sunday
Set firstweekday=calendar.SUNDAY to render weeks starting on Sunday. This modifies the ordering of the date tuples, not the weekday associated with any particular date.
import calendar
cal = calendar.Calendar(firstweekday=calendar.SUNDAY)
slots = list(cal.itermonthdays3(2020, 7))
print('First week:', slots[:7])
print('Number of weeks:', len(slots) // 7)
Output:
First week: [(2020, 6, 28), (2020, 6, 29), (2020, 6, 30), (2020, 7, 1), (2020, 7, 2), (2020, 7, 3), (2020, 7, 4)]
Number of weeks: 5
Each month view has enough week rows to include every date of the month, including the complete first and last weeks. The number of rows can change when you change firstweekday.
import calendar
for weekday in (calendar.MONDAY, calendar.THURSDAY):
slots = list(calendar.Calendar(firstweekday=weekday).itermonthdays3(2020, 7))
print(calendar.day_name[weekday] + '-first:',
len(slots) // 7, 'weeks;', len(slots), 'dates')
Output:
Monday-first: 5 weeks; 35 dates
Thursday-first: 6 weeks; 42 dates
The returned year and month make the method useful for calendars crossing December and January. For a December 2024 month view, some padding dates fall in January 2025.
import calendar
slots = list(calendar.Calendar().itermonthdays3(2024, 12))
print('First:', slots[0])
print('Last:', slots[-1])
print('Dates from 2025:', [x for x in slots if x[0] == 2025])
Output:
First: (2024, 11, 25)
Last: (2025, 1, 5)
Dates from 2025: [(2025, 1, 1), (2025, 1, 2), (2025, 1, 3), (2025, 1, 4), (2025, 1, 5)]
Because it reads the real Gregorian calendar, this method includes February 29 in leap years. The surrounding dates may belong to January or March, depending on the week start.
import calendar
slots = list(calendar.Calendar().itermonthdays3(2024, 2))
february = [(y, m, d) for y, m, d in slots if (y, m) == (2024, 2)]
print('Leap year:', calendar.isleap(2024))
print('Days in February:', len(february))
print('Last February date:', february[-1])
Output:
Leap year: True
Days in February: 29
Last February date: (2024, 2, 29)
Choose the method based on the data you need: day numbers only, weekday numbers, full year-month-day tuples, or full datetime.date objects. Python 3.7 and newer also provides itermonthdays4(), which adds a weekday number.
| Method | Item returned | Adjacent-month dates |
|---|---|---|
itermonthdays() | day integer | Day is zero |
itermonthdays2() | (day, weekday) | Day is zero |
itermonthdays3() | (year, month, day) | Full numeric date |
itermonthdays4() | (year, month, day, weekday) | Full numeric date |
itermonthdates() | datetime.date | Real date object |
import calendar
cal = calendar.Calendar()
print('days: ', next(cal.itermonthdays(2020, 7)))
print('days2:', next(cal.itermonthdays2(2020, 7)))
print('days3:', next(cal.itermonthdays3(2020, 7)))
print('days4:', next(cal.itermonthdays4(2020, 7)))
print('dates:', next(cal.itermonthdates(2020, 7)))
Output:
days: 0
days2: (0, 0)
days3: (2020, 6, 29)
days4: (2020, 6, 29, 0)
dates: 2020-06-29
An iterator yields values in sequence. Once it has been exhausted, iterating over the same object again produces no values. To reuse a month view, create a fresh iterator or convert its contents to a list.
import calendar
items = calendar.Calendar().itermonthdays3(2020, 7)
first_pass = list(items)
second_pass = list(items)
print('First pass:', len(first_pass))
print('Second pass:', len(second_pass))
Output:
First pass: 35
Second pass: 0
A practical use is to create a date label for each Monday–Friday in the selected month. This example lists a few working dates from July 2020. Public holidays are not included in this simple rule.
import calendar
from datetime import date
plan = []
for year, month, day in calendar.Calendar().itermonthdays3(2020, 7):
if (year, month) == (2020, 7) and day <= 8:
current = date(year, month, day)
if current.weekday() < 5:
plan.append(f'{current.isoformat()} ({current:%a}): Review tasks')
for item in plan:
print(item)
Output:
2020-07-01 (Wed): Review tasks
2020-07-02 (Thu): Review tasks
2020-07-03 (Fri): Review tasks
2020-07-06 (Mon): Review tasks
2020-07-07 (Tue): Review tasks
2020-07-08 (Wed): Review tasks
itermonthdays3() returns integers and is not limited to the datetime.date year range of 1–9999. This matters for historical or extended-year calendars, although converting those tuples to datetime.date may fail.
import calendar
slots = list(calendar.Calendar().itermonthdays3(10000, 1))
print('First tuple:', slots[0])
print('Last tuple:', slots[-1])
print('Total slots:', len(slots))
Output:
First tuple: (9999, 12, 27)
Last tuple: (10000, 2, 6)
Total slots: 42
The month must be 1 through 12. Python raises calendar.IllegalMonthError if an invalid month is requested. Validate input before building the calendar, or handle the exception.
import calendar
try:
slots = list(calendar.Calendar().itermonthdays3(2020, 13))
except calendar.IllegalMonthError:
print('Choose a month between 1 and 12.')
Output:
Choose a month between 1 and 12.
(year, month, day), not (day, month, year).itermonthdays() and itermonthdays2().(year, month) to exclude padding dates.firstweekday=3 means Thursday; it does not change the three values stored in each tuple.list(...) if you need indexes or repeated passes.datetime.date(*entry) only for valid years 1–9999.itermonthdays3() requires Python 3.7 or later.Open the Colab practice notebook to run examples and check your solutions. Try these exercises before revealing the notebook checks:
An iterator that yields tuples containing three integers: (year, month, day), including the adjacent-month dates needed for complete weeks.
itermonthdays2() gives (day, weekday) tuples with zero placeholders outside the selected month. itermonthdays3() gives full numeric dates for every calendar slot.
No. It changes the order in which the calendar weeks begin and can change how many full weeks are returned. Each date remains the same Gregorian date.
Yes. Use itermonthdays4() to get (year, month, day, weekday) tuples, or convert tuples to datetime.date objects and call weekday().
Yes. Wrap it with list(), for example list(calendar.Calendar().itermonthdays3(2020, 7)).
Yes. The calendar module is part of Python’s standard library and requires no installation.
date objects.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.