mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-10 03:49:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

[3.12] GH-119054: Add "Renaming and deleting" section to pathlib docs. (GH-120465) (#120473)

Browse source 
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 d88a1f2e15)

Co-authored-by: Barney Gale <barney.gale@gmail.com>
This commit is contained in:
Miss Islington (bot) 2024-06-13 22:31:52 +02:00 • committed by GitHub
parent 7719eefcce
commit c9fc099c59
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 64 additions and 60 deletions
Download patch file Download diff file Expand all files Collapse all files

124
Doc/library/pathlib.rst
View file

@ -1316,6 +1316,70 @@ Creating files and directories
.. versionadded:: 3.10
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
^^^^^^^^^^^^^
@ -1409,47 +1473,6 @@ Other methods
.. versionadded:: 3.9
.. 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.
@ -1489,25 +1512,6 @@ Other methods
The *strict* parameter was added (pre-3.6 behavior is 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.
Correspondence to tools in the :mod:`os` module
-----------------------------------------------