Repository navigation
pydoc should use inspect.signature instead of inspect.getfullargspec #61255
Description
| BPO | 17053 |
|---|---|
| Nosy | @ronaldoussoren, @1st1 |
| Superseder | |
| Files |
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 2014-02-25.00:27:31.490>
created_at = <Date 2013-01-27.13:17:12.257>
labels = ['type-bug', 'library']
title = 'pydoc should use inspect.signature instead of inspect.getfullargspec'
updated_at = <Date 2014-02-25.00:27:31.484>
user = 'https://github.com/ronaldoussoren'bugs.python.org fields:
activity = <Date 2014-02-25.00:27:31.484>
actor = 'yselivanov'
assignee = 'none'
closed = True
closed_date = <Date 2014-02-25.00:27:31.490>
closer = 'yselivanov'
components = ['Library (Lib)']
creation = <Date 2013-01-27.13:17:12.257>
creator = 'ronaldoussoren'
dependencies = []
files = ['29415', '29502']
hgrepos = []
issue_num = 17053
keywords = ['patch', 'needs review']
message_count = 7.0
messages = ['180768', '181077', '184227', '184499', '184543', '184747', '212151']
nosy_count = 3.0
nosy_names = ['jafo', 'ronaldoussoren', 'yselivanov']
pr_nums = []
priority = 'low'
resolution = 'out of date'
stage = 'patch review'
status = 'closed'
superseder = '19674'
type = 'behavior'
url = 'https://bugs.python.org/issue17053'
versions = ['Python 3.4']
Activity
ronaldoussoren commentedon Jan 27, 2013
pydoc currently uses inspect.getfullargspec to determine the signature of a callable when rendering its documentation. It should use inspect.signature instead because that function can work with callables that aren't python functions or methods.
Changing pydoc to use inspect.signature would make it possible to render more useful documentation for callables implemented in C, when those callables also implement the "__signature__" special method.
ronaldoussoren commentedon Feb 1, 2013
The attached patch is a very rough prototype which seems to work (but wasn't tested beyond running pydoc on a number of function(-like) objects.
With the patch the documentation for a callable defined in C but with a __signature__ property shows argument names in the rendered prototype instead of just '(...)' while the documentation for python functions and C functions without a __signature__ also works.
Issues:
Rendering to HTML is broken if a function has POSITIONAL_ONLY arguments
(the names of those arguments are rendered as '<arg>' and that value
is not escaped in the HTML output)
This adds a "render" method to inspect.Signature and inspect.Param
to be able to pass custom render function for elements of a signature
and I'm not convinced that this is the right solution.
There are no unittests for the new code (and I haven't run the existing
tests to check if anything else has broken)
ronaldoussoren commentedon Mar 15, 2013
The attached patch appears to work correctly and includes a test for pydoc (text output). There could be more testing (HTML output, annotations, positional-only arguments).
With this patch I can get usable documentation for Cocoa classes with a patched version of PyObjC that includes an __signature__ property on ObjC method objects.
As mentioned before I'm not sure about the 'render' method added to inspect.Signature and inspect.Parameter. These methods were needed to generate output that's compatible with the current pydoc output, in particular to emit better HTML output.
jafo commentedon Mar 18, 2013
This may be related to: http://bugs.python.org/issue17424
Perhaps there is a common fix that can address this for both?
ronaldoussoren commentedon Mar 18, 2013
See my comment in bpo-17424: the code in that issue doesn't work with my patch because __signature__ is defined on the class instead of the method where help is called on.
ronaldoussoren commentedon Mar 20, 2013
renamed "render" method of inspect.Parameter and inspect.Signature
to "_render" to avoid changing the public API
updated patch for current tip (I got a merge conflict when pulling
in the tip due to a patch for Lib/test/test_pydoc.py)
1st1 commentedon Feb 25, 2014
Fixed in 19674. Closing this one.