https://github.com/python/cpython/commit/d5ad3b7fc8f5c02210b19bf833582f9f89010658
commit: d5ad3b7fc8f5c02210b19bf833582f9f89010658
branch: 3.13
author: Miss Islington (bot) <31488909+miss-isling...@users.noreply.github.com>
committer: barneygale <barney.g...@gmail.com>
date: 2024-06-13T20:43:59Z
summary:
[3.13] GH-119054: Add "Renaming and deleting" section to pathlib docs.
(GH-120465) (#120472)
GH-119054: Add "Renaming and deleting" section to pathlib docs. (GH-120465)
Add dedicated subsection for `pathlib.Path.rename()`, `replace()`,
`unlink()` and `rmdir()`.
(cherry picked from commit d88a1f2e156cd1072119afa91d4f4dc4037c1b21)
Co-authored-by: Barney Gale <barney.g...@gmail.com>
files:
M Doc/library/pathlib.rst
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 5b38fe25b5e2a8..ebed9d50931061 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1411,6 +1411,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
^^^^^^^^^^^^^
@@ -1528,47 +1592,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.
@@ -1611,25 +1634,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:
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
