Author larry
Recipients larry, meador.inge, nadeem.vawda, serhiy.storchaka
Date 2014-01-09.00:52:45
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1389228766.25.0.118610429629.issue20193@psf.upfronthosting.co.za>
In-reply-to
Content
I just realized, you're misunderstanding what the first line of the docstring is.

When you run help(function_written_in_Python), the first line of the help is the function's signature rendered in text.  That's generated by "pydoc", which gets signature information from inspect.  Now, it used to be that this didn't work for builtins.  pydoc would look at the function, say "I can't get metadata for this function, I'll skip it".  And it'd just print the builtin's docstring.  Builtins worked around this problem by having their first line *look* like a Python signature.  So the user kind of couldn't tell the difference.

As part of adding Argument Clinic, I changed this.  Now the first line of a docstring is a machine-readable representation of the signature of the function.  Internally it gets split off from the docstring--you won't see it if you look at builtin.__doc__.  Instead this first line is provided via a new property called __text_signature__.  inspect.Signature supports builtins by parsing this string.

As it happens, the format of the string happens to look exactly like a Python function definition.  Because... it is!  inspect.Signature parses the string by passing it in to ast.parse.

"decompressobj([wbits], [zdict])" is not legal Python; if you gave that to ast.parse it would reject it.  (I tried, with PEP 457, but so far nobody has been interested.)  On the other hand, ast.parse is totally happy with "decompressobj(wbits=None, zdict=None)".
History
Date User Action Args
2014-01-09 00:52:46larrysetrecipients: + larry, nadeem.vawda, meador.inge, serhiy.storchaka
2014-01-09 00:52:46larrysetmessageid: <1389228766.25.0.118610429629.issue20193@psf.upfronthosting.co.za>
2014-01-09 00:52:46larrylinkissue20193 messages
2014-01-09 00:52:45larrycreate