GeezerVison is showing github.com — Minor mistake in dataclasses documentation update · Issue #108267 · python/cpython
Minor mistake in dataclasses documentation update #108267DescriptionAn update to the dataclasses docs, intended to make magic method names link to the relevant data model documentation, accidentally changed a line that shouldn't have been changed.
The docs used to say
There is a tiny performance penalty when using frozen=True: __init__() cannot use simple assignment to initialize fields, and must use object.__setattr__().
The documentation update accidentally changed object.__setattr__ to just __setattr__ here, so now it reads
There is a tiny performance penalty when using frozen=True: __init__() cannot use simple assignment to initialize fields, and must use __setattr__().
This line was specifically meant to refer to object.__setattr__, the __setattr__ method of the base object class, as simple attribute assignment would hit the frozen dataclass's __setattr__ override.
This part of the documentation should be reverted. I think it should just take a 1-character change, simply removing a tilde.
Linked PRs
Activityericvsmith commented on Aug 22, 2023 I'm no sphinx expert. Would removing a tilde restore the output text to be object.__setattr__? That's what I think should be displayed. hugovk commented on Aug 22, 2023 Yes, removing the tilde gives object.__setattr__():
@FrozenBob Thanks for the report, would you like to create a PR to fix this? ericvsmith commented on Aug 22, 2023
Yes, removing the tilde gives object.__setattr__():
How on earth is someone supposed to know that? Seriously: where could I find out more info? I'd like to get better at this. AlexWaygood commented on Aug 22, 2023 AlexWaygood commented on Aug 22, 2023 If we just remove the tilde, the link will take people to the entry in the data model documentation for the __setattr__ magic method, rather than the docs for object.__setattr__ itself (we have no docs for object.__setattr__ itself). Maybe it would be better in this case to suppress the link entirely?
:meth:`!object.__setattr__` That will render as object.__setattr__() in the HTML documentation, but won't add a link. Reacted by Hugo van Kemenade FrozenBob commented on Aug 22, 2023 ContributorAuthor More actions Suppressing the link sounds reasonable to me. ericvsmith commented on Aug 22, 2023
Suppressing the link sounds reasonable to me.
Agreed. FrozenBob commented on May 17, 2024 ContributorAuthor More actions I think you might need an extra blank line before the comment or something - it's rendering in the generated documentation. FrozenBob commented on May 17, 2024 ContributorAuthor More actions I see a confused emoji. In case it wasn't clear, this is what's showing up in the docs now:
There is a tiny performance penalty when using frozen=True: __init__() cannot use simple assignment to initialize fields, and must use object.__setattr__(). .. Make sure to not remove “object” from “object.__setattr__” in the above markup
The part starting with the ".." looks like it was supposed to be a reStructuredText comment, but it's showing up in the actual documentation. I think this may be because it needs a blank line above it. AlexWaygood commented on May 17, 2024 I understood the problem — sorry for the ambiguous reaction emoji I applied! I suppose I intended to convey that I was frustrated at myself for not checking the docs preview before merging, but sadly there's no reaction emoji for that exact sentiment ;-) Reacted by Jelle Zijlstra
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|
