classification
Title: Output the text signature in the help of a class
Type: enhancement Stage: resolved
Components: Argument Clinic, Library (Lib) Versions: Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: ethan.furman, larry, ncoghlan, python-dev, rhettinger, serhiy.storchaka, xiang.zhang, yselivanov
Priority: normal Keywords: patch

Created on 2017-01-21 09:42 by serhiy.storchaka, last changed 2017-03-31 16:36 by dstufft. This issue is now closed.

Files
File name Uploaded Description Edit
pydoc-class-signature.patch serhiy.storchaka, 2017-01-21 16:40 review
Pull Requests
URL Status Linked Edit
PR 552 closed dstufft, 2017-03-31 16:36
Messages (12)
msg285946 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-01-21 09:42
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.
msg285962 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-01-21 16:40
Proposed patch adds a text signature at the start of class description.
msg286061 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-01-23 08:46
The patch looks fine and meets a real need.  I say go ahead and apply it if no other objections arise.
msg286070 - (view) Author: Roundup Robot (python-dev) Date: 2017-01-23 10:37
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
msg286071 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-01-23 10:37
Thanks Raymond.
msg286073 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2017-01-23 11:14
The buildbots are failing due to test_pydoc. :-(
msg286078 - (view) Author: Roundup Robot (python-dev) Date: 2017-01-23 12:02
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
msg286079 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-01-23 12:03
Oh, I forgot to run tests for such simple change! Thanks for reminder Xiang!
msg286127 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2017-01-24 02:45
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.
msg286139 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-01-24 05:40
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?
msg286140 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-01-24 06:26
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.
msg286146 - (view) Author: Roundup Robot (python-dev) Date: 2017-01-24 07:06
New changeset b74a6a7d4389 by Serhiy Storchaka in branch 'default':
Issue #29338: Fix test_enum.
https://hg.python.org/cpython/rev/b74a6a7d4389
History
Date User Action Args
2017-03-31 16:36:17dstufftsetpull_requests: + pull_request913
2017-01-24 07:09:14serhiy.storchakasetstatus: open -> closed
resolution: fixed
stage: resolved
2017-01-24 07:06:41python-devsetmessages: + msg286146
2017-01-24 06:26:51ncoghlansetmessages: + msg286140
2017-01-24 05:40:14serhiy.storchakasetstatus: closed -> open

nosy: + ethan.furman
messages: + msg286139

resolution: fixed -> (no value)
stage: resolved -> (no value)
2017-01-24 02:45:08xiang.zhangsetmessages: + msg286127
2017-01-23 12:03:50serhiy.storchakasetmessages: + msg286079
2017-01-23 12:02:53python-devsetmessages: + msg286078
2017-01-23 11:14:38xiang.zhangsetnosy: + xiang.zhang
messages: + msg286073
2017-01-23 10:37:57serhiy.storchakasetstatus: open -> closed
resolution: fixed
messages: + msg286071

stage: patch review -> resolved
2017-01-23 10:37:19python-devsetnosy: + python-dev
messages: + msg286070
2017-01-23 08:46:39rhettingersetmessages: + msg286061
2017-01-21 16:40:30serhiy.storchakasetfiles: + pydoc-class-signature.patch
keywords: + patch
messages: + msg285962

stage: patch review
2017-01-21 09:42:36serhiy.storchakacreate