1New and Changed ``setup()`` Keywords
2====================================
3
4The following keyword arguments to ``setup()`` are added or changed by
5``setuptools``.  All of them are optional; you do not have to supply them
6unless you need the associated ``setuptools`` feature.
7
8``include_package_data``
9    If set to ``True``, this tells ``setuptools`` to automatically include any
10    data files it finds inside your package directories that are specified by
11    your ``MANIFEST.in`` file.  For more information, see the section on
12    :ref:`Including Data Files`.
13
14``exclude_package_data``
15    A dictionary mapping package names to lists of glob patterns that should
16    be *excluded* from your package directories.  You can use this to trim back
17    any excess files included by ``include_package_data``.  For a complete
18    description and examples, see the section on :ref:`Including Data Files`.
19
20``package_data``
21    A dictionary mapping package names to lists of glob patterns.  For a
22    complete description and examples, see the section on :ref:`Including
23    Data Files`.  You do not need to use this option if you are using
24    ``include_package_data``, unless you need to add e.g. files that are
25    generated by your setup script and build process.  (And are therefore not
26    in source control or are files that you don't want to include in your
27    source distribution.)
28
29``zip_safe``
30    A boolean (True or False) flag specifying whether the project can be
31    safely installed and run from a zip file.  If this argument is not
32    supplied, the ``bdist_egg`` command will have to analyze all of your
33    project's contents for possible problems each time it builds an egg.
34
35``install_requires``
36    A string or list of strings specifying what other distributions need to
37    be installed when this one is.  See the section on :ref:`Declaring
38    Dependencies` for details and examples of the format of this argument.
39
40``entry_points``
41    A dictionary mapping entry point group names to strings or lists of strings
42    defining the entry points.  Entry points are used to support dynamic
43    discovery of services or plugins provided by a project.  See :ref:`Dynamic
44    Discovery of Services and Plugins` for details and examples of the format
45    of this argument.  In addition, this keyword is used to support
46    :ref:`Automatic Script Creation <entry_points>`.
47
48``extras_require``
49    A dictionary mapping names of "extras" (optional features of your project)
50    to strings or lists of strings specifying what other distributions must be
51    installed to support those features.  See the section on :ref:`Declaring
52    Dependencies` for details and examples of the format of this argument.
53
54``python_requires``
55    A string corresponding to a version specifier (as defined in PEP 440) for
56    the Python version, used to specify the Requires-Python defined in PEP 345.
57
58``setup_requires``
59    A string or list of strings specifying what other distributions need to
60    be present in order for the *setup script* to run.  ``setuptools`` will
61    attempt to obtain these (using pip if available) before processing the
62    rest of the setup script or commands.  This argument is needed if you
63    are using distutils extensions as part of your build process; for
64    example, extensions that process setup() arguments and turn them into
65    EGG-INFO metadata files.
66
67    (Note: projects listed in ``setup_requires`` will NOT be automatically
68    installed on the system where the setup script is being run.  They are
69    simply downloaded to the ./.eggs directory if they're not locally available
70    already.  If you want them to be installed, as well as being available
71    when the setup script is run, you should add them to ``install_requires``
72    **and** ``setup_requires``.)
73
74``dependency_links``
75    A list of strings naming URLs to be searched when satisfying dependencies.
76    These links will be used if needed to install packages specified by
77    ``setup_requires`` or ``tests_require``.  They will also be written into
78    the egg's metadata for use during install by tools that support them.
79
80``namespace_packages``
81    A list of strings naming the project's "namespace packages".  A namespace
82    package is a package that may be split across multiple project
83    distributions.  For example, Zope 3's ``zope`` package is a namespace
84    package, because subpackages like ``zope.interface`` and ``zope.publisher``
85    may be distributed separately.  The egg runtime system can automatically
86    merge such subpackages into a single parent package at runtime, as long
87    as you declare them in each project that contains any subpackages of the
88    namespace package, and as long as the namespace package's ``__init__.py``
89    does not contain any code other than a namespace declaration.  See the
90    section below on :ref:`Namespace Packages` for more information.
91
92``test_suite``
93    A string naming a ``unittest.TestCase`` subclass (or a package or module
94    containing one or more of them, or a method of such a subclass), or naming
95    a function that can be called with no arguments and returns a
96    ``unittest.TestSuite``.  If the named suite is a module, and the module
97    has an ``additional_tests()`` function, it is called and the results are
98    added to the tests to be run.  If the named suite is a package, any
99    submodules and subpackages are recursively added to the overall test suite.
100
101    Specifying this argument enables use of the :ref:`test <test>` command to run the
102    specified test suite, e.g. via ``setup.py test``.  See the section on the
103    :ref:`test <test>` command below for more details.
104
105    New in 41.5.0: Deprecated the test command.
106
107``tests_require``
108    If your project's tests need one or more additional packages besides those
109    needed to install it, you can use this option to specify them.  It should
110    be a string or list of strings specifying what other distributions need to
111    be present for the package's tests to run.  When you run the ``test``
112    command, ``setuptools`` will  attempt to obtain these (using pip if
113    available).  Note that these required projects will *not* be installed on
114    the system where the tests are run, but only downloaded to the project's setup
115    directory if they're not already installed locally.
116
117    New in 41.5.0: Deprecated the test command.
118
119.. _test_loader:
120
121``test_loader``
122    If you would like to use a different way of finding tests to run than what
123    setuptools normally uses, you can specify a module name and class name in
124    this argument.  The named class must be instantiable with no arguments, and
125    its instances must support the ``loadTestsFromNames()`` method as defined
126    in the Python ``unittest`` module's ``TestLoader`` class.  Setuptools will
127    pass only one test "name" in the ``names`` argument: the value supplied for
128    the ``test_suite`` argument.  The loader you specify may interpret this
129    string in any way it likes, as there are no restrictions on what may be
130    contained in a ``test_suite`` string.
131
132    The module name and class name must be separated by a ``:``.  The default
133    value of this argument is ``"setuptools.command.test:ScanningLoader"``.  If
134    you want to use the default ``unittest`` behavior, you can specify
135    ``"unittest:TestLoader"`` as your ``test_loader`` argument instead.  This
136    will prevent automatic scanning of submodules and subpackages.
137
138    The module and class you specify here may be contained in another package,
139    as long as you use the ``tests_require`` option to ensure that the package
140    containing the loader class is available when the ``test`` command is run.
141
142    New in 41.5.0: Deprecated the test command.
143
144``eager_resources``
145    A list of strings naming resources that should be extracted together, if
146    any of them is needed, or if any C extensions included in the project are
147    imported.  This argument is only useful if the project will be installed as
148    a zipfile, and there is a need to have all of the listed resources be
149    extracted to the filesystem *as a unit*.  Resources listed here
150    should be "/"-separated paths, relative to the source root, so to list a
151    resource ``foo.png`` in package ``bar.baz``, you would include the string
152    ``bar/baz/foo.png`` in this argument.
153
154    If you only need to obtain resources one at a time, or you don't have any C
155    extensions that access other files in the project (such as data files or
156    shared libraries), you probably do NOT need this argument and shouldn't
157    mess with it.  For more details on how this argument works, see the section
158    below on :ref:`Automatic Resource Extraction`.
159
160``project_urls``
161    An arbitrary map of URL names to hyperlinks, allowing more extensible
162    documentation of where various resources can be found than the simple
163    ``url`` and ``download_url`` options provide.
164