Do not touch sys.path when site is imported and python was started with -S.

Original patch by Carl Meyer, review by Brett Cannon, small doc editions by
yours truly.  Fixes #11591.

Doc/library/site.rst

@@ -13,7 +13,11 @@ import can be suppressed using the interpreter's :option:`-S` option.
 
 .. index:: triple: module; search; path
 
-Importing this module will append site-specific paths to the module search path.
+Importing this module will append site-specific paths to the module search
+path, unless :option:`-S` was used.  In that case, this module can be safely
+imported with no automatic modifications to the module search path.  To
+explicitly trigger the usual site-specific additions, call the
+:func:`site.main` function.
 
 .. index::
    pair: site-python; directory
@@ -114,6 +118,13 @@ empty, and the path manipulations are skipped; however the import of
 .. envvar:: PYTHONUSERBASE
 
 
+.. function:: main()
+
+   Adds all the standard site-specific directories to the module search
+   path.  This function is called automatically when this module is imported,
+   unless the :program:`python` interpreter was started with the :option:`-S`
+   flag.
+
 .. function:: addsitedir(sitedir, known_paths=None)
 
    Adds a directory to sys.path and processes its pth files.

Doc/using/cmdline.rst

@@ -239,7 +239,9 @@ Miscellaneous options
 .. cmdoption:: -S
 
    Disable the import of the module :mod:`site` and the site-dependent
-   manipulations of :data:`sys.path` that it entails.
+   manipulations of :data:`sys.path` that it entails.  Also disable these
+   manipulations if :mod:`site` is explicitly imported later (call
+   :func:`site.main` if you want them to be triggered).
 
 
 .. cmdoption:: -u

Doc/whatsnew/3.3.rst

@@ -128,3 +128,8 @@ that may require changes to your code:
 
 * Stub
 
+
+.. Issue #11591: When :program:`python` was started with :option:`-S`,
+   ``import site`` will not add site-specific paths to the module search
+   paths.  In previous versions, it did.  See changeset for doc changes in
+   various files.  Contributed by Carl Meyer with editions by Éric Araujo.

Lib/site.py

@@ -508,6 +508,11 @@ def execusercustomize():
 
 
 def main():
+    """Add standard site-specific directories to the module search path.
+
+    This function is called automatically when this module is imported,
+    unless the python interpreter was started with the -S flag.
+    """
     global ENABLE_USER_SITE
 
     abs_paths()
@@ -526,7 +531,10 @@ def main():
     if ENABLE_USER_SITE:
         execusercustomize()
 
-main()
+# Prevent edition of sys.path when python was started with -S and
+# site is imported later.
+if not sys.flags.no_site:
+    main()
 
 def _script():
     help = """\

Misc/NEWS

@@ -81,12 +81,15 @@ Core and Builtins
 Library
 -------
 
+- Issue #11591: Prevent "import site" from modifying sys.path when python
+  was started with -S.
+
 - Issue #11371: Mark getopt error messages as localizable.  Patch by Filip
   Gruszczyński.
 
 - Issue #11333: Add __slots__ to collections ABCs.
 
-- Issue #11628: cmp_to_key generated class should use __slots__
+- Issue #11628: cmp_to_key generated class should use __slots__.
 
 - Issue #5537: Fix time2isoz() and time2netscape() functions of
   httplib.cookiejar for expiration year greater than 2038 on 32-bit systems.

Misc/python.man

@@ -169,7 +169,9 @@ Disable the import of the module
 .I site
 and the site-dependent manipulations of
 .I sys.path
-that it entails.
+that it entails.  Also disable these manipulations if
+.I site
+is explicitly imported later.
 .TP
 .B \-u
 Force the binary I/O layers of stdin, stdout and stderr to be unbuffered.