Package discovery¶

For projects that follow a simple directory structure,setuptools should beable to automatically detect allpackages andnamespaces. However, complex projects might includeadditional folders and supporting files that not necessarily should bedistributed (or that can confusesetuptools auto discovery algorithm).

Therefore,setuptools provides a convenient way to customizewhich packages should be distributed and in which directory they should befound, as shown in the example below:

# ...[tool.setuptools.packages]find={}# Scan the project directory with the default parameters# OR[tool.setuptools.packages.find]# All the following settings are optional:where=["src"]# ["."] by defaultinclude=["mypackage*"]# ["*"] by defaultexclude=["mypackage.tests*"]# empty by defaultnamespaces=false# true by default

[options]packages=find:# OR `find_namespace:` if you want to use namespaces[options.packages.find]  # (always `find` even if `find_namespace:` was used before)# This section is optional as well as each of the following options:where=src# . by defaultinclude=mypackage*# * by defaultexclude=mypackage.tests*# empty by default

fromsetuptoolsimportsetup,find_packages# or find_namespace_packagessetup(# ...packages=find_packages(# All keyword arguments below are optional:where='src',# '.' by defaultinclude=['mypackage*'],# ['*'] by defaultexclude=['mypackage.tests'],# empty by default),# ...)

When you pass the above information, alongside other necessary information,setuptools walks through the directory specified inwhere (defaults to.) and filters the packagesit can find following theinclude patterns (defaults to*), then it removesthose that match theexclude patterns (defaults to empty) and returns a list of Python packages.

For more details and advanced use, go toPackage Discovery and Namespace Packages.

Entry points and automatic script creation¶

Setuptools supports automatic creation of scripts upon installation, that runcode within your package if you specify them asentry points.An example of how this feature can be used inpip:it allows you to run commands likepipinstall instead of havingto typepython-mpipinstall.

The following configuration examples show how to accomplish this:

[project.scripts]cli-name="mypkg.mymodule:some_func"

[options.entry_points]console_scripts=cli-name=mypkg.mymodule:some_func

setup(# ...entry_points={'console_scripts':['cli-name = mypkg.mymodule:some_func',]})

When this project is installed, acli-name executable will be created.cli-name will invoke the functionsome_func in themypkg/mymodule.py file when called by the user.Note that you can also use theentry-points mechanism to advertisecomponents between installed packages and implement plugin systems.For detailed usage, go toEntry Points.

Dependency management¶

Packages built withsetuptools can specify dependencies to be automaticallyinstalled when the package itself is installed.The example below shows how to configure this kind of dependencies:

[project]# ...dependencies=["docutils","requests <= 0.4",]# ...

[options]install_requires=docutilsrequests <=0.4

setup(# ...install_requires=["docutils","requests <= 0.4"],# ...)

Each dependency is represented by a string that can optionally contain version requirements(e.g. one of the operators <, >, <=, >=, == or !=, followed by a version identifier),and/or conditional environment markers, e.g.sys_platform=="win32"(seeVersion specifiers for more information).

When your project is installed, all of the dependencies not already installedwill be located (via PyPI), downloaded, built (if necessary), and installed.This, of course, is a simplified scenario. You can also specify groups ofextra dependencies that are not strictly required by your package to work, butthat will provide additional functionalities.For more advanced use, seeDependencies Management in Setuptools.

Including Data Files¶

Setuptools offers three ways to specify data files to be included in your packages.For the simplest use, you can simply use theinclude_package_data keyword:

[tool.setuptools]include-package-data=true# This is already the default behaviour if you are using# pyproject.toml to configure your build.# You can deactivate that with `include-package-data = false`

[options]include_package_data=True

setup(# ...include_package_data=True,# ...)

This tells setuptools to install any data files it finds in your packages.The data files must be specified via theMANIFEST.infile or automatically added by aRevision Control System plugin.For more details, seeData Files Support.

Development mode¶

setuptools allows you to install a package without copying any filesto your interpreter directory (e.g. thesite-packages directory).This allows you to modify your source code and have the changes takeeffect without you having to rebuild and reinstall.Here’s how to do it:

pipinstall--editable.

SeeDevelopment Mode (a.k.a. “Editable Installs”) for more information.

fromsetuptoolsimportsetupsetup()

Uploading your package to PyPI¶

After generating the distribution files, the next step would be to upload yourdistribution so others can use it. This functionality is provided bytwine and is documented in thePython packaging tutorial.

Transitioning fromsetup.py to declarative config¶

To avoid executing arbitrary scripts and boilerplate code, we are transitioningfrom defining all your package information by runningsetup() to doing thisdeclaratively - by usingpyproject.toml (or oldersetup.cfg).

To ease the challenges of transitioning, we provide a quickguide to understanding howpyproject.tomlis parsed bysetuptools. (Alternatively, here is theguide forsetup.cfg).