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?

If you review, you can ignore the changes to the .c files, those only got touched because of the new autogenerated "def (" lines in the docstrings.  No other changes there.

(Well, except for Object/methodobject.c.)

I think there's a similar but slightly different convention in Sphinx
autodoc -- the first line of the docstring can be "name(...)" . Isn't that
better than def?

I was deliberately trying to avoid something that a person might do by accident.  Also, "def (" is consistently only five bytes, whereas "pterodactyl (" or whatever will often be much longer, in case static data size is a concern.

But I could switch it to that if you think that's better.  Certainly it's a tiny amount more readable.

(I don't think this would make the docstrings compatible with sphinx autodoc though.)

Great! See also issue16842 and issue16638.

Sounds good to me (with either Larry's or Guido's spelling).

We should ensure this still works with the config option that disables docstrings entirely.

For Nick: "still works" as in the metadata is still available without docstrings or "still works" as in it won't crash?

I changed it to "<callablename>(".  Patch attached.  Still works.

"still works" as in "doesn't crash and the docstrings are still missing to
save memory".

Anybody have a better name for __textsig__ ?

__signature_text__? __textsignature__? No need to abbreviate that much since there is no built-in function equivalent and people are not expected to work with it.

I went with __text_signature__.  I also did some more polishing, and added / fixed the unit tests, and even added a Misc/NEWS.  Is it good enough to go in before the beta?

+1 from me (I see this as the key benefit of argument clinic).

For 3.5, we can look at ducktyping on the attribute, but for now I think
it's worth keeping that text format internal to CPython.

Fresh patch attached.  pydoc now uses inspect.signature instead of inspect.getfullargspec to generate the arguments for the function, and supports builtins.  That's everything :D

Planning on checking this in pretty soon, to get it in for beta (which hopefully still gets tagged today).

New changeset 78ec18f5cb45 by Larry Hastings in branch 'default':
Issue #19674: inspect.signature() now produces a correct signature
http://hg.python.org/cpython/rev/78ec18f5cb45