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

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 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/ -------------- 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