[Python-Dev] How to document functions with optional positional parameters?

[Nick Coghlan]

On 22 March 2015 at 04:47, Terry Reedy <tjreedy at udel.edu> wrote:
> On 3/21/2015 12:41 AM, Serhiy Storchaka wrote:
>>
>> How to document functions with optional positional parameters?
>>
>> For example binascii.crc32(). It has two positional parameters, one is
>> mandatory, and one is optional with default value 0. With Argument
>> Clinic its signature is crc32(data, crc=0, /). In the documentation it
>> is written as crc32(data[, crc]) (and noted that the default value of
>> the second parameter is 0). Both are not valid Python syntax. Can the
>> documentation be change to crc32(data, crc=0)?
>
>
> I think the docs should be using / as well.

Right, even though the Python level parser doesn't allow this syntax,
it's the one used by Argument Clinic to express positional-only
parameters for functions defined in C, and as a result the inspect
module uses it as well:

>>> import inspect
>>> print(inspect.signature(hex))
(number, /)

This is the specific problem Larry was aiming to address in
https://www.python.org/dev/peps/pep-0457/ - getting the docs, Argument
Clinic and the inspect module to align in their notation, even though
he wasn't proposing to change Python itself to allow positional-only
parameter definitions.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia