[Python-checkins] cpython (3.2): #13498: Clarify docs of os.makedirs()'s exist_ok argument.

[hynek.schlawack]

http://hg.python.org/cpython/rev/88a7b9c3b6c0
changeset:   79591:88a7b9c3b6c0
branch:      3.2
parent:      79587:e4598364ea29
user:        Hynek Schlawack <hs at ox.cx>
date:        Sun Oct 07 18:04:38 2012 +0200
summary:
  #13498: Clarify docs of os.makedirs()'s exist_ok argument.

Done with great native-speaker help from R. David Murray.

files:
  Doc/library/os.rst |  19 +++++++++++--------
  Misc/NEWS          |   3 +++
  2 files changed, 14 insertions(+), 8 deletions(-)


diff --git a/Doc/library/os.rst b/Doc/library/os.rst
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1183,18 +1183,21 @@
       single: UNC paths; and os.makedirs()
 
    Recursive directory creation function.  Like :func:`mkdir`, but makes all
-   intermediate-level directories needed to contain the leaf directory.  If
-   the target directory with the same mode as specified already exists,
-   raises an :exc:`OSError` exception if *exist_ok* is False, otherwise no
-   exception is raised.  If the directory cannot be created in other cases,
-   raises an :exc:`OSError` exception.  The default *mode* is ``0o777`` (octal).
-   On some systems, *mode* is ignored.  Where it is used, the current umask
-   value is first masked out.
+   intermediate-level directories needed to contain the leaf directory.
+
+   The default *mode* is ``0o777`` (octal).  On some systems, *mode* is
+   ignored.  Where it is used, the current umask value is first masked out.
+
+   If *exists_ok* is ``False`` (the default), an :exc:`OSError` is raised if
+   the target directory already exists.  If *exists_ok* is ``True`` an
+   :exc:`OSError` is still raised if the umask-masked *mode* is different from
+   the existing mode, on systems where the mode is used.  :exc:`OSError` will
+   also be raised if the directory creation fails.
 
    .. note::
 
       :func:`makedirs` will become confused if the path elements to create
-      include :data:`pardir`.
+      include :data:`pardir` (eg. ".." on UNIX systems).
 
    This function handles UNC paths correctly.
 
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -609,6 +609,9 @@
 Documentation
 -------------
 
+- Issue #13498: Clarify docs of os.makedirs()'s exist_ok argument.  Done with
+  great native-speaker help from R. David Murray.
+
 - Issue #15533: Clarify docs and add tests for subprocess.Popen()'s cwd
   argument.
 

-- 
Repository URL: http://hg.python.org/cpython