bpo-33944: Add site.py debugging via PYTHONSITEDEBUG

Doc/using/cmdline.rst

@@ -917,6 +917,15 @@ conflict.
       See :pep:`540` for more details.
 
 
+.. envvar:: PYTHONSITEDEBUG
+
+   If set to a non-empty string, drop into the :mod:`pdb` prompt
+   at the start of the :mod:`site` module.
+   This is useful to diagnose issues in 3rd-party code that runs at startup.
+
+   .. versionadded:: 3.8
+
+
 Debug-mode variables
 ~~~~~~~~~~~~~~~~~~~~
 

Lib/site.py

@@ -74,6 +74,11 @@
 import builtins
 import _sitebuiltins
 
+
+if os.environ.get("PYTHONSITEDEBUG", ""):
+    breakpoint()
+
+
 # Prefixes for site-packages; add additional prefixes like /usr/local here
 PREFIXES = [sys.prefix, sys.exec_prefix]
 # Enable per user site-packages directory
@@ -636,5 +641,6 @@ def _script():
         print(textwrap.dedent(help % (sys.argv[0], os.pathsep)))
         sys.exit(10)
 
+
 if __name__ == '__main__':
     _script()

Lib/test/test_site.py

@@ -310,6 +310,30 @@ def test_no_home_directory(self):
             mock_addsitedir.assert_not_called()
             self.assertFalse(known_paths)
 
+    def test_debug(self):
+        def _run(input_):
+            p = subprocess.Popen([sys.executable, "-c", "pass"], env=environ,
+                                 stdin=subprocess.PIPE,
+                                 stdout=subprocess.PIPE,
+                                 stderr=subprocess.STDOUT)
+            out, _ = p.communicate(b"c\n" if input_ else b"")
+            return out
+        re_pdb_prompt = rb"(?m)^\(Pdb\)\s*$"
+        envvar = 'PYTHONSITEDEBUG'
+
+        environ = os.environ.copy()
+        try: del environ['PYTHONBREAKPOINT']
+        except KeyError: pass
+
+        environ[envvar]="1"
+        self.assertRegex(_run(True), re_pdb_prompt)
+        environ[envvar]=""
+        self.assertNotRegex(_run(False), re_pdb_prompt)
+        del environ[envvar]
+        self.assertNotRegex(_run(False), re_pdb_prompt)
+
+
+
 
 class PthFile(object):
     """Helper class for handling testing of .pth files"""

Misc/NEWS.d/next/Library/2019-03-01-01-08-38.bpo-33944.8gWRAj.rst

@@ -0,0 +1 @@
+Added startup code debugging with the PYTHONSITEDEBUG environment variable