[docs] [issue8350] Document lack of support for keyword arguments in C functions

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

If there is no indication in the lib manual as to which parameter names and defaults are real and which are fake, then the safe guideline is to never use keywards for library functions and methods and always pass everything positionally.

Slightly more complicated is to be aware of which classes and modules are Python versus C coded. (If needed, change for module.py in /Lib.) For some modules, one can take a cue from doc examples that use keywords.

Otherwise, each person has to experiment for himself and  check each TypeError messages to determine whether it arises from a misspelling or a hidden limitation. And maybe go through the same process a year later after forgetting.

>"We've lived without this spec for almost twenty years,"
Yes, and people have been stumbling on this and complaining for probably just as long. Since []s are no longer used in the doc to indicate 'optional', they can and are being used to indicate 'position-only'. Specify in the introduction, where notation should be explained, that the limitation is only for current CPython and may be changed in the future or be different for other implementations. However....

In my opinion, the real solution is to remove the limitation. Since the language spec says args can be passed by keyword as well as by position, make it be that way for everything we distribute.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue8350>
_______________________________________