Repository navigation
Minor mistake in dataclasses documentation update #108267
Description
Activity
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.Yes, removing the tilde gives
object.__setattr__():
@FrozenBob Thanks for the report, would you like to create a PR to fix this?
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.
@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/
Reacted by Eric V. SmithIf 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 forobject.__setattr__itself (we have no docs forobject.__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 KemenadeSuppressing the link sounds reasonable to me.
Suppressing the link sounds reasonable to me.
Agreed.
12 remaining items
I think you might need an extra blank line before the comment or something - it's rendering in the generated documentation.
Reacted by Alex WaygoodI 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 useobject.__setattr__(). .. Make sure to not remove “object” from “object.__setattr__” in the above markupThe 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.
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
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
The documentation update accidentally changed
object.__setattr__to just__setattr__here, so now it readsThis line was specifically meant to refer to
object.__setattr__, the__setattr__method of the baseobjectclass, 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