[Python-checkins] bpo-41376: Fix the documentation of `site.getusersitepackages()` (GH-21602) (GH-22592)

[Miss Skeleton (bot)]

https://github.com/python/cpython/commit/1006f63a8b4327e8a74eb978b175b5234bb46c6c
commit: 1006f63a8b4327e8a74eb978b175b5234bb46c6c
branch: 3.8
author: Miss Skeleton (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2020-10-11T19:21:31+01:00
summary:

bpo-41376: Fix the documentation of `site.getusersitepackages()` (GH-21602) (GH-22592)

`site.getusersitepackages()` returns the location of the user-specific site-packages directory
even when the user-specific site-packages is disabled.

```
$ python -s -m site
sys.path = [
    '/home/user/conda/lib/python37.zip',
    '/home/user/conda/lib/python3.7',
    '/home/user/conda/lib/python3.7/lib-dynload',
    '/home/user/conda/lib/python3.7/site-packages',
]
USER_BASE: '/home/user/.local' (exists)
USER_SITE: '/home/user/.local/lib/python3.7/site-packages' (doesn't exist)
ENABLE_USER_SITE: False
```

It was not practical to prevent the function from returning None if user-specific site-packages are disabled, since there are other uses of the function which are relying on this behaviour (e.g. `python -m site`).
(cherry picked from commit 35f041dd0171f575fc3adce1709b31fdf45a5ff6)

Co-authored-by: Phil Elson <pelson.pub at gmail.com>

Co-authored-by: Phil Elson <pelson.pub at gmail.com>

files:
M Doc/library/site.rst

diff --git a/Doc/library/site.rst b/Doc/library/site.rst
index b424e1ba348d8..2e3646f6a74f8 100644
--- a/Doc/library/site.rst
+++ b/Doc/library/site.rst
@@ -231,7 +231,9 @@ Module contents
 
    Return the path of the user-specific site-packages directory,
    :data:`USER_SITE`.  If it is not initialized yet, this function will also set
-   it, respecting :envvar:`PYTHONNOUSERSITE` and :data:`USER_BASE`.
+   it, respecting :data:`USER_BASE`.  To determine if the user-specific
+   site-packages was added to ``sys.path`` :data:`ENABLE_USER_SITE` should be
+   used.
 
    .. versionadded:: 3.2