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

[Nikolaus Rath]

Larry Hastings <larry at hastings.org> writes:
> In the second attempt, the signature looked like this:
>
>    sig=(arguments)\n
>
[...]
> This all has caused no problems so far.  But my panicky email last
> night was me realizing a problem we may see down the road.  To recap:
> if a programmer writes a module using the binary ABI, in theory they
> can use it with different Python versions without modification.  If
> this programmer added Python 3.4+ compatible signatures, they'd have
> to insert this "sig=(" line at the top of their docstring.  The
> downside: Python 3.3 doesn't understand that this is a signature and
> would happily display it to the user as part of help().

I think this is not a bug, it's a feature. Since 3.3 users don't have
the special signature parser either, this gives them exactly the
information they need and without any duplication. The only drawback is
in the cosmetic "sig=" prefix -- but that's the right amount of
non-intrusive, kind nudging to get people to eventually update.

>> How bad would it be if we decided to just live with it or if we
>> added a new flag bit (only recognized by 3.4) to disambiguate
>> corner-cases?
>
> A new flag might solve the problem cheaply.  Let's call it METH_SIG,
> set in the flags portion of the PyMethodDef.  It would mean "This
> docstring contains a computer-readable signature".  One could achieve
> source compatibility with 3.3 easily by adding "#ifndef METH_SIG /
> #define METH_SIG 0 / #endif"; the next version of 3.3 could add that
> itself.  We could then switch back to the original approach of
> "<name-of-function>(", so the signature would look presentable when
[...]

That much effort to fix a purely cosmetic problem showing up only in
older releases? Note that it's going to be a while until machine
generated signatures have actually trickled down to end-users, so it's
not as if every 3.3 installation would suddenly show different
docstrings for all modules. 

Just my $0.02 of course.

Best,
Nikolaus

-- 
Encrypted emails preferred.
PGP fingerprint: 5B93 61F8 4EA2 E279 ABF6  02CF A9AD B7F8 AE4E 425C

             »Time flies like an arrow, fruit flies like a Banana.«