Docs: the calendar module lacks documentation for several APIs

[erlend-aasland]

But first than documenting these particular method or two, we should decide whether they should be documented at all.

See past issues with the calendar module. There may be requests for undocumented methods, and some of them may even be rejected already. I think this has already been discussed.

Originally posted by @serhiy-storchaka in #108192 (comment)

Linked PRs

• GH-108202: Document calendar exceptions #108398
• [3.12] GH-108202: Document calendar exceptions (GH-108398) #108467
• [3.11] GH-108202: Document calendar exceptions (GH-108398) #108468
• gh-108202: calendar: Document prweek #108466
• GH-108202: Combine documentation of calendar constants #108492
• [3.12] GH-108202: Combine documentation of calendar constants (GH-108492) #108579
• GH-108202: Document calendar's command-line interface #109020
• [3.12] GH-108202: Document calendar's command-line interface (GH-109020) #109030
• [3.11] GH-108202: Document calendar's command-line interface (GH-109020) #109031
• gh-108202: calendar: Document getfirstweekday and setfirstweekday #127579
• gh-108202: calendar: Document TextCalendar methods #127608

[AA-Turner]

(status as at 21c0844)

Defined in __all__ but not documented

• IllegalMonthError (GH-108202: Document calendar exceptions #108398)
• IllegalWeekdayError (GH-108202: Document calendar exceptions #108398)
• JANUARY, etc (These are documented as Month.X, but also exist in the module scope) (GH-108202: Combine documentation of calendar constants #108492)
• MONDAY, etc (These are documented as Day.X, but also exist in the module scope) (GH-108202: Combine documentation of calendar constants #108492)

Undocumented classes

• different_locale (should not be documented, helper class)

Undocumented functions

• prweek()
• week()
• format()
• formatstring()

Undocumented methods

Calendar

• Calendar.getfirstweekday()
• Calendar.setfirstweekday()
• Calendar.firstweekday

TextCalendar

• TextCalendar.prweek() (gh-108202: calendar: Document prweek #108466)
• TextCalendar.formatday()
• TextCalendar.formatweek()
• TextCalendar.formatweekday()
• TextCalendar.formatweekheader()
• TextCalendar.formatmonthname()

HTMLCalendar

• HTMLCalendar.formatday()
• HTMLCalendar.formatweek()
• HTMLCalendar.formatweekday()
• HTMLCalendar.formatweekheader()
• HTMLCalendar.formatmonthname()

Undocumented attributes

• EPOCH (should not be documented, of no use)
• mdays (should not be documented, of no use)

Undocumented miscellany

• python -m calendar (main()) (GH-108202: Document calendar's command-line interface #109020)

A

[AA-Turner]

I think at the least we ought document IllegalMonthError and IllegalWeekdayError, I'll open a PR shortly.

A

[erlend-aasland]

I think I managed to dig up the discussion @serhiy-storchaka was referring to in his previous comment:

• https://mail.python.org/archives/list/[email protected]/thread/SJWR73UOGRSVC3HKHR4SZEJ3KINH32PQ/#ACNDSI6FN6DZKOASNZS4AEQJWWXL6F7Q

See also:

• https://mail.python.org/archives/list/[email protected]/thread/UEKY2MA6MFHP2KQ6B6TMFWXETRAOWGU5/#URCWZKVYAF3S6URR4RWUAMFMQHSMI3IU
• Make Calendar.itermonthdates() behave consistently in edge cases #72479 (comment) (and the following discussion and PR)