pyproject.tomlsetup.py based project?The document aims to outline the flow involved in publishing/distributing adistribution package, usually to thePythonPackage Index (PyPI). It is written for package publishers, who are assumedto be the package author.
While thetutorial walks through theprocess of preparing a simple package for release, it does not fully enumeratewhat steps and files are required, and for what purpose.
Publishing a package requires a flow from the author’s source code to an enduser’s Python environment. The steps to achieve this are:
Have a source tree containing the package. This is typically a checkout froma version control system (VCS).
Prepare a configuration file describing the package metadata (name, versionand so forth) and how to create the build artifacts. For most packages, thiswill be apyproject.toml file, maintained manually in the sourcetree.
Create build artifacts to be sent to the package distribution service(usually PyPI); these will normally be asource distribution (“sdist”)and one or morebuilt distributions (“wheels”).These are made by a build tool using the configuration file from theprevious step. Often there is just one generic wheel for a pure Pythonpackage.
Upload the build artifacts to the package distribution service.
At that point, the package is present on the package distribution service.To use the package, end users must:
Download one of the package’s build artifacts from the package distributionservice.
Install it in their Python environment, usually in itssite-packagesdirectory. This step may involve a build/compile step which, if needed, mustbe described by the package metadata.
These last 2 steps are typically performed bypip when an end user runspipinstall.
The steps above are described in more detail below.
The source tree contains the package source code, usually a checkout from aVCS. The particular version of the code used to create the build artifactswill typically be a checkout based on a tag associated with the version.
The configuration file depends on the tool used to create the build artifacts.The standard practice is to use apyproject.toml file in theTOMLformat.
At a minimum, thepyproject.toml file needs a[build-system] tablespecifying your build tool. There are many build tools available, includingbut not limited toflit,hatch,pdm,poetry,Setuptools,trampolim, andwhey. Each tool’s documentation willshow what to put in the[build-system] table.
For example, here is a table for usinghatch:
[build-system]requires=["hatchling"]build-backend="hatchling.build"
With such a table in thepyproject.toml file,a “frontend” tool likebuild can run your chosenbuild tool’s “backend”to create the build artifacts.Your build tool may also provide its own frontend. An install toollikepip also acts as a frontend when it runs your build tool’s backendto install from a source distribution.
The particular build tool you choose dictates what additional information isrequired in thepyproject.toml file. For example, you might specify:
a[project] table containing projectCore Metadata(name, version, author and so forth),
a[tool] table containing tool-specific configuration options.
Refer to thepyproject.toml guide for acomplete guide topyproject.toml configuration.
A source distribution contains enough to install the package from source in anend user’s Python environment. As such, it needs the package source, and mayalso include tests and documentation. These are useful for end users wantingto develop your sources, and for end user systems where some local compilationstep is required (such as a C extension).
Thebuild package knows how to invoke your build tool to create one ofthese:
python3-mbuild--sdistsource-tree-directory
Or, your build tool may provide its own interface for creating an sdist.
A built distribution contains only the files needed for an end user’s Pythonenvironment. No compilation steps are required during the install, and thewheel file can simply be unpacked into thesite-packages directory. Thismakes the install faster and more convenient for end users.
A pure Python package typically needs only one “generic” wheel. A package withcompiled binary extensions needs a wheel for each supported combination ofPython interpreter, operating system, and CPU architecture that it supports.If a suitable wheel file is not available, tools likepip will fallback to installing the source distribution.
Thebuild package knows how to invoke your build tool to create one ofthese:
python3-mbuild--wheelsource-tree-directory
Or, your build tool may provide its own interface for creating a wheel.
Note
The default behaviour ofbuild is to make both an sdist and a wheelfrom the source in the current directory; the above examples aredeliberately specific.
Thetwine tool can upload build artifacts to PyPI for distribution,using a command like:
twineuploaddist/package-name-version.tar.gzdist/package-name-version-py3-none-any.whl
Or, your build tool may provide its own interface for uploading.
Now that the package is published, end users can download and install thepackage into their Python environment. Typically this is done withpip,using a command like:
python3-mpipinstallpackage-name
End users may also use other tools likePipenv,poetry, orpdm.