New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Output the text signature in the help of a class #73524
Comments
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': |
Thanks Raymond. |
The buildbots are failing due to test_pydoc. :-( |
New changeset cebc9c7ad195 by Serhiy Storchaka in branch 'default': |
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: |
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 In this case, I think a reasonable quick fix would be to add the new text |
New changeset b74a6a7d4389 by Serhiy Storchaka in branch 'default': |
Misc/NEWS
so that it is managed by towncrier #552Note: 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:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: