Merge pull request #1877 from pypa/feature/distribution-options-hooks

Add new hook 'setuptools.finalize_distribution_options'

changelog.d/1877.change.rst

+Setuptools now exposes a new entry point hook "setuptools.finalize_distribution_options", enabling plugins like `setuptools_scm <https://pypi.org/project/setuptools_scm>`_ to configure options on the distribution at finalization time.

docs/setuptools.txt

@@ -2419,6 +2419,10 @@ script defines entry points for them!
 Adding ``setup()`` Arguments
 ----------------------------
 
+.. warning:: Adding arguments to setup is discouraged as such arguments
+   are only supported through imperative execution and not supported through
+   declarative config.
+
 Sometimes, your commands may need additional arguments to the ``setup()``
 call.  You can enable this by defining entry points in the
 ``distutils.setup_keywords`` group.  For example, if you wanted a ``setup()``
@@ -2470,6 +2474,25 @@ script using your extension lists your project in its ``setup_requires``
 argument.
 
 
+Customizing Distribution Options
+--------------------------------
+
+Plugins may wish to extend or alter the options on a Distribution object to
+suit the purposes of that project. For example, a tool that infers the
+``Distribution.version`` from SCM-metadata may need to hook into the
+option finalization. To enable this feature, Setuptools offers an entry
+point "setuptools.finalize_distribution_options". That entry point must
+be a callable taking one argument (the Distribution instance).
+
+If the callable has an ``.order`` property, that value will be used to
+determine the order in which the hook is called. Lower numbers are called
+first and the default is zero (0).
+
+Plugins may read, alter, and set properties on the distribution, but each
+plugin is encouraged to load the configuration/settings for their behavior
+independently.
+
+
 Adding new EGG-INFO Files
 -------------------------
 

setup.py

@@ -89,6 +89,13 @@ setup_params = dict(
             "%(cmd)s = setuptools.command.%(cmd)s:%(cmd)s" % locals()
             for cmd in read_commands()
         ],
+        "setuptools.finalize_distribution_options": [
+            "parent_finalize = setuptools.dist:_Distribution.finalize_options",
+            "features = setuptools.dist:Distribution._finalize_feature_opts",
+            "keywords = setuptools.dist:Distribution._finalize_setup_keywords",
+            "2to3_doctests = "
+            "setuptools.dist:Distribution._finalize_2to3_doctests",
+        ],
         "distutils.setup_keywords": [
             "eager_resources        = setuptools.dist:assert_string_list",
             "namespace_packages     = setuptools.dist:check_nsp",

setuptools/dist.py

@@ -725,15 +725,28 @@ class Distribution(_Distribution):
         return resolved_dists
 
     def finalize_options(self):
-        _Distribution.finalize_options(self)
-        if self.features:
-            self._set_global_opts_from_features()
+        """
+        Allow plugins to apply arbitrary operations to the
+        distribution. Each hook may optionally define a 'order'
+        to influence the order of execution. Smaller numbers
+        go first and the default is 0.
+        """
+        hook_key = 'setuptools.finalize_distribution_options'
+
+        def by_order(hook):
+            return getattr(hook, 'order', 0)
+        eps = pkg_resources.iter_entry_points(hook_key)
+        for ep in sorted(eps, key=by_order):
+            ep.load()(self)
 
+    def _finalize_setup_keywords(self):
         for ep in pkg_resources.iter_entry_points('distutils.setup_keywords'):
             value = getattr(self, ep.name, None)
             if value is not None:
                 ep.require(installer=self.fetch_build_egg)
                 ep.load()(self, ep.name, value)
+
+    def _finalize_2to3_doctests(self):
         if getattr(self, 'convert_2to3_doctests', None):
             # XXX may convert to set here when we can rely on set being builtin
             self.convert_2to3_doctests = [
@@ -763,9 +776,12 @@ class Distribution(_Distribution):
         from setuptools.installer import fetch_build_egg
         return fetch_build_egg(self, req)
 
-    def _set_global_opts_from_features(self):
+    def _finalize_feature_opts(self):
         """Add --with-X/--without-X options based on optional features"""
 
+        if not self.features:
+            return
+
         go = []
         no = self.negative_opt.copy()