Repository navigation
Incomplete or incorrect calendar documentation #126164
Description
Documentation
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())
>>> 22. Instance attribute
import calendar
cal = calendar.Calendar()
print(cal.firstweekday)
>>> 0
cal.setfirstweekday(2)
print(cal.firstweekday)
>>> 2Is 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.
Activity
eendebakpt commentedon Nov 2, 2024
I agree the documentation is unclear. The
cal.firstweekdayis a property which aliases to the methodcal.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
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
calendarmodule 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 commentedon Feb 2, 2025
This was/is tracked in #108202 and was updated in #128566.