---
name: "pyproject-build"
section: "1"
platform: "linux"
package: "python3-build"
version: "1.2.2-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/pyproject-build"
---

# pyproject-build(1)

build 1.2.2 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.

## NAME

build - build 1.2.2

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] [--verbose] [--sdist] [--wheel] [--outdir PATH]
                [--skip-dependency-check] [--no-isolation | --installer {pip,uv}]
                [--config-setting KEY[=VALUE]]
                [srcdir]
```

### python -m build positional arguments

- •

  *srcdir* - source directory (defaults to current directory)

### python -m build options

- •

  *-h*, *--help* - show this help message and exit

- •

  *--version*, *-V* - show program's version number and exit

- •

  *--verbose*, *-v* - increase verbosity (default: **0**)

- •

  *--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

- •

  *--installer* **INSTALLER** - Python package installer to use (defaults to pip)

- •

  *--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. *Attestations* are available after 1.2.1 and can be verified with the **gh** CLI tool:

```
$ python -m pip --no-cache-dir download --no-deps build
$ gh attestation verify build*.whl --repo pypa/build
```

Build plans to support *PEP 740* if accepted.

**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).

There is also a **uv** extra, which can be used for **--installer=uv** if you don't have another install of **uv** available.

### 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\.8

- •

  3\.9

- •

  3\.10

- •

  3\.11

- •

  3\.12

- •

  PyPy3

## CHANGELOG

### 1.2.2 (2024-09-06)

- •

  Add editable to **builder.get\_requries\_for\_build**'s static types (PR *#764*, fixes issue *#763*)

- •

  Include artifact attestations in our release (PR *#782*)

- •

  Fix typing compatibility with typed **pyproject-hooks** (PR *#788*)

- •

  Mark more tests with **network** (PR *#808*)

- •

  Add more intersphinx links to docs (PR *#804*)

- •

  Make **uv** optional for tests (PR *#807* and *#813*)

### 1.2.1 (2024-03-28)

- •

  Avoid error when terminal width is undetectable on Python \< 3.11 (PR *#761*)

### 1.2.0 (2024-03-27)

- •

  Add **--installer** option, supporting **pip** and **uv**. Added **uv** extra. (PR *#751*)

- •

  Improve console output and provide **-v** for dependency installation (PR *#749*)

- •

  Avoid compiling unused bytecode when using **pip** (PR *#752*)

- •

  Dropped support for Python 3.7 (PR *#743*)

### 1.1.1 (2024-02-29)

- •

  Fixed invoking outer pip from user site packages (PR *#746*, fixes issue *#745*)

- •

  Corrected the minimum pip version required to use an outer pip (PR *#746*, fixes issue *#745*)

### 1.1.0 (2024-02-29)

- •

  Use external pip if available instead of installing, speeds up environment setup with virtualenv slightly and venv significantly. (PR *#736*)

- •

  Stopped injecting **wheel** as a build dependency automatically, in the case of missing **pyproject.toml** -- by *@webknjaz*. (PR *#716*)

- •

  Use **importlib\_metadata** on Python \<3.10.2 for bugfixes not present in those CPython standard libraries (not required when bootstrapping) -- by *@GianlucaFicarelli*. (PR *#693*, fixes issue *#692*)

### 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 Python 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.13', 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** (**Literal**\[**'sdist'**, **'wheel'**, **'editable'**\]) -- 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** (**str** \| **None**) -- 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** (**Literal**\[**'sdist'**, **'wheel'**, **'editable'**\]) -- 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** (**Literal**\[**'sdist'**, **'wheel'**, **'editable'**\]) -- 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**\]

  - **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** (**Literal**\[**'sdist'**, **'wheel'**, **'editable'**\]) -- 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**

      **str** \| **None**

    - **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(\*, installer='pip')**

  Bases: *IsolatedEnv*

  Isolated environment which supports several different underlying implementations.

  - **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**

  - **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**

      **Mapping**\[**str**, **str**\] \| **None**

  - **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

You may release the project by following these steps:

- 1\.

  Bump the version **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 --sign 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\.

  Make a release on GitHub or with the **gh** CLI tool. Copy the release notes into the release.

If you have any questions, please look at previous releases and/or ping the other maintainers.

## AUTHOR

Filipe Laíns

## COPYRIGHT

2020, Filipe Laíns