Document lack of support for keyword arguments in C functions

[twhitema]

BPO	8350
Nosy	@loewis, @birkenfeld, @rhettinger, @terryjreedy, @pitrou, @ericvsmith, @ezio-melotti, @merwok, @ambv
Files	posixmodule.patch: Tries to fix the doc command for posix.mkdir

^{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:

assignee = None
closed_at = None
created_at = <Date 2010-04-08.22:02:36.710>
labels = ['type-bug', 'docs']
title = 'Document lack of support for keyword arguments in C functions'
updated_at = <Date 2019-04-26.17:36:18.158>
user = 'https://bugs.python.org/twhitema'

bugs.python.org fields:

activity = <Date 2019-04-26.17:36:18.158>
actor = 'BreamoreBoy'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2010-04-08.22:02:36.710>
creator = 'twhitema'
dependencies = []
files = ['16836']
hgrepos = []
issue_num = 8350
keywords = ['patch']
message_count = 22.0
messages = ['102648', '102683', '102713', '102714', '102716', '102717', '104113', '104114', '104116', '105366', '105367', '112071', '112078', '112079', '125017', '125018', '125019', '125021', '125024', '125026', '125034', '227854']
nosy_count = 14.0
nosy_names = ['loewis', 'georg.brandl', 'rhettinger', 'terry.reedy', 'pitrou', 'eric.smith', 'fossilet', 'ezio.melotti', 'eric.araujo', 'twhitema', 'schof', 'l0nwlf', 'docs@python', 'lukasz.langa']
pr_nums = []
priority = 'normal'
resolution = 'accepted'
stage = 'needs patch'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue8350'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']

[twhitema]

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.

[l0nwlf]

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.

[pitrou]

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

[merwok]

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]

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.

[merwok]

A more attainable fix would be a way to mark up positional-only arguments that have a default value.

[merwok]

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

[pitrou]

I think it would be overkill to add special markup for positional-only arguments. I think we should just close the issue as invalid.

[merwok]

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]

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.

[schof]

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