[Python-checkins] Doc: os.path.abspath and Path.resolve are also different (GH-23276)

[JulienPalard]

https://github.com/python/cpython/commit/1459fed92c4bf6bb0d18a4c5637e8f1d8662bed5
commit: 1459fed92c4bf6bb0d18a4c5637e8f1d8662bed5
branch: master
author: Hong Xu <hong at topbug.net>
committer: JulienPalard <julien at palard.fr>
date: 2021-01-20T11:20:00+01:00
summary:

Doc: os.path.abspath and Path.resolve are also different (GH-23276)

files:
M Doc/library/pathlib.rst

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 2bbf3aad61988..ac96de334b329 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1195,14 +1195,15 @@ Below is a table mapping various :mod:`os` functions to their corresponding
 
 .. note::
 
-   Although :func:`os.path.relpath` and :meth:`PurePath.relative_to` have some
-   overlapping use-cases, their semantics differ enough to warrant not
-   considering them equivalent.
+   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.resolve`,
+   :func:`os.path.relpath` and :meth:`PurePath.relative_to`.
 
 ====================================   ==============================
-os and os.path                         pathlib
+:mod:`os` and :mod:`os.path`           :mod:`pathlib`
 ====================================   ==============================
-:func:`os.path.abspath`                :meth:`Path.resolve`
+:func:`os.path.abspath`                :meth:`Path.resolve` [#]_
 :func:`os.chmod`                       :meth:`Path.chmod`
 :func:`os.mkdir`                       :meth:`Path.mkdir`
 :func:`os.makedirs`                    :meth:`Path.mkdir`
@@ -1221,6 +1222,7 @@ os and os.path                         pathlib
 :func:`os.link`                        :meth:`Path.link_to`
 :func:`os.symlink`                     :meth:`Path.symlink_to`
 :func:`os.readlink`                    :meth:`Path.readlink`
+:func:`os.path.relpath`                :meth:`Path.relative_to` [#]_
 :func:`os.stat`                        :meth:`Path.stat`,
                                        :meth:`Path.owner`,
                                        :meth:`Path.group`
@@ -1231,3 +1233,8 @@ os and os.path                         pathlib
 :func:`os.path.samefile`               :meth:`Path.samefile`
 :func:`os.path.splitext`               :data:`PurePath.suffix`
 ====================================   ==============================
+
+.. rubric:: Footnotes
+
+.. [#] :func:`os.path.abspath` does not resolve symbolic links while :meth:`Path.resolve` does.
+.. [#] :meth:`Path.relative_to` requires ``self`` to be the subpath of the argument, but :func:`os.path.relpath` does not.