bpo-41376: Correct the documentation on site.getusersitepackages() regarding respecting PYTHONNOUSERSITE

pelson · pelson · commit 46430b8c1d99 · 2020-07-23T17:37:09.000+02:00
``site.getusersitepackages()`` returns the location of the user-specific site-packages directory
whether or not it exists, or is added to the ``sys.path``. We can see this easily with:

```
$ python  -c "import site; print(site.getusersitepackages())"
/home/user/.local/lib/python3.7/site-packages

$ python -s -c "import site; print(site.getusersitepackages())"
/home/user/.local/lib/python3.7/site-packages

```

This is even true when the user-specific site-packages doesn't exist, as is demonstrated by:

```
$ python -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: True

$ 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``).
diff --git 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
 
