On Mon, Feb 3, 2014 at 8:43 AM, Larry Hastings <la...@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
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
