(original) (raw)


On 01/27/2014 01:39 AM, Antoine Pitrou wrote:
On Sun, 26 Jan 2014 21:01:08 -0800  
Larry Hastings  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 > 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