From ae8750bca8234a9af9382b9d7e457b57f810ad64 Mon Sep 17 00:00:00 2001
From: Jamiel Almeida <slashfoo@gmail.com>
Date: Fri, 2 Jun 2017 11:36:02 -0700
Subject: [PATCH] bpo-24899: Add comparison table for os.path -> pathlib
 (GH-1753)

---
 Doc/library/pathlib.rst | 33 +++++++++++++++++++++++++++++++++
 Misc/ACKS               |  9 +++++----
 2 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 14452264472..0c9bd0d940a 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`
+============================   ==============================
diff --git a/Misc/ACKS b/Misc/ACKS
index 6fe57d548be..3000bc36d2c 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -33,6 +33,7 @@ Fred Allen
 Jeff Allen
 Ray Allen
 Billy G. Allie
+Jamiel Almeida
 Kevin Altis
 Skyler Leigh Amador
 Joe Amenta
@@ -436,6 +437,7 @@ Tim Everett
 Paul Everitt
 David Everly
 Daniel Evers
+evilzero
 Winston Ewert
 Greg Ewing
 Martijn Faassen
@@ -523,6 +525,7 @@ Elazar (אלעזר) Gershuni
 Ben Gertzfield
 Nadim Ghaznavi
 Dinu Gherman
+Subhendu Ghosh
 Jonathan Giddy
 Johannes Gijsbers
 Michael Gilfix
@@ -1242,6 +1245,7 @@ Jérôme Radix
 Burton Radons
 Abhilash Raj
 Shorya Raj
+Dhushyanth Ramasamy
 Jeff Ramnani
 Bayard Randel
 Varpu Rantala
@@ -1505,6 +1509,7 @@ Nathan Sullivan
 Mark Summerfield
 Reuben Sumner
 Eryk Sun
+Sanjay Sundaresan
 Marek Šuppa
 Hisao Suzuki
 Kalle Svensson
@@ -1747,7 +1752,3 @@ Jelle Zijlstra
 Gennadiy Zlobin
 Doug Zongker
 Peter Åstrand
-evilzero
-Dhushyanth Ramasamy
-Subhendu Ghosh
-Sanjay Sundaresan