Output the text signature in the help of a class

[serhiy-storchaka]

BPO	29338
Nosy	@rhettinger, @ncoghlan, @larryhastings, @ethanfurman, @serhiy-storchaka, @1st1, @zhangyangyu
PRs	[Do Not Merge] Convert Misc/NEWS so that it is managed by towncrier #552
Files	pydoc-class-signature.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2017-01-24.07:09:14.013>
created_at = <Date 2017-01-21.09:42:36.906>
labels = ['3.7', 'type-feature', 'library', 'expert-argument-clinic']
title = 'Output the text signature in the help of a class'
updated_at = <Date 2017-03-31.16:36:17.389>
user = 'https://github.com/serhiy-storchaka'

bugs.python.org fields:

activity = <Date 2017-03-31.16:36:17.389>
actor = 'dstufft'
assignee = 'none'
closed = True
closed_date = <Date 2017-01-24.07:09:14.013>
closer = 'serhiy.storchaka'
components = ['Library (Lib)', 'Argument Clinic']
creation = <Date 2017-01-21.09:42:36.906>
creator = 'serhiy.storchaka'
dependencies = []
files = ['46373']
hgrepos = []
issue_num = 29338
keywords = ['patch']
message_count = 12.0
messages = ['285946', '285962', '286061', '286070', '286071', '286073', '286078', '286079', '286127', '286139', '286140', '286146']
nosy_count = 8.0
nosy_names = ['rhettinger', 'ncoghlan', 'larry', 'ethan.furman', 'python-dev', 'serhiy.storchaka', 'yselivanov', 'xiang.zhang']
pr_nums = ['552']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue29338'
versions = ['Python 3.7']

[serhiy-storchaka]

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.

[serhiy-storchaka]

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

[rhettinger]

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

[python-dev]

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

[serhiy-storchaka]

Thanks Raymond.

[zhangyangyu]

The buildbots are failing due to test_pydoc. :-(

[python-dev]

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

[serhiy-storchaka]

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

[zhangyangyu]

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.

[serhiy-storchaka]

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?