Issue 29338: Output the text signature in the help of a class

Pydoc outputs the text signature for C functions. It defines parameters and default values and is a part of function description.

Help on built-in function format in module builtins:

format(value, format_spec='', /)
    Return value.__format__(format_spec)
    
    format_spec defaults to the empty string

When builtin or extension class is converted to Argument Clinic, the generated docstring and text signature of __new__ or __init__ methods usually is used as class docstring and text signature. But pydoc doesn't output the text signature for classes. The important part of information is lost.

For example, for just converted builtin enumerate class:

Help on class enumerate in module builtins:

class enumerate(object)
 |  Return an enumerate object.
 |  
 |    iterable
 |      an object supporting iteration
 |  
 |  The enumerate object yields pairs containing a count (from start, which
 |  defaults to zero) and a value yielded by the iterable argument.
 |  
 |  enumerate is useful for obtaining an indexed list:
 |      (0, seq[0]), (1, seq[1]), (2, seq[2]), ...
 |  
 |  Methods defined here:
 |  
 |  __getattribute__(self, name, /)
 |      Return getattr(self, name).
 |  
 |  __iter__(self, /)
 |      Implement iter(self).
 |  
 |  __new__(*args, **kwargs) from builtins.type
 |      Create and return a new object.  See help(type) for accurate signature.
 |  
 |  __next__(self, /)
 |      Implement next(self).
 |  
 |  __reduce__(...)
 |      Return state information for pickling.

The iterable and start parameters of the constructor are referred but not defined.

Proposed patch adds a text signature at the start of class description.

The patch looks fine and meets a real need.  I say go ahead and apply it if no other objections arise.

New changeset 3d5dcdf26fab by Serhiy Storchaka in branch 'default':
Issue #29338: The help of a builtin or extension class now includes the
https://hg.python.org/cpython/rev/3d5dcdf26fab

Thanks Raymond.

The buildbots are failing due to test_pydoc. :-(

New changeset cebc9c7ad195 by Serhiy Storchaka in branch 'default':
Issue #29338: Don't output an empty signature for class constructor.
https://hg.python.org/cpython/rev/cebc9c7ad195

Oh, I forgot to run tests for such simple change! Thanks for reminder Xiang!

Things doesn't come to an end. :-( The enum test suite also gets a related test and make the buildbot fail:

FAIL: test_pydoc (test.test_enum.TestStdLib)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "D:\buildarea\3.x.bolen-windows10\build\lib\test\test_enum.py", line 2409, in test_pydoc
    self.assertEqual(result, expected_text)
AssertionError: 'Help[68 chars]n |  Color(value, names=None, *, module=None, [896 chars]ing.' != 'Help[68 chars]n |  An enumeration.\n |  \n |  Method resolut[809 chars]ing.'
  Help on class Color in module test.test_enum:
  
  class Color(enum.Enum)
-  |  Color(value, names=None, *, module=None, qualname=None, type=None, start=1)
-  |  
   |  An enumeration.
   |  
   |  Method resolution order:
   |      Color
   |      enum.Enum
   |      builtins.object
   |  
   |  Data and other attributes defined here:
   |  
   |  blue = <Color.blue: 3>
   |  
   |  green = <Color.green: 2>
   |  
   |  red = <Color.red: 1>
   |  
   |  ----------------------------------------------------------------------
   |  Data descriptors inherited from enum.Enum:
   |  
   |  name
   |      The name of the Enum member.
   |  
   |  value
   |      The value of the Enum member.
   |  
   |  ----------------------------------------------------------------------
   |  Data descriptors inherited from enum.EnumMeta:
   |  
   |  __members__
   |      Returns a mapping of member name->value.
   |      
   |      This mapping lists all enum members, including aliases. Note that this
   |      is a read-only view of the internal mapping.

It is easy to fix the test by adding missed lines. But I'm not sure that output the (correct) signature of enum classes makes the help better.

    Color(value, names=None, *, module=None, qualname=None, type=None, start=1)

Ethan, what are your thoughts?

Enum's interaction with the help subsystem has always been somewhat
fragile: http://bugs.python.org/issue18693

In this case, I think a reasonable quick fix would be to add the new text
to the expected output for enum instances (allowing this issue to be closed
again), and then file a separate issue about offering a way to omit that
text for types that discourage or don't allow dynamic creation of new
instances.

New changeset b74a6a7d4389 by Serhiy Storchaka in branch 'default':
Issue #29338: Fix test_enum.
https://hg.python.org/cpython/rev/b74a6a7d4389

nosy: + ethan.furman
messages: + msg286139

resolution: fixed -> (no value)
stage: resolved -> (no value)

stage: patch review -> resolved

stage: patch review