From 46ed3d891871afc83ee8a1eed400fc5256721118 Mon Sep 17 00:00:00 2001 From: barneygale Date: Fri, 7 Jun 2024 01:03:27 +0100 Subject: [PATCH 1/3] GH-119054: Add "Creating files and directories" section to pathlib docs. Add dedicated subsection for `pathlib.Path.touch()`, `mkdir()`, `symlink_to()` and `hardlink_to()`. Also note that `open()`, `write_text()` and `write_bytes()` are often used to create files. --- Doc/library/pathlib.rst | 165 +++++++++++++++++++++------------------- 1 file changed, 86 insertions(+), 79 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index b7ab44706a0160..86effeb5139999 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1343,6 +1343,92 @@ Reading directories .. versionadded:: 3.12 +Creating files and directories +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. method:: Path.touch(mode=0o666, exist_ok=True) + + Create a file 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 file already exists, the function succeeds if *exist_ok* + is true (and its modification time is updated to the current time), + otherwise :exc:`FileExistsError` is raised. + + .. seealso:: + The :meth:`~Path.open`, :meth:`~Path.write_text` and + :meth:`~Path.write_bytes` methods are commonly used to create files. + + +.. method:: 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, :exc:`FileExistsError` + is raised. + + 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 + :exc:`FileNotFoundError`. + + If *exist_ok* is false (the default), :exc:`FileExistsError` is + raised if the target directory already exists. + + If *exist_ok* is true, :exc:`FileExistsError` will not be raised unless the given + path already exists in the file system and is not a directory (same + behavior as the POSIX ``mkdir -p`` command). + + .. versionchanged:: 3.5 + The *exist_ok* parameter was added. + + +.. method:: Path.symlink_to(target, target_is_directory=False) + + Make this path a symbolic link pointing to *target*. + + On Windows, a symlink represents either a file or a directory, and does not + morph to the target dynamically. If the target is present, the type of the + symlink will be created to match. Otherwise, the symlink will be created + as a directory if *target_is_directory* is ``True`` or a file symlink (the + default) otherwise. On non-Windows platforms, *target_is_directory* is ignored. + + :: + + >>> p = Path('mylink') + >>> p.symlink_to('setup.py') + >>> p.resolve() + PosixPath('/home/antoine/pathlib/setup.py') + >>> p.stat().st_size + 956 + >>> p.lstat().st_size + 8 + + .. note:: + The order of arguments (link, target) is the reverse + of :func:`os.symlink`'s. + + .. versionchanged:: 3.13 + Raises :exc:`UnsupportedOperation` if :func:`os.symlink` is not + available. In previous versions, :exc:`NotImplementedError` was raised. + + +.. method:: Path.hardlink_to(target) + + Make this path a hard link to the same file as *target*. + + .. note:: + The order of arguments (link, target) is the reverse + of :func:`os.link`'s. + + .. versionadded:: 3.10 + + .. versionchanged:: 3.13 + Raises :exc:`UnsupportedOperation` if :func:`os.link` is not + available. In previous versions, :exc:`NotImplementedError` was raised. + + Other methods ^^^^^^^^^^^^^ @@ -1426,31 +1512,6 @@ Other methods symbolic link's mode is changed rather than its target's. -.. method:: 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, :exc:`FileExistsError` - is raised. - - 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 - :exc:`FileNotFoundError`. - - If *exist_ok* is false (the default), :exc:`FileExistsError` is - raised if the target directory already exists. - - If *exist_ok* is true, :exc:`FileExistsError` will not be raised unless the given - path already exists in the file system and is not a directory (same - behavior as the POSIX ``mkdir -p`` command). - - .. versionchanged:: 3.5 - The *exist_ok* parameter was added. - - .. method:: Path.owner(*, follow_symlinks=True) Return the name of the user owning the file. :exc:`KeyError` is raised @@ -1572,60 +1633,6 @@ Other methods Remove this directory. The directory must be empty. -.. method:: Path.symlink_to(target, target_is_directory=False) - - Make this path a symbolic link pointing to *target*. - - On Windows, a symlink represents either a file or a directory, and does not - morph to the target dynamically. If the target is present, the type of the - symlink will be created to match. Otherwise, the symlink will be created - as a directory if *target_is_directory* is ``True`` or a file symlink (the - default) otherwise. On non-Windows platforms, *target_is_directory* is ignored. - - :: - - >>> p = Path('mylink') - >>> p.symlink_to('setup.py') - >>> p.resolve() - PosixPath('/home/antoine/pathlib/setup.py') - >>> p.stat().st_size - 956 - >>> p.lstat().st_size - 8 - - .. note:: - The order of arguments (link, target) is the reverse - of :func:`os.symlink`'s. - - .. versionchanged:: 3.13 - Raises :exc:`UnsupportedOperation` if :func:`os.symlink` is not - available. In previous versions, :exc:`NotImplementedError` was raised. - - -.. method:: Path.hardlink_to(target) - - Make this path a hard link to the same file as *target*. - - .. note:: - The order of arguments (link, target) is the reverse - of :func:`os.link`'s. - - .. versionadded:: 3.10 - - .. versionchanged:: 3.13 - Raises :exc:`UnsupportedOperation` if :func:`os.link` is not - available. In previous versions, :exc:`NotImplementedError` was raised. - - -.. method:: Path.touch(mode=0o666, exist_ok=True) - - Create a file 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 file already exists, the function succeeds if *exist_ok* - is true (and its modification time is updated to the current time), - otherwise :exc:`FileExistsError` is raised. - - .. method:: Path.unlink(missing_ok=False) Remove this file or symbolic link. If the path points to a directory, From 6c33e0415dd462d0bb51142c5f6e412fc669375d Mon Sep 17 00:00:00 2001 From: barneygale Date: Fri, 7 Jun 2024 16:03:57 +0100 Subject: [PATCH 2/3] Simplify wording --- Doc/library/pathlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 86effeb5139999..84e1b7f7f0c82d 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1356,7 +1356,7 @@ Creating files and directories .. seealso:: The :meth:`~Path.open`, :meth:`~Path.write_text` and - :meth:`~Path.write_bytes` methods are commonly used to create files. + :meth:`~Path.write_bytes` methods are often used to create files. .. method:: Path.mkdir(mode=0o777, parents=False, exist_ok=False) From 7800a46505eb18d702ae41d7a7451919cc63c76b Mon Sep 17 00:00:00 2001 From: Barney Gale Date: Thu, 13 Jun 2024 18:41:57 +0100 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/library/pathlib.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 84e1b7f7f0c82d..138e41404dec9c 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1349,8 +1349,8 @@ Creating files and directories .. method:: Path.touch(mode=0o666, exist_ok=True) Create a file 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 file already exists, the function succeeds if *exist_ok* + with the process's ``umask`` value to determine the file mode and access + flags. If the file already exists, the function succeeds when *exist_ok* is true (and its modification time is updated to the current time), otherwise :exc:`FileExistsError` is raised. @@ -1362,7 +1362,7 @@ Creating files and directories .. method:: 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 + combined with the process's ``umask`` value to determine the file mode and access flags. If the path already exists, :exc:`FileExistsError` is raised. @@ -1391,7 +1391,7 @@ Creating files and directories On Windows, a symlink represents either a file or a directory, and does not morph to the target dynamically. If the target is present, the type of the symlink will be created to match. Otherwise, the symlink will be created - as a directory if *target_is_directory* is ``True`` or a file symlink (the + as a directory if *target_is_directory* is true or a file symlink (the default) otherwise. On non-Windows platforms, *target_is_directory* is ignored. ::