164 lines
8.7 KiB
ReStructuredText
164 lines
8.7 KiB
ReStructuredText
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 tells ``setuptools`` to automatically include any
|
|
data files it finds inside your package directories that are specified by
|
|
your ``MANIFEST.in`` file. For more information, see the section on
|
|
:ref:`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 :ref:`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 :ref:`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 :ref:`Declaring
|
|
Dependencies` 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 :ref:`Dynamic
|
|
Discovery of Services and Plugins` for details and examples of the format
|
|
of this argument. In addition, this keyword is used to support
|
|
:ref:`Automatic Script Creation <entry_points>`.
|
|
|
|
``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 :ref:`Declaring
|
|
Dependencies` 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 to ``install_requires``
|
|
**and** ``setup_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`` or ``tests_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 like ``zope.interface`` and ``zope.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 :ref:`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 a
|
|
``unittest.TestSuite``. If the named suite is a module, and the module
|
|
has an ``additional_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 :ref:`test <test>` command to run the
|
|
specified test suite, e.g. via ``setup.py test``. See the section on the
|
|
:ref:`test <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:
|
|
|
|
``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 Python ``unittest`` module's ``TestLoader`` class. Setuptools will
|
|
pass only one test "name" in the ``names`` argument: the value supplied for
|
|
the ``test_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 a ``test_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 default ``unittest`` behavior, you can specify
|
|
``"unittest:TestLoader"`` as your ``test_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 the ``test`` 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 package ``bar.baz``, you would include the string
|
|
``bar/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 :ref:`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`` and ``download_url`` options provide.
|