Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2026-06-21 08:34:55 +00:00
Code Issues Projects Releases Packages Wiki Activity

[3.12] GH-119054: Add "Expanding and resolving paths" section to pathlib docs. (GH-120970) (#121156)

Browse source 
Add dedicated subsection for `home()`, `expanduser()`, `cwd()`,
`absolute()`, `resolve()` and `readlink()`. The position of this section
keeps all the `Path` constructors (`Path()`, `Path.from_uri()`,
`Path.home()` and `Path.cwd()`) near the top. Within the section, closely
related methods are kept adjacent. Specifically:

- `home()` and `expanduser()` (the former calls the latter)
- `cwd()` and `absolute()` (the former calls the latter)
- `absolute()` and `resolve()` (both make paths absolute)
- `resolve()` and `readlink()` (both read symlink targets)
- Ditto `cwd()` and `absolute()`
- Ditto `absolute()` and `resolve()`

The "Other methods" section is removed.

(cherry picked from commit d6d8707ff2)
This commit is contained in:
Barney Gale 2024-06-29 16:38:39 +01:00 • committed by GitHub
parent 6a8cb77f49
commit 22dfecf1f5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 93 additions and 94 deletions
Download patch file Download diff file Expand all files Collapse all files

187
Doc/library/pathlib.rst
View file

@ -793,6 +793,99 @@ Some concrete path methods can raise an :exc:`OSError` if a system call fails
(for example because the path doesn't exist).
Expanding and resolving paths
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. classmethod:: Path.home()
Return a new path object representing the user's home directory (as
returned by :func:`os.path.expanduser` with ``~`` construct). If the home
directory can't be resolved, :exc:`RuntimeError` is raised.
::
>>> Path.home()
PosixPath('/home/antoine')
.. versionadded:: 3.5
.. method:: Path.expanduser()
Return a new path with expanded ``~`` and ``~user`` constructs,
as returned by :meth:`os.path.expanduser`. If a home directory can't be
resolved, :exc:`RuntimeError` is raised.
::
>>> p = PosixPath('~/films/Monty Python')
>>> p.expanduser()
PosixPath('/home/eric/films/Monty Python')
.. versionadded:: 3.5
.. classmethod:: Path.cwd()
Return a new path object representing the current directory (as returned
by :func:`os.getcwd`)::
>>> Path.cwd()
PosixPath('/home/antoine/pathlib')
.. method:: Path.absolute()
Make the path absolute, without normalization or resolving symlinks.
Returns a new path object::
>>> p = Path('tests')
>>> p
PosixPath('tests')
>>> p.absolute()
PosixPath('/home/antoine/pathlib/tests')
.. method:: Path.resolve(strict=False)
Make the path absolute, resolving any symlinks. A new path object is
returned::
>>> p = Path()
>>> p
PosixPath('.')
>>> p.resolve()
PosixPath('/home/antoine/pathlib')
"``..``" components are also eliminated (this is the only method to do so)::
>>> p = Path('docs/../setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')
If the path doesn't exist and *strict* is ``True``, :exc:`FileNotFoundError`
is raised. If *strict* is ``False``, the path is resolved as far as possible
and any remainder is appended without checking whether it exists. If an
infinite loop is encountered along the resolution path, :exc:`RuntimeError`
is raised.
.. versionchanged:: 3.6
The *strict* parameter was added (pre-3.6 behavior is strict).
.. method:: Path.readlink()
Return the path to which the symbolic link points (as returned by
:func:`os.readlink`)::
>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.readlink()
PosixPath('setup.py')
.. versionadded:: 3.9
Querying file type and status
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -1422,100 +1515,6 @@ Ownership and permissions
symbolic link's mode is changed rather than its target's.
Other methods
^^^^^^^^^^^^^
.. classmethod:: Path.cwd()
Return a new path object representing the current directory (as returned
by :func:`os.getcwd`)::
>>> Path.cwd()
PosixPath('/home/antoine/pathlib')
.. classmethod:: Path.home()
Return a new path object representing the user's home directory (as
returned by :func:`os.path.expanduser` with ``~`` construct). If the home
directory can't be resolved, :exc:`RuntimeError` is raised.
::
>>> Path.home()
PosixPath('/home/antoine')
.. versionadded:: 3.5
.. method:: Path.expanduser()
Return a new path with expanded ``~`` and ``~user`` constructs,
as returned by :meth:`os.path.expanduser`. If a home directory can't be
resolved, :exc:`RuntimeError` is raised.
::
>>> p = PosixPath('~/films/Monty Python')
>>> p.expanduser()
PosixPath('/home/eric/films/Monty Python')
.. versionadded:: 3.5
.. method:: Path.readlink()
Return the path to which the symbolic link points (as returned by
:func:`os.readlink`)::
>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.readlink()
PosixPath('setup.py')
.. versionadded:: 3.9
.. method:: Path.absolute()
Make the path absolute, without normalization or resolving symlinks.
Returns a new path object::
>>> p = Path('tests')
>>> p
PosixPath('tests')
>>> p.absolute()
PosixPath('/home/antoine/pathlib/tests')
.. method:: Path.resolve(strict=False)
Make the path absolute, resolving any symlinks. A new path object is
returned::
>>> p = Path()
>>> p
PosixPath('.')
>>> p.resolve()
PosixPath('/home/antoine/pathlib')
"``..``" components are also eliminated (this is the only method to do so)::
>>> p = Path('docs/../setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')
If the path doesn't exist and *strict* is ``True``, :exc:`FileNotFoundError`
is raised. If *strict* is ``False``, the path is resolved as far as possible
and any remainder is appended without checking whether it exists. If an
infinite loop is encountered along the resolution path, :exc:`RuntimeError`
is raised.
.. versionchanged:: 3.6
The *strict* parameter was added (pre-3.6 behavior is strict).
Correspondence to tools in the :mod:`os` module
-----------------------------------------------