summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorHynek Schlawack <hs@ox.cx>2012-10-07 16:04:38 (GMT)
committerHynek Schlawack <hs@ox.cx>2012-10-07 16:04:38 (GMT)
commit0230b6af78c9059016df341dc94a4a09ccbe3881 (patch)
tree4e55f0d6c4cf3ab18b9f7af7865d96d0a44d6ef6
parent83fe2e1c22e6ff72a308e82e1e24ca03f8c51339 (diff)
downloadcpython-0230b6af78c9059016df341dc94a4a09ccbe3881.zip
cpython-0230b6af78c9059016df341dc94a4a09ccbe3881.tar.gz
cpython-0230b6af78c9059016df341dc94a4a09ccbe3881.tar.bz2
#13498: Clarify docs of os.makedirs()'s exist_ok argument.
Done with great native-speaker help from R. David Murray.
-rw-r--r--Doc/library/os.rst19
-rw-r--r--Misc/NEWS3
2 files changed, 14 insertions, 8 deletions
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 5991e29..410e03a 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1183,18 +1183,21 @@ Files and Directories
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
index 5cd69b4..409c1f3 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -609,6 +609,9 @@ Build
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.