[issue8350] os.mkdir doc comment is incorrect

Łukasz Langa added the comment: 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

[issue8350] os.mkdir doc comment is incorrect

Changes by Éric Araujo : -- assignee: georg.brandl -> d...@python nosy: +d...@python ___ Python tracker ___ ___ Python-bugs-list mailin

[issue8350] os.mkdir doc comment is incorrect

John Mark Schofield added the comment: 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.) -- ___ P

[issue8350] os.mkdir doc comment is incorrect

John Mark Schofield added the comment: 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,

[issue8350] os.mkdir doc comment is incorrect

Éric Araujo added the comment: 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 do

[issue8350] os.mkdir doc comment is incorrect

Antoine Pitrou added the comment: I think it would be overkill to add special markup for positional-only arguments. I think we should just close the issue as invalid. -- ___ Python tracker

[issue8350] os.mkdir doc comment is incorrect

Éric Araujo added the comment: >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 b

[issue8350] os.mkdir doc comment is incorrect

Éric Araujo added the comment: A more attainable fix would be a way to mark up positional-only arguments that have a default value. -- ___ Python tracker ___ ___

[issue8350] os.mkdir doc comment is incorrect

Shashwat Anand added the comment: 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. -- ___ Python tracker ___

[issue8350] os.mkdir doc comment is incorrect

Éric Araujo added the comment: 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

[issue8350] os.mkdir doc comment is incorrect

Antoine Pitrou added the comment: 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-

[issue8350] os.mkdir doc comment is incorrect

Shashwat Anand added the comment: 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 >

[issue8350] os.mkdir doc comment is incorrect

New submission from Todd Whiteman : 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 direc