New and Changed setup()
Keywords#
The following keyword arguments to setup()
are added or changed by
setuptools
. All of them are optional; you do not have to supply them
unless you need the associated setuptools
feature.
include_package_data
If set to
True
, this tellssetuptools
to automatically include any data files it finds inside your package directories that are specified by yourMANIFEST.in
file. For more information, see the section on Including Data Files.exclude_package_data
A dictionary mapping package names to lists of glob patterns that should be excluded from your package directories. You can use this to trim back any excess files included by
include_package_data
. For a complete description and examples, see the section on Including Data Files.package_data
A dictionary mapping package names to lists of glob patterns. For a complete description and examples, see the section on Including Data Files. You do not need to use this option if you are using
include_package_data
, unless you need to add e.g. files that are generated by your setup script and build process. (And are therefore not in source control or are files that you don’t want to include in your source distribution.)zip_safe
A boolean (True or False) flag specifying whether the project can be safely installed and run from a zip file. If this argument is not supplied, the
bdist_egg
command will have to analyze all of your project’s contents for possible problems each time it builds an egg.install_requires
A string or list of strings specifying what other distributions need to be installed when this one is. See the section on Declaring required dependency for details and examples of the format of this argument.
entry_points
A dictionary mapping entry point group names to strings or lists of strings defining the entry points. Entry points are used to support dynamic discovery of services or plugins provided by a project. See Advertising Behavior for details and examples of the format of this argument. In addition, this keyword is used to support Automatic Script Creation.
extras_require
A dictionary mapping names of “extras” (optional features of your project) to strings or lists of strings specifying what other distributions must be installed to support those features. See the section on Declaring required dependency for details and examples of the format of this argument.
python_requires
A string corresponding to a version specifier (as defined in PEP 440) for the Python version, used to specify the Requires-Python defined in PEP 345.
setup_requires
A string or list of strings specifying what other distributions need to be present in order for the setup script to run.
setuptools
will attempt to obtain these (using pip if available) before processing the rest of the setup script or commands. This argument is needed if you are using distutils extensions as part of your build process; for example, extensions that process setup() arguments and turn them into EGG-INFO metadata files.(Note: projects listed in
setup_requires
will NOT be automatically installed on the system where the setup script is being run. They are simply downloaded to the ./.eggs directory if they’re not locally available already. If you want them to be installed, as well as being available when the setup script is run, you should add them toinstall_requires
andsetup_requires
.)dependency_links
A list of strings naming URLs to be searched when satisfying dependencies. These links will be used if needed to install packages specified by
setup_requires
ortests_require
. They will also be written into the egg’s metadata for use during install by tools that support them.namespace_packages
A list of strings naming the project’s “namespace packages”. A namespace package is a package that may be split across multiple project distributions. For example, Zope 3’s
zope
package is a namespace package, because subpackages likezope.interface
andzope.publisher
may be distributed separately. The egg runtime system can automatically merge such subpackages into a single parent package at runtime, as long as you declare them in each project that contains any subpackages of the namespace package, and as long as the namespace package’s__init__.py
does not contain any code other than a namespace declaration. See the section below on Using find_namespace: or find_namespace_packages for more information.test_suite
A string naming a
unittest.TestCase
subclass (or a package or module containing one or more of them, or a method of such a subclass), or naming a function that can be called with no arguments and returns aunittest.TestSuite
. If the named suite is a module, and the module has anadditional_tests()
function, it is called and the results are added to the tests to be run. If the named suite is a package, any submodules and subpackages are recursively added to the overall test suite.Specifying this argument enables use of the test command to run the specified test suite, e.g. via
setup.py test
. See the section on the test command below for more details.New in 41.5.0: Deprecated the test command.
tests_require
If your project’s tests need one or more additional packages besides those needed to install it, you can use this option to specify them. It should be a string or list of strings specifying what other distributions need to be present for the package’s tests to run. When you run the
test
command,setuptools
will attempt to obtain these (using pip if available). Note that these required projects will not be installed on the system where the tests are run, but only downloaded to the project’s setup directory if they’re not already installed locally.New in 41.5.0: Deprecated the test command.
test_loader
If you would like to use a different way of finding tests to run than what setuptools normally uses, you can specify a module name and class name in this argument. The named class must be instantiable with no arguments, and its instances must support the
loadTestsFromNames()
method as defined in the Pythonunittest
module’sTestLoader
class. Setuptools will pass only one test “name” in thenames
argument: the value supplied for thetest_suite
argument. The loader you specify may interpret this string in any way it likes, as there are no restrictions on what may be contained in atest_suite
string.The module name and class name must be separated by a
:
. The default value of this argument is"setuptools.command.test:ScanningLoader"
. If you want to use the defaultunittest
behavior, you can specify"unittest:TestLoader"
as yourtest_loader
argument instead. This will prevent automatic scanning of submodules and subpackages.The module and class you specify here may be contained in another package, as long as you use the
tests_require
option to ensure that the package containing the loader class is available when thetest
command is run.New in 41.5.0: Deprecated the test command.
eager_resources
A list of strings naming resources that should be extracted together, if any of them is needed, or if any C extensions included in the project are imported. This argument is only useful if the project will be installed as a zipfile, and there is a need to have all of the listed resources be extracted to the filesystem as a unit. Resources listed here should be “/”-separated paths, relative to the source root, so to list a resource
foo.png
in packagebar.baz
, you would include the stringbar/baz/foo.png
in this argument.If you only need to obtain resources one at a time, or you don’t have any C extensions that access other files in the project (such as data files or shared libraries), you probably do NOT need this argument and shouldn’t mess with it. For more details on how this argument works, see the section below on Automatic Resource Extraction.
project_urls
An arbitrary map of URL names to hyperlinks, allowing more extensible documentation of where various resources can be found than the simple
url
anddownload_url
options provide.