Minor mistake in dataclasses documentation update

[FrozenBob]

An 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

• gh-108267: Dataclasses docs line should have said "object.__setattr__" instead of just "__setattr__" #108355
• [3.11] gh-108267: Dataclasses docs: Fix object.__setattr__ typo (GH-108355) #108357
• [3.12] gh-108267: Dataclasses docs: Fix object.__setattr__ typo (GH-108355) #108358
• gh-108267: Fix object.__setattr__ regression in dataclasses docs #119082
• [3.13] gh-108267: Fix object.__setattr__ regression in dataclasses docs (GH-119082) #119097
• [3.12] gh-108267: Fix object.__setattr__ regression in dataclasses docs (GH-119082) #119098
• gh-108267 Fix another dataclasses docs typo #119277
• [3.13] gh-108267 Fix another dataclasses docs typo (GH-119277) #119279
• [3.12] gh-108267 Fix another dataclasses docs typo (GH-119277) #119280

[ericvsmith]

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]

Yes, removing the tilde gives object.__setattr__():

@FrozenBob Thanks for the report, would you like to create a PR to fix this?

[ericvsmith]

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]

@ericvsmith there's some useful info on the markup in the devguide here (in particular, see the "quick reference" section at the top of the page): https://devguide.python.org/documentation/markup/

[AlexWaygood]

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.

[FrozenBob]

Suppressing the link sounds reasonable to me.

[ericvsmith]

Suppressing the link sounds reasonable to me.

Agreed.

[AlexWaygood]

Thanks @FrozenBob!

[FrozenBob]

This error appears to have been reintroduced during an overhaul of the dataclasses docs' links. Looks like it needs to be re-fixed.

[hauntsaninja]

Thank you for your vigilance!

[AlexWaygood]

Thanks @FrozenBob! We've fixed this on main (again!), and automerge has been scheduled for the backport PRs.

[FrozenBob]

I think you might need an extra blank line before the comment or something - it's rendering in the generated documentation.

[FrozenBob]

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]

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 ;-)