classification
Title: pydoc should use inspect.signature instead of inspect.getfullargspec
Type: behavior Stage: patch review
Components: Library (Lib) Versions: Python 3.4
process
Status: closed Resolution: out of date
Dependencies: Superseder: Add introspection information for builtins
View: 19674
Assigned To: Nosy List: jafo, ronaldoussoren, yselivanov
Priority: low Keywords: needs review, patch

Created on 2013-01-27 13:17 by ronaldoussoren, last changed 2014-02-25 00:27 by yselivanov. This issue is now closed.

Files
File name Uploaded Description Edit
issue17053.txt ronaldoussoren, 2013-03-15 12:59 review
issue17053-v2.txt ronaldoussoren, 2013-03-20 09:34 review
Messages (7)
msg180768 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2013-01-27 13:17
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.
msg181077 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2013-02-01 12:04
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)
msg184227 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2013-03-15 12:59
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.
msg184499 - (view) Author: Sean Reifschneider (jafo) * (Python committer) Date: 2013-03-18 19:29
This may be related to: http://bugs.python.org/issue17424

Perhaps there is a common fix that can address this for both?
msg184543 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2013-03-18 22:30
See my comment in issue 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.
msg184747 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2013-03-20 09:34
* 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)
msg212151 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2014-02-25 00:27
Fixed in 19674. Closing this one.
History
Date User Action Args
2014-02-25 00:27:31yselivanovsetstatus: open -> closed

nosy: + yselivanov
messages: + msg212151

superseder: Add introspection information for builtins
resolution: out of date
2013-03-20 09:34:17ronaldoussorensetfiles: + issue17053-v2.txt

messages: + msg184747
2013-03-18 22:31:46ronaldoussorensetkeywords: + needs review
2013-03-18 22:30:54ronaldoussorensetmessages: + msg184543
2013-03-18 19:29:34jafosetnosy: + jafo
messages: + msg184499
2013-03-15 12:59:22ronaldoussorensetkeywords: + patch
files: + issue17053.txt
messages: + msg184227

stage: test needed -> patch review
2013-02-01 12:04:09ronaldoussorensetmessages: + msg181077
stage: needs patch -> test needed
2013-01-27 13:17:12ronaldoussorencreate