[Python-Dev] Negative times behaviour in itertools.repeat for Python maintenance releases (2.7, 3.3 and maybe 3.4)

Larry Hastings larry at hastings.org
Mon Jan 27 13:01:02 CET 2014

On 01/27/2014 01:39 AM, Antoine Pitrou wrote:
> On Sun, 26 Jan 2014 21:01:08 -0800
> Larry Hastings <larry at 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 at speaklikeaking.com <mailto:sky.kok at 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 

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.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20140127/bf4bd671/attachment.html>

More information about the Python-Dev mailing list