Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

GH-121462: pathlib docs: improve table of corresponding os/os.path functions (#121465) 

Re-order table of corresponding functions with the following priorities:

1. Pure functionality is at the top
2. `os.path` functions are shown before `os` functions
3. Similar functionality is kept together
4. Functionality follows docs order where possible

Add a few missed correspondences:

- `os.path.isjunction` and `Path.is_junction`
- `os.path.ismount` and `Path.is_mount`
- `os.lstat()` and `Path.lstat()`
- `os.lchmod()` and `Path.lchmod()`

Also add footnotes describing a few differences.
This commit is contained in:
Barney Gale 2024-07-27 18:03:18 +01:00 committed by GitHub
parent 45614ecb2b
commit cbac8a3888
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 51 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
Doc/library/pathlib.rst
View File

@ -1864,39 +1864,54 @@ Corresponding tools
Below is a table mapping various :mod:`os` functions to their corresponding Below is a table mapping various :mod:`os` functions to their corresponding
:class:`PurePath`/:class:`Path` equivalent. :class:`PurePath`/:class:`Path` equivalent.
==================================== ============================== ===================================== ==============================================
:mod:`os` and :mod:`os.path` :mod:`pathlib` :mod:`os` and :mod:`os.path` :mod:`pathlib`
==================================== ============================== ===================================== ==============================================
:func:`os.path.abspath` :meth:`Path.absolute` :func:`os.path.dirname` :attr:`PurePath.parent`
:func:`os.path.realpath` :meth:`Path.resolve` :func:`os.path.basename` :attr:`PurePath.name`
:func:`os.chmod` :meth:`Path.chmod` :func:`os.path.splitext` :attr:`PurePath.stem`, :attr:`PurePath.suffix`
:func:`os.mkdir` :meth:`Path.mkdir` :func:`os.path.join` :meth:`PurePath.joinpath`
:func:`os.makedirs` :meth:`Path.mkdir` :func:`os.path.isabs` :meth:`PurePath.is_absolute`
:func:`os.rename` :meth:`Path.rename` :func:`os.path.relpath` :meth:`PurePath.relative_to` [1]_
:func:`os.replace` :meth:`Path.replace` :func:`os.path.expanduser` :meth:`Path.expanduser` [2]_
:func:`os.rmdir` :meth:`Path.rmdir` :func:`os.path.realpath` :meth:`Path.resolve`
:func:`os.remove`, :func:`os.unlink` :meth:`Path.unlink` :func:`os.path.abspath` :meth:`Path.absolute` [3]_
:func:`os.getcwd` :func:`Path.cwd` :func:`os.path.exists` :meth:`Path.exists`
:func:`os.path.exists` :meth:`Path.exists` :func:`os.path.isfile` :meth:`Path.is_file`
:func:`os.path.expanduser` :meth:`Path.expanduser` and :func:`os.path.isdir` :meth:`Path.is_dir`
:meth:`Path.home` :func:`os.path.islink` :meth:`Path.is_symlink`
:func:`os.listdir` :meth:`Path.iterdir` :func:`os.path.isjunction` :meth:`Path.is_junction`
:func:`os.walk` :meth:`Path.walk` :func:`os.path.ismount` :meth:`Path.is_mount`
:func:`os.path.isdir` :meth:`Path.is_dir` :func:`os.path.samefile` :meth:`Path.samefile`
:func:`os.path.isfile` :meth:`Path.is_file` :func:`os.getcwd` :meth:`Path.cwd`
:func:`os.path.islink` :meth:`Path.is_symlink` :func:`os.stat` :meth:`Path.stat`
:func:`os.link` :meth:`Path.hardlink_to` :func:`os.lstat` :meth:`Path.lstat`
:func:`os.symlink` :meth:`Path.symlink_to` :func:`os.listdir` :meth:`Path.iterdir`
:func:`os.readlink` :meth:`Path.readlink` :func:`os.walk` :meth:`Path.walk` [4]_
:func:`os.path.relpath` :meth:`PurePath.relative_to` :func:`os.mkdir`, :func:`os.makedirs` :meth:`Path.mkdir`
:func:`os.stat` :meth:`Path.stat`, :func:`os.link` :meth:`Path.hardlink_to`
:meth:`Path.owner`, :func:`os.symlink` :meth:`Path.symlink_to`
:meth:`Path.group` :func:`os.readlink` :meth:`Path.readlink`
:func:`os.path.isabs` :meth:`PurePath.is_absolute` :func:`os.rename` :meth:`Path.rename`
:func:`os.path.join` :func:`PurePath.joinpath` :func:`os.replace` :meth:`Path.replace`
:func:`os.path.basename` :attr:`PurePath.name` :func:`os.remove`, :func:`os.unlink` :meth:`Path.unlink`
:func:`os.path.dirname` :attr:`PurePath.parent` :func:`os.rmdir` :meth:`Path.rmdir`
:func:`os.path.samefile` :meth:`Path.samefile` :func:`os.chmod` :meth:`Path.chmod`
:func:`os.path.splitext` :attr:`PurePath.stem` and :func:`os.lchmod` :meth:`Path.lchmod`
:attr:`PurePath.suffix` ===================================== ==============================================
==================================== ==============================
.. rubric:: Footnotes
.. [1] :func:`os.path.relpath` calls :func:`~os.path.abspath` to make paths
absolute and remove "``..``" parts, whereas :meth:`PurePath.relative_to`
is a lexical operation that raises :exc:`ValueError` when its inputs'
anchors differ (e.g. if one path is absolute and the other relative.)
.. [2] :func:`os.path.expanduser` returns the path unchanged if the home
directory can't be resolved, whereas :meth:`Path.expanduser` raises
:exc:`RuntimeError`.
.. [3] :func:`os.path.abspath` removes "``..``" components without resolving
symlinks, which may change the meaning of the path, whereas
:meth:`Path.absolute` leaves any "``..``" components in the path.
.. [4] :func:`os.walk` always follows symlinks when categorizing paths into
*dirnames* and *filenames*, whereas :meth:`Path.walk` categorizes all
symlinks into *filenames* when *follow_symlinks* is false (the default.)