The build system is a fundamental tool for packaging Python libraries. It generates distribution files that can be shared with users and developers.
The build system allows maintainers to generate artifacts for their Python libraries. Here, artifacts refers to both wheel and source files:
Wheel fileshave the
Source fileshave the
These are the files to upload to PyPI when releasing a new version of a PyAnsys project.
Not all files are included by default in the source distribution. A MANIFEST.in is required at the root of the project to specify additional files.
The interaction between the maintainer and the build system is performed using a build system tool. This tool provides both a frontend and a backend. The maintainers trigger the frontend, which then calls the backend to read the project directory and generate the artifacts, as Fig. 11 shows.
PEP 517 and PEP 518#
For a long time, the
setup.py file was the only way of specifying the
project structure, metadata, and installation workflow that pip was to follow.
However, having to execute a Python file when installing a Python package
introduced the following problems:
It was not possible to know which dependencies required the
setup.pyfile to be properly executed.
Setuptools , while very popular, lacks the ability to declare build time dependencies and is difficult to extend.
Flit is a lightweight build system tool for Python.
Poetry focuses on dependency management and environment isolation.
PEP 517 introduced the
build-backend key inside the
[build-system] table in the
In addition to the
setup.py file, PEP 518 includes a project file named
pyproject.toml. The main goal of this file is to specify build time dependencies.
However, some build system tools like flit or poetry are able to specify all
project metadata inside the
pyproject.toml file and eliminate usage of the
To specify the build time requirements, the
[build-system] table must be
declared in the
pyproject.toml file. Within it, the
requires key is
assigned to a list of strings, which are the build time
[build-system] requires = ["flit"] # Defined by PEP 518 build-backend = "flit_core.api" # Defined by PEP 517
Build backend tools#
This section lists some of the most popular build systems in the Python ecosystem. Although all of them achieve the same goal, there are a few differences regarding their capabilities and the way of specifying project metadata.
If you do not need a dynamic installation process, you can consider using a
setup.cfg file. However, the
setup.py file is still required. The
should have a call to the
setup function to act as the entry point of the
build backend system.
All of these setuptools metadata fields are valid and must be
specified either in the
Flit is a modern and lightweight build system that requires developers to manage virtual environments on their own. Developers must:
Create a virtual environment and activate it.
Install the package in editable mode.
Flit is the default tool for creating a new
pyansys project when using the
[project] section specifies the project’s metadata and required
dependencies. For more information, see flit pyproject.toml
Because of its
poetry.lock file, Poetry provides strong dependency pinning. When
installing a package, poetry creates a virtual environment, thus ensuring an isolated
package development environment.
Nevertheless, it is possible to make Poetry ignore the
poetry.lock file with:
poetry config virtualenvs.create false --local
Using poetry is popular because it:
Supports pinning dependency versions via a
poetry.lockfile that can be used for testing and CI
Allows downstream packages to still consume a loose dependency specification
Integrates with dependabot to update the pinned version
[tool.poetry] section contains metadata and defines project
dependencies. For more information, see poetry pyproject.toml documentation.