Displaying Calendars in Your Terminal

Unix andUnix-like operating systems such as macOS and Linux include acal command-line utility for displaying calendars in an interactive console:

$cal      May 2024Su Mo Tu We Th Fr Sa          1  2  3  4 5  6  7  8  9 10 1112 13 14 15 16 17 1819 20 21 22 23 24 2526 27 28 29 30 31

Python provides a similar tool, which allows you to run thecalendar module as a command-line script. To begin exploring the Pythoncalendar module, open up yourterminal program and enter the following command:

$python-mcalendar                                  2024      January                   February                   MarchMo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su 1  2  3  4  5  6  7                1  2  3  4                   1  2  3 8  9 10 11 12 13 14       5  6  7  8  9 10 11       4  5  6  7  8  9 1015 16 17 18 19 20 21      12 13 14 15 16 17 18      11 12 13 14 15 16 1722 23 24 25 26 27 28      19 20 21 22 23 24 25      18 19 20 21 22 23 2429 30 31                  26 27 28 29               25 26 27 28 29 30 31       April                      May                       JuneMo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su 1  2  3  4  5  6  7             1  2  3  4  5                      1  2 8  9 10 11 12 13 14       6  7  8  9 10 11 12       3  4  5  6  7  8  915 16 17 18 19 20 21      13 14 15 16 17 18 19      10 11 12 13 14 15 1622 23 24 25 26 27 28      20 21 22 23 24 25 26      17 18 19 20 21 22 2329 30                     27 28 29 30 31            24 25 26 27 28 29 30        July                     August                  SeptemberMo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su 1  2  3  4  5  6  7                1  2  3  4                         1 8  9 10 11 12 13 14       5  6  7  8  9 10 11       2  3  4  5  6  7  815 16 17 18 19 20 21      12 13 14 15 16 17 18       9 10 11 12 13 14 1522 23 24 25 26 27 28      19 20 21 22 23 24 25      16 17 18 19 20 21 2229 30 31                  26 27 28 29 30 31         23 24 25 26 27 28 29                                                    30      October                   November                  DecemberMo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su    1  2  3  4  5  6                   1  2  3                         1 7  8  9 10 11 12 13       4  5  6  7  8  9 10       2  3  4  5  6  7  814 15 16 17 18 19 20      11 12 13 14 15 16 17       9 10 11 12 13 14 1521 22 23 24 25 26 27      18 19 20 21 22 23 24      16 17 18 19 20 21 2228 29 30 31               25 26 27 28 29 30         23 24 25 26 27 28 29                                                    30 31

Runningpython -m calendar with no arguments outputs a full year’s calendar for the current year. To display the full calendar for a different year, pass in the integer representation of a year as the first argument of thecalendar command:

$python-mcalendar1989

To view a single month, pass in both a year and a month as the second parameter:

$python-mcalendar205407     July 2054Mo Tu We Th Fr Sa Su       1  2  3  4  5 6  7  8  9 10 11 1213 14 15 16 17 18 1920 21 22 23 24 25 2627 28 29 30 31

As you can see in these examples, thecalendar module can display calendars for both past and future dates. According to the official documentation, thecalendar module uses the currentGregorian calendar, extended indefinitely in both directions. It also uses theISO 8601 standard, which is an international standard for exchanging and communicating date and time-related data.

Now that you know how to display calendars in your terminal with Python, you can move on and explore other approaches to creating calendars as plain text orHTML markup representations.

Creating Text-Based Calendars

To generate plain text calendars, thecalendar module providescalendar.TextCalendar with methods to format and print monthly and yearly calendars.

TextCalendar.formatyear() accepts a single parameter for the year, like thecalendar command-line script. Try it out in yourPython REPL by executing the following code:

>>>importcalendar>>>text_calendar=calendar.TextCalendar()>>>text_calendar.formatyear(2024)'                                  2024\n\n      January    (...)'

Here, after instantiating atext_calendar instance ofcalendar.TextCalendar, you call.formatyear(2024), which returns the full calendar for 2024 as a multiline string. You can make that look nicer withTextCalendar.pryear(), which prints the year’s calendar in a more readable format:

>>>text_calendar.pryear(2024)                                  2024      January                   February                   MarchMo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su 1  2  3  4  5  6  7                1  2  3  4                   1  2  3 8  9 10 11 12 13 14       5  6  7  8  9 10 11       4  5  6  7  8  9 1015 16 17 18 19 20 21      12 13 14 15 16 17 18      11 12 13 14 15 16 1722 23 24 25 26 27 28      19 20 21 22 23 24 25      18 19 20 21 22 23 2429 30 31                  26 27 28 29               25 26 27 28 29 30 31       April                      May                       JuneMo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su 1  2  3  4  5  6  7             1  2  3  4  5                      1  2 8  9 10 11 12 13 14       6  7  8  9 10 11 12       3  4  5  6  7  8  915 16 17 18 19 20 21      13 14 15 16 17 18 19      10 11 12 13 14 15 1622 23 24 25 26 27 28      20 21 22 23 24 25 26      17 18 19 20 21 22 2329 30                     27 28 29 30 31            24 25 26 27 28 29 30        July                     August                  SeptemberMo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su 1  2  3  4  5  6  7                1  2  3  4                         1 8  9 10 11 12 13 14       5  6  7  8  9 10 11       2  3  4  5  6  7  815 16 17 18 19 20 21      12 13 14 15 16 17 18       9 10 11 12 13 14 1522 23 24 25 26 27 28      19 20 21 22 23 24 25      16 17 18 19 20 21 2229 30 31                  26 27 28 29 30 31         23 24 25 26 27 28 29                                                    30      October                   November                  DecemberMo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su    1  2  3  4  5  6                   1  2  3                         1 7  8  9 10 11 12 13       4  5  6  7  8  9 10       2  3  4  5  6  7  814 15 16 17 18 19 20      11 12 13 14 15 16 17       9 10 11 12 13 14 1521 22 23 24 25 26 27      18 19 20 21 22 23 24      16 17 18 19 20 21 2228 29 30 31               25 26 27 28 29 30         23 24 25 26 27 28 29                                                    30 31

As you can see,.pryear() requires the year as its first argument. It also provides some optional parameters to format the calendar’s display properties that look like this:.pryear(theyear, w=2, l=1, c=6, m=3).

Thew parameter sets the date column width,l is the number of lines per week,c sets the spacing between month columns, andm is the number of month columns.

To format and print a calendar for a single month as plain text,TextCalendar provides.formatmonth() and.prmonth(), which are similar to the yearly calendar methods. The.prmonth() method includes a second required parameter for the month as an integer, as well as two optional parameters:w for the width of the date columns, andl for the number of lines each week will use. Both of these optional parameters default to zero.

Working in the same console session as before, useTextCalendar.prmonth() to generate and print a plain text calendar for a single month like so:

>>>text_calendar.prmonth(2024,1)    January 2024Mo Tu We Th Fr Sa Su 1  2  3  4  5  6  7 8  9 10 11 12 13 1415 16 17 18 19 20 2122 23 24 25 26 27 2829 30 31

Now that you understand the basics of creating calendars in plain text, you can take it a step further and learn how to generate HTML calendars with Python to display on the web.

Generating and Styling HTML Calendars

If you need to create a calendar for a website, thecalendar module can also output calendars in HTML withcalendar.HTMLCalendar. Its methods.formatmonth() and.formatyear() work like their correspondingTextCalendar methods. But they replace the formatting parameters with the ability to generate CSS classes for styling HTML.

To use this class, create anhtml_calendar instance in your Python console and test it out by calling.formatyear():

>>>importcalendar>>>html_calendar=calendar.HTMLCalendar()>>>html_calendar.formatyear(2024)'<table border="0" cellpadding="0" cellspacing="0" class="year">\n<tr> (...)'

This will return a long Python string of HTML markup representing a calendar for the full year as an HTML table. To view this HTML calendar in a web browser, first use Python’sprint() function to output the string as HTML in your console:

>>>print(html_calendar.formatyear(2024))

Now copy the output of that command and paste it into a new file calledformatyear.html. Open that file with your computer’s web browser, and it should appear something like this:

As you can see, unstyled HTML tables are not exactly the most user-friendly way to display and read a calendar. Thankfully,HTMLCalendar.formatyearpage() allows you to include a CSS stylesheet by generating a year’s calendar as a full HTML page. This method’s optionalcss parameter defaults to a value of'calendar.css', referring to the name of the CSS file that will include the custom styles.

To create a new file containing a full HTML page generated by.formatyearpage(), use Python’s built-inopen() function. Then pass in'wb' as the second argument after the file name to write to the file inbinary mode:

>>>withopen("formatyearpage.html",mode="wb")asfile:...file.write(html_calendar.formatyearpage(2024))...

Here you use the Pythonwith statement to open your file, creating acontext manager object to ensure the file will always be closed even if an exception is thrown in thewith block. It’s important toalways close files opened by Python to preserve operating system resources and protect the files from data loss.

Now you should see a new file calledformatyearpage.html in the folder where you opened your Python console. Open that file, and you’ll see the markup for a full HTML page including this<link> tag:

<linkrel="stylesheet"type="text/css"href="calendar.css"/>

Create a new file calledcalendar.css in the same directory as theformatyearpage.html file and add the following CSS code:

body{font:16px"Helvetica Neue",Arial,Helvetica,Geneva,sans-serif;}table{margin:10px;}th,td{padding:5px;}

Now you can openformatyearpage.html with your web browser to see how you’ve made your calendar a bit more readable. You’ve added some padding around the date rows and columns, increased the margins of the month tables, and updated the HTML body’s font property:

In addition to the methods you’ve learned to create plain text and HTML calendars, thecalendar module also allows you to create calendars for different global locations, which you’ll explore next.

Formatting Calendars for Specific Locations

By default, all calendars generated by thecalendar module follow theEuropean convention of using Monday as the first day of the week. You can change this withCalendar.setfirstweekday(), which is available as an instance method forTextCalendar andHTMLCalendar.

Thecalendar module uses integers to represent days of the week, where zero is Monday, and six is Sunday, or it uses constants such ascalendar.MONDAY, which is defined for readability.

To change the first day of the week from Monday to Sunday for a plain text calendar, execute the following code in your Python console:

>>>importcalendar>>>text_calendar=calendar.TextCalendar()>>>text_calendar.prmonth(2024,1)    January 2024Mo Tu We Th Fr Sa Su 1  2  3  4  5  6  7 8  9 10 11 12 13 1415 16 17 18 19 20 2122 23 24 25 26 27 2829 30 31>>>text_calendar.setfirstweekday(calendar.SUNDAY)>>>text_calendar.prmonth(2024,1)    January 2024Su Mo Tu We Th Fr Sa    1  2  3  4  5  6 7  8  9 10 11 12 1314 15 16 17 18 19 2021 22 23 24 25 26 2728 29 30 31

Additionally, thecalendar module provides location-specific subclasses ofTextCalendar andHTMLCalendar that display the month and weekday names for a specific locale. Below is an example of how it would look if you usedcalendar.LocaleTextCalendar to output a calendar for the locale of Germany usingUTF-8 encoding:

>>>locale_calendar=calendar.LocaleTextCalendar(locale="de_DE.UTF-8")>>>locale_calendar.prmonth(2024,1)    Januar 2024Mo Di Mi Do Fr Sa So 1  2  3  4  5  6  7 8  9 10 11 12 13 1415 16 17 18 19 20 2122 23 24 25 26 27 2829 30 31

Your calendar now displays the month and day of the week abbreviations based on their German spelling.

Working With Other Python Calendar Functions and Methods

There are several additional methods available on allCalendar and subclass instances that allow you to work with lower-level calendar data and prepare that data for formatting. For simplicity’s sake, you’ll explore a few of them here usingTextCalendar.

TextCalendar.iterweekdays() returns an iterator of weekday number values for a calendar, beginning with the day set by.setfirstweekday() for the calendar:

>>>importcalendar>>>text_calendar=calendar.TextCalendar()>>>forday_numberintext_calendar.iterweekdays():...print(day_number)...0123456

In this code, the call totext_calendar.iterweekdays() returns agenerator object that you can then loop through to display each of the weekday numerical values for your calendar. If you were to change the first weekday to Sunday, it would have the following effect on the output of this method:

>>>text_calendar.setfirstweekday(calendar.SUNDAY)>>>forday_numberintext_calendar.iterweekdays():...print(day_number)...6012345

TextCalendar.itermonthdates() returns an iterator for all the days in a given month as Pythondatetime.date objects, including the days before the start of the month, and the days after the end of the month that are needed to complete those weeks.

Here’s an example of how you loop through the iterator and usedatetime.date.strftime() to print a readable version of eachdatetime.date object:

>>>fordayintext_calendar.itermonthdates(2024,1):...day.strftime("%m/%d/%Y")...'12/31/2023''01/01/2024''01/02/2024''01/03/2024''01/04/2024''01/05/2024''01/06/2024''01/07/2024''01/08/2024''01/09/2024''01/10/2024''01/11/2024''01/12/2024''01/13/2024''01/14/2024''01/15/2024''01/16/2024''01/17/2024''01/18/2024''01/19/2024''01/20/2024''01/21/2024''01/22/2024''01/23/2024''01/24/2024''01/25/2024''01/26/2024''01/27/2024''01/28/2024''01/29/2024''01/30/2024''01/31/2024''02/01/2024''02/02/2024''02/03/2024'

There are several methods similar toTextCalendar.itermonthdates() including.itermonthdays(), which return the days of the month as numbers, with zeros for the days needed to complete the first and last week of the month:

>>>fordayintext_calendar.itermonthdays(2024,1):...print(day)...012345678910111213141516171819202122232425262728293031000

In this output, the zeros at the beginning and end indicate the days in December and February that need to be included in the visual representation of the calendar to complete the first and last weeks of January.

Similarly,.itermonthdays2() returns a tuple for each day containing the day of the month and weekday number. Additional methods include the year, day of the week, and day of the month astuples:

>>>fordayintext_calendar.itermonthdays2(2024,1):...print(day)...(0, 6)(1, 0)(2, 1)(3, 2)(4, 3)(5, 4)(6, 5)(7, 6)(8, 0)(9, 1)(10, 2)(11, 3)(12, 4)(13, 5)(14, 6)(15, 0)(16, 1)(17, 2)(18, 3)(19, 4)(20, 5)(21, 6)(22, 0)(23, 1)(24, 2)(25, 3)(26, 4)(27, 5)(28, 6)(29, 0)(30, 1)(31, 2)(0, 3)(0, 4)(0, 5)

Here you can see the zero dates for December and February along with the numbered days of the week that they represent in the calendar as the second item of the tuples.

Thecalendar module also includes a couple of module-level functions for working specifically withleap years. The.isleap() functiondetermines if the given year is a leap year, and.leapdays() accepts two years as arguments, identifying the number of leap years between the two years:

>>>calendar.isleap(2024)True>>>calendar.leapdays(1980,2024)11

These are just a few of the lower-level functions and methods that thecalendar module provides for working with calendar-related data. In the next section, you’ll explore some ideas to go further in your learning and start using Python’s calendar-building capabilities in your own projects.

Next Steps

Now that you’ve got a sense of the core features of the Pythoncalendar module, check out the officialdocumentation to dig in a bit deeper into the additional features the module has to offer.

For example,calendar.HTMLCalendar provides several attributes for overriding and customizing the default CSS classes for more fine-grained control over your calendar’s appearance. And with the ability to subclass and extendHTMLCalendar itself, there’s a wide range of possibilities for building interactive web-based calendars with Python by overwriting its attributes and methods.

In addition to the variety of tools you’ve explored so far, thecalendar.Calendar base class provides many other methods for working with calendar data. These methods don’t return fully formatted calendars. Rather, they provide the pieces of data that are necessary to compose those calendars. So you can use them to prepare data for formatting in more complex or interactive calendar applications.

To complement your mastery of the Pythoncalendar module, take some time to dive into the details of the Pythondatetime andtime modules that can be combined to build richly featured programs that work with dates and times.

Conclusion

Calendars are a key component of many software programs and websites. With the Pythoncalendar module, there are a variety of options available for you to create, display, and customize calendars in your Python programs.

In this tutorial, you’ve learned:

• How todisplay calendars interactively by running thecalendar module as a command-line script in your terminal.
• How togenerate plain text and HTML calendars and use the various formatting and styling options for each type
• How to formatcalendars for specific locations and display conventions
• How to uselower-level functions and methods for working with calendar data

Now that you’re familiar with the range of functionality thecalendar module provides, it’s time to put that knowledge to use as you build your own calendar applications with Python!

Take the Quiz: Test your knowledge with our interactive “The Python calendar Module” quiz. You’ll receive a score upon completion to help you track your learning progress:

---

Interactive Quiz

The Python calendar Module

In this quiz, you'll test your understanding of the calendar module in Python. It'll evaluate your proficiency in manipulating, customizing, and displaying calendars directly within your terminal. By working through this quiz, you'll revisit the fundamental functions and methods provided by the calendar module.