How to document functions with optional positional parameters?
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)? Related issues: https://bugs.python.org/issue21488 (changed encode(obj, encoding='ascii', errors='strict') to encode(obj, [encoding[, errors]])) https://bugs.python.org/issue22832 (changed ioctl(fd, op[, arg[, mutate_flag]]) to ioctl(fd, request, arg=0, mutate_flag=True)) https://bugs.python.org/issue22341 (discussed changing crc32(data[, crc]) to crc32(data, crc=0))
Le samedi 21 mars 2015, Serhiy Storchaka <storchaka@gmail.com> a écrit :
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, /). The \ is useful, it indicates that you cannot use keywords. If you want to drop \, modify the function to accept keywords.
On 21.03.15 13:03, Victor Stinner wrote:
The \ is useful, it indicates that you cannot use keywords.
Wouldn't it confuse users?
If you want to drop \, modify the function to accept keywords.
Yes, this is a solution. But parsing keyword arguments is slower than parsing positional arguments. And I'm working on patches that optimizes parsing code generated by Argument Clinic. First my patches will handle only positional parameters, with keywords it is harder.
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.
Related issues:
https://bugs.python.org/issue21488 (changed encode(obj, encoding='ascii', errors='strict') to encode(obj, [encoding[, errors]]))
https://bugs.python.org/issue22832 (changed ioctl(fd, op[, arg[, mutate_flag]]) to ioctl(fd, request, arg=0, mutate_flag=True))
https://bugs.python.org/issue22341 (discussed changing crc32(data[, crc]) to crc32(data, crc=0))
-- Terry Jan Reedy
On 22 March 2015 at 04:47, Terry Reedy <tjreedy@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@gmail.com | Brisbane, Australia
participants (4)
-
Nick Coghlan -
Serhiy Storchaka -
Terry Reedy -
Victor Stinner