Highlight today in colour in calendar's CLI output

[hugovk]

Feature or enhancement

In Python 3.13 we added colour output to the new REPL, tracebacks and doctest, and in 3.14 to unittest and test.regrtest, which can also be controlled with the PYTHON_COLORS, NO_COLOR and FORCE_COLOR environment variables:

• https://docs.python.org/3.14/whatsnew/3.14.html#unittest
• https://docs.python.org/3.14/using/cmdline.html#using-on-controlling-color

On macOS, the cal utility does something similar, but highlights today.

The calendar module has a CLI to print out a calendar to the terminal, but with no highlighting. Let's add it.

Linked PRs

• gh-128317: Highlight today in colour in calendar CLI output #128318
• gh-128317: Document calendar.TextCalendar.formatweek #128353
• [3.13] gh-128317: Document calendar.TextCalendar.formatweek (GH-128353) #128357
• [3.12] gh-128317: Document calendar.TextCalendar.formatweek (GH-128353) #128358
• gh-128317: Move CLI calendar highlighting to private class #129625

[encukou]

Thank you!
I hate to spoil the fun, but this breaks non-interactive usage (e.g. ./python -m calendar | less).
IMO, the default should look at sys.stdout.isatty() (not stderr). , and be off for formatweek (edit: oh, it already is).

[hugovk]

Thanks, good idea. Please see PR #128498.

[encukou]

Did you consider putting the feature in a private _CLIDemoCalendar class, which would override formatday?

(As I said I'd hate to spoil the fun. Please do take my opinions just as input for consideration.)

This feature adds some complexity to the API, but doesn't generalize to any other use cases -- for example, highlight weekends/holidays, not just the current day. Or highlight in HTML. Or highlight today in a pure text calendar, for example:

     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

calendar has a rather powerful (though perhaps dated) mechanism for configuration: subclassing and overriding methods like formatday. This feature adds an alternate mechanism, and I'm not sure it meshes well with the current API.

[joey-cramer]

Hi @hugovk,

I hope this is the right place to comment with my idea.

I am interested in if there are any plans or interest in adding week number to the python calendar?

According to this document (https://docs.python.org/3/library/time.html) %V for week is already a defined entity.

ISO 8601 week number (as a decimal number [01,53]). The first week of the year is the one that contains the first Thursday of the year. Weeks start on Monday.

[hugovk]

Hello! I think it could be useful. There's some potential complexity as some countries decide which is week 1 differently, but if we can follow ISO 8601 that would simplify things.

The calendar module docs (https://docs.python.org/3/library/calendar.html) says ISO 8601 is used for other calculations:

Zero and negative years are interpreted as prescribed by the ISO 8601 standard.

The calendar module also allows you to define set a different weekday as the first one od the week, we'd need to check how that affects things.

https://docs.python.org/3/library/calendar.html#calendar.setfirstweekday

Please could you post a proposal to the ideas forum?

https://discuss.python.org/c/ideas/6

Thanks!

[ZeroIntensity]

Using Hugo's dashboard: is this all done now?

[hugovk]

Using Hugo's dashboard:

🎉

is this all done now?

Thanks for the reminder, not yet: I was planning on giving Petr's suggestion a shot: #128317 (comment).

Did you consider putting the feature in a private _CLIDemoCalendar class, which would override formatday?

I hadn't, something like this? hugovk@8856aeb. It overrides formatday, formatmonth and formatyear.

There's quite a bit of duplication between each class's formatmonth and formatyear. We could deduplicate formatmonth like hugovk@05a5099, and perhaps formatyear like hugovk@738844f, but I'm not sure about those.

What do you think?

(As I said I'd hate to spoil the fun. Please do take my opinions just as input for consideration.)

Thank you, it's very welcome!

[encukou]

Thanks for considering it!

The first commit does seem cleaner to me than putting terminal colours directly in TextCalendar.
Perhaps add an __init__ with self.highlight_day = highlight_day?

[hugovk]

Good idea, please see PR #129625.

[serhiy-storchaka]

This change caused a regression. See #130665.