mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-03 08:34:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

GH-113838: Add "Comparison to os.path" section to pathlib docs (#115926)

Browse source
This commit is contained in:
Barney Gale 2024-03-15 00:11:49 +00:00 • committed by GitHub
parent be1c808fca
commit 1904f0a224
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 44 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

63
Doc/library/pathlib.rst
View file

@ -1664,7 +1664,7 @@ the pattern to match only directories.
Comparison to the :mod:`glob` module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------
The patterns accepted and results generated by :meth:`Path.glob` and
:meth:`Path.rglob` differ slightly from those by the :mod:`glob` module:
@ -1682,27 +1682,57 @@ The patterns accepted and results generated by :meth:`Path.glob` and
5. The values returned from pathlib's ``path.glob()`` and ``path.rglob()``
include the *path* as a prefix, unlike the results of
``glob.glob(root_dir=path)``.
6. ``bytes``-based paths and :ref:`paths relative to directory descriptors
<dir_fd>` are not supported by pathlib.
Correspondence to tools in the :mod:`os` module
-----------------------------------------------
Comparison to the :mod:`os` and :mod:`os.path` modules
------------------------------------------------------
pathlib implements path operations using :class:`PurePath` and :class:`Path`
objects, and so it's said to be *object-oriented*. On the other hand, the
:mod:`os` and :mod:`os.path` modules supply functions that work with low-level
``str`` and ``bytes`` objects, which is a more *procedural* approach. Some
users consider the object-oriented style to be more readable.
Many functions in :mod:`os` and :mod:`os.path` support ``bytes`` paths and
:ref:`paths relative to directory descriptors <dir_fd>`. These features aren't
available in pathlib.
Python's ``str`` and ``bytes`` types, and portions of the :mod:`os` and
:mod:`os.path` modules, are written in C and are very speedy. pathlib is
written in pure Python and is often slower, but rarely slow enough to matter.
pathlib's path normalization is slightly more opinionated and consistent than
:mod:`os.path`. For example, whereas :func:`os.path.abspath` eliminates
"``..``" segments from a path, which may change its meaning if symlinks are
involved, :meth:`Path.absolute` preserves these segments for greater safety.
pathlib's path normalization may render it unsuitable for some applications:
1. pathlib normalizes ``Path("my_folder/")`` to ``Path("my_folder")``, which
changes a path's meaning when supplied to various operating system APIs and
command-line utilities. Specifically, the absence of a trailing separator
may allow the path to be resolved as either a file or directory, rather
than a directory only.
2. pathlib normalizes ``Path("./my_program")`` to ``Path("my_program")``,
which changes a path's meaning when used as an executable search path, such
as in a shell or when spawning a child process. Specifically, the absence
of a separator in the path may force it to be looked up in :envvar:`PATH`
rather than the current directory.
As a consequence of these differences, pathlib is not a drop-in replacement
for :mod:`os.path`.
Corresponding tools
^^^^^^^^^^^^^^^^^^^
Below is a table mapping various :mod:`os` functions to their corresponding
:class:`PurePath`/:class:`Path` equivalent.
.. note::
Not all pairs of functions/methods below are equivalent. Some of them,
despite having some overlapping use-cases, have different semantics. They
include :func:`os.path.abspath` and :meth:`Path.absolute`,
:func:`os.path.relpath` and :meth:`PurePath.relative_to`.
==================================== ==============================
:mod:`os` and :mod:`os.path` :mod:`pathlib`
==================================== ==============================
:func:`os.path.abspath` :meth:`Path.absolute` [#]_
:func:`os.path.abspath` :meth:`Path.absolute`
:func:`os.path.realpath` :meth:`Path.resolve`
:func:`os.chmod` :meth:`Path.chmod`
:func:`os.mkdir` :meth:`Path.mkdir`
@ -1723,7 +1753,7 @@ Below is a table mapping various :mod:`os` functions to their corresponding
:func:`os.link` :meth:`Path.hardlink_to`
:func:`os.symlink` :meth:`Path.symlink_to`
:func:`os.readlink` :meth:`Path.readlink`
:func:`os.path.relpath` :meth:`PurePath.relative_to` [#]_
:func:`os.path.relpath` :meth:`PurePath.relative_to`
:func:`os.stat` :meth:`Path.stat`,
:meth:`Path.owner`,
:meth:`Path.group`
@ -1735,8 +1765,3 @@ Below is a table mapping various :mod:`os` functions to their corresponding
:func:`os.path.splitext` :attr:`PurePath.stem` and
:attr:`PurePath.suffix`
==================================== ==============================
.. rubric:: Footnotes
.. [#] :func:`os.path.abspath` normalizes the resulting path, which may change its meaning in the presence of symlinks, while :meth:`Path.absolute` does not.
.. [#] :meth:`PurePath.relative_to` requires ``self`` to be the subpath of the argument, but :func:`os.path.relpath` does not.