https://github.com/python/cpython/commit/1904f0a2245f500aa85fba347b260620350efc78
commit: 1904f0a2245f500aa85fba347b260620350efc78
branch: main
author: Barney Gale <[email protected]>
committer: barneygale <[email protected]>
date: 2024-03-15T00:11:49Z
summary:
GH-113838: Add "Comparison to os.path" section to pathlib docs (#115926)
files:
M Doc/library/pathlib.rst
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 9041f37bd668fa..3ff2631d73c0b2 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -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
+------------------------------------------------------
-Below is a table mapping various :mod:`os` functions to their corresponding
-:class:`PurePath`/:class:`Path` equivalent.
+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.
-.. note::
+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.
- 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`.
+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.
==================================== ==============================
: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.
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
