[Python-Dev] The docstring hack for signature information has to go

[Zachary Ware]

On Mon, Feb 3, 2014 at 8:43 AM, Larry Hastings <larry at hastings.org> wrote:
>
>
> A quick summary of the context: currently in CPython 3.4, a builtin function
> can publish its "signature" as a specially encoded line at the top of its
> docstring.  CPython internally detects this line inside
> PyCFunctionObject.__doc__ and skips past it, and there's a new getter at
> PyCFunctionObject.__text_signature__ that returns just this line.  As an
> example, the signature for os.stat looks like this:
>
>     sig=($module, path, *, dir_fd=None, follow_symlinks=True)
>
> The convention is, if you have this signature, you shouldn't have your
> docstring start with a handwritten signature like 3.3 and before.  help() on
> a callable displays the signature automatically if it can, so if you *also*
> had a handwritten signature, help() would show two signatures.  That would
> look dumb.
>
> -----
>
> So here's the problem.  Let's say you want to write an extension that will
> work with Python 3.3 and 3.4, using the stable ABI.  If you don't add this
> line, then in 3.4 you won't have introspection information, drat.  But if
> you *do* add this line, your docstring will look mildly stupid in 3.3,
> because it'll have this unsightly "sig=(" line at the top.  And it *won't*
> have a nice handwritten docstring.  (And if you added both a sig= signature
> *and* a handwritten signature, in 3.4 it would display both.  That would
> also look dumb.)

What about just choosing a marker value that is somewhat less
unsightly?  "signature = (", or "parameters: (", or something (better)
to that effect?  It may not be beautiful in 3.3, but we can at least
make it make sense.

-- 
Zach