help() on types has strange (if defined) notice for attributes that are defined

[sobolevn]

Feature or enhancement

Let's say we have a regular class and we call help() on it:

>>> class A: ...
... 
>>> help(A)
Help on class A in module __main__:

class A(builtins.object)
 |  Data descriptors defined here:
 |
 |  __dict__
 |      dictionary for instance variables (if defined)
 |
 |  __weakref__
 |      list of weak references to the object (if defined)

This leaves a strange impression: what does it mean for __dict__?

dictionary for instance variables (if defined)

It is defined.

The same for regular __doc__:

>>> A.__dict__['__dict__'].__doc__
'dictionary for instance variables (if defined)'

Let's see what happens when __dict__ and __weakref__ are not defined:

>>> class B:
...    __slots__ = ()
... 
>>> help(B)
Help on class B in module __main__:

class B(builtins.object)

And:

>>> B.__dict__['__dict__']
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    B.__dict__['__dict__']
    ~~~~~~~~~~^^^^^^^^^^^^
KeyError: '__dict__'

The historical reason behind it is: 373c741#diff-1decebeef15f4e0b0ce106c665751ec55068d4d1d1825847925ad4f528b5b872R1356-R1377

What do others think: should we remove (if defined) part?
If so, I have a PR ready.

Linked PRs

• gh-112266: Remove (if defined) part from __dict__ and __weakref__ docstrings #112268
• [3.12] gh-112266: Remove (if defined) part from __dict__ and __weakref__ docstrings (GH-112268) #112270
• [3.11] gh-112266: Remove (if defined) part from __dict__ and __weakref__ docstrings (GH-112268) #112276

[AlexWaygood]

What it's trying to say is that there might not be any instance variables defined, i.e., A().__dict__ might be empty if it has no instance variables

[chgnrdv]

I guess that "if defined" refers not to __dict__ attribute itself but to variables it contains. Same is for __weakref__ and weak references. Maybe "if any defined" would sound better in this case?

[AlexWaygood]

I personally find the current text clear, but I'm a native English speaker, and it's true that the current text is very terse. If the current text isn't clear to non-native English speakers, then I agree we should change it to something that is.

I actually quite like @sobolevn's idea of just removing the "(if defined)". I'm not sure it adds anything; if it's unclear to some people, let's just get rid of it

[sobolevn]

Context: while working on #112143 I've spent like 20 minutes debugging help and __dict__ outputs to find out that this behaviour is expected. So, I got totally confused.

After the change:

>>> class A: ...
... 
>>> help(A)
Help on class A in module __main__:

class A(builtins.object)
 |  Data descriptors defined here:
 |
 |  __dict__
 |      dictionary for instance variables
 |
 |  __weakref__
 |      list of weak references to the object

[terryjreedy]

I agree with the change.