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

Add new hook 'setuptools.finalize_distribution_options'

1 files changed, 23 insertions, 0 deletions

diff --git a/docs/setuptools.txt b/docs/setuptools.txt
index 0dda5622..c109e673 100644
--- a/docs/setuptools.txt
+++ b/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
 -------------------------