Provided by: python3-build_1.0.3-2_all 
NAME
build - build 1.0.3
A simple, correct Python packaging build frontend.
build manages pyproject.toml-based builds, invoking build-backend hooks as appropriate to build a
distribution package. It is a simple build tool and does not perform any dependency management.
PYTHON -M BUILD
A simple, correct Python build frontend.
By default, a source distribution (sdist) is built from {srcdir}
and a binary distribution (wheel) is built from the sdist.
This is recommended as it will ensure the sdist can be used
to build wheels.
Pass -s/--sdist and/or -w/--wheel to build a specific distribution.
If you do this, the default behavior will be disabled, and all
artifacts will be built from {srcdir} (even if you combine
-w/--wheel with -s/--sdist, the wheel will be built from {srcdir}).
python -m build [-h] [--version] [--sdist] [--wheel] [--outdir PATH]
[--skip-dependency-check] [--no-isolation] [--config-setting KEY[=VALUE]]
[srcdir]
python -m positional arguments
• srcdir - source directory (defaults to current directory)
python -m options
• -h, --help - show this help message and exit
• --version, -V - show program's version number and exit
• --sdist, -s - build a source distribution (disables the default behavior)
• --wheel, -w - build a wheel (disables the default behavior)
• --outdir PATH, -o PATH - output directory (defaults to {srcdir}/dist)
• --skip-dependency-check, -x - do not check that build dependencies are installed
• --no-isolation, -n - disable building the project in an isolated virtual environment. Build
dependencies must be installed separately when this option is used
• --config-setting KEY[=VALUE], -C KEY[=VALUE] - settings to pass to the backend. Multiple settings can
be provided. Settings beginning with a hyphen will erroneously be interpreted as options to build if
separated by a space character; use --config-setting=--my-setting -C--my-other-setting (default: None)
NOTE:
A pyproject-build CLI script is also available, so that tools such as pipx can use it.
By default build will build the package in an isolated environment, but this behavior can be disabled
with --no-isolation.
MISSION STATEMENT
In the Python ecosystem, the build system tools and the package management are very intertwined. While it
might be useful for user to be able to access all this capabilities in a single project (such as pip),
there are several use cases where this is not desirable. The main being custom environments (outside
PyPI) or situations where the user does its own package management, such as Linux distributions.
This project aims to fit the "building packages hole" for such use-cases in PEP 517/PEP 518 workflows.
As it is intended to be used by users that do their own package management, we will try to keep
dependencies to a minimum, in order to try make bootstrapping easier.
DIFFERENCES FROM OTHER TOOLS
pep517.build
build implements a CLI tailored to end users.
pep517.build contained a proof-of-concept of a PEP 517 frontend. It "implement[ed] essentially the
simplest possible frontend tool, to exercise and illustrate how the core functionality can be used". It
has since been deprecated and is scheduled for removal.
setup.py sdist bdist_wheel
build is roughly the equivalent of setup.py sdist bdist_wheel but with PEP 517 support, allowing use with
projects that don't use setuptools.
Custom Behaviors
Fallback Backend
As recommended in PEP 517, if no backend is specified, build will fallback to
setuptools.build_meta:__legacy__.
INSTALLATION
build can be installed via pip or an equivalent:
$ pip install build
You can also check out the latest git tag, download a tarball from GitHub, or manually fetch the
artifacts from the project page on PyPI. The git tags are recommended for redistribution and are
PGP-signed with one of the following keys:
• 3DCE51D60930EBA47858BA4146F633CBB0EB4BF2 (Filipe Laíns)
TIP:
If you prefer, or are already using virtualenv in your workflow, you can install build with the
optional virtualenv dependency:
$ pip install 'build[virtualenv]'
this way, build will use virtualenv for isolation, instead of venv. This can be particularly useful,
for example, when using automation tools that rely on virtualenv, such as tox, or when your operating
system's Python package does not include venv in the standard installation (such as some versions of
Ubuntu).
Bootstrapping
This package can build itself only with the tomli (can be omitted in Python 3.11+) and pyproject-hooks
dependencies. The --skip-dependency-check flag should be used in this case.
Compatibility
build is verified to be compatible with the following Python versions:
• 3.7
• 3.8
• 3.9
• 3.10
• 3.11
• PyPy3
CHANGELOG
1.0.3 (2023-09-06)
• Avoid CPython 3.8.17, 3.9.17, 3.10.12, and 3.11.4 tarfile symlink bug triggered by adding data_filter
in 1.0.0. (PR #675, fixes issue #674)
1.0.0 (2023-09-01)
• Removed the toml library fallback; toml can no longer be used as a substitute for tomli (PR #567)
• Added runner parameter to util.project_wheel_metadata (PR #566, fixes issue #553)
• Modified ProjectBuilder constructor signature, added alternative ProjectBuilder.from_env constructor,
redefined env.IsolatedEnv interface, and exposed env.DefaultIsolatedEnv, replacing
env.IsolatedEnvBuilder. The aim has been to shift responsibility for modifying the environment from
the project builder to the IsolatedEnv entirely and to ensure that the builder will be initialised from
an IsolatedEnv in a consistent manner. Mutating the project builder is no longer supported. (PR #537)
• virtualenv is no longer imported when using -n, for faster builds (PR #636, fixes issue #510)
• The SDist now contains the repository contents, including tests. Flit-core 3.8+ required. (PR #657,
#661, fixes issue #656)
• The minimum version of importlib-metadata has been increased to 4.6 and Python 3.10 due to a bug in the
standard library version with URL requirements in extras. This is still not required for 3.8 when
bootstrapping (as long as you don't have URL requirements in extras). (PR #631, fixes issue #630)
• Docs now built with Sphinx 7 (PR #660)
• Tests now contain a network marker (PR #649, fixes issue #648)
• Config-settings are now passed to get_requires* hooks, fixing a long standing bug. If this affects your
setuptools build, you can use -C--build-option=<cmd> -C--build-option=<option> to workaround an issue
with Setuptools not allowing unrecognised build options when running this hook. (PR #627, fixes issue
##264)
• Test on Python 3.12 betas/RCs (PR #624)
• Filter out malicious files when extracting tar archives when Python supports it (PR #609)
• Specify encoding, fixing issues when PYTHONWARNDEFAULTENCODING is set. (PR #587, fixes issue #577)
• Ruff is now used for linting.
0.10.0 (2023-01-11)
• Replace pep517 dependency with pyproject_hooks, into which pep517 has been renamed (PR #539, Fixes
#529)
• Change build backend from setuptools to flit (PR #470, Fixes #394)
• Dropped support for Python 3.6 (PR #532)
0.9.0 (2022-10-27)
• Hide a Python 3.11.0 unavoidable warning with venv (PR #527)
• Fix infinite recursion error in check_dependency with circular dependencies (PR #512, Fixes #511)
• Only import colorama on Windows (PR #494, Fixes #493)
• Flush output more often to reduce interleaved output (PR #494)
• Small API cleanup, like better _all__ and srcdir being read only. (PR #477)
• Only use importlib_metadata when needed (PR #401)
• Clarify in printout when build dependencies are being installed (PR #514)
0.8.0 (2022-05-22)
• Accept os.PathLike[str] in addition to str for paths in public API (PR #392, Fixes #372)
• Add schema validation for build-system table to check conformity with PEP 517 and PEP 518 (PR #365,
Fixes #364)
• Better support for Python 3.11 (sysconfig schemes PR #434, PR #463, tomllib PR #443, warnings PR #420)
• Improved error printouts (PR #442)
• Avoid importing packaging unless needed (PR #395, Fixes #393)
Breaking Changes
• Failure to create a virtual environment in the build.env module now raises build.FailedProcessError (PR
#442)
0.7.0 (2021-09-16)
• Add build.util module with an high-level utility API (PR #340)
0.6.0.post1 (2021-08-05)
• Fix compatibility with Python 3.6 and 3.7 (PR #339, Fixes #338)
0.6.0 (2021-08-02)
• Improved output (PR #333, Fixes #142)
• The CLI now honors NO_COLOR (PR #333)
• The CLI can now be forced to colorize the output by setting the FORCE_COLOR environment variable (PR
#335)
• Added logging to build and build.env (PR #333)
• Switch to a TOML v1 compliant parser (PR #336, Fixes #308)
Breaking Changes
• Dropped support for Python 2 and 3.5.
0.5.1 (2021-06-22)
• Fix invoking the backend on an inexistent output directory with multiple levels (PR #318, Fixes #316)
• When building wheels via sdists, use an isolated temporary directory (PR #321, Fixes #320)
0.5.0 (2021-06-19)
• Add ProjectBuilder.metadata_path helper (PR #303, Fixes #301)
• Added a build.__main__.build_package_via_sdist method (PR #304)
• Use appropriate installation scheme for Apple Python venvs (PR #314, Fixes #310)
Breaking Changes
• Binary distributions are now built via the sdist by default in the CLI (PR #304, Fixes #257) - python
-m build will now build a sdist, extract it, and build a wheel from the source
• As a side-effect of PR #304, build.__main__.build_package no longer does CLI error handling (print nice
message and exit the program)
• Importing build.__main__ no longer has any side-effects, it no longer overrides warnings.showwarning or
runs colorama.init on import (PR #312)
0.4.0 (2021-05-23)
• Validate that the supplied source directory is valid (PR #260, Fixes #259)
• Set and test minimum versions of build's runtime dependencies (PR #267, Fixes #263)
• Use symlinks on creating venv's when available (PR #274, Fixes #271)
• Error sooner if pip upgrade is required and fails (PR #288, Fixes #256)
• Add a runner argument to ProjectBuilder (PR #290, Fixes #289)
• Hide irrelevant pep517 error traceback and improve error messages (PR #296)
• Try to use colorama to fix colors on Windows (PR #300)
Breaking Changes
• As a side-effect of PR #260, projects not containing either a pyproject.toml or setup.py will be
reported as invalid. This affects projects specifying only a setup.cfg, such projects are recommended
to add a pyproject.toml. The new behavior is on par with what pip currently does, so if you are
affected by this, your project should not be pip installable.
• The --skip-dependencies option has been renamed to --skip-dependency-check (PR #297)
• The skip_dependencies argument of build.__main__.build_package has been renamed to
skip_dependency_check (PR #297)
• build.ConfigSettings has been renamed to build.ConfigSettingsType (PR #298)
• build.ProjectBuilder.build_dependencies to build.ProjectBuilder.build_system_requires (PR #284, Fixes
#182)
• build.ProjectBuilder.get_dependencies to build.ProjectBuilder.get_requires_for_build (PR #284, Fixes
#182)
0.3.1 (2021-03-09)
• Support direct usage from pipx run in 0.16.1.0+ (PR #247)
• Use UTF-8 encoding when reading pyproject.toml (PR #251, Fixes #250)
0.3.0 (2021-02-19)
• Upgrade pip based on venv pip version, avoids error on Debian Python 3.6.5-3.8 or issues installing
wheels on Big Sur (PR #229, PR #230, Fixes #228)
• Build dependencies in isolation, instead of in the build environment (PR #232, Fixes #231)
• Fallback on venv if virtualenv is too old (PR #241)
• Add metadata preparation hook (PR #217, Fixes #130)
0.2.1 (2021-02-09)
• Fix error from unrecognised pip flag on Python 3.6.0 to 3.6.5 (PR #227, Fixes #226)
0.2.0 (2021-02-07)
• Check dependencies recursively (PR #183, Fixes #25)
• Build wheel and sdist distributions in separate environments, as they may have different dependencies
(PR #195, Fixes #194)
• Add support for pre-releases in check_dependency (PR #204, Fixes #191)
• Fixes console scripts not being available during build (PR #221, Fixes #214)
• Do not add the default backend requirements to requires when no backend is specified (PR #177, Fixes
#107)
• Return the sdist name in ProjectBuild.build (PR #197)
• Improve documentation (PR #178, PR #203)
• Add changelog (PR #219, Fixes #169)
Breaking changes
• Move config_settings argument to the hook calls (PR #218, Fixes #216)
0.1.0 (2020-10-29)
• Moved the upstream to PyPA
• Fixed building with isolation in a virtual environment
• Added env.IsolatedEnv abstract class
• Added env.IsolatedEnvBuilder (replaces env.IsolatedEnvironment usages)
• Added python_executable argument to the ProjectBuilder constructor
• Added --version/-V option to the CLI
• Added support for Python 3.9
• Added py.typed marker
• Various miscellaneous fixes in the virtual environment creation
• Many general improvements in the documentation
• Documentation moved to the furo theme
• Updated the CoC to the PSF CoC, which PyPA has adopted
Breaking changes
• Renamed the entrypoint script to pyproject-build
• Removed default arguments from all paths in ProjectBuilder
• Removed ProjectBuilder.hook
• Renamed __main__.build to __main__.build_package
• Changed the default outdir value to {srcdir}/dest
• Removed env.IsolatedEnvironment
0.0.4 (2020-09-08)
• Packages are now built in isolation by default
• Added --no-isolation/-n flag to build in the current environment
• Add --config-setting/-C option to pass options to the backend
• Add IsolatedEnvironment class
• Fix creating the output directory if it doesn't exit
• Fix building with in-tree backends
• Fix broken entrypoint script (python-build)
• Add warning about incomplete verification when verifying extras
• Automatically detect typos in the build system table
• Minor documentation improvements
0.0.3.1 (2020-06-10)
• Fix bug preventing the CLI from being invoked
• Improved documentation
0.0.3 (2020-06-09)
• Misc improvements
• Added documentation
0.0.2 (2020-05-29)
• Add setuptools as a default fallback backend
• Fix extras handling in requirement strings
0.0.1 (2020-05-17)
• Initial release
API DOCUMENTATION
build module
build - A simple, correct PEP 517 build frontend
exception build.BuildBackendException(exception, description=None, exc_info=(None, None, None))
Bases: Exception
Exception raised when a backend operation fails.
exception build.BuildException
Bases: Exception
Exception raised by build.ProjectBuilder.
exception build.BuildSystemTableValidationError
Bases: BuildException
Exception raised when the [build-system] table in pyproject.toml is invalid.
exception build.FailedProcessError(exception, description)
Bases: Exception
Exception raised when a setup or preparation operation fails.
class build.ProjectBuilder(source_dir, python_executable='/usr/bin/python3.11', runner=<function
default_subprocess_runner>)
Bases: object
The PEP 517 consumer API.
Parameters
• source_dir (Union[str, PathLike[str]]) -- The source directory
• python_executable (str) -- The python executable where the backend lives
• runner (Callable[[Sequence[str], Optional[str], Optional[Mapping[str, str]]], None]) --
Runner for backend subprocesses
The runner, if provided, must accept the following arguments:
• cmd: a list of strings representing the command and arguments to execute, as would be passed to
e.g. 'subprocess.check_call'.
• cwd: a string representing the working directory that must be used for the subprocess.
Corresponds to the provided source_dir.
• extra_environ: a dict mapping environment variable names to values which must be set for the
subprocess execution.
The default runner simply calls the backend hooks in a subprocess, writing backend output to
stdout/stderr.
build(distribution, output_directory, config_settings=None, metadata_directory=None)
Build a distribution.
Parameters
• distribution (str) -- Distribution to build (sdist or wheel)
• output_directory (Union[str, PathLike[str]]) -- Directory to put the built
distribution in
• config_settings (Optional[Mapping[str, Union[str, Sequence[str]]]]) -- Config
settings for the build backend
• metadata_directory (Optional[str]) -- If provided, should be the return value of a
previous prepare call on the same distribution kind
Return type
str
Returns
The full path to the built distribution
property build_system_requires: set[str]
The dependencies defined in the pyproject.toml's build-system.requires field or the default
build dependencies if pyproject.toml is missing or build-system is undefined.
check_dependencies(distribution, config_settings=None)
Return the dependencies which are not satisfied from the combined set of
build_system_requires and get_requires_for_build() for a given distribution.
Parameters
• distribution (str) -- Distribution to check (sdist or wheel)
• config_settings (Optional[Mapping[str, Union[str, Sequence[str]]]]) -- Config
settings for the build backend
Return type
set[tuple[str, ...]]
Returns
Set of variable-length unmet dependency tuples
classmethod from_isolated_env(env, source_dir, runner=<function default_subprocess_runner>)
Return type
TypeVar(_TProjectBuilder, bound= ProjectBuilder)
get_requires_for_build(distribution, config_settings=None)
Return the dependencies defined by the backend in addition to build_system_requires for a
given distribution.
Parameters
• distribution (str) -- Distribution to get the dependencies of (sdist or wheel)
• config_settings (Optional[Mapping[str, Union[str, Sequence[str]]]]) -- Config
settings for the build backend
Return type
set[str]
static log(message)
Log a message.
The default implementation uses the logging module but this function can be overridden by
users to have a different implementation.
Parameters
message (str) -- Message to output
Return type
None
metadata_path(output_directory)
Generate the metadata directory of a distribution and return its path.
If the backend does not support the prepare_metadata_for_build_wheel hook, a wheel will be
built and the metadata will be extracted from it.
Parameters
output_directory (Union[str, PathLike[str]]) -- Directory to put the metadata
distribution in
Return type
str
Returns
The path of the metadata directory
prepare(distribution, output_directory, config_settings=None)
Prepare metadata for a distribution.
Parameters
• distribution (str) -- Distribution to build (must be wheel)
• output_directory (Union[str, PathLike[str]]) -- Directory to put the prepared
metadata in
• config_settings (Optional[Mapping[str, Union[str, Sequence[str]]]]) -- Config
settings for the build backend
Return type
Optional[str]
Returns
The full path to the prepared metadata directory
property python_executable: str
The Python executable used to invoke the backend.
property source_dir: str
Project source directory.
exception build.TypoWarning
Bases: Warning
Warning raised when a possible typo is found.
build.check_dependency(req_string, ancestral_req_strings=(), parent_extras=frozenset({}))
Verify that a dependency and all of its dependencies are met.
Parameters
• req_string (str) -- Requirement string
• parent_extras (Set[str]) -- Extras (eg. "test" in myproject[test])
Yields Unmet dependencies
Return type
Iterator[tuple[str, ...]]
build.env module
class build.env.DefaultIsolatedEnv(*args, **kwargs)
Bases: IsolatedEnv
An isolated environment which combines venv and virtualenv with pip.
install(requirements)
Install packages from PEP 508 requirements in the isolated build environment.
Parameters
requirements (Collection[str]) -- PEP 508 requirement specification to install
Note Passing non-PEP 508 strings will result in undefined behavior, you should not rely
on it. It is merely an implementation detail, it may change any time without
warning.
Return type
None
static log(message)
Prints message
The default implementation uses the logging module but this function can be overwritten by
users to have a different implementation.
Parameters
msg -- Message to output
Return type
None
make_extra_environ()
Generate additional env vars specific to the isolated environment.
Return type
dict[str, str]
property path: str
The location of the isolated build environment.
property python_executable: str
The python executable of the isolated build environment.
class build.env.IsolatedEnv(*args, **kwargs)
Bases: Protocol
Isolated build environment ABC.
abstract make_extra_environ()
Generate additional env vars specific to the isolated environment.
Return type
Optional[Mapping[str, str]]
abstract property python_executable: str
The Python executable of the isolated environment.
build.util module
build.util.project_wheel_metadata(source_dir, isolated=True, *, runner=<function
quiet_subprocess_runner>)
Return the wheel metadata for a project.
Uses the prepare_metadata_for_build_wheel hook if available, otherwise build_wheel.
Parameters
• source_dir (Union[str, PathLike[str]]) -- Project source directory
• isolated (bool) -- Whether or not to run invoke the backend in the current environment or
to create an isolated one and invoke it there.
• runner (Callable[[Sequence[str], Optional[str], Optional[Mapping[str, str]]], None]) --
An alternative runner for backend subprocesses
Return type
PackageMetadata
TEST SUITE
Due to its nature, build has a somewhat complex test suite, which we will try to go through in this
document.
Firstly, there are two set of tests, unit tests and integration tests. In unit tests, we test the actual
code implementation. In integration tests, we test build on a few real world projects; this is mostly a
sanity test.
Integration tests take a long time to run, and are not very helpful tracking down issues, so they are
disabled by default. They can be enabled by passing either --run-integration or --only-integration
arguments to pytest, where the latter will disable the unit tests and only run the integration ones.
Even though these tests are disabled by default, they will be run in CI, where test suite run durations
are not a big issue.
To run the test suite we use tox, which automates running the test suite on different environments:
tox
You can find out more about how to run tox and its arguments in the tox documentation.
We have a fairly large environment matrix. We run tests for all supported Python versions and
implementations, and with the module being invoked from path, sdist install, or wheel install.
Additionally, we have an environment for type checking, and one to produce the documentation. There are
some other extra environments, like checking the code with the minimum version of each dependency.
Some examples commands for this project:
• Run type checking: tox -e type
• Only run unit tests against Python 3.9: tox -e py39
• Run both unit and integration tests: tox -- --run-integration
• Only run integration tests: tox -- --only-integration
• Only run integration tests with parallel tasks: tox -- -n auto --only-integration
• Only run unit tests against Python 3.9 with the module installed via wheel: tox -e py39-wheel
We have CI testing, where we the test suite across all supported operating systems, and have test
coverage reports.
RELEASE PROCESS
As this project is critical to the Python ecosystem's supply chain security, all releases are PGP signed
with one of the keys listed in the installation page. Before releasing please make sure your PGP key is
listed there, and preferably signed by one of the other key holders. If your key is not signed by one of
the other key holders, please make sure the PR that added your key to the installation page was approved
by at least one other maintainer.
After that is done, you may release the project by following these steps:
1. Bump the versions in pyproject.toml and src/build/__init__.py
2. Update CHANGELOG.rst with the new version and current date
3.
Make a release commit with the changes made above
• The commit message should follow the release X.Y.Z format
4.
Make a signed tag (git tag -s X.Y.Z)
• The tag title should follow the build X.Y.Z format
• The tag body should be a plaintext version of the changelog for the current release
5. Push the commit and tag to the repository (git push and git push --tags)
6. Build the Python artifacts (python -m build)
7. Sign and push the artifacts to PyPI (twine upload -s dist/*)
If you have any questions, please look at previous releases and/or ping the other maintainers.
AUTHOR
Filipe Laíns
COPYRIGHT
2024, Filipe Laíns
1.0.3 Jan 31, 2024 BUILD(1)