<html>
  <head>
    <meta content="text/html; charset=ISO-8859-1"
      http-equiv="Content-Type">
  </head>
  <body text="#000000" bgcolor="#FFFFFF">
    <div class="moz-cite-prefix">On 07/07/2013 12:32 AM, Nick Coghlan
      wrote:<br>
    </div>
    <blockquote
cite="mid:CADiSq7eYz0KDxNKtiih9RVBgLEei8tA=uiXP1AnWKMd450ep7g@mail.gmail.com"
      type="cite">
      <p dir="ltr">Rather than perpetuating unwanted complexity, can't
        we just add a single "incomplete signature" flag to handle the
        legacy cases, and leave those to the docstrings? </p>
      <p dir="ltr">As in, if the flag is set, pydoc displays the "..."
        because it knows the signature data isn't quite right.</p>
      <p dir="ltr">Alternatively (and even more simply), is it really so
        bad if argument clinic doesn't support introspection of such
        functions at all, and avoids setting __signature__ for such
        cases?</p>
      <p dir="ltr">As a third option, we could add an "alternative
        signatures" attribute to capture multiple orthogonal signatures
        that should be presented on separate lines.</p>
      <p dir="ltr">All of those possibilities sound more appealing to me
        than adding direct support for parameter groups at the Python
        level (with my preference being to postpone the question to 3.5
        by not allowing introspection of affected functions in this
        initial iteration).<br>
      </p>
    </blockquote>
    <br>
    First, I think the PyCharm case is compelling enough on its own.  I
    realized after I sent it that there's a related class of tools that
    are interested: PyFlakes, PyLint, and the like.  I'm sure the static
    correctness analyzers would like to be able to automatically
    determine "this is an illegal number of parameters for this
    function" for builtins--particularly for third-party builtins!  The
    fact that we wouldn't need to special-case pydoc suggests it's the
    superior approach.  ("Special cases aren't special enough to break
    the rules.")<br>
    <br>
    Second, the added complexity would be a single new member on the
    Parameter object.  Let me propose such a parameter here, in the
    style of the Parameter class documentation:<br>
    <blockquote>group<br>
      <blockquote>If not None, represents which "optional parameter
        group" this parameter belongs to.  Optional parameter groups are
        contiguous sequences of parameters that must either all be
        specified or all be unspecified.  For example, if a function
        takes four parameters but the last two are in an optional
        parameter group, you could specify either two or four arguments
        to that function--it would be illegal to specify three
        arguments.  Parameter groups can only contain positional-only
        parameters; therefore group will only be a non-None value when
        kind is POSITIONAL_ONLY.<br>
      </blockquote>
    </blockquote>
    <br>
    I suggest that is a manageable level of complexity.  And that the
    tooling projects would very much like to have this information.<br>
    <br>
    Third, your proposals are respectively: 1) a hack which fixes the
    docstring but doesn't fix the introspection information (so we'd be
    providing incorrect introspection information to tools), 2) a small
    cop-out (which I think would also probably require a hack to pydoc),
    and 3) way more complicated than doing it the right way (so I don't
    see how it's an improvement).  Of your three suggestions I dislike
    2) least.<br>
    <br>
    This facet of call signatures has existed in Python since the
    addition of range().  I concede that it's legacy, but it's not going
    away.  Ever.  I now think we're better off embracing this complexity
    than trying to sweep it under the rug.<br>
    <br>
    <br>
    <i>/arry</i><br>
  </body>
</html>