gh-110722: Add PYTHON_PRESITE to import a module before site.py is run

Doc/c-api/init_config.rst

@@ -1100,6 +1100,7 @@ PyConfig
 
       Set by the :option:`-X pycache_prefix=PATH <-X>` command line option and
       the :envvar:`PYTHONPYCACHEPREFIX` environment variable.
+      The command-line option takes precedence.
 
       If ``NULL``, :data:`sys.pycache_prefix` is set to ``None``.
 
@@ -1143,6 +1144,20 @@ PyConfig
 
       Default: ``NULL``.
 
+   .. c:member:: wchar_t* run_presite
+
+      ``package.module`` path to module that should be imported before
+      ``site.py`` is run.
+
+      Set by the :option:`-X presite=package.module <-X>` command-line
+      option and the :envvar:`PYTHON_PRESITE` environment variable.
+      The command-line option takes precedence.
+
+      Need a :ref:`debug build of Python <debug-build>` (the ``Py_DEBUG`` macro
+      must be defined).
+
+      Default: ``NULL``.
+
    .. c:member:: int show_ref_count
 
       Show total reference count at exit (excluding immortal objects)?

Doc/using/cmdline.rst

@@ -552,6 +552,10 @@ Miscellaneous options
      This option may be useful for users who need to limit CPU resources of a
      container system. See also :envvar:`PYTHON_CPU_COUNT`.
      If *n* is ``default``, nothing is overridden.
+   * :samp:`-X presite={package.module}` specifies a module that should be
+     imported before ``site.py`` is executed.  Python needs to be
+     :ref:`built in debug mode <debug-build>` for this option to exist.
+     See also :envvar:`PYTHON_PRESITE <PYTHON_PRESITE=package.module>`.
 
    It also allows passing arbitrary values and retrieving them through the
    :data:`sys._xoptions` dictionary.
@@ -602,6 +606,9 @@ Miscellaneous options
    .. versionadded:: 3.13
       The ``-X cpu_count`` option.
 
+   .. versionadded:: 3.13
+      The ``-X presite`` option.
+
 
 Options you shouldn't use
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1100,3 +1107,13 @@ Debug-mode variables
    Need Python configured with the :option:`--with-trace-refs` build option.
 
    .. versionadded:: 3.11
+
+.. envvar:: PYTHON_PRESITE=package.module
+
+   If this variable is set to a module, that module will be imported
+   early in the interpreter lifecycle, before ``site.py`` is executed.
+
+   See also the :option:`-X presite <-X>` command-line option,
+   which takes precedence over this variable.
+
+   .. versionadded:: 3.13

Include/cpython/initconfig.h

@@ -225,6 +225,12 @@ typedef struct PyConfig {
     // If non-zero, turns on statistics gathering.
     int _pystats;
 #endif
+
+#ifdef Py_DEBUG
+    // If not empty, import a non-__main__ module before site.py is executed.
+    // PYTHON_PRESITE=package.module or -X presite=package.module
+    wchar_t *run_presite;
+#endif
 } PyConfig;
 
 PyAPI_FUNC(void) PyConfig_InitPythonConfig(PyConfig *config);

Lib/test/test_embed.py

@@ -515,6 +515,8 @@ class InitConfigTests(EmbeddingTestsMixin, unittest.TestCase):
     }
     if Py_STATS:
         CONFIG_COMPAT['_pystats'] = 0
+    if support.Py_DEBUG:
+        CONFIG_COMPAT['run_presite'] = None
     if MS_WINDOWS:
         CONFIG_COMPAT.update({
             'legacy_windows_stdio': 0,

Misc/NEWS.d/next/Core and Builtins/2023-10-12-17-15-23.gh-issue-110722.sjMwQe.rst

@@ -0,0 +1,3 @@
+Add :envvar:`PYTHON_PRESITE=package.module` to import a module early in the
+interpreter lifecycle before ``site.py`` is executed.  Python needs to be
+:ref:`built in debug mode <debug-build>` for this option to exist.

Python/initconfig.c

@@ -117,6 +117,9 @@ static const PyConfigSpec PYCONFIG_SPEC[] = {
     SPEC(_is_python_build, UINT),
 #ifdef Py_STATS
     SPEC(_pystats, UINT),
+#endif
+#ifdef Py_DEBUG
+    SPEC(run_presite, WSTR_OPT),
 #endif
     {NULL, 0, 0},
 };
@@ -241,6 +244,11 @@ The following implementation-specific options are available:\n\
 \n\
 -X pystats: Enable pystats collection at startup."
 #endif
+#ifdef Py_DEBUG
+"\n\
+\n\
+-X presite=package.module: import this module before site.py is run."
+#endif
 ;
 
 /* Envvars that don't have equivalent command-line options are listed first */
@@ -297,6 +305,9 @@ static const char usage_envvars[] =
 #ifdef Py_STATS
 "PYTHONSTATS             : turns on statistics gathering\n"
 #endif
+#ifdef Py_DEBUG
+"PYTHON_PRESITE=pkg.mod  : import this module before site.py is run\n"
+#endif
 ;
 
 #if defined(MS_WINDOWS)
@@ -790,6 +801,9 @@ PyConfig_Clear(PyConfig *config)
     CLEAR(config->run_module);
     CLEAR(config->run_filename);
     CLEAR(config->check_hash_pycs_mode);
+#ifdef Py_DEBUG
+    CLEAR(config->run_presite);
+#endif
 
     _PyWideStringList_Clear(&config->orig_argv);
 #undef CLEAR
@@ -1806,6 +1820,36 @@ config_init_pycache_prefix(PyConfig *config)
 }
 
 
+#ifdef Py_DEBUG
+static PyStatus
+config_init_run_presite(PyConfig *config)
+{
+    assert(config->run_presite == NULL);
+
+    const wchar_t *xoption = config_get_xoption(config, L"presite");
+    if (xoption) {
+        const wchar_t *sep = wcschr(xoption, L'=');
+        if (sep && wcslen(sep) > 1) {
+            config->run_presite = _PyMem_RawWcsdup(sep + 1);
+            if (config->run_presite == NULL) {
+                return _PyStatus_NO_MEMORY();
+            }
+        }
+        else {
+            // PYTHON_PRESITE env var ignored
+            // if "-X presite=" option is used
+            config->run_presite = NULL;
+        }
+        return _PyStatus_OK();
+    }
+
+    return CONFIG_GET_ENV_DUP(config, &config->run_presite,
+                              L"PYTHON_PRESITE",
+                              "PYTHON_PRESITE");
+}
+#endif
+
+
 static PyStatus
 config_read_complex_options(PyConfig *config)
 {
@@ -1861,6 +1905,16 @@ config_read_complex_options(PyConfig *config)
             return status;
         }
     }
+
+#ifdef Py_DEBUG
+    if (config->run_presite== NULL) {
+        status = config_init_run_presite(config);
+        if (_PyStatus_EXCEPTION(status)) {
+            return status;
+        }
+    }
+#endif
+
     return _PyStatus_OK();
 }
 

Python/pylifecycle.c

@@ -1157,6 +1157,28 @@ init_interp_main(PyThreadState *tstate)
         return status;
     }
 
+#ifdef Py_DEBUG
+    if (config->run_presite) {
+        PyObject *presite_modname = PyUnicode_FromWideChar(
+            config->run_presite,
+            wcslen(config->run_presite)
+        );
+        if (presite_modname == NULL) {
+            fprintf(stderr, "Could not convert module name to unicode\n");
+            Py_DECREF(presite_modname);
+        }
+        else {
+            PyObject *presite = PyImport_Import(presite_modname);
+            if (presite == NULL) {
+                fprintf(stderr, "pre-site import failed:\n");
+                _PyErr_Print(tstate);
+            }
+            Py_XDECREF(presite);
+            Py_DECREF(presite_modname);
+        }
+    }
+#endif
+
     status = add_main_module(interp);
     if (_PyStatus_EXCEPTION(status)) {
         return status;