From 893bce1b7d74b95023e4bf2b1c81587f0e303fb6 Mon Sep 17 00:00:00 2001
From: Barry Warsaw <barry@python.org>
Date: Wed, 24 Jan 2018 10:43:11 -0500
Subject: [PATCH 1/4] bpo-32651 - In the documentation for os.getlogin(),
 recommend getpass.getuser()

---
 Doc/library/getpass.rst                                | 10 ++++++----
 Doc/library/os.rst                                     |  9 +++++----
 .../2018-01-24-10-42-57.bpo-32651.a_tZhY.rst           |  2 ++
 3 files changed, 13 insertions(+), 8 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst

diff --git a/Doc/library/getpass.rst b/Doc/library/getpass.rst
index 5eb9f04a8da795..cfc06e9f021136 100644
--- a/Doc/library/getpass.rst
+++ b/Doc/library/getpass.rst
@@ -42,8 +42,10 @@ The :mod:`getpass` module provides two functions:
    Return the "login name" of the user.
 
    This function checks the environment variables :envvar:`LOGNAME`,
-   :envvar:`USER`, :envvar:`LNAME` and :envvar:`USERNAME`, in order, and returns
-   the value of the first one which is set to a non-empty string.  If none are set,
-   the login name from the password database is returned on systems which support
-   the :mod:`pwd` module, otherwise, an exception is raised.
+   :envvar:`USER`, :envvar:`LNAME` and :envvar:`USERNAME`, in order, and
+   returns the value of the first one which is set to a non-empty string.  If
+   none are set, the login name from the password database is returned on
+   systems which support the :mod:`pwd` module, otherwise, an exception is
+   raised.
 
+   In general, this function should be preferred over :func:`os.getlogin()`
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index ee08853087f71e..9cb34deb0423cc 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -325,10 +325,11 @@ process and user.
 .. function:: getlogin()
 
    Return the name of the user logged in on the controlling terminal of the
-   process.  For most purposes, it is more useful to use the environment
-   variables :envvar:`LOGNAME` or :envvar:`USERNAME` to find out who the user
-   is, or ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the current
-   real user id.
+   process.  For most purposes, it is more useful to use
+   :func:`getpass.getuser` since the latter checks the environment variables
+   :envvar:`LOGNAME` or :envvar:`USERNAME` to find out who the user is, and
+   falls back to ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the
+   current real user id.
 
    Availability: Unix, Windows.
 
diff --git a/Misc/NEWS.d/next/Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst b/Misc/NEWS.d/next/Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst
new file mode 100644
index 00000000000000..9510d41fb48b9a
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst
@@ -0,0 +1,2 @@
+In the :func:`os.getlogin()` documentation, recommend
+func:`getpass.getuser()`.

From 0e029b201cd62a78d6160781d79b6c97b8659a4d Mon Sep 17 00:00:00 2001
From: Barry Warsaw <barry@python.org>
Date: Wed, 24 Jan 2018 10:45:55 -0500
Subject: [PATCH 2/4] Complete the sentence

---
 Doc/library/getpass.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Doc/library/getpass.rst b/Doc/library/getpass.rst
index cfc06e9f021136..82b11919a3d2bf 100644
--- a/Doc/library/getpass.rst
+++ b/Doc/library/getpass.rst
@@ -48,4 +48,4 @@ The :mod:`getpass` module provides two functions:
    systems which support the :mod:`pwd` module, otherwise, an exception is
    raised.
 
-   In general, this function should be preferred over :func:`os.getlogin()`
+   In general, this function should be preferred over :func:`os.getlogin()`.

From 9f4b4bc2c157c1a8c0d349ff46f5075bfefc972e Mon Sep 17 00:00:00 2001
From: Barry Warsaw <barry@python.org>
Date: Wed, 24 Jan 2018 11:21:20 -0500
Subject: [PATCH 3/4] Fix formatting

---
 .../Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst    | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Misc/NEWS.d/next/Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst b/Misc/NEWS.d/next/Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst
index 9510d41fb48b9a..ffd37e25b8fba5 100644
--- a/Misc/NEWS.d/next/Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst
+++ b/Misc/NEWS.d/next/Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst
@@ -1,2 +1,2 @@
-In the :func:`os.getlogin()` documentation, recommend
-func:`getpass.getuser()`.
+In the :func:`os.getlogin` documentation, recommend
+:func:`getpass.getuser`.

From 25aa65c4a18627287164903bbb5bebf83d71a368 Mon Sep 17 00:00:00 2001
From: Barry Warsaw <barry@python.org>
Date: Wed, 24 Jan 2018 11:23:04 -0500
Subject: [PATCH 4/4] We really don't need a news file entry

---
 .../next/Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst | 2 --
 1 file changed, 2 deletions(-)
 delete mode 100644 Misc/NEWS.d/next/Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst

diff --git a/Misc/NEWS.d/next/Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst b/Misc/NEWS.d/next/Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst
deleted file mode 100644
index ffd37e25b8fba5..00000000000000
--- a/Misc/NEWS.d/next/Documentation/2018-01-24-10-42-57.bpo-32651.a_tZhY.rst
+++ /dev/null
@@ -1,2 +0,0 @@
-In the :func:`os.getlogin` documentation, recommend
-:func:`getpass.getuser`.