[New-bugs-announce] [issue38514] pathlib's mkdir documentation improvement

Jérôme Laurens report at bugs.python.org
Fri Oct 18 06:00:47 EDT 2019


New submission from Jérôme Laurens <jerome.laurens at u-bourgogne.fr>:

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

----------
assignee: docs at python
components: Documentation
messages: 354874
nosy: docs at python, jlaurens
priority: normal
severity: normal
status: open
title: pathlib's mkdir documentation improvement
type: enhancement
versions: Python 3.7

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue38514>
_______________________________________


More information about the New-bugs-announce mailing list