[Python-Dev] Negative times behaviour in itertools.repeat for Python maintenance releases (2.7, 3.3 and maybe 3.4)
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...
More information about the Python-Dev