bpo-24899: Add comparison table for os.path -> pathlib (GH-1753)

1 files changed, 33 insertions, 0 deletions

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 1445226..0c9bd0d 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1055,3 +1055,36 @@ call fails (for example because the path doesn't exist):
       'Text file contents'
 
    .. versionadded:: 3.5
+
+Correspondence to tools in the :mod:`os` module
+-----------------------------------------------
+
+Below is a table mapping various :mod:`os` functions to their corresponding
+:class:`PurePath`/:class:`Path` equivalent.
+
+.. 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.
+
+============================   ==============================
+os and os.path                 pathlib
+============================   ==============================
+:func:`os.path.abspath`        :meth:`Path.resolve`
+:func:`os.getcwd`              :func:`Path.cwd`
+:func:`os.path.exists`         :meth:`Path.exists`
+:func:`os.path.expanduser`     :meth:`Path.expanduser` and
+                               :meth:`Path.home`
+:func:`os.path.isdir`          :meth:`Path.is_dir`
+:func:`os.path.isfile`         :meth:`Path.is_file`
+:func:`os.path.islink`         :meth:`Path.is_symlink`
+:func:`os.stat`                :meth:`Path.stat`,
+                               :meth:`Path.owner`,
+                               :meth:`Path.group`
+:func:`os.path.isabs`          :meth:`PurePath.is_absolute`
+:func:`os.path.join`           :func:`PurePath.joinpath`
+:func:`os.path.basename`       :data:`PurePath.name`
+:func:`os.path.dirname`        :data:`PurePath.parent`
+:func:`os.path.splitext`       :data:`PurePath.suffix`
+============================   ==============================