The 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.

Tested 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:
1. Patch python-svn/Modules/posixmodule.c to take the keyword arguments.
2. 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

The 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.

Please 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.

I'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.)

Closing as invalid would not be wise because using named arguments as keywords is in Python taken for granted. Cases that are exceptions from this rule should be explicitly noted as to avoid confusion, especially for less experienced programmers.

Similar case for builtins: #9426

Currently it's somewhat surprising that while the documentation often states the default values for certain builtins, invoking the builtin with keyword arguments as described in the documentation does not work.

Original discussion: #7447

I'm going through all builtins to see how the keyword arg support looks and I'm going to present a patch for Doc/library/builtins.rst that explicitly states that builtins don't support this kind of invocation.

Expect a patch for that case later today. As for `os` et al, the discussion goes on.

You could copy this notice from reference/expressions#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.”

An addition to documenting/rest or documenting/markup would be useful too.

Hmm, it may indeed be the best option to add a new directive option to say "this function does not take keyword args".  It would result in some form of unobtrusive but noticeable output in HTML.

It is a bit of an effort to add it everywhere it's necessary, but the most important instances (e.g. string methods) can be covered quickly, and it's fairly easy to grep the other instances (namely, grepping for METH_O and METH_VARARGS without METH_KEYWORDS).

> Hmm, it may indeed be the best option to add a new directive option to
> say "this function does not take keyword args".  It would result in
> some form of unobtrusive but noticeable output in HTML.

Isn't it kind of a CPython-specific detail, though?

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.

> Isn'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.

Has the Argument Clinic had an impact on this or is that a different kettle of fish?