[issue13498] os.makedirs exist_ok documentation is incorrect, as is some of the behavior

[R. David Murray]

New submission from R. David Murray <rdmurray at bitdance.com>:

The documentation for os.makedirs says:

  If the target directory with the same mode as specified already exists, raises an OSError exception if exist_ok is False, otherwise no exception is raised.

This is not correct.  If the file exists but the mode is different than that specified (or defaulted) after applying the umask, then an error is raised regardless of the value of exist_ok.  The above wording also implies that if the directory exists but has a different mode, that the mode will be changed.  Again, this is not what the code does.

It's not clear how useful this raise behavior is, but reading the original issue that added this option it is clearly intentional.  The documented behavior does seem useful, but if it actually reset the mode that would be a fairly significant behavior change, and would not be a good idea if the user had not specified a mode.  However, at the very least exists_ok should not raise if no mode was specified in the call.

The error message raised is also wrong in this case, since it says that the error is that the file already exists when we've said that that is OK.  A custom error message for this case would be better.

----------
assignee: docs at python
components: Documentation, Library (Lib)
keywords: easy
messages: 148564
nosy: docs at python, r.david.murray
priority: normal
severity: normal
stage: needs patch
status: open
title: os.makedirs exist_ok documentation is incorrect, as is some of the behavior
type: behavior
versions: Python 3.2, Python 3.3

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