alias - Define shortcuts for commonly used commands¶

Sometimes, you need to use the same commands over and over, but you can’tnecessarily set them as defaults. For example, if you produce both developmentsnapshot releases and “stable” releases of a project, you may want to putthe distributions in different places, or use differentegg_info taggingoptions, etc. In these cases, it doesn’t make sense to set the options ina distutils configuration file, because the values of the options changed basedon what you’re trying to do.

Setuptools therefore allows you to define “aliases” - shortcut names foran arbitrary string of commands and options, usingsetup.pyaliasaliasnameexpansion, where aliasname is the name of the new alias, and the remainder ofthe command line supplies its expansion. For example, this command definesa sitewide alias called “daily”, that sets variousegg_info taggingoptions:

setup.pyalias--global-configdailyegg_info--tag-build=development

Once the alias is defined, it can then be used with other setup commands,e.g.:

setup.pydailybdist_egg# generate a daily-build .egg filesetup.pydailysdist# generate a daily-build source distrosetup.pydailysdistbdist_egg# generate both

The above commands are interpreted as if the worddaily were replaced withegg_info--tag-build=development.

Note that setuptools will expand each aliasat most once in a given commandline. This serves two purposes. First, if you accidentally create an aliasloop, it will have no effect; you’ll instead get an error message about anunknown command. Second, it allows you to define an alias for a command, thatuses that command. For example, this (project-local) alias:

setup.pyaliasbdist_eggbdist_eggrotate-k1-m.egg

redefines thebdist_egg command so that it always runs therotatecommand afterwards to delete all but the newest egg file. It doesn’t loopindefinitely onbdist_egg because the alias is only expanded once whenused.

You can remove a defined alias with the--remove (or-r) option, e.g.:

setup.pyalias--global-config--removedaily

would delete the “daily” alias we defined above.

Aliases can be defined on a project-specific, per-user, or sitewide basis. Thedefault is to define or remove a project-specific alias, but you can use any oftheconfiguration file options (listed under thesaveopts command, below)to determine which distutils configuration file an aliases will be added to(or removed from).

Note that if you omit the “expansion” argument to thealias command,you’ll get output showing that alias’ current definition (and whatconfiguration file it’s defined in). If you omit the alias name as well,you’ll get a listing of all current aliases along with their configurationfile locations.

bdist_egg - Create a Python Egg for the project¶

This command generates a Python Egg (.egg file) for the project. PythonEggs are the preferred binary distribution format for EasyInstall, because theyare cross-platform (for “pure” packages), directly importable, and containproject metadata including scripts and information about the project’sdependencies. They can be simply downloaded and added tosys.pathdirectly, or they can be placed in a directory onsys.path and thenautomatically discovered by the egg runtime system.

This command runs theegg_info command (if it hasn’t already run) to updatethe project’s metadata (.egg-info) directory. If you have added any extrametadata files to the.egg-info directory, those files will be included inthe new egg file’s metadata directory, for use by the egg runtime system or byany applications or frameworks that use that metadata.

You won’t usually need to specify any special options for this command; justusebdist_egg and you’re done. But there are a few options that maybe occasionally useful:

--dist-dir=DIR,-dDIR

Set the directory where the.egg file will be placed. If you don’tsupply this, then the--dist-dir setting of thebdist commandwill be used, which is usually a directory nameddist in the projectdirectory.

--plat-name=PLATFORM,-pPLATFORM

Set the platform name string that will be embedded in the egg’s filename(assuming the egg contains C extensions). This can be used to overridethe distutils default platform name with something more meaningful. Keepin mind, however, that the egg runtime system expects to see eggs withdistutils platform names, so it may ignore or reject eggs with non-standardplatform names. Similarly, the EasyInstall program may ignore them whensearching web pages for download links. However, if you arecross-compiling or doing some other unusual things, you might find a usefor this option.

--exclude-source-files

Don’t include any modules’.py files in the egg, just compiled Python,C, and data files. (Note that this doesn’t affect any.py files in theEGG-INFO directory or its subdirectories, since for example there may bescripts with a.py extension which must still be retained.) We don’trecommend that you use this option except for packages that are beingbundled for proprietary end-user applications, or for “embedded” scenarioswhere space is at an absolute premium. On the other hand, if your packageis going to be installed and used in compressed form, you might as wellexclude the source because Python’straceback module doesn’t currentlyunderstand how to display zipped source code anyway, or how to deal withfiles that are in a different place from where their code was compiled.

There are also some options you will probably never need, but which are therebecause they were copied from similarbdist commands used as an example forcreating this one. They may be useful for testing and debugging, however,which is why we kept them:

--keep-temp,-k

Keep the contents of the--bdist-dir tree around after creating the.egg file.

--bdist-dir=DIR,-bDIR

Set the temporary directory for creating the distribution. The entirecontents of this directory are zipped to create the.egg file, afterrunning various installation commands to copy the package’s modules, data,and extensions here.

--skip-build

Skip doing any “build” commands; just go straight to theinstall-and-compress phases.

develop - Deploy the project source in “Development Mode”¶

This command allows you to deploy your project’s source for use in one or more“staging areas” where it will be available for importing. This deployment isdone in such a way that changes to the project source are immediately availablein the staging area(s), without needing to run a build or install step aftereach change.

Thedevelop command works by creating an.egg-link file (named for theproject) in the given staging area. If the staging area is Python’ssite-packages directory, it also updates aneasy-install.pth file sothat the project is onsys.path by default for all programs run using thatPython installation.

Thedevelop command also installs wrapper scripts in the staging area (ora separate directory, as specified) that will ensure the project’s dependenciesare available onsys.path before running the project’s source scripts.And, it ensures that any missing project dependencies are available in thestaging area, by downloading and installing them if necessary.

Last, but not least, thedevelop command invokes thebuild_ext-icommand to ensure any C extensions in the project have been built and areup-to-date, and theegg_info command to ensure the project’s metadata isupdated (so that the runtime and wrappers know what the project’s dependenciesare). If you make any changes to the project’s setup script or C extensions,you should rerun thedevelop command against all relevant staging areas tokeep the project’s scripts, metadata and extensions up-to-date. Most otherkinds of changes to your project should not require any build operations orrerunningdevelop, but keep in mind that even minor changes to the setupscript (e.g. changing an entry point definition) require you to re-run thedevelop ortest commands to keep the distribution updated.

Here are some of the options that thedevelop command accepts. Note thatthey affect the project’s dependencies as well as the project itself, so if youhave dependencies that need to be installed and you use--exclude-scripts(for example), the dependencies’ scripts will not be installed either! Forthis reason, you may want to use pip to install the project’s dependenciesbefore using thedevelop command, if you need finer control over theinstallation options for dependencies.

--uninstall,-u

Un-deploy the current project. You may use the--install-dir or-doption to designate the staging area. The created.egg-link file willbe removed, if present and it is still pointing to the project directory.The project directory will be removed fromeasy-install.pth if thestaging area is Python’ssite-packages directory.

Note that this option currently doesnot uninstall script wrappers! Youmust uninstall them yourself, or overwrite them by using pip to install adifferent version of the package. You can also avoid installing scriptwrappers in the first place, if you use the--exclude-scripts (aka-x) option when you rundevelop to deploy the project.

--multi-version,-m

“Multi-version” mode. Specifying this option preventsdevelop fromadding aneasy-install.pth entry for the project(s) being deployed, andif an entry for any version of a project already exists, the entry will beremoved upon successful deployment. In multi-version mode, no specificversion of the package is available for importing, unless you usepkg_resources.require() to put it onsys.path, or you are runninga wrapper script generated bysetuptools. (In which case the wrapperscript callsrequire() for you.)

Note that if you install to a directory other thansite-packages,this option is automatically in effect, because.pth files can only beused insite-packages (at least in Python 2.3 and 2.4). So, if you usethe--install-dir or-d option (or they are set via configurationfile(s)) your project and its dependencies will be deployed inmulti-version mode.

--install-dir=DIR,-dDIR

Set the installation directory (staging area). If this option is notdirectly specified on the command line or in a distutils configurationfile, the distutils default installation location is used. Normally, thiswill be thesite-packages directory, but if you are using distutilsconfiguration files, setting things likeprefix orinstall_lib,then those settings are taken into account when computing the defaultstaging area.

--script-dir=DIR,-sDIR

Set the script installation directory. If you don’t supply this option(via the command line or a configuration file), but youhave suppliedan--install-dir (via command line or config file), then this optiondefaults to the same directory, so that the scripts will be able to findtheir associated package installation. Otherwise, this setting defaultsto the location where the distutils would normally install scripts, takingany distutils configuration file settings into account.

--exclude-scripts,-x

Don’t deploy script wrappers. This is useful if you don’t want to disturbexisting versions of the scripts in the staging area.

--always-copy,-a

Copy all needed distributions to the staging area, even if theyare already present in another directory onsys.path. By default, ifa requirement can be met using a distribution that is already available ina directory onsys.path, it will not be copied to the staging area.

--egg-path=DIR

Force the generated.egg-link file to use a specified relative pathto the source directory. This can be useful in circumstances where yourinstallation directory is being shared by code running under multipleplatforms (e.g. Mac and Windows) which have different absolute locationsfor the code under development, but the samerelative locations withrespect to the installation directory. If you use this option wheninstalling, you must supply the same relative path when uninstalling.

In addition to the above options, thedevelop command also accepts all ofthe same options accepted byeasy_install. If you’ve configured anyeasy_install settings in yoursetup.cfg (or other distutils configfiles), thedevelop command will use them as defaults, unless you overridethem in a[develop] section or on the command line.

egg_info - Create egg metadata and set build tags¶

This command performs two operations: it updates a project’s.egg-infometadata directory (used by thebdist_egg,develop, andtestcommands), and it allows you to temporarily change a project’s version string,to support “daily builds” or “snapshot” releases. It is run automatically bythesdist,bdist_egg,develop, andtest commands in order toupdate the project’s metadata, but you can also specify it explicitly in orderto temporarily change the project’s version string while executing othercommands. (It also generates the.egg-info/SOURCES.txt manifest file, whichis used when you are building source distributions.)

In addition to writing the core egg metadata defined bysetuptools andrequired bypkg_resources, this command can be extended to write othermetadata files as well, by defining entry points in theegg_info.writersgroup. See the section onAdding new EGG-INFO Files below for more details.Note that using additional metadata writers may require you to include asetup_requires argument tosetup() in order to ensure that the desiredwriters are available onsys.path.

setup.pyegg_info--tag-date--tag-build=DEVbdist_egg

setup.pyegg_info-RDb""sdistbdist_egg

rotate - Delete outdated distribution files¶

As you develop new versions of your project, your distribution (dist)directory will gradually fill up with older source and/or binary distributionfiles. Therotate command lets you automatically clean these up, keepingonly the N most-recently modified files matching a given pattern.

--match=PATTERNLIST,-mPATTERNLIST

Comma-separated list of glob patterns to match. This option isrequired.The project name and-* is prepended to the supplied patterns, in orderto match only distributions belonging to the current project (in case youhave a shared distribution directory for multiple projects). Typically,you will use a glob pattern like.zip or.egg to match files ofthe specified type. Note that each supplied pattern is treated as adistinct group of files for purposes of selecting files to delete.

--keep=COUNT,-kCOUNT

Number of matching distributions to keep. For each group of filesidentified by a pattern specified with the--match option, delete allbut the COUNT most-recently-modified files in that group. This option isrequired.

--dist-dir=DIR,-dDIR

Directory where the distributions are. This defaults to the value of thebdist command’s--dist-dir option, which will usually be theproject’sdist subdirectory.

Example 1: Delete all .tar.gz files from the distribution directory, exceptfor the 3 most recently modified ones:

setup.pyrotate--match=.tar.gz--keep=3

Example 2: Delete all Python 2.3 or Python 2.4 eggs from the distributiondirectory, except the most recently modified one for each Python version:

setup.pyrotate--match=-py2.3*.egg,-py2.4*.egg--keep=1

saveopts - Save used options to a configuration file¶

Finding and editingdistutils configuration files can be a pain, especiallysince you also have to translate the configuration options from command-lineform to the proper configuration file format. You can avoid these hassles byusing thesaveopts command. Just add it to the command line to save theoptions you used. For example, this command builds the project usingthemingw32 C compiler, then saves the –compiler setting as the defaultfor future builds (even those run implicitly by theinstall command):

setup.pybuild--compiler=mingw32saveopts

Thesaveopts command saves all options for every command specified on thecommand line to the project’s localsetup.cfg file, unless you use one oftheconfiguration file options to change where the options are saved. Forexample, this command does the same as above, but saves the compiler settingto the site-wide (global) distutils configuration:

setup.pybuild--compiler=mingw32saveopts-g

Note that it doesn’t matter where you place thesaveopts command on thecommand line; it will still save all the options specified for all commands.For example, this is another valid way to spell the last example:

setup.pysaveopts-gbuild--compiler=mingw32

Note, however, that all of the commands specified are always run, regardless ofwheresaveopts is placed on the command line.

setopt - Set a distutils or setuptools option in a config file¶

This command is mainly for use by scripts, but it can also be used as a quickand dirty way to change a distutils configuration option without having toremember what file the options are in and then open an editor.

Example 1. Set the default C compiler tomingw32 (using long optionnames):

setup.pysetopt--command=build--option=compiler--set-value=mingw32

Example 2. Remove any setting for the distutils default packageinstallation directory (short option names):

setup.pysetopt-cinstall-oinstall_lib-r

Options for thesetopt command:

--command=COMMAND,-cCOMMAND

Command to set the option for. This option is required.

--option=OPTION,-oOPTION

The name of the option to set. This option is required.

--set-value=VALUE,-sVALUE

The value to set the option to. Not needed if-r or--remove isset.

--remove,-r

Remove (unset) the option, instead of setting it.

In addition to the above options, you may use any of theconfiguration fileoptions (listed under thesaveopts command, above) to determine whichdistutils configuration file the option will be added to (or removed from).

test - Build package and run a unittest suite¶

When doing test-driven development, or running automated builds that needtesting before they are deployed for downloading or use, it’s often usefulto be able to run a project’s unit tests without actually deploying the projectanywhere, even using thedevelop command. Thetest command runs aproject’s unit tests without actually deploying it, by temporarily putting theproject’s source onsys.path, after first runningbuild_ext-i andegg_info to ensure that any C extensions and project metadata areup-to-date.

To use this command, your project’s tests must be wrapped in aunittesttest suite by either a function, aTestCase class or method, or a moduleor package containingTestCase classes. If the named suite is a module,and the module has anadditional_tests() function, it is called and theresult (which must be aunittest.TestSuite) is added to the tests to berun. If the named suite is a package, any submodules and subpackages arerecursively added to the overall test suite. (Note: if your project specifiesatest_loader, the rules for processing the chosentest_suite maydiffer; see thetest_loader documentation for more details.)

Note that many test systems includingdoctest support wrapping theirnon-unittest tests inTestSuite objects. So, if you are using a testpackage that does not support this, we suggest you encourage its developers toimplement test suite support, as this is a convenient and standard way toaggregate a collection of tests to be run under a common test harness.

By default, tests will be run in the “verbose” mode of theunittestpackage’s text test runner, but you can get the “quiet” mode (just dots) ifyou supply the-q or--quiet option, either as a global option tothe setup script (e.g.setup.py-qtest) or as an option for thetestcommand itself (e.g.setup.pytest-q). There is one other optionavailable:

--test-suite=NAME,-sNAME

Specify the test suite (or module, class, or method) to be run(e.g.some_module.test_suite). The default for this option can beset by giving atest_suite argument to thesetup() function, e.g.:

setup(# ...test_suite="my_package.tests.test_all")

If you did not set atest_suite in yoursetup() call, and do notprovide a--test-suite option, an error will occur.

New in 41.5.0: Deprecated the test command.

upload - Upload source and/or egg distributions to PyPI¶

Theupload command was deprecated in version 40.0 and removed in version42.0. Usetwine instead.

For more information on the current best practices in uploading your packagesto PyPI, see the Python Packaging User Guide’s “Packaging Python Projects”tutorial specifically the section onuploading the distribution archives.