On 01/27/2014 01:39 AM, Antoine Pitrou wrote:

On Sun, 26 Jan 2014 21:01:08 -0800
Larry Hastings <larry@hastings.org> wrote:

On 01/26/2014 08:40 PM, Alexander Belopolsky wrote:

On Sun, Jan 26, 2014 at 11:26 PM, Vajrasky Kok 
<sky.kok@speaklikeaking.com <mailto:sky.kok@speaklikeaking.com>> wrote:

    In case we are taking "not backporting anything at all" road, what is
    the best fix for the document?


I would say no fix is needed for this doc because the signature 
suggests (correctly) that passing times by keyword is not supported.

Where does it do that?

In the "[,times]" spelling, which is the spelling customarily used for
positional-only arguments.

That's not my experience. It's very common--in fact I believe more common--for functions that only accept positional arguments to *not* use the square-brackets-for-optional-parameters convention. The square-brackets-for-optional-parameters convention is not legal Python syntax, so I observe that documentation authors avoid it when they can, preferring to express their function's signature in real Python. As an example, consider "heapq.nlargest(n, iterable, key=None)". The implementation uses PyArg_ParseTuple to parse its parameters, and therefore does not accept keyword arguments. But--no square brackets.

My experience is that the doc convention of square-brackets-for-optional-parameters is primarily used in two circumstances: one, when doing something really crazy like optional groups, and two, when the default value of one of the function's parameters is inconvenient to specify as a Python value. Of these two the second is far more common.

An example of this latter case is zlib.compressobj(). The documentation shows its last parameter as "[, zdict]". However, the implementation parses uses PyArg_ParseTupleAndKeywords(), and therefore accepts keyword arguments.

Furthermore, this notation simply cannot be used for functions that have only required parameters. You can't look at the constructor for "memoryview(object)" and determine whether or not it accepts keyword arguments. (It does.)

There seems to be no strong correlation between functions that only accept positional-only parameters and functions whose documentation uses square-brackets-for-optional-parameters. Indeed, this is one of the things that can be frustrating about Python, which is why I hope we can make Python 3.5 more predictable in this area.

/arry