mirror of https://github.com/python/cpython
[3.13] GH-119054: Add "Expanding and resolving paths" section to pathlib docs. (GH-120970) (#121155)
GH-119054: Add "Expanding and resolving paths" section to pathlib docs. (GH-120970)
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)
Co-authored-by: Barney Gale <barney.gale@gmail.com>
This commit is contained in:
Miss Islington (bot)
GitHub
parent
d96a52e136
commit
c70f1122b4
|
|
@ -872,6 +872,107 @@ conforming to :rfc:`8089`.
|
|||
it strictly impure.
|
||||
|
||||
|
||||
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 a path doesn't exist or a symlink loop is encountered, and *strict* is
|
||||
``True``, :exc:`OSError` is raised. If *strict* is ``False``, the path is
|
||||
resolved as far as possible and any remainder is appended without checking
|
||||
whether it exists.
|
||||
|
||||
.. versionchanged:: 3.6
|
||||
The *strict* parameter was added (pre-3.6 behavior is strict).
|
||||
|
||||
.. versionchanged:: 3.13
|
||||
Symlink loops are treated like other errors: :exc:`OSError` is raised in
|
||||
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.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
|
||||
|
||||
.. versionchanged:: 3.13
|
||||
Raises :exc:`UnsupportedOperation` if :func:`os.readlink` is not
|
||||
available. In previous versions, :exc:`NotImplementedError` was raised.
|
||||
|
||||
|
||||
Querying file type and status
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -1537,107 +1638,6 @@ Permissions and ownership
|
|||
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
|
||||
|
||||
.. versionchanged:: 3.13
|
||||
Raises :exc:`UnsupportedOperation` if :func:`os.readlink` is not
|
||||
available. In previous versions, :exc:`NotImplementedError` was raised.
|
||||
|
||||
|
||||
.. 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 a path doesn't exist or a symlink loop is encountered, and *strict* is
|
||||
``True``, :exc:`OSError` is raised. If *strict* is ``False``, the path is
|
||||
resolved as far as possible and any remainder is appended without checking
|
||||
whether it exists.
|
||||
|
||||
.. versionchanged:: 3.6
|
||||
The *strict* parameter was added (pre-3.6 behavior is strict).
|
||||
|
||||
.. versionchanged:: 3.13
|
||||
Symlink loops are treated like other errors: :exc:`OSError` is raised in
|
||||
strict mode, and no exception is raised in non-strict mode. In previous
|
||||
versions, :exc:`RuntimeError` is raised no matter the value of *strict*.
|
||||
|
||||
|
||||
.. _pathlib-pattern-language:
|
||||
|
||||
Pattern language
|
||||
|
|
|
|||
Loading…
Reference in New Issue