============================
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 market. Every 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
+be generated with whatever tool that provides a ``build sdist``-like
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:`PEP 517 <517#build-requirements>`. To learn more about Python packaging in general,
setup.cfg # or setup.py
mypackage/__init__.py
-Then, you need an builder, such as :std:doc:`PyPA build <pypa-build:index>`
+Then, you need a builder, such as :std:doc:`PyPA build <pypa-build:index>`
which you can obtain via ``pip install build``. After downloading it, invoke
the builder::
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 sections,
-we will walk through those additional but essential information you need
+we will walk through the 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``
+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 two convenient tools to ease the burden: :literal:`find:\ ` and
:literal:`find_namespace:\ `. To use it in your project:
include=pkg1, pkg2
exclude=pk3, pk4
-When you pass the above information, alongside other necessary ones,
+When you pass the above information, alongside other necessary information,
``setuptools`` walks through the directory specified in ``where`` (omitted
-here as the package reside in current directory) and filters the packages
-it can find following the ``include`` (default to none), then remove
-those that match the ``exclude`` and return a list of Python packages. Note
+here as the package resides in the current directory) and filters the packages
+it can find following the ``include`` (defaults to none), then removes
+those that match the ``exclude`` and returns a list of Python packages. Note
that each entry in the ``[options.packages.find]`` is optional. The above
setup also allows you to adopt a ``src/`` layout. 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
+Setuptools supports automatic creation of scripts upon installation, that runs
code within your package if you specify them with the ``entry_points`` keyword.
This is what allows you to run commands like ``pip install`` instead of having
to type ``python -m pip install``. To accomplish this, add the entry_points
When your project is installed, all of the dependencies not already installed
will be located (via PyPI), downloaded, built (if necessary), and installed.
-This, of course, is a simplified scenarios. ``setuptools`` also provide
+This, of course, is a simplified scenarios. ``setuptools`` also provides
additional keywords such as ``setup_requires`` that allows you to install
dependencies before running the script, and ``extras_require`` that take
care of those needed by automatically generated scripts. It also provides
Uploading your package to PyPI
==============================
-After generating the distribution files, next step would be to upload your
+After generating the distribution files, the next step would be to upload your
distribution so others can use it. This functionality is provided by
`twine <https://pypi.org/project/twine/>`_ and we will only demonstrate the
basic use here.