[Python-Dev] Decision on the docstring hack (was Re: The docstring hack for signature information has to go)

[Larry Hastings]

In the absence of a ruling from above I'm making a decision.  I say we 
keep the docstring hack, but go back to the human-readable version, only 
this time with a *much* stricter signature.  That should reduce the 
number of false positives to zero.

Furthermore, I say we don't add any flags--adding a flag to the callable 
would mean doing it three different ways, and adding a flag to the type 
might not work in all cases.

And finally, I agree with Nick, that publishing signatures shall not be 
a supported API for Python 3.4.  If external modules publish signatures, 
and we break their support in 3.5, it's on them.


The rules enforced on the signature will be as per Georg's suggestion 
but made slightly more stringent:

    The signature must start with "<name-of-function>(".
    The signature must end with ")\n--\n\n".
    The signature may contain newlines, but must not contain empty lines.
    The signature may have non-Python syntax in it, such as "$"
    indicating a self parameter, "/" to indicate positional-only
    parameters, and "[" and "]" to indicate optional groups (though I
    don't expect 3.4 will ship with support for this last one).

Here it is in non-working pseudo-code:

    s = function.docstring
    if not s.startswith(function.name + "(")
       return failure
    end = s.find(")\n--\n\n")
    if end < 0:
       return failure
    newline = s.find("n\n")
    if newline > 0 and newline < end:
       return failure
    return success

(The actual implementation will be in C, in find_signature in 
Objects/typeobject.c.)

Expect a patch in about 24 hours,


//arry/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20140204/46f4a5c7/attachment.html>