bpo-32651 Recommend getpass.getuser() (GH-5301) (#5304)

* bpo-32651 - In the documentation for os.getlogin(), recommend getpass.getuser()
(cherry picked from commit d499031f5f33c3ef71be7c81ef52eee6b47c42e1)

diff --git a/Doc/library/getpass.rst b/Doc/library/getpass.rst
index 5eb9f04a8da795332cf0d6b8ba77e42558187c09..82b11919a3d2bf67eeb7ef40e80d51b93f96a4bb 100644 (file)
--- 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 974ab2d481e21070c4c6b5f36fca398e7a1e42ef..b2722168bc213841b638e2f8c82e4b50a5370cf6 100644 (file)
--- 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.