Improve day constants (`MONDAY` ... `SUNDAY`) in `calendar.py`

[sobolevn]

BPO	46266
Nosy	@rhettinger, @vstinner, @miss-islington, @sobolevn
PRs	bpo-46266: Improve day constants (MONDAY ... SUNDAY) in calendar #30412 [3.10] bpo-46266: Add calendar day of week constants to __all__ (GH-30412) #30424

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2022-01-05.20:22:13.992>
created_at = <Date 2022-01-05.09:38:21.996>
labels = ['type-bug', 'library', '3.11']
title = 'Improve day constants (`MONDAY` ... `SUNDAY`) in `calendar.py`'
updated_at = <Date 2022-01-23.01:00:14.784>
user = 'https://github.com/sobolevn'

bugs.python.org fields:

activity = <Date 2022-01-23.01:00:14.784>
actor = 'vstinner'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2022-01-05.20:22:13.992>
closer = 'rhettinger'
components = ['Library (Lib)']
creation = <Date 2022-01-05.09:38:21.996>
creator = 'sobolevn'
dependencies = []
files = []
hgrepos = []
issue_num = 46266
keywords = ['patch']
message_count = 7.0
messages = ['409742', '409786', '409789', '409793', '409804', '409805', '411324']
nosy_count = 4.0
nosy_names = ['rhettinger', 'vstinner', 'miss-islington', 'sobolevn']
pr_nums = ['30412', '30424']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue46266'
versions = ['Python 3.11']

[sobolevn]

For some reasons useful day constants (MONDAY ... SUNDAY) from calendar are not properly recognised.

Several problems:
0. Not all code inside uses these constants

1. They are not tested. Only .MONDAY and .SUNDAY are tested to be present in https://github.com/python/cpython/blob/main/Lib/test/test_calendar.py#L508-L511
2. They are not in __all__
3. They are partially documented. There are some notes about them in https://docs.python.org/3/library/calendar.html#calendar.setfirstweekday

Sets the weekday (0 is Monday, 6 is Sunday) to start each week. The values :const:`MONDAY`, :const:`TUESDAY`, :const:`WEDNESDAY`, :const:`THURSDAY`, :const:`FRIDAY`, :const:`SATURDAY`, and :const:`SUNDAY` are provided for convenience. For example, to set the first weekday to Sunday:

import calendar
calendar.setfirstweekday(calendar.SUNDAY)

But, they are not clickable, because, for example, ":const:`MONDAY`" does not exist in docs index.

So, my plan is:
0. Improve constant usage in the source code to make it more readable

1. Test that constants are there
2. Add them to __all__ as a part of public API
3. Improve their docs

[rhettinger]

I don't think these were intended to be public. like "January" and "February", they were for internal use. Presumably, this is because the names vary across languages.

In the absence of some demonstrated user need, we should leave this alone.