Customizing Commands¶

Bothsetuptools anddistutils are structured around thecommand designpattern. This means that each main action executed when building adistribution package (such as creating asdistorwheel) correspond to the implementation of a Python class.

Originally indistutils, these commands would correspond to actual CLIarguments that could be passed to thesetup.py script to trigger adifferent aspect of the build. Insetuptools, however, these commandobjects are just a design abstraction that encapsulate logic and help toorganise the code.

You can overwrite existing commands (or add new ones) by defining entrypoints in thedistutils.commands group. For example, if you wanted to addafoo command, you might add something like this to your project:

# setup.cfg...[options.entry_points]distutils.commands=foo=mypackage.some_module:foo

Assuming, of course, that thefoo class inmypackage.some_module isasetuptools.Command subclass (documented below).

Once a project containing such entry points has been activated onsys.path,(e.g. by runningpipinstall) the command(s) will be available to anysetuptools-based project. In fact, this ishow setuptools’ own commands are installed: the setuptools project’s setupscript defines entry points for them!

The commandssdist,build_py andbuild_ext are especially usefulto customizesetuptools builds. Note however that when overwriting existingcommands, you should be very careful to maintain API compatibility.Custom commands should try to replicate the same overall behavior as theoriginal classes, and when possible, even inherit from them.

You should also consider handling exceptions such asCompileError,LinkError,LibError, among others. These exceptions are available inthesetuptools.errors module.

classsetuptools.Command(dist:Distribution,**kw)¶

Setuptools internal actions are organized using acommand design pattern.This means that each action (or group of closely related actions) executed duringthe build should be implemented as aCommand subclass.

These commands are abstractions and do not necessarily correspond to a command thatcan (or should) be executed via a terminal, in a CLI fashion (although historicallythey would).

When creating a new command from scratch, custom defined classesSHOULD inheritfromsetuptools.Command and implement a few mandatory methods.Between these mandatory methods, are listed:initialize_options(),finalize_options() andrun().

A useful analogy for command classes is to think of them as subroutines with localvariables called “options”. The options are “declared” ininitialize_options()and “defined” (given their final values, aka “finalized”) infinalize_options(),both of which must be defined by every command class. The “body” of the subroutine,(where it does all the work) is therun() method.Betweeninitialize_options() andfinalize_options(),setuptools may setthe values for options/attributes based on user’s input (or circumstance),which means that the implementation should be careful to not overwrite values infinalize_options() unless necessary.

Please note that other commands (or other parts of setuptools) may also overwritethe values of the command’s options/attributes multiple times during the buildprocess.Therefore it is important to consistently implementinitialize_options() andfinalize_options(). For example, all derived attributes (or attributes thatdepend on the value of other attributes)SHOULD be recomputed infinalize_options().

When overwriting existing commands, custom defined classesMUST abide by thesame APIs implemented by the original class. They alsoSHOULD inherit from theoriginal class.

abstractmethodfinalize_options()→None¶

Set final values for all options/attributes used by the command.Most of the time, each option/attribute/cache should only be set if it does nothave any value yet (e.g.ifself.attrisNone:self.attr=val).

abstractmethodinitialize_options()→None¶

Set or (reset) all options/attributes/caches used by the commandto their default values. Note that these values may be overwritten duringthe build.

abstractmethodrun()→None¶

Execute the actions intended by the command.(Side effectsSHOULD only take place whenrun() is executed,for example, creating new files or writing to the terminal output).

Adding Arguments¶

Sometimes, your commands may need additional arguments to thesetup()call. You can enable this by defining entry points in thedistutils.setup_keywords group. For example, if you wanted asetup()argument calledbar_baz, you might add something like this to yourextension project:

# setup.cfg...[options.entry_points]distutils.commands=foo=mypackage.some_module:foodistutils.setup_keywords=bar_baz=mypackage.some_module:validate_bar_baz

The idea here is that the entry point defines a function that will be calledto validate thesetup() argument, if it’s supplied. TheDistributionobject will have the initial value of the attribute set toNone, and thevalidation function will only be called if thesetup() call sets it toa non-None value. Here’s an example validation function:

defassert_bool(dist,attr,value):"""Verify that value is True, False, 0, or 1"""ifbool(value)!=value:raiseSetupError(f"{attr!r} must be a boolean value (got{value!r}")

Your function should accept three arguments: theDistribution object,the attribute name, and the attribute value. It should raise aSetupError (from thesetuptools.errors module) if the argumentis invalid. Remember, your function will only be called with non-None values,and the default value of arguments defined this way is alwaysNone. So, yourcommands should always be prepared for the possibility that the attribute willbeNone when they access it later.

If more than one active distribution defines an entry point for the samesetup() argument,all of them will be called. This allows multipleextensions to define a common argument, as long as they agree onwhat values of that argument are valid.

Customizing Distribution Options¶

Plugins may wish to extend or alter the options on aDistribution object tosuit the purposes of that project. For example, a tool that infers theDistribution.version from SCM-metadata may need to hook into theoption finalization. To enable this feature, Setuptools offers an entrypointsetuptools.finalize_distribution_options. That entry point mustbe a callable taking one argument (theDistribution instance).

If the callable has an.order property, that value will be used todetermine the order in which the hook is called. Lower numbers are calledfirst and the default is zero (0).

Plugins may read, alter, and set properties on the distribution, but eachplugin is encouraged to load the configuration/settings for their behaviorindependently.

Defining Additional Metadata¶

Some extensible applications and frameworks may need to define their own kindsof metadata, which they can then access using theimportlib.metadata APIs.Ordinarily, this is done by having plugindevelopers include additional files in theirProjectName.egg-infodirectory. However, since it can be tedious to create such files by hand, youmay want to create an extension that will create the necessary filesfrom arguments tosetup(), in much the same way thatsetuptools doesfor many of thesetup() arguments it adds. See the section below for moredetails.

# setup.cfg...[options.entry_points]distutils.setup_keywords=foo_bar=setuptools.dist:assert_string_listegg_info.writers=foo_bar.txt=setuptools.command.egg_info:write_arg

defwrite_arg(cmd,basename,filename):argname=os.path.splitext(basename)[0]value=getattr(cmd.distribution,argname,None)ifvalueisnotNone:value="\n".join(value)+"\n"cmd.write_or_delete_file(argname,filename,value)

Adding Support for Revision Control Systems¶

If the files you want to include in the source distribution are tracked usingGit, Mercurial or SVN, you can use the following packages to achieve that:

• Git and Mercurial:setuptools_scm

• SVN:setuptools_svn

If you would like to create a plugin forsetuptools to find files trackedby another revision control system, you can do so by adding an entry point tothesetuptools.file_finders group. The entry point should be a functionaccepting a single directory name, and should yield all the filenames withinthat directory (and any subdirectories thereof) that are under revisioncontrol.

For example, if you were going to create a plugin for a revision control systemcalled “foobar”, you would write a function something like this:

deffind_files_for_foobar(dirname):...# loop to yield paths that start with `dirname`

And you would register it in a setup script using something like this:

# setup.cfg...[options.entry_points]setuptools.file_finders=foobar=my_foobar_module:find_files_for_foobar

Then, anyone who wants to use your plugin can simply install it, and theirlocal setuptools installation will be able to find the necessary files.

It is not necessary to distribute source control plugins with projects thatsimply use the other source control system, or to specify the plugins insetup_requires. When you create a source distribution with thesdistcommand, setuptools automatically records what files were found in theSOURCES.txt file. That way, recipients of source distributions don’t needto have revision control at all. However, if someone is working on a packageby checking out with that system, they will need the same plugin(s) that theoriginal author is using.

A few important points for writing revision control file finders:

• Your finder function MUST return relative paths, created by appending to thepassed-in directory name. Absolute paths are NOT allowed, nor are relativepaths that reference a parent directory of the passed-in directory.

• Your finder function MUST accept an empty string as the directory name,meaning the current directory. You MUST NOT convert this to a dot; justyield relative paths. So, yielding a subdirectory namedsome/dir underthe current directory should NOT be rendered as./some/dir or/somewhere/some/dir, butalways as simplysome/dir

• Your finder function SHOULD NOT raise any errors, and SHOULD deal gracefullywith the absence of needed programs (i.e., ones belonging to the revisioncontrol system itself. Itmay, however, uselogging.warning() toinform the user of the missing program(s).

Final Remarks¶

• To use asetuptools plugin, your users will need to add your package as abuild requirement to their build-system configuration. Please check out ourguides onDependencies Management in Setuptools for more information.

• Directly callingpythonsetup.py... is considered adeprecated practice.You should not add new commands tosetuptools expecting them to be runvia this interface.