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

Author: barneygale

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.