classification
Title: pathlib's mkdir documentation improvement
Type: enhancement Stage:
Components: Documentation Versions: Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, jlaurens, pitrou
Priority: normal Keywords:

Created on 2019-10-18 10:00 by jlaurens, last changed 2019-10-19 16:52 by xtreak.

Messages (1)
msg354874 - (view) Author: Jérôme Laurens (jlaurens) Date: 2019-10-18 10:00
There are some inconsistencies in the actual documentation of path lib's mkdir doc.

Here is the 3.7 version, annotated and followed by a change proposal

Path.mkdir(mode=0o777, parents=False, exist_ok=False)
Create a new directory at this given path. If mode is given, it is combined with the process’ umask value to determine the file mode and access flags. If the path already exists, FileExistsError is raised. <<<<<<<<<<<<<<<<<< NOT ALWAYS due to exist_ok.

If parents is true, any missing parents of this path are created as needed; they are created with the default permissions without taking mode into account (mimicking the POSIX mkdir -p command).

If parents is false (the default), a missing parent raises FileNotFoundError.

If exist_ok is false (the default), FileExistsError is raised if the target directory already exists.

If exist_ok is true, FileExistsError exceptions will be ignored (same behavior as the POSIX mkdir -p command), but only if the last path component is not an existing non-directory file. <<<<<<<<<<<<<<<<<< UNCLEAR: 1) what is an ignored exception ? 2) The reference to POSIX should appear at the end, like above, 3) the last path component is a string 4) usage of a double negation ignore/is not

----- CHANGE ----

Path.mkdir(mode=0o777, parents=False, exist_ok=False)
Create a new directory in the file system at this given path.

If mode is given, it is combined with the process’ umask value to determine the file mode and access flags.

If parents is false (the default), a missing parent raises FileNotFoundError.

If parents is true, any missing parents of this path are created as needed; they are created with the default permissions without taking mode into account (mimicking the POSIX mkdir -p command).

If exist_ok is false (the default), FileExistsError is raised if the given path already exists in the file system, whether a directory or not.

If exist_ok is true, FileExistsError is raised only if the given path already exists in the file system and is not a directory (same behavior as the POSIX mkdir -p command).

Thanks for reading

JL
History
Date User Action Args
2019-10-19 16:52:11xtreaksetnosy: + pitrou
2019-10-18 10:00:46jlaurenscreate