Skip to content

gh-72073: Clarify pathlib rename() and replace() docs #149323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
purushothamanlabi wants to merge 1 commit into from
+15 −7
Closed

gh-72073: Clarify pathlib rename() and replace() docs #149323

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 15 additions & 7 deletions Doc/library/pathlib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1626,9 +1626,14 @@ Copying, moving 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.
:class:`!Path` instance pointing to *target*. This method is implemented
in terms of :func:`os.rename`, and gives the same guarantees.

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. If you want to replace the target
consistently across platforms, use :meth:`Path.replace`.

*target* can be either a string or another path object::

>>> p = Path('foo')
Expand All @@ -1644,17 +1649,20 @@ Copying, moving and deleting
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.
:class:`!Path` instance pointing to *target*. Unlike :meth:`Path.rename`,
if *target* points to an existing file or empty directory, it will be
unconditionally replaced.

This method is implemented in terms of :func:`os.replace`; use it when you
want consistent cross-platform replacement semantics for an existing file or
empty directory.

The target path may be absolute or relative. Relative paths are interpreted
relative to the current working directory, *not* the directory of the
Expand Down
Loading