gh-94343: Ease initialization of reprlib.Repr attributes #94581
Conversation
Since the keyword arguments now show up in the docs, the order should reflect their usage frequency to some degree
| attributes of the :class:`Repr` instance. Which means that the following | ||
| initialization:: | ||
|
|
||
| aRepr = reprlib.Repr(maxlevel=3) |
There was a problem hiding this comment.
I think the example can be omitted because it's both fairly obvious and consistent with many other classes in standard lib.
There was a problem hiding this comment.
Thanks for taking a look! :) I fully agree that it is "fairly obvious". However, regarding "consistent with many other classes in standard"... I actually couldn't find or come up with any but one object in the stdlib were you can set an object's attribute via keyword argument during initialization. That's why I included the example code. Maybe I just didn't search well enough? Which stdlib objects did you have in mind?
There was a problem hiding this comment.
You are welcome; for example datetime.timedelta(days=1) ...
There was a problem hiding this comment.
That's a different case, though, isn't it? You must write that as datetime.timedelta(days=1) because:
dt = datetime.timedelta()
dt.days = 1 # AttributeError: readonly attribute
There was a problem hiding this comment.
Ok, then look at calendar.Calendar(firstweekday=1)
There was a problem hiding this comment.
That's a very interesting example, thank you. :) I definitely looked at the docs for calendar, when I was researching how other stdlib classes describe attributes set by keyword arguments. But I must have missed this one because looking at https://docs.python.org/3/library/calendar.html, it seems like the firstweekday property is not listed as an attribute at all? It is mentioned in the description for the iterweekdays method, but otherwise doesn't show up. The constructor only describes it as a keyword argument and further above it says to use calendar.setfirstweekday to set the default for calendar.c but the setter method calendar.Calendar.setfirstweekday for the Calendar class is not described anywhere. Classes TextCalendar and HTMLCalendar don't mention that they're subclasses of Calendar. To be honest, I think the docs for calendar could use a few fixes themselves and in their current form, I wouldn't want to use them as a guide how to write the docs for this reprlib extension.
There was a problem hiding this comment.
To be clear: I don't feel strongly about leaving the example in. It's a valid point you're raising. However, I still haven't found any stdlib class that uses attributes and keyword arguments in the same way that reprlib.Repr does. Therefore, a precedent on how the docs should handle such a case is missing, too. If it's okay with you, I'd not remove the lines with the example code for now, keep this conversation thread marked "unresolved" and just leave the final decision up to the core dev review.
#94343