Links
- User guide
- Quickstart
- Supported Interfaces
- Package Discovery and Namespace Packages
- Dependencies Management in Setuptools
- Development Mode (a.k.a. “Editable Installs”)
- Entry Points
- Data Files Support
- Building Extension Modules
- Specifying Your Project’s Version
- Controlling files in the distribution
- Caching and Troubleshooting
- Extending or Customizing Setuptools
- Configuring setuptools using
setup.cfgfiles - Configuring setuptools using
pyproject.tomlfiles
- Build System Support
- Package Discovery and Resource Access using
pkg_resources - Keywords
- Building and Distributing Packages with Setuptools
Project
- Roadmap
- Development guide
- Backward compatibility & deprecated practice
- New and Changed
setup()Keywords - Specifying dependencies that aren’t in PyPI via
dependency_links - The Internal Structure of Python Eggs
- Easy Install
- Understanding the
zip_safeflag - Automatic Resource Extraction
- Distributing Python Modules (Legacy version)
- Porting from Distutils
- “Eggsecutable” Scripts
- Running
setuptoolscommands
- New and Changed
- History
- Credits
- Artwork
7.Extending Distutils¶
Note
This document is being retained solely until thesetuptools documentationathttps://setuptools.pypa.io/en/latest/setuptools.htmlindependently covers all of the relevant information currently included here.
Distutils can be extended in various ways. Most extensions take the form of newcommands or replacements for existing commands. New commands may be written tosupport new types of platform-specific packaging, for example, whilereplacements for existing commands may be made to modify details of how thecommand operates on a package.
Most extensions of the distutils are made withinsetup.py scripts thatwant to modify existing commands; many simply add a few file extensions thatshould be copied into packages in addition to.py files as aconvenience.
Most distutils command implementations are subclasses of thedistutils.cmd.Command class. New commands may directly inherit fromCommand, while replacements often derive fromCommandindirectly, directly subclassing the command they are replacing. Commands arerequired to derive fromCommand.
7.1.Integrating new commands¶
There are different ways to integrate new command implementations intodistutils. The most difficult is to lobby for the inclusion of the new featuresin distutils itself, and wait for (and require) a version of Python thatprovides that support. This is really hard for many reasons.
The most common, and possibly the most reasonable for most needs, is to includethe new implementations with yoursetup.py script, and cause thedistutils.core.setup() function use them:
fromdistutils.command.build_pyimportbuild_pyas_build_pyfromdistutils.coreimportsetupclassbuild_py(_build_py):"""Specialized Python source builder."""# implement whatever needs to be different...setup(cmdclass={'build_py':build_py},...)
This approach is most valuable if the new implementations must be used to use aparticular package, as everyone interested in the package will need to have thenew command implementation.
Beginning with Python 2.4, a third option is available, intended to allow newcommands to be added which can support existingsetup.py scripts withoutrequiring modifications to the Python installation. This is expected to allowthird-party extensions to provide support for additional packaging systems, butthe commands can be used for anything distutils commands can be used for. A newconfiguration option,command_packages (command-line option--command-packages), can be used to specify additional packages to besearched for modules implementing commands. Like all distutils options, thiscan be specified on the command line or in a configuration file. This optioncan only be set in the[global] section of a configuration file, or beforeany commands on the command line. If set in a configuration file, it can beoverridden from the command line; setting it to an empty string on the commandline causes the default to be used. This should never be set in a configurationfile provided with a package.
This new option can be used to add any number of packages to the list ofpackages searched for command implementations; multiple package names should beseparated by commas. When not specified, the search is only performed in thedistutils.command package. Whensetup.py is run with the option--command-packagesdistcmds,buildcmds, however, the packagesdistutils.command,distcmds, andbuildcmds will be searchedin that order. New commands are expected to be implemented in modules of thesame name as the command by classes sharing the same name. Given the examplecommand line option above, the commandbdist_openpkg could beimplemented by the classdistcmds.bdist_openpkg.bdist_openpkg orbuildcmds.bdist_openpkg.bdist_openpkg.
7.2.Adding new distribution types¶
Commands that create distributions (files in thedist/ directory) needto add(command,filename) pairs toself.distribution.dist_files so thatupload can upload it to PyPI. Thefilename in the pair contains nopath information, only the name of the file itself. In dry-run mode, pairsshould still be added to represent what would have been created.