homepage

When a function has only positional arguments and at least one argument is optional, the expected signature is:
 func(mandatory_arg1, mandatory_arg2[, optional_arg3[, optinal_arg4]])
For example, the signature of format() is inconsistent with its documentation.
Signature:
---
$ python3 -c 'help(format)'|cat
Help on built-in function format in module builtins:
format(value, format_spec='', /)
 Return value.__format__(format_spec)
 
 format_spec defaults to the empty string
---
Documentation:
---
.. function:: format(value[, format_spec])
---
Attached patch is a first attempt to fix the issue. The problem is that my heuristic to check if an argument is "optional" doesn't seem to work as expected in all cases. I chose to check if the C default is NULL.
The problem is that some functions defines a C default to NULL whereas the Python default is set to a different value and is correct.
Example with _io.FileIO.truncate:
 /*[clinic input]
 _io.FileIO.truncate
 size as posobj: object = NULL
 /
whereas the documentation says that the default is None:
 .. method:: truncate(size=None)
It's easy to fix the default, but in this case my change doesn't fix the signature anymore since the C default is still NULL:
 /*[clinic input]
 _io.FileIO.truncate
 size as posobj: object(c_default="NULL") = None
 /
We need a different heuristic than C default is NULL, or we should fix functions where the heuristic fails.