[issue19674] Add introspection information for builtins

[Larry Hastings]

New submission from Larry Hastings:

Let's see if we can get introspection information for builtins using the Clinic for 3.4.

Georg suggested part of the approach while we were hanging out in Tokyo.  I'd considered it previously before but dispensed with the idea because it seemed too loopy.  Actually it seems to work great.  

The approach:

* Clinic generates an extra first line for the docstring, that looks like "def (...)\n".  (Note: no function name!)

* The PyCFunctionObject __doc__ getter detects this line and skips it if present.

* Add a new getter to PyCFunctionObject, which I've called "__textsig__", that returns this first line if present in the docstring.  (It skips the "def " at the front, and clips it at the newline.)

* inspect now notices if it's passed in a PyCFunctionObject.  If it gets one, it checks to see if it has a valid __textsig__.  If it does, it parses it (using ast.parse) and produces a valid signature.

Advantages of this approach:
* It was easy to do and took very few lines of code.

* For signatures that are impossible to convert to Clinic, we can
  write the metadata by hand.

Disadvantages of this approach:
* Uh, nothing, really!

The next step is probably to convert pydoc to use inspect.signature instead of the manky old methods it currently uses.  After that, clean up the patch, and add a unit test or two.

What do you think?

----------
assignee: larry
components: Interpreter Core
files: larry.introspection.for.builtins.patch.1.txt
messages: 203549
nosy: brett.cannon, georg.brandl, gvanrossum, larry
priority: normal
severity: normal
stage: patch review
status: open
title: Add introspection information for builtins
type: behavior
versions: Python 3.4
Added file: http://bugs.python.org/file32739/larry.introspection.for.builtins.patch.1.txt

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue19674>
_______________________________________