[issue15831] comma after leading optional argument is after bracket in docs

Ezio Melotti added the comment: The * is not supposed to be used on 2.7, but I missed that. Thanks for noticing! -- resolution: -> fixed stage: needs patch -> committed/rejected status: open -> closed type: behavior -> enhancement ___ Python tracker

[issue15831] comma after leading optional argument is after bracket in docs

Roundup Robot added the comment: New changeset 881acdf9133f by Ezio Melotti in branch '2.7': #15831: avoid using 3.x syntax for keyword-only args. http://hg.python.org/cpython/rev/881acdf9133f -- ___ Python tracker

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: Since the bare * notation wasn't added until 3.0, my guess is that we want to remove the * below (from the 2.7 application of the patch) rather than adding it back in the max() function I pasted above: -.. function:: min(iterable[, args...][key]) +.. function:

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: Someone pointed out that keyword-only arguments were introduced only in 3.0, but I'm not sure whether that means we can't use them as a notational device in the 2.7 docs. -- ___ Python tracker

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: Thanks, Ezio! By the way, I didn't do a thorough check, but I noticed this difference in the 2.7 application of the patch. The *key* argument for max() needs to be marked keyword-only. This difference doesn't exist for the min() function. Or are we not usi

[issue15831] comma after leading optional argument is after bracket in docs

Ezio Melotti added the comment: Fixed, thanks for the patch! -- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed ___ Python tracker __

[issue15831] comma after leading optional argument is after bracket in docs

Roundup Robot added the comment: New changeset b01eb870f84f by Ezio Melotti in branch '3.2': #15831: document multiple signatures on different lines. Patch by Chris Jerdonek. http://hg.python.org/cpython/rev/b01eb870f84f New changeset 0ed61ee823d8 by Ezio Melotti in branch 'default': #15831: m

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: > We are moving toward using the same signatures that we have in the Python > code The single * is not so common (yet), I created issue 15865 to add the single * to the documentation where appropriate. -- ___

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: Attaching an updated patch after doing another pass at the code and in light of Ezio's comments. Let me know if and when you'd like me to prepare separate patches for 2.7 and 3.2. -- Added file: http://bugs.python.org/file27120/issue-15831-2.patch __

[issue15831] comma after leading optional argument is after bracket in docs

Ezio Melotti added the comment: > So I wasn't sure if this notation was preferred or discouraged. We are moving toward using the same signatures that we have in the Python code, but that doesn't always work (e.g. when the meaning of values changes depending on the number of args, when there's

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: Thanks for responding to all of those questions, Ezio. I will update the patch based on your responses. (Likely most of it will remain the same.) > Note that if possible, it's better to avoid using the [] and put the default > values. However, in these cases

[issue15831] comma after leading optional argument is after bracket in docs

Ezio Melotti added the comment: > Do we like how these look? Is the bare star notation too obscure? > > inspect.Signature.replace(*[, parameters][, return_annotation]) > inspect.Parameter.replace(*[, name][, kind][, default][, annotation]) Note that if possible, it's better to avoid using the [

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: Attaching a proposed patch for the default branch. Also, here are several comments and questions. > I think/hope that all the APIs we have in the stdlib are sane enough to have > no more than 2-3 signatures I found this one in the curses module with four: w

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: FWIW, I submitted a patch for the Sphinx issue I created: https://bitbucket.org/birkenfeld/sphinx/issue/1001 Ironically, that patch was probably easier than this patch will be. -- ___ Python tracker

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: Here are a couple functions that may need a fix different from multiple signatures: print([object, ...], *, sep=' ', end='\n', file=sys.stdout, flush=False) http://docs.python.org/dev/library/functions.html#print class argparse.ArgumentParser([description][,

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: Something to be aware of that may or may not affect the patch I'm preparing: One reason that Sphinx seems able to render some of the more complicated function signatures is that it has logic to bail and print the parameter list verbatim from the reST file when

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: I will prepare a patch (multiple signatures, for the Python fix). -- ___ Python tracker ___ ___ Pyth

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: > (The double signature might be easier to understand, but the original issue > should probably be fixed in Sphinx, even if we decide to stop using this kind > of signature.) I filed an issue for this in the Sphinx tracker here: https://bitbucket.org/birkenfe

[issue15831] comma after leading optional argument is after bracket in docs

Georg Brandl added the comment: +1 for multiple signatures. -- ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue15831] comma after leading optional argument is after bracket in docs

Ezio Melotti added the comment: I think/hope that all the APIs we have in the stdlib are sane enough to have no more than 2-3 signatures (I'm not counting optional args (at the end) here). If that's not the case we should still be able to add as many signature as we need (I don't know if Sphi

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: > What's this even supposed to mean? I started wondering the same thing after I posted. :) I guess my point/question is: are there any cases where more than two signatures would be needed to account for all of the possibilities? -- __

[issue15831] comma after leading optional argument is after bracket in docs

Ezio Melotti added the comment: > 766:.. method:: window.chgat([y, x, ] [num,] attr) What's this even supposed to mean? See also #14783. -- ___ Python tracker ___ _

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: > It would be fine with me to use a double signature for these. Just an FYI that more than two signatures would be needed for cases like this: 766:.. method:: window.chgat([y, x, ] [num,] attr) -- ___ Python tracker

[issue15831] comma after leading optional argument is after bracket in docs

Ezio Melotti added the comment: > No, methods for *curses* are also corrupted. I meant the double signature support. -- ___ Python tracker ___ __

[issue15831] comma after leading optional argument is after bracket in docs

Ezio Melotti added the comment: > This is what my search for ",] " gave me It would be fine with me to use a double signature for these. Georg, do you have any opinion? (The double signature might be easier to understand, but the original issue should probably be fixed in Sphinx, even if we d

[issue15831] comma after leading optional argument is after bracket in docs

Ezio Melotti added the comment: > Does Sphinx support it for *.. function::*? I'm pretty sure it does for methods, so I don't see why it shouldn't work for functions. -- ___ Python tracker ___

[issue15831] comma after leading optional argument is after bracket in docs

Andrew Svetlov added the comment: No, methods for *curses* are also corrupted. -- ___ Python tracker ___ ___ Python-bugs-list mailing

[issue15831] comma after leading optional argument is after bracket in docs

Andrew Svetlov added the comment: Yes, it looks like Sphinx problem. About having tho signatures for single function/method. Does Sphinx support it for *.. function::*? Pointing to anchor for first signature with adding second one somewhere in paragraph text doesn't look good. --

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: This is what my search for ",] " gave me (though the OP's print and random.seed do not show up in this list): library/curses.rst 380:.. function:: newwin([nlines, ncols,] begin_y, begin_x) 659:.. method:: window.addch([y, x,] ch[, attr]) 673:.. method:: window.

[issue15831] comma after leading optional argument is after bracket in docs

Ezio Melotti added the comment: I thought that was just a matter of finding the wrong commas and fixing them, but if they are correct in the source, then the situation might be a bit more complicated. Does this happen only with "unusual" signatures like range([start], stop [, step])? FWIW th

[issue15831] comma after leading optional argument is after bracket in docs

Chris Jerdonek added the comment: Do we know that this is easy? It might be a Sphinx issue, in which case it might not be as trivial as fixing typos. I ask because the reST file looks correct (for range() for example): .. function:: range([start,] stop[, step]) -- __

[issue15831] comma after leading optional argument is after bracket in docs

Changes by Andrew Svetlov : -- nosy: +asvetlov ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.pyth

[issue15831] comma after leading optional argument is after bracket in docs

Changes by Ezio Melotti : -- keywords: +easy nosy: +ezio.melotti stage: -> needs patch versions: +Python 3.4 ___ Python tracker ___ _

[issue15831] comma after leading optional argument is after bracket in docs

New submission from Chris Jerdonek: >From d...@python.org: """ In a number of places we find documentation with optional leading arguments where the meta-notation (square brackets) are in the wrong place. For example, for range, the standard doc heading says range([start], stop [, st