mirror of https://github.com/python/cpython
GH-119054: Add "Expanding and resolving paths" section to pathlib docs. (#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.
This commit is contained in:
Barney Gale
GitHub
parent
2cb84b107a
commit
d6d8707ff2
|
|
@ -885,6 +885,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
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -1605,107 +1706,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