Package: pyproject-installer
pyproject-installerThis tool is intended for build, install, run or management of dependencies
sources of Python project in source tree within network-isolated environments.DescriptionSupported platform: Unix.Currently, platform-specific parts:pipe is used for calling build backend hooks in subprocessscript wrappers are generated only for Unix systemsOS environment of this project is anetwork-isolatedenvironment, which
implies that a local loopback interface is the only available network
interface. Thus,pyproject-installerdoesn't perform any network activity
(e.g. it doesn't install build dependencies specified via PEP518 configuration
or PEP517'sget_requires_for_*hooks). This also makes it difficult or
impossible to create an isolated Python environment for calling build backend
hooks specified in PEP517, therefore, current Python environment is the only
available environment.Source tree can be either checkout of VCS or unpacked source distribution.An installation result will be consumed by external tool like RPM.The main usage ofpyproject-installerlooks like:external tool => (pyproject-installer: build => install to destdir) => external tool packages destdirTherefore, there is no need to build intermediate source distribution for
build wheel, onlybuild_wheelbackend's hook is actually called.Note: an installation into Python virtual environment is also supported, but
only the manual uninstallation of such packages is possible (tools should
refuse an uninstallation of distribution with missingRECORDfile).Only stdlib or vendored dependencies can be used in runtime for bootstrapping
any Python project.Current vendored packages:tomli(used for parsingpyproject.tomlconfiguration file).
Note:tomliis the part of stdlib since Python 3.11.packaging(used for parsing PEP508 dependencies)Installation of build dependencies is up to the caller.These dependencies of Python projects are managed externally with system
package managers likeaptordnf.External sourceof upstream's
dependencies may be used for provision of formatted list of dependencies to external tools.There is no post-installation bytecompilation.PEP427 says that wheel installers should compile any installed .py to .pyc.
External tools like RPM already provide Python bytecompilation means, which
compile for multiple optimization levels at a time. No point to compile
modules twice.RECORD file is not installed.https://peps.python.org/pep-0627/#optional-record-file:Specifically, the RECORD file is unnecessary when projects are installed by
a Linux system packaging system, which has its own ways to keep track of
files, uninstall them or check their integrity. Having to keep a RECORD file
in sync with the disk and the system package database would be unreasonably
fragile, and no RECORD file is better than one that does not correspond to
reality.INSTALLER file is not installed by default(optional).https://peps.python.org/pep-0627/#optional-installer-file:The INSTALLER file is also made optional, and specified to be used for
informational purposes only. It is still a single-line text file containing
the name of the installer.https://packaging.python.org/en/latest/specifications/recording-installed-packages/#the-installer-file:This value should be used for informational purposes only. For example, if a
tool is asked to uninstall a project but finds no RECORD file, it may
suggest that the tool named in INSTALLER may be able to do the
uninstallation.Built distribution can be checked within Python virtual environment with the
help ofruncommand.Project's dependencies sources can be managed (i.e. stored, synced, verified
or evaluated) with the help ofdepscommand.UsageBuildBuild project from source tree in current Python environment according to
PEP517. This doesn't trigger installation of project's build dependencies.python -m pyproject_installer buildBuild positional arguments:description: source directorydefault: current working directoryexample: python -m pyproject_installer build .Build options:name: --outdir OUTDIR, -o OUTDIRdescription: output directory for built wheeldefault: {srcdir}/distexample: python -m pyproject_installer build --outdir ~/outdirUpon successful buildpyproject_installerdumps wheel filename into{OUTDIR}/.wheeltracker.name: --sdistdescription: build source distribution(sdist) instead of binary
one(wheel).note: installer supports only wheel format.default: build wheelexample: python -m pyproject_installer build --sdistname: --backend-config-settings BACKEND_CONFIG_SETTINGSdescription: ad-hoc configuration for build backend as dumped JSON dictionarydefault: None

Example of passingconfig_settingsfor setuptools>=64.0.0:
python -m pyproject_installer build --backend-config-settings='{"--build-option": ["--python-tag=sometag", "--build-number=123"]}'

Example of passingconfig_settingsfor setuptools<64.0.0:
python -m pyproject_installer build --backend-config-settings='{"--global-option": ["--python-tag=sometag", "--build-number=123"]}'

Example of passingconfig_settingsfor pdm backend:
python -m pyproject_installer build --backend-config-settings='{"--python-tag": "sometag"}'InstallInstall project built in wheel format. This doesn't trigger installation of
project's runtime dependencies.python -m pyproject_installer installInstall positional arguments:description: wheel file to installdefault: contructed as directory {cwd}/dist and wheel filename read from
{cwd}/dist/.wheeltrackerexample: python -m pyproject_installer install wheel.whlInstall options:name: --destdir DESTDIR, -d DESTDIRdescription: Wheel installation root will be prepended with destdirdefault: /example: python -m pyproject_installer install --destdir ~/destdirname: --installer INSTALLERdescription: Name of installer to be recorded in dist-info/INSTALLERdefault: None, INSTALLER will be omittedexample: python -m pyproject_installer install --installer custom_installername: --no-strip-dist-infodescription: Don't strip dist-info. By default onlyMETADATAandentry_points.txtfiles are allowed indist-infodirectory.note:RECORDis unconditionally filtered out.default: Falseexample: python -m pyproject_installer install --no-strip-dist-infoRunRun command within Python virtual environment that has access to system and user
site packages, their console scripts and installed built package.python -m pyproject_installer runRun positional arguments:description: command to run within virtual environmentexample: python -m pyproject_installer run pytestDash note:https://docs.python.org/3/library/argparse.html#arguments-containingIf you have positional arguments that must begin with - and don't look like
negative numbers, you can insert the pseudo-argument '--' which tellsparse_args()that everything after that is a positional argument:python -m pyproject_installer run -- pytest -vraRun options:name: --wheel WHEELdescription: wheel file to install into virtual environmentdefault: contructed as directory {cwd}/dist and wheel filename read from
{cwd}/dist/.wheeltrackerexample: python -m pyproject_installer run --wheel wheel.whl pytestNote: venv's directory name is.run_venv.Management of dependencies sourcesCollect PEP508 requirements from different sources, store and evaluate
them in Python environment.python -m pyproject_installer deps --helpCommon deps options:name: --depsconfigdescription: configuration file to usedefault: {cwd}/pyproject_deps.jsonexample: python -m pyproject_installer deps --depsconfig foo.jsondeps subcommandsname: showdescription: show configuration and data of dependencies's sourcesexample: python -m pyproject_installer deps show --helpPositional arguments:description: source namesdefault: allexample: python -m pyproject_installer deps show buildname: adddescription: configure source of Python dependencies. Supported sources: standardized formats like PEP517, PEP518 or core metadata are fully supported, while tool-specific formats like pip, tox, poetry, hatch or pdm have limited support.example: python -m pyproject_installer deps add --helpPositional arguments:description: source namedescription: source typechoice: pep517, pep518, metadata, pip_reqfile, poetry, tox, hatch, pdmdescription: specific configuration options for sourcedefault: []examples:
Configuration of source ofPEP518dependencies:
python -m pyproject_installer deps add build_pep518 pep518

Configuration of source ofPEP517dependencies:
python -m pyproject_installer deps add build_pep517 pep517

Configuration of source ofmetadatadependencies:
python -m pyproject_installer deps add runtime metadata

Configuration of source ofpiprequirements:
python -m pyproject_installer deps add check pip_reqfile requirements.txt

Configuration of source oftoxrequirements:
python -m pyproject_installer deps add check tox tox.ini testenv

Configuration of source ofpoetryrequirements:
python -m pyproject_installer deps add check poetry dev

Configuration of source ofhatchrequirements:
python -m pyproject_installer deps add check hatch hatch.toml test

Configuration of source ofpdmrequirements:
python -m pyproject_installer deps add check pdm testname: syncdescription: sync stored requirements to configured sourcesexample: python -m pyproject_installer deps sync --helpPositional arguments:description: source namesdefault: allexample: python -m pyproject_installer deps sync buildOptions:name: --verifydescription: Sync sources, but print diff and exits with code 4 if the sources were unsynceddefault: only syncexample: python -m pyproject_installer deps sync --verify buildname: evaldescription: evaluate stored requirements according to PEP508 in current Python environment and print them to stdout in PEP508 format (by default) or specified oneexample: python -m pyproject_installer deps eval --helpPositional arguments:description: source namesdefault: allexample: python -m pyproject_installer deps eval buildOptions:name: --depformatdescription: format of dependency to print. Supported substitutions: $name - project's name, $nname - PEP503 normalized project's name, $fextra - project's extras (expanded first with --depformatextra)default: PEP508 formatexample: python -m pyproject_installer deps eval build --depformat='python3-$nn'name: --depformatextradescription: format of extras to print (one extra of dependencies per line). Result is expanded in format specified by --depformat as $fextra. Supported substitutions: $extradefault: ''example: python -m pyproject_installer deps eval build --depformat='python3-$nn$fextra' --depformatextra='+$extra'name: --extradescription: PEP508 'extra' marker to evaluate withdefault: Noneexample: python -m pyproject_installer deps eval build --extra testsname: --excludedescription: regexes patterns, exclude requirement having PEP503-normalized name that matches one of these patternsdefault: []example: python -m pyproject_installer deps eval build --exclude types- pytest-covname: deletedescription: deconfigure source of Python dependenciesexample: python -m pyproject_installer deps delete --helpPositional arguments:description: source nameexample: python -m pyproject_installer deps delete buildComparison with other toolspyproject-installerconsists of builder and installer, both provideonly necessaryandsufficientfunctionality.builderFunctionally, today's builder is similar tobuild.The key differences are:highly specialized defaults (seedescription)highly specialized features to drop extra runtime dependencies likepep517. No point to vendorpep517to call onlybuild_wheelbackend hook
in subprocess.installerFunctionally, today's installer is similar toinstaller.The key differences are:highly specialized defaults and features (seedescription)Both can be replaced withpip. But again, no
point to use full-featured complexpipto highly specialized task.BootstrapThere is a self-hosted build backend to avoid dependency on any other backend.For example, bootstrap can be done as:export PYTHONPATH=$(pwd)/srcpython -m pyproject_installer buildpython -m pyproject_installer install --destdir=/rootdirTestsunit tests can be run as:pytest tests/unitintegration tests (require internet connection andgittool) can be run as:pytest tests/integrationLicenseDistributed under the terms of theMITlicense,pyproject-installeris
free and open source software.