API to call PEP 517 hooks for building Python packages https://pep517.readthedocs.io/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Thomas Kluyver 44780f6fb2 Start writing release notes for 0.11 1 year ago
.github/workflows Add job to publish packages on PyPI 1 year ago
doc Start writing release notes for 0.11 1 year ago
pep517 Bump version: 0.9.1 → 0.10.0 2 years ago
tests Add comment 2 years ago
.bumpversion.cfg Bump version: 0.9.1 → 0.10.0 2 years ago
.gitignore Add tests for #104 2 years ago
LICENSE Packaging with flit 5 years ago
README.rst Explain deprecated parts of API in README 2 years ago
RELEASE.rst Add release instructions. Fixes #29. 4 years ago
appveyor.yml Add tox for testing 4 years ago
dev-requirements.txt tests: remove dependency on mock for python3 2 years ago
issue_template.md Clarify the issue template 2 years ago
pyproject.toml Allow building with Flit 3.x 2 years ago
pytest.ini Test modules with flake8. Ref #21. 4 years ago
tox.ini Flit no longer needs pygments to validate rst 2 years ago

README.rst

API to call PEP 517 hooks

PEP 517 specifies a standard API for systems which build Python packages.

This package contains wrappers around the hooks specified by PEP 517. It provides:

  • A mechanism to call the hooks in a subprocess, so they are isolated from the current process.
  • Fallbacks for the optional hooks, so that frontends can call the hooks without checking which are defined.

Run the tests with pytest or tox.

Usage—you are responsible for ensuring build requirements are available:

import os
import toml
from pep517.wrappers import Pep517HookCaller

src = 'path/to/source'  # Folder containing 'pyproject.toml'
with open(os.path.join(src, 'pyproject.toml')) as f:
    build_sys = toml.load(f)['build-system']

print(build_sys['requires'])  # List of static requirements
# The caller is responsible for installing these and running the hooks in
# an environment where they are available.

hooks = Pep517HookCaller(
    src, 
    build_backend=build_sys['build-backend'],
    backend_path=build_sys.get('backend-path'),
)

config_options = {}   # Optional parameters for backend
# List of dynamic requirements:
print(hooks.get_requires_for_build_wheel(config_options))
# Again, the caller is responsible for installing these build requirements

destination = 'also/a/folder'
whl_filename = hooks.build_wheel(destination, config_options)
assert os.path.isfile(os.path.join(destination, whl_filename))

Deprecated high-level

For now, pep517 also contains higher-level functions which install the build dependencies into a temporary environment and build a wheel/sdist using them. This is a rough implementation, e.g. it does not do proper build isolation. The PyPA build project is recommended as an alternative, although it's still quite young in October 2020. This layer of functionality in pep517 is now deprecated, but won't be removed for some time, as there is code relying on it.

High level usage, with build requirements handled:

import os
from pep517.envbuild import build_wheel, build_sdist

src = 'path/to/source'  # Folder containing 'pyproject.toml'
destination = 'also/a/folder'
whl_filename = build_wheel(src, destination)
assert os.path.isfile(os.path.join(destination, whl_filename))

targz_filename = build_sdist(src, destination)
assert os.path.isfile(os.path.join(destination, targz_filename))

To test the build backend for a project, run in a system shell:

python3 -m pep517.check path/to/source  # source dir containing pyproject.toml

To build a backend into source and/or binary distributions, run in a shell:

python -m pep517.build path/to/source  # source dir containing pyproject.toml

All of this high-level functionality is deprecated.