Repository navigation
Document lack of support for keyword arguments in C functions #52597
Description
Activity
twhitema commented
on Apr 8, 2010 twhitemamannequinMannequinAuthorThe doc command for os.mkdir is incorrect (at least for posix). It specifies that there is an optional mode keyword, but it's not a keyword argument, see below:
>>> import os >>> help(os.mkdir) mkdir(...) mkdir(path [, mode=0777]) Create a directory. >>> os.mkdir("/tmp/1", mode=777) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: mkdir() takes no keyword arguments
Suggest the following doc comment change:
mkdir(...) mkdir(path [, mode]) Create a directory. Mode defaults to 0777 if not specified.
l0nwlf commented
on Apr 9, 2010 l0nwlfmannequinMannequinTested on trunk.
11:46:02 l0nwlf-MBP:python-svn $ ./python.exe Python 2.7a4+ (trunk:79888M, Apr 9 2010, 11:41:22) [GCC 4.2.1 (Apple Inc. build 5646) (dot 1)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import posix >>> posix.mkdir('1') >>> posix.mkdir('2', 000) >>> posix.mkdir('3', mode=000) Traceback (most recent call last): File "<input>", line 1, in <module> TypeError: mkdir() takes no keyword arguments >>> import os >>> os.mkdir('4', 777) >>> os.mkdir('5', mode=777) Traceback (most recent call last): File "<input>", line 1, in <module> TypeError: mkdir() takes no keyword arguments >>>
The two options to fix this are:
- Patch python-svn/Modules/posixmodule.c to take the keyword arguments.
- Modify the PyDoc in posixmodule.c as Todd suggested.
I had attached a patch which solves the issue using solution '2'.
Also I observed that os.makedirs() have no such issue even though it uses os.mkdir() because it uses 'mkdir(name, mode)' to call mkdir.
The docstring looks right to me. "mode=0777" doesn't mean it takes a keyword argument, only that this argument has a default value.
You might want to fix posixmodule to accept keyword arguments, but it should probably be done for all functions then. An mkdir-specific patch would have little point IMO (after all it takes only two args, there's hardly any risk of confusion).
Hello
This is a recurrent problem with Python functions implemented in C. Since introspection is not possible, developers have to use the first line of the docstring to write the signature, including default arguments. With your patch, people can’t rely on IDE tooltips that display introspected signature + first line of docstring anymore.
The ideal right fix would be for C functions to support introspection, e.g. with PEP-362.
Regards
l0nwlf commented
on Apr 9, 2010 l0nwlfmannequinMannequinThe ideal right fix would be for C functions to support introspection - Agreed, but then it will be needed to do so in quite a number of C codes.
A more attainable fix would be a way to mark up positional-only arguments that have a default value.
From http://docs.python.org/dev/reference/expressions.html#calls
“An implementation may provide built-in functions whose positional parameters do not have names, even if they are ‘named’ for the purpose of documentation, and which therefore cannot be supplied by keyword.”
I think it would be overkill to add special markup for positional-only arguments. I think we should just close the issue as invalid.
The comment I made before yours supports that. It’s not a bug, it’s a documented behavior that just needs more exposure in the intro to the docs. (Do we have a page explaining markup?)
The real real fix would be for C functions to accept kwargs, but as far as doc is concerned, it’s ok.
schof commented
on May 9, 2010 schofmannequinMannequinPlease don't close this as "invalid."
Most (all?) of the functions in the os module have positional-only arguments, which are documented in exactly the same manner as arguments which can be supplied using a keyword.
As someone reading the documentation, how am I supposed to know which arguments can be supplied with keywords and which can't?
This ticket and the link to http://docs.python.org/dev/reference/expressions.html#calls are helpful in explaining this now, but I would NEVER have thought to look there to find out why os.fdopen isn't working the way it's documented. Requiring me to experiment to determine which function works which way seems to miss the point of having documentation in the first place.
I take no position on whether this should be fixed with a documentation change or a code change, but it should be fixed. If the consensus is that a documentation change would be quicker to implement, I'm happy to submit a doc patch.
schof commented
on May 9, 2010 schofmannequinMannequinI'd also suggest changing the title to "Documentation for many functions in os module is incomplete." I didn't because I don't know if that would be considered rude. (I'm new to the Python community.)
8 remaining items
Yes. It's still an important detail; the explanation could say, "In CPython, this function does not take keyword args" and furthermore it's not really clear to me how much of the library reference applies to all Python implementations anyway.
This is an implementation detail specific to CPython and subject to change. I'm -1 on documenting it for every function/method and thereby making it part of the language spec. We've lived without this spec for almost twenty years, so I'm inclined to think it is truly unimportant.
It is sufficient to mention just once in the docs that CPython functions/methods sometimes don't take keywords.
I think that the warning that things are not always as they seem should be repeated in the front of the library manual where the pseudo-arg names are actual used, so the library manual stands on its own. In any case, I believe a lot of people use the lib ref without reading and remembering every detail of the language ref.
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.
loewis commented
on Jan 2, 2011 loewismannequinMannequinIsn't it kind of a CPython-specific detail, though?
If other implementations do provide proper keyword arguments,
I'd be skeptical that they all settled on the names that the
library documentation gives to the arguments.- changed the title
[-]Document lack of support for keyword arguments in C functions[/-][+]Document lack of support for keyword arguments in C functions[/+]on Jan 2, 2011 - changed the title
[-]Document lack of support for keyword arguments in C functions[/-][+]Document lack of support for keyword arguments in C functions[/+]on Jan 22, 2013 BreamoreBoy commented
on Sep 29, 2014 BreamoreBoymannequinMannequinHas the Argument Clinic had an impact on this or is that a different kettle of fish?
- added a commit that references this issue
on Sep 29, 2022 At least some C functions (like
os.mkdir()) do support keyword arguments now, but I'm not sure about the coverage of this support. Please help decide whether this issue should remain open if you know more about this.Some but not all positional-only C function parameters have been converted. @serhiy-storchaka either proposes or has added '' markers to signatures of builtin functions and has proposed/worked on making names consistent between doc strings and doc entry.
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields: