bork.builder

Bork’s package-building abstraction

This module provides an abstraction for building various kind of artefacts from a Python package, in isolation: * `Built Metadata`_ ; * `Python source distributions`_, a.k.a. sdist ; * `Built distributions`_ in the standard `wheel`_ format ; * :py:mod:`zipapp`s.

It is used by invoking the prepare() `context manager`_, which sets up an isolated build environment and yields a Builder whose methods are then called to build the desired artefacts.

This module is meant to be independent of global state, including: * current working directory ; * pre-existing contents of the artefacts directory.

Example ” .. code:: python with bork.builder.prepare(src_dir, artefacts_dir) as b:

b.build(“wheel”) b.zipapp()

meta = b.metadata() with (artefacts_dir / f”{meta[‘name’]}-{meta[‘version’]}.json”).open(“w”) as meta_file:

json.dump(meta.json, meta_file)

.. _Built distributions: https://packaging.python.org/en/latest/glossary/#term-Built-Distribution
.. _Built Metadata: https://packaging.python.org/en/latest/glossary/#term-Built-Metadata
.. _Python source distributions: https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist
.. _context manager: https://docs.python.org/3/library/stdtypes.html#typecontextmanager
.. _wheel: https://packaging.python.org/en/latest/glossary/#term-Wheel

class bork.builder.Builder

Bases: ABC

abstractmethod build(dist: Literal['sdist', 'wheel'], *, settings: Mapping[str, str | Sequence[str]] = {}) → Path

Build a given distribution of the package

Parameters:

dist – The distribution to be built, must be one of "sdist" or "wheel".
settings – Configuration settings for the build backend.

Returns:

The pathlib.Path to the built artefact.

abstractmethod metadata() → PackageMetadata: Build the package’s wheel metadata

abstractmethod zipapp(main: str | None) → Path

Build a zipapp containing the package and its runtime dependencies

Parameters:: main – The name of a callable used as the zipapp’s entry point. It must be in the form "pkg.mod:func", or None in which case the source tree must contain a __main__.py; see zipapp.create_archive().
Returns:: The pathlib.Path to the executable archive.

exception bork.builder.NeedsBuildError: Bases: Exception

bork.builder.prepare(src: Path, dst: Path) → Iterator[Builder]

Context manager for performing builds in an isolated environments.

Parameters:

src – The pathlib.Path of the source tree to be built.
dst – The pathlib.Path to the directory where to store built artefacts. It will be created if it does not yet exist.

Returns:

A concrete Builder

bork.builder.version_from_bdist_file()