[issue20326] Argument Clinic should use a non-error-prone syntax to mark text signatures

[Stefan Behnel]

Stefan Behnel added the comment:

I stumble over this because I had already adapted our doctests in Cython to the changed Py3.4 behaviour, so they started failing now because the automatic signature extraction was essentially reverted in CPython.

I had started to consider it a feature that CPython 3.4 was finally smart enough to pick up signatures from docstrings, at least for documentation purposes, much the same way that tools like epydoc or Sphinx do it. Cython has a feature to embed signatures for that reason, and so far, they happily ended up in "__text_signature__" in Py3.4.

I understand the problem that not all of these signatures are valid Python signatures. What Cython currently generates certainly isn't.

The new "sig=" is not supported by any of the existing documentation tools. Having Cython follow here would mean that they would no longer be able to read the signatures, and it's clearly more important for the time being to keep *them* working nicely. This change actually facilitates that, because it leaves the embedded signatures untouched, so that these tools can normally pick them up again. So I agree that the reverted behaviour is in fact better than what Py3.4 previously did.

FWIW, I think the best way to go forward would be to try to find a way to map Cython's C signatures directly to a reasonable version of a "__signature__" object. This hasn't appeared entirely trivial so far, but my guess is that the recent requirements on and improvements to the argument clinic should also have made this mapping a little less hard, because there are at least a bit of an infrastructure and some precedents around. Still, Cython's coverage of C/C++ types (also in signatures) is hugely broader than what ac would ever want to support, so we'll have to see what stumbling blocks remain on that road.

----------
nosy: +scoder

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