Incomplete or incorrect calendar documentation

Documentation

calendar.firstweekday()

The documentation describes this function only in the following way:

For simple text calendars this module provides the following functions.

This doesn't make it entirely clear whether this is a class method, a module method, or an instance method.

As it turns out, it's not only a method but also an instance attribute.

1. Class/module method

import calendar

print(calendar.firstweekday())
>>> 0

calendar.setfirstweekday(2)
print(calendar.firstweekday())
>>> 2

2. Instance attribute

import calendar

cal = calendar.Calendar()

print(cal.firstweekday)
>>> 0

cal.setfirstweekday(2)
print(cal.firstweekday)
>>> 2

Is this intentional? If so, I can't find the attribute in the docs nor have I been able to find any mention of this also being an attribute by searching online - I can only find a mention of the method.

In general, I think the Python docs could be massively improved by being more clear on things like this. If you take a look the docs for other languages, they are generally explicit about whether something is a class method, an instance method, a class attribute, or an instance attribute. The Python docs seem to be hit or miss on this.

For example, the description:

For simple text calendars this module provides the following functions.

Is not nearly as clear as simply labeling the methods as being either class methods, module methods, instance methods, or whatever other term may be applicable. Some docs pages do something approaching this, but most don't.

The above examples use Python 3.11.9.

[eendebakpt]

I agree the documentation is unclear. The cal.firstweekday is a property which aliases to the method cal.getfirstweekday, but this is not mentioned in the documentation.

The module level methods seems to be for backward compatibility, see the comment

cpython/Lib/calendar.py

Lines 641 to 649 in 7d7d56d

	# Support for old module level interface
	c = TextCalendar()
	firstweekday = c.getfirstweekday
	def setfirstweekday(firstweekday):
	if not MONDAY <= firstweekday <= SUNDAY:
	raise IllegalWeekdayError(firstweekday)
	c.firstweekday = firstweekday

But I am not sure whether it is discouraged (or deprecated) to keep using the module level methods. There already is a tracking issue for the calendar module documentation #108202, so I suggest this can be closed as a duplicate.

@statusdocs09234 PRs to improve the documentation are always welcome. If you would like to help, you can make a PR and ping me to help reviewing.

[StanFromIreland]

This was/is tracked in #108202 and was updated in #128566.