================================================== Building and Distributing Packages with Setuptools ================================================== ``Setuptools`` is a collection of enhancements to the Python ``distutils`` that allow developers to more easily build and distribute Python packages, especially ones that have dependencies on other packages. Packages built and distributed using ``setuptools`` look to the user like ordinary Python packages based on the ``distutils``. Feature Highlights: * Create `Python Eggs `_ - a single-file importable distribution format * Enhanced support for accessing data files hosted in zipped packages. * Automatically include all packages in your source tree, without listing them individually in setup.py * Automatically include all relevant files in your source distributions, without needing to create a ``MANIFEST.in`` file, and without having to force regeneration of the ``MANIFEST`` file when your source tree changes. * Automatically generate wrapper scripts or Windows (console and GUI) .exe files for any number of "main" functions in your project. (Note: this is not a py2exe replacement; the .exe files rely on the local Python installation.) * Transparent Cython support, so that your setup.py can list ``.pyx`` files and still work even when the end-user doesn't have Cython installed (as long as you include the Cython-generated C in your source distribution) * Command aliases - create project-specific, per-user, or site-wide shortcut names for commonly used commands and options * Deploy your project in "development mode", such that it's available on ``sys.path``, yet can still be edited directly from its source checkout. * Easily extend the distutils with new commands or ``setup()`` arguments, and distribute/reuse your extensions for multiple projects, without copying code. * Create extensible applications and frameworks that automatically discover extensions, using simple "entry points" declared in a project's setup script. * Full support for PEP 420 via ``find_namespace_packages()``, which is also backwards compatible to the existing ``find_packages()`` for Python >= 3.3. .. contents:: **Table of Contents** ----------------- Developer's Guide ----------------- TRANSITIONAL NOTE ~~~~~~~~~~~~~~~~~ Setuptools automatically calls ``declare_namespace()`` for you at runtime, but future versions may *not*. This is because the automatic declaration feature has some negative side effects, such as needing to import all namespace packages during the initialization of the ``pkg_resources`` runtime, and also the need for ``pkg_resources`` to be explicitly imported before any namespace packages work at all. In some future releases, you'll be responsible for including your own declaration lines, and the automatic declaration feature will be dropped to get rid of the negative side effects. During the remainder of the current development cycle, therefore, setuptools will warn you about missing ``declare_namespace()`` calls in your ``__init__.py`` files, and you should correct these as soon as possible before the compatibility support is removed. Namespace packages without declaration lines will not work correctly once a user has upgraded to a later version, so it's important that you make this change now in order to avoid having your code break in the field. Our apologies for the inconvenience, and thank you for your patience. ----------------------------------------- Configuring setup() using setup.cfg files ----------------------------------------- .. note:: New in 30.3.0 (8 Dec 2016). .. important:: If compatibility with legacy builds (i.e. those not using the :pep:`517` build API) is desired, a ``setup.py`` file containing a ``setup()`` function call is still required even if your configuration resides in ``setup.cfg``. ``Setuptools`` allows using configuration files (usually :file:`setup.cfg`) to define a package’s metadata and other options that are normally supplied to the ``setup()`` function (declarative config). This approach not only allows automation scenarios but also reduces boilerplate code in some cases. .. note:: This implementation has limited compatibility with the distutils2-like ``setup.cfg`` sections used by the ``pbr`` and ``d2to1`` packages. Namely: only metadata-related keys from ``metadata`` section are supported (except for ``description-file``); keys from ``files``, ``entry_points`` and ``backwards_compat`` are not supported. .. code-block:: ini [metadata] name = my_package version = attr: src.VERSION description = My package description long_description = file: README.rst, CHANGELOG.rst, LICENSE.rst keywords = one, two license = BSD 3-Clause License classifiers = Framework :: Django License :: OSI Approved :: BSD License Programming Language :: Python :: 3 Programming Language :: Python :: 3.5 [options] zip_safe = False include_package_data = True packages = find: scripts = bin/first.py bin/second.py install_requires = requests importlib; python_version == "2.6" [options.package_data] * = *.txt, *.rst hello = *.msg [options.extras_require] pdf = ReportLab>=1.2; RXP rest = docutils>=0.3; pack ==1.1, ==1.3 [options.packages.find] exclude = src.subpackage1 src.subpackage2 [options.data_files] /etc/my_package = site.d/00_default.conf host.d/00_default.conf data = data/img/logo.png, data/svg/icon.svg Metadata and options are set in the config sections of the same name. * Keys are the same as the keyword arguments one provides to the ``setup()`` function. * Complex values can be written comma-separated or placed one per line in *dangling* config values. The following are equivalent: .. code-block:: ini [metadata] keywords = one, two [metadata] keywords = one two * In some cases, complex values can be provided in dedicated subsections for clarity. * Some keys allow ``file:``, ``attr:``, and ``find:`` and ``find_namespace:`` directives in order to cover common usecases. * Unknown keys are ignored. Using a ``src/`` layout ======================= One commonly used package configuration has all the module source code in a subdirectory (often called the ``src/`` layout), like this:: ├── src │   └── mypackage │   ├── __init__.py │   └── mod1.py ├── setup.py └── setup.cfg You can set up your ``setup.cfg`` to automatically find all your packages in the subdirectory like this: .. code-block:: ini # This example contains just the necessary options for a src-layout, set up # the rest of the file as described above. [options] package_dir= =src packages=find: [options.packages.find] where=src Specifying values ================= Some values are treated as simple strings, some allow more logic. Type names used below: * ``str`` - simple string * ``list-comma`` - dangling list or string of comma-separated values * ``list-semi`` - dangling list or string of semicolon-separated values * ``bool`` - ``True`` is 1, yes, true * ``dict`` - list-comma where keys are separated from values by ``=`` * ``section`` - values are read from a dedicated (sub)section Special directives: * ``attr:`` - Value is read from a module attribute. ``attr:`` supports callables and iterables; unsupported types are cast using ``str()``. * ``file:`` - Value is read from a list of files and then concatenated .. note:: The ``file:`` directive is sandboxed and won't reach anything outside the directory containing ``setup.py``. Metadata -------- .. note:: The aliases given below are supported for compatibility reasons, but their use is not advised. ============================== ================= ================= =============== ===== Key Aliases Type Minimum Version Notes ============================== ================= ================= =============== ===== name str version attr:, file:, str 39.2.0 (1) url home-page str download_url download-url str project_urls dict 38.3.0 author str author_email author-email str maintainer str maintainer_email maintainer-email str classifiers classifier file:, list-comma license str license_file str license_files list-comma description summary file:, str long_description long-description file:, str long_description_content_type str 38.6.0 keywords list-comma platforms platform list-comma provides list-comma requires list-comma obsoletes list-comma ============================== ================= ================= =============== ===== .. note:: A version loaded using the ``file:`` directive must comply with PEP 440. It is easy to accidentally put something other than a valid version string in such a file, so validation is stricter in this case. Notes: 1. The `version` file attribute has only been supported since 39.2.0. Options ------- ======================= =================================== =============== ===== Key Type Minimum Version Notes ======================= =================================== =============== ===== zip_safe bool setup_requires list-semi install_requires list-semi extras_require section python_requires str entry_points file:, section use_2to3 bool use_2to3_fixers list-comma use_2to3_exclude_fixers list-comma convert_2to3_doctests list-comma scripts list-comma eager_resources list-comma dependency_links list-comma tests_require list-semi include_package_data bool packages find:, find_namespace:, list-comma package_dir dict package_data section (1) exclude_package_data section namespace_packages list-comma py_modules list-comma data_files dict 40.6.0 ======================= =================================== =============== ===== .. note:: **packages** - The ``find:`` and ``find_namespace:`` directive can be further configured in a dedicated subsection ``options.packages.find``. This subsection accepts the same keys as the `setuptools.find_packages` and the `setuptools.find_namespace_packages` function: ``where``, ``include``, and ``exclude``. **find_namespace directive** - The ``find_namespace:`` directive is supported since Python >=3.3. Notes: 1. In the `package_data` section, a key named with a single asterisk (`*`) refers to all packages, in lieu of the empty string used in `setup.py`. Configuration API ================= Some automation tools may wish to access data from a configuration file. ``Setuptools`` exposes a ``read_configuration()`` function for parsing ``metadata`` and ``options`` sections into a dictionary. .. code-block:: python from setuptools.config import read_configuration conf_dict = read_configuration("/home/user/dev/package/setup.cfg") By default, ``read_configuration()`` will read only the file provided in the first argument. To include values from other configuration files which could be in various places, set the ``find_others`` keyword argument to ``True``. If you have only a configuration file but not the whole package, you can still try to get data out of it with the help of the ``ignore_option_errors`` keyword argument. When it is set to ``True``, all options with errors possibly produced by directives, such as ``attr:`` and others, will be silently ignored. As a consequence, the resulting dictionary will include no such options. Mailing List and Bug Tracker ============================ Please use the `distutils-sig mailing list`_ for questions and discussion about setuptools, and the `setuptools bug tracker`_ ONLY for issues you have confirmed via the list are actual bugs, and which you have reduced to a minimal set of steps to reproduce. .. _distutils-sig mailing list: http://mail.python.org/pipermail/distutils-sig/ .. _setuptools bug tracker: https://github.com/pypa/setuptools/