From a7ef09ce87459925723a003853fd8afb00cb9bce Mon Sep 17 00:00:00 2001 From: Barney Gale Date: Thu, 13 Jun 2024 21:25:26 +0100 Subject: [PATCH] GH-119054: Add "Renaming and deleting" section to pathlib docs. (#120465) Add dedicated subsection for `pathlib.Path.rename()`, `replace()`, `unlink()` and `rmdir()`. --- Doc/library/pathlib.rst | 124 +++++++++++++++++++++------------------- 1 file changed, 64 insertions(+), 60 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 138e41404dec9cd..278851549c6c3bb 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1429,6 +1429,70 @@ Creating files and directories available. In previous versions, :exc:`NotImplementedError` was raised. +Renaming and deleting +^^^^^^^^^^^^^^^^^^^^^ + +.. method:: Path.rename(target) + + Rename this file or directory to the given *target*, and return a new + :class:`!Path` instance pointing to *target*. On Unix, if *target* exists + and is a file, it will be replaced silently if the user has permission. + On Windows, if *target* exists, :exc:`FileExistsError` will be raised. + *target* can be either a string or another path object:: + + >>> p = Path('foo') + >>> p.open('w').write('some text') + 9 + >>> target = Path('bar') + >>> p.rename(target) + PosixPath('bar') + >>> target.open().read() + 'some text' + + The target path may be absolute or relative. Relative paths are interpreted + relative to the current working directory, *not* the directory of the + :class:`!Path` object. + + It is implemented in terms of :func:`os.rename` and gives the same guarantees. + + .. versionchanged:: 3.8 + Added return value, return the new :class:`!Path` instance. + + +.. method:: Path.replace(target) + + Rename this file or directory to the given *target*, and return a new + :class:`!Path` instance pointing to *target*. If *target* points to an + existing file or empty directory, it will be unconditionally replaced. + + The target path may be absolute or relative. Relative paths are interpreted + relative to the current working directory, *not* the directory of the + :class:`!Path` object. + + .. versionchanged:: 3.8 + Added return value, return the new :class:`!Path` instance. + + +.. method:: Path.unlink(missing_ok=False) + + Remove this file or symbolic link. If the path points to a directory, + use :func:`Path.rmdir` instead. + + If *missing_ok* is false (the default), :exc:`FileNotFoundError` is + raised if the path does not exist. + + If *missing_ok* is true, :exc:`FileNotFoundError` exceptions will be + ignored (same behavior as the POSIX ``rm -f`` command). + + .. versionchanged:: 3.8 + The *missing_ok* parameter was added. + + +.. method:: Path.rmdir() + + Remove this directory. The directory must be empty. + + Other methods ^^^^^^^^^^^^^ @@ -1545,47 +1609,6 @@ Other methods available. In previous versions, :exc:`NotImplementedError` was raised. -.. method:: Path.rename(target) - - Rename this file or directory to the given *target*, and return a new Path - instance pointing to *target*. On Unix, if *target* exists and is a file, - it will be replaced silently if the user has permission. - On Windows, if *target* exists, :exc:`FileExistsError` will be raised. - *target* can be either a string or another path object:: - - >>> p = Path('foo') - >>> p.open('w').write('some text') - 9 - >>> target = Path('bar') - >>> p.rename(target) - PosixPath('bar') - >>> target.open().read() - 'some text' - - The target path may be absolute or relative. Relative paths are interpreted - relative to the current working directory, *not* the directory of the Path - object. - - It is implemented in terms of :func:`os.rename` and gives the same guarantees. - - .. versionchanged:: 3.8 - Added return value, return the new Path instance. - - -.. method:: Path.replace(target) - - Rename this file or directory to the given *target*, and return a new Path - instance pointing to *target*. If *target* points to an existing file or - empty directory, it will be unconditionally replaced. - - The target path may be absolute or relative. Relative paths are interpreted - relative to the current working directory, *not* the directory of the Path - object. - - .. versionchanged:: 3.8 - Added return value, return the new Path instance. - - .. method:: Path.absolute() Make the path absolute, without normalization or resolving symlinks. @@ -1628,25 +1651,6 @@ Other methods strict mode, and no exception is raised in non-strict mode. In previous versions, :exc:`RuntimeError` is raised no matter the value of *strict*. -.. method:: Path.rmdir() - - Remove this directory. The directory must be empty. - - -.. method:: Path.unlink(missing_ok=False) - - Remove this file or symbolic link. If the path points to a directory, - use :func:`Path.rmdir` instead. - - If *missing_ok* is false (the default), :exc:`FileNotFoundError` is - raised if the path does not exist. - - If *missing_ok* is true, :exc:`FileNotFoundError` exceptions will be - ignored (same behavior as the POSIX ``rm -f`` command). - - .. versionchanged:: 3.8 - The *missing_ok* parameter was added. - .. _pathlib-pattern-language: