========================== ``setuptools`` Quickstart ========================== Installation ============ .. _Installing Packages: https://packaging.python.org/tutorials/installing-packages/ To install the latest version of setuptools, use:: pip install --upgrade setuptools Refer to `Installing Packages`_ guide for more information. Python packaging at a glance ============================ The landscape of Python packaging is shifting and ``Setuptools`` has evolved to only provide backend support, no longer being the de-facto packaging tool in the market. All python package must provide a ``pyproject.toml`` and specify the backend (build system) it wants to use. The distribution can then be generated with whatever tools that provides a ``build sdist``-alike functionality. While this may appear cumbersome, given the added pieces, it in fact tremendously enhances the portability of your package. The change is driven under `PEP 517 `` Basic Use ========= For basic use of setuptools, you will need a ``pyproject.toml`` with the exact following info, which declares you want to use ``setuptools`` to package your project: .. code-block:: toml [build-system] requires = ["setuptools", "wheel"] build-backend = "setuptools.build_meta" Then, you will need a ``setup.cfg`` to specify your package information, such as metadata, contents, dependencies, etc. Here we demonstrate the minimum .. code-block:: ini [metadata] name = "mypackage" version = 0.0.1 [options] packages = "mypackage" install_requires = requests importlib; python_version == "2.6" This is what your project would look like:: ~/mypackage/ pyproject.toml setup.cfg mypackage/__init__.py As you can see, it doesn't take much to use setuptools in a project. Invoke the installer at the root of your package:: pep517 build You now have your distribution ready, which you can upload to PyPI. Of course, before you release your project to PyPI, you'll want to add a bit more information to your setup script to help people find or learn about your project. And maybe your project will have grown by then to include a few dependencies, and perhaps some data files and scripts. In the next few section, we will walk through those additional but essential information you need to specify to properly package your project. Automatic package discovery =========================== For simple projects, it's usually easy enough to manually add packages to the ``packages`` keyword in ``setup.cfg``. However, for very large projects , it can be a big burden to keep the package list updated. ``setuptools`` therefore provides tools to ease the burden. ``find_packages()`` takes a source directory and two lists of package name patterns to exclude and include. It then walks the target directory, filtering by inclusion patterns, and return a list of Python packages (any directory). Finally, exclusion patterns are applied to remove matching packages. For example:: #... from setuptools import find_packages() setup( #..., packages = find_packages() ) For more details and advanced use, go to :ref:`package_discovery` Entry points and automatic script creation =========================================== Setuptools support automatic creation of scripts upon installation, that runs code within your package if you specify them with the ``entry_point`` keyword. This is what allows you to run commands like ``pip install`` instead of having to type ``python -m pip install``. To accomplish this, consider the following example:: setup( #.... entry_points={ "console_scripts": [ "foo = my_package.some_module:main_func", ], } ) When this project is installed, a ``foo`` script will be installed and will invoke the ``main_func`` when called by the user. For detailed usage, including managing the additional or optional dependencies, go to :ref:`entry_point`. Dependency management ===================== ``setuptools`` supports automatically installing dependencies when a package is installed. The simplest way to include requirement specifiers is to use the ``install_requires`` argument to ``setup()``. It takes a string or list of strings containing requirement specifiers:: setup( #... install_requires = "docutils >= 0.3" ) When your project is installed, either by using pip, ``setup.py install``, or ``setup.py develop``, all of the dependencies not already installed will be located (via PyPI), downloaded, built (if necessary), and installed. For more advanced use, see :ref:`dependency_management` Including Data Files ==================== The distutils have traditionally allowed installation of "data files", which are placed in a platform-specific location. Setuptools offers three ways to specify data files to be included in your packages. For the simpliest use, you can simply use the ``include_package_data`` keyword e.g.:: 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 the distutils' ``MANIFEST.in`` file. For more details, see :ref:`datafiles` Development mode ================ Setuptools allows you to deploy your projects for use in a common directory or staging area, but without copying any files. Thus, you can edit each project's code in its checkout directory, and only need to run build commands when you change a project's C extensions or similarly compiled files. To do this, use the ``setup.py develop`` command. It works very similarly to ``setup.py install``, except that it doesn't actually install anything. Instead, it creates a special ``.egg-link`` file in the deployment directory, that links to your project's source code. And, if your deployment directory is Python's ``site-packages`` directory, it will also update the ``easy-install.pth`` file to include your project's source code, thereby making it available on ``sys.path`` for all programs using that Python installation. for more information, go to :ref:`development_mode` Distributing a ``setuptools``-based project =========================================== Before you begin, make sure you have the latest versions of setuptools and wheel:: pip install --upgrade setuptools wheel To build a setuptools project, run this command from the same directory where setup.py is located:: setup.py sdist bdist_wheel This will generate distribution archives in the `dist` directory. Before you upload the generated archives make sure you're registered on https://test.pypi.org/account/register/. You will also need to verify your email to be able to upload any packages. You should install twine to be able to upload packages:: pip install --upgrade twine Now, to upload these archives, run:: twine upload --repository-url https://test.pypi.org/legacy/ dist/* To install your newly uploaded package ``example_pkg``, you can use pip:: pip install --index-url https://test.pypi.org/simple/ example_pkg The next following sections will walk you through all of the available functions ``setuptools`` offers in excrutiating details (including those already mentioned) for more advanced use.