<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix"><br>
<br>
On 02/03/2014 08:19 PM, Guido van Rossum wrote:<br>
</div>
<blockquote
cite="mid:CAP7+vJJtwLWeFuL0D9db8qVzBVxEBffHUaf6hRPJoW8Ou-MUGw@mail.gmail.com"
type="cite">
<div dir="ltr">But why do you even need a flag? Reading issue
20075 where the complaint started, it really feels that the
change was an overreaction to a very minimal problem.</div>
</blockquote>
<br>
I'll cop to that. I'm pretty anxious about trying to "get it
right". My worry was (and is) that this
hiding-the-signature-in-the-docstring approach is a cheap hack, and
it will have unexpected and undesirable side-effects that will in
retrospect seem obvious. This is FUD I admit. But it seems to me
if we did it "the right way", with a "PyMethodDefEx", we'd be able
to do a lot better job predicting the side-effects.<br>
<br>
<br>
<blockquote
cite="mid:CAP7+vJJtwLWeFuL0D9db8qVzBVxEBffHUaf6hRPJoW8Ou-MUGw@mail.gmail.com"
type="cite">
<div dir="ltr"> A few docstrings appear truncated. Big deal. We
can rewrite the ones that are reported as broken (either by
adjusting the docstring to not match the patter or by adjusting
it to match the pattern better, depending on the case). Tons of
docstrings contain incorrect info, we just fix them when we
notice the issue, we don't declare the language broken.<br>
</div>
</blockquote>
<br>
I don't think #20075 touches on it, but my biggest concern was
third-party modules. If you maintain a Python module, you very well
might compile for 3.4 only to find that the first line of your
docstrings have mysteriously vanished. You'd have to be very
current on changes in Python 3.4 to know what was going on. It
seemed like an overly efficient way of pissing off external module
maintainers.<br>
<br>
(Why would they vanish? The mechanical separator for __doc__ vs
__text_signature__ would accept them, but unless they're 100%
compatible Python ast.parse will reject them. So they'd get
stripped from your docstring, but you wouldn't get a valid signature
in return.)<br>
<br>
<br>
I'd feel much better with an explicit flag--explicit is better than
implicit, after all. But here's a reminder, to make it easier for
you to say "no". That would mean adding an explicit flag to all the
objects which support a signature hidden in the docstring:<br>
<ul>
<li>PyTypeObject (has tp_flags, we've used 18 of 32 bits by my
count)</li>
<li>PyMethodDef (has ml_flags, 7 of 32 bits in use)</li>
<li>PyMethodDescrObject (reuses PyMethodDef)</li>
<li>PyWrapperDescrObject (has d_base->flags, 1 of 32 bits in
use)<br>
</li>
<li>wrapperobject (reuses PyWrapperDescrObject)</li>
</ul>
Argument Clinic would write the PyMethodDefs, so we'd get those for
free. The last three all originate from a PyMethodDef, so when we
copied out the docstring pointer we could also propagate the flag.
But we'd have to add the flag by hand to the PyTypeObjects.<br>
<br>
<br>
If you won't let me have a flag, can I at least have a more-clever
marker? How about this:<br>
<blockquote><name-of-function>(...)\n \n<br>
</blockquote>
Yes, the last four characters are right-parenthesis, newline, space,
and newline. Benefits:<br>
<ul>
<li>The odds of finding *that* in the wild seem remote.</li>
<li>If this got displayed as help in 3.3 the user would never
notice the space.<br>
</li>
</ul>
For the record, here are things that may be in the signature that
aren't legal Python syntax and therefore might be surprising:<br>
<ul>
<li>"self" parameters (and "module" and "type") are prefixed with
'$'.</li>
<li>Positional-only parameters will soon be delimited by '/', just
as keyword-only parameters are currently delimited by '*'.
(Hasn't happened yet. Needs to happen for 3.4, in order for
inspect.Signature to be accurate.)<br>
</li>
</ul>
<br>
<br>
<i>/arry</i><br>
</body>
</html>