Idea: Add ISO 8601 Week Numbers to Calendar CLI Output

Background

The calendar module in Python provides a CLI (python -m calendar) for generating text-based and HTML calendars. While the output is functional and customizable (e.g., adjusting the starting day of the week), it currently lacks an option to display ISO 8601 week numbers alongside the calendar days.

The inclusion of ISO 8601 week numbers would enhance the usability of the CLI for users who rely on week-based planning. ISO 8601 week numbering is already a core part of Python’s time module (e.g., %V for week number in strftime), and the calendar module adheres to ISO 8601 conventions in other respects, such as defining the first week of the year.

Proposal

I propose adding an option to the calendar CLI to include ISO 8601 week numbers in the text-based output. This could be implemented as an optional flag (e.g., --show-week-numbers or -w) that prefixes each week row with the corresponding ISO 8601 week number.

Benefits

  1. Enhanced Usability: Many users rely on week numbers for scheduling and planning, particularly in business and educational contexts.
  2. Alignment with Standards: ISO 8601 week numbers are a recognized standard, and Python already supports them in other modules.
  3. Consistency: The calendar module already follows ISO 8601 conventions for other calculations, such as interpreting zero and negative years.
  4. Minimal Impact: The proposed feature would be optional and would not affect the default behavior of the CLI.

Example Output

Current Output (python -m calendar):

January 2025
Mo Tu We Th Fr Sa Su
       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

Proposed Output with --show-week-numbers:

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

The “Wk” column shows the ISO 8601 week number for each row.

Compatibility and Implementation

This feature would be optional, preserving the current CLI behavior by default. Users could enable it with a simple flag. Internally, the implementation could leverage the time module’s %V specifier or calendar module’s setfirstweekday() method to ensure ISO 8601 compliance.

Conclusion

Adding week numbers to the calendar CLI output would provide a practical and user-friendly enhancement to the Python calendar module. I welcome feedback on this idea and am happy to discuss implementation details or alternatives.

2 Likes

Thanks for the proposal, I think this would be useful. I never really know where to look when needing to find the week number, an I often use this CLI when needing to check a calendar.

There’s some complexity as some countries decide which week to count as week 1 differently. And some start the week on different days.

Using ISO 8601 would simplify the matter, which starts weeks on Monday, and counts week 1 as the the week with the first Thursday of January in it. So it will always have at least 4 days.

However, this CLI has a --first-weekday option, allowing you to define which weekday to start each week with. How would this affect the output with --show-week-numbers?

I think that the calendar module should, first and foremost, provide the API to make customizations like this trivial to do.
“How to add week numbers” could be a great recipe in the docs. It could also work well in the demo CLI tool. But I don’t think it should be designed as a CLI feature.

3 Likes

Thank you for your input and question regarding the affect of --first-weekday option on ‘–show-week-numbers’.

When reading through the official calendar documentation https://docs.python.org/3/library/calendar.html I interpret it as if that Python is alligned with the ISO 8601 standard, yet that it for obvious reasons doesnt lock itself in the role of defining which standard is the universally true one.

Week numbering inherently relies on the assumption that Monday is the first day of the week. Changing the starting day of the week (e.g., to Sunday or Saturday) would create a conflict with the ISO 8601 week numbering system, which could lead to confusion or incorrect output.

The --first-weekday option is designed to let users format the calendar view for their locale or preferences. For example:

  • Sunday-first calendars (common in the US).
  • Saturday-first calendars (used in some Middle Eastern countries).

This affects how days are displayed in the calendar output but does not necessarily align with ISO 8601 week numbering conventions.

The Potential Conflict

If --show-week-numbers and --first-weekday are used together:

  • ISO 8601 rules should take precedence for week numbering. The week numbers should always reflect a Monday-first calculation, regardless of the visual arrangement of days in the calendar.
  • Changing the starting day with --first-weekday would affect only how days of the week are displayed, not the week number calculations.

In Python’s ecosystem and other tools:

  • ISO 8601 standards are typically upheld for week numbers, even if there are options to change the start day of the week for display purposes. Examples include:
    • pandas in Python, where week numbers are based on ISO 8601 regardless of locale settings.
    • Calendar tools like Google Calendar or Microsoft Outlook often let users set the start day for display but still adhere to ISO 8601 for week numbers.

Documentation

To prevent confusion, the documentation for --show-week-numbers and --first-weekday should explicitly state:

  • Week numbers always adhere to ISO 8601 conventions, regardless of the starting day of the week chosen with --first-weekday.
  • The --first-weekday option affects only the visual arrangement of the calendar days and does not impact the week number calculation.

This approach ensures:

  1. Consistency: Users can rely on week numbers conforming to the ISO 8601 standard, which is widely recognized and adopted globally.
  2. Flexibility: Users retain the ability to customize the calendar layout to fit their regional or personal preferences.

Please can you give an example of how it would display?

Here’s the default with the week starting on Monday, with ISO weeks:

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

Here’s with --first-weekday 6 to start the week on Sunday:

    January 2025
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

And here’s with ISO weeks (week 1 is 1-5 January, week 2 is 6-12 January, etc.). Would it display something like this?

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

This feels a bit odd to me. Do any other calendars mix ISO weeks with non-Monday starts, and how do they deal with it?

2 Likes

With a somewhat high level of confidence I believe that the different calendars use a version of the Gregorian calendar but once and twice ‘start of week’ moved.
[Countries where week days start with]
If taking a look at wikipedia’s (not best source, but at a lack of better), it showcases that there are 3 predominant and widely used week format systems all relying on Gregorian calendar meaning that they superficially utilize the same type of logic. Tan=Monday, Blue=Sunday, Green=Saturday.

And a tiny small dot in red which represents Maldives I believe, which allegedly use Friday, but I have no information nor verification on that.
It should also be noted that the map shown, I have compared it to other maps where the country coverage varies.
(https://upload.wikimedia.org/wikipedia/commons/thumb/e/e2/First_Day_of_Week_World_Map.svg/2880px-First_Day_of_Week_World_Map.svg.png)

In response to your question @ hugovk

ISO 8601 (Monday as the First Day)
January 2025

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

US Style (Sunday-first)
January 2025

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

Eastern (Saturday-first)
January 2025

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

Thrice removed (Friday-first)
January 2025

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

What I have found thus far has raised a large question all revolving around ‘what could the potential downsides be by having a visualisation’. This is a first time attempt at creating something for any coding language; base idea is to enrich the calendar feature positively and making life marginally easier.

Edit:
Added Friday-first calendar.

(Please could you edit your last reply to add code-formatting around the output with triple-backticks?)

Thanks, that looks much more sensible than week numbers always reflecting a Monday-first calculation, regardless of visual arrangement.

Friday first added for consistency.

As a side note:
After reviewing a larger amount of calendars in search of the Saturday and Friday variants, I fall short of finding any significant examples of such, yet I can not rule out their existence by searching in English only.

However I have observed plenty of Sunday and Monday/ISO 8691 variants, which only reinforce my belief that these do in fact exist.

Added to this, the Weeks article refers to ISO 8601, Middle Eastern and Western Traditional (US)
Wikipedia “Weeks” article

ISO 8601 starts on Monday, Week 1 must contain 1st Thursday or 4 days in that week.
Western(US) starts on Sunday, Week 1 must contain 1st Saturday.
Eastern starts on Saturday, Week 1 must contain 1st Friday.

By the way, now these are formatted and we can see them better, I don’t think we should show the end of December 2024 in the January 2025 month (just like we don’t right now).

1 Like

I entirely agree with this.
By the way, thank you for the feedback.