How to use Python calendar.Calendar()

Setting up

Before we can use the class, we need to import it first. There are two ways to do this. The first is by importing just the module and then using the dot operator to load the class and set up your Calendar object. You can do it like this:

import calendar
my_calendar = calendar.Calendar(firstweekday = 0)

You should use this method of importing when you intend to use the other classes in the module, such as TextCalendar and HTMLCalendar.

However, if you are going to be working with just the Calendar class, it’s best to import it this way:

from calendar import Calendar
my_calendar = Calendar(firstweekday = 0)

The firstweekday argument is an integer ranging from 0 to 6, and it determines which day of the week you want your month to start with. For example, if you set it to 0, your month will begin with Monday. If you set it to 6, your month will begin with Sunday, and so on. By default, this argument is set to 0 (Monday), but you can set it to any day you wish.

Using our pre-set examples of 2021 for the year argument and 6 (June) for the month argument, if the firstweekday argument is set to default (0), our calendar will look like this:

If we set the firstweekday argument to 3, it will look like this:

For the purposes of this article, we will set the firstweekday argument to 6 so that our month will begin on Sunday.

We are now ready to apply the methods to our Calendar object.

1. iterweekdays()

This method returns an iterator that gives you the weekday numbers starting from the number specified in the argument as the first weekday to the last weekday.

my_calendar = Calendar()

for weekday in my_calendar.iterweekdays():
    print(weekday, end = ", ")

The above code snippet will return 0, 1, 2, 3, 4, 5, 6,.

my_calendar = Calendar(firstweekday = 3)

for weekday in my_calendar.iterweekdays():
      print(weekday, end = ", ")

This one will return 3, 4, 5, 6, 0, 1, 2, .

2. itermonthdates(year, month)

This iterator takes year and month as arguments and returns all the days in that year-month combination, including the days of the preceding and succeeding months if they are part of that month’s first and last weeks respectively.

my_calendar = calendar.Calendar(firstweekday = 6)

for date in my_calendar.itermonthdates(2021, 6):
    print(date)

This code will print something like this:

As you can see, even though we have specified that we want the dates of June 2021, we still got May 30th and 31st, and July 1st, 2nd, and 3rd because they are part of June 2021’s full month, as shown in this screenshot of June 2021 taken from Google Calendar:

3. The itermonthdays(year, month) collection

3.1. itermonthdays(year, month)

This iterator behaves in a similar manner to itermonthdates(year, month) with the exception that it will return only the days of the specified month and year. In addition to that, the days of the preceding and succeeding months that are required to make it a full month are replaced with 0.

for date in my_calendar.itermonthdays(2021, 6):
    print(date, end = ", ")

The result of the above code will be:

Note how May 30 and 31, and July 1, 2, and 3 have been replaced with 0.

3.2. itermonthdays2(year, month)

This iterator behaves in a similar manner to its predecessor, except where itermonthdays(year, month) returned only the days of the specified month, itermonthdays2(year, month) returns a tuple that contains both the days of the month and their respective weekday numbers. As with its predecessor, this method replaces the days of the months before and after the specified month with 0.

for date in my_calendar.itermonthdays2(2021, 6):
    print(date)

3.3. itermonthdays3(year, month)

This iterator returns the year, month, and day of the full month in the form of a tuple.

for date in my_calendar.itermonthdays3(2021, 6):
    print(date)

3.4. itermonthdays4(year, month)

This returns a list of tuples containing the year, month, day, and weekday number of the specified month.

for date in my_calendar.itermonthdays4(2021, 6):
    print(date)

4. monthdatescalendar(year, month)

This iterator returns a list of lists where each list contains the dates of each full week of the specified month.

for date in my_calendar.monthdatescalendar(2021, 6):
    print(date)

5. The monthdayscalendar(year, month) collection

5.1. monthdayscalendar(year, month)

This iterator returns a list of lists where each list contains the days of the specified month. The days of the preceeding and succeeding months are replaced with 0.

for date in my_calendar.monthdayscalendar(2021, 6):
    print(date)

5.2. monthdays2calendar(year, month)

This iterator, like its predecessor, returns a list of lists containing the days of the specified month. However, unlike monthdayscalendar() which returned just the days of the month, monthdays2calendar() encloses each the day of the month and its respective weekday number in a tuple.

for date in my_calendar.monthdays2calendar(2021, 6):
    print(date)

6. yeardatescalendar(year, width=3)

This iterator is different from all the other iterators that we have covered and is a bit trickier to understand. It takes year and width as its arguments, where width denotes the number of months and is set to 3 by default. The result is three lists in one, i.e., a list of lists of lists. They can be broken down as follows:

• The innermost list contains the full weeks.
• The next list contains the lists of each full week for each month, including the days of the preceding and succeeding months.
• The outermost list contains the months specified by the width argument. For example, where width=3, the first list on this level will give data for January, February, and March. If width=6, the first list will contain data from January all the way to June.

Let’s understand this better using code.

results = [] 

for date in my_calendar.yeardatescalendar(2021, width = 2):
    results.append(date)

The first full week of January 2021 can be obtained through the following:

results[0][0][0]

To obtain the list of lists for the whole month of January, do:

results[0][0]

If you want to see the date entries for the first group of months as specified by width (in this case, width=2, which means we are looking at January and February), run the following:

results[0]

7. The yeardayscalendar(year, width=3) collection

7.1. yeardayscalendar(year, width=3)

This iterator behaves in the same way as yeardatescalendar(year, width=3) with the exception that, where the elements in the list of objects with the yeardatescalendar(year, width=3) method were in datetime format, objects in yeardayscalendar(year, width=3) are simply the days of each month. The days that belong to months preceding or succeeding a specific month are replaced with 0.

To get the first week of the first month of the year:

results = []

for date in my_calendar.yeardayscalendar(2021, width = 2):
    results.append(date)
    
results[0][0][0]

To get the list of weeks of the first month:

results[0][0]

To get the list of weeks for the first month range specified by width:

results[0]

7.2. yeardays2calendar(year, width=3)

This iterator is very similar to yeardayscalendar(year, width=3) with the exception that the elements in the lists are tuples containing both the days of the month and their respective weekday numbers.

To get the first week of the first month of the year:

results = []

for date in my_calendar.yeardays2calendar(2021, width = 2):
    results.append(date)
    
results[0][0][0]

To get the list of weeks of the first month:

results[0][0]

To get the list of weeks for the first month range specified by width:

results[0]

Conclusion

I hope this article has taught you all you need to know about using the Python Calendar class. Now you can create projects involving days, weeks, months, and years.

Until next time, happy learning!