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.
|
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
|
Querying file type and status
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
|
@ -1605,107 +1706,6 @@ Permissions and ownership
|
||||||
symbolic link's mode is changed rather than its target's.
|
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:
|
.. _pathlib-pattern-language:
|
||||||
|
|
||||||
Pattern language
|
Pattern language
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue