Add DIST_EXTRA_CONFIG option for passing setup.cfg overrides during build

distutils/dist.py

@@ -8,6 +8,7 @@
 import os
 import re
 import pathlib
+import contextlib
 from email import message_from_file
 
 try:
@@ -323,14 +324,14 @@ def find_config_files(self):
         should be parsed.  The filenames returned are guaranteed to exist
         (modulo nasty race conditions).
 
-        There are three possible config files: distutils.cfg in the
-        Distutils installation directory (ie. where the top-level
-        Distutils __inst__.py file lives), a file in the user's home
-        directory named .pydistutils.cfg on Unix and pydistutils.cfg
-        on Windows/Mac; and setup.cfg in the current directory.
-
-        The file in the user's home directory can be disabled with the
-        --no-user-cfg option.
+        There are multiple possible config files:
+        - distutils.cfg in the Distutils installation directory (i.e.
+          where the top-level Distutils __inst__.py file lives)
+        - a file in the user's home directory named .pydistutils.cfg
+          on Unix and pydistutils.cfg on Windows/Mac; may be disabled
+          with the ``--no-user-cfg`` option
+        - setup.cfg in the current directory
+        - a file named by an environment variable
         """
         check_environ()
         files = [str(path) for path in self._gen_paths() if path.is_file()]
@@ -354,6 +355,10 @@ def _gen_paths(self):
         # All platforms support local setup.cfg
         yield pathlib.Path('setup.cfg')
 
+        # Additional config indicated in the environment
+        with contextlib.suppress(TypeError):
+            yield pathlib.Path(os.getenv("DIST_EXTRA_CONFIG"))
+
     def parse_config_files(self, filenames=None):  # noqa: C901
         from configparser import ConfigParser
 

distutils/tests/test_dist.py

@@ -8,6 +8,7 @@
 import unittest.mock as mock
 
 import pytest
+import jaraco.path
 
 from distutils.dist import Distribution, fix_help_options
 from distutils.cmd import Command
@@ -486,6 +487,15 @@ def test_custom_pydistutils(self):
         finally:
             os.remove(user_filename)
 
+    def test_extra_pydistutils(self, monkeypatch, tmp_path):
+        jaraco.path.build({'overrides.cfg': '.'}, tmp_path)
+        filename = tmp_path / 'overrides.cfg'
+
+        monkeypatch.setenv('DIST_EXTRA_CONFIG', filename)
+        dist = Distribution()
+        files = dist.find_config_files()
+        assert str(filename) in files
+
     def test_fix_help_options(self):
         help_tuples = [('a', 'b', 'c', 'd'), (1, 2, 3, 4)]
         fancy_options = fix_help_options(help_tuples)

docs/distutils/configfile.rst

@@ -36,7 +36,8 @@ consequences:
   :file:`setup.py`
 
 * installers can override anything in :file:`setup.cfg` using the command-line
-  options to :file:`setup.py`
+  options to :file:`setup.py` or by pointing :envvar:`DIST_EXTRA_CONFIG`
+  to another configuration file
 
 The basic syntax of the configuration file is simple: