Skip to content

Commit

Permalink
GH-119054: Add "Renaming and deleting" section to pathlib docs. (#120465
Browse files Browse the repository at this point in the history
)

Add dedicated subsection for `pathlib.Path.rename()`, `replace()`,
`unlink()` and `rmdir()`.
  • Loading branch information
barneygale committed Jun 13, 2024
1 parent a3711af commit d88a1f2
Showing 1 changed file with 64 additions and 60 deletions.
124 changes: 64 additions & 60 deletions Doc/library/pathlib.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
^^^^^^^^^^^^^

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:

Expand Down

0 comments on commit d88a1f2

Please sign in to comment.