whey.builder

The actual wheel builder.

Classes:

AbstractBuilder(project_dir, config[, …])

Abstract base class for builders of Python distributions using metadata read from pyproject.toml.

SDistBuilder(project_dir, config[, …])

Builds source distributions using metadata read from pyproject.toml.

WheelBuilder(project_dir, config[, …])

Builds wheel binary distributions using metadata read from pyproject.toml.

class AbstractBuilder(project_dir, config, build_dir=None, out_dir=None, *args, verbose=False, colour=None, **kwargs)[source]

Bases: ABC

Abstract base class for builders of Python distributions using metadata read from pyproject.toml.

Parameters
  • project_dir (PathPlus) – The project to build the distribution for.

  • build_dir (Union[str, Path, PathLike, None]) – The (temporary) build directory. Default <project_dir>/build/.

  • out_dir (Union[str, Path, PathLike, None]) – The output directory. Default <project_dir>/dist/.

  • verbose (bool) – Whether to enable verbose output. Default False.

  • colour (Optional[bool]) – Whether to use coloured output. Default None.

Attributes:

archive_name

The archive name, without the tag

build_dir

The (temporary) build directory.

code_directory

The directory containing the code in the build directory.

colour

Whether to use coloured output.

config

Configuration parsed from pyproject.toml.

default_build_dir

Provides a default for the build_dir argument.

default_out_dir

Provides a default for the out_dir argument.

out_dir

The output directory.

project_dir

The pyproject.toml directory

verbose

Whether to enable verbose output.

Methods:

build()

Build the distribution.

call_additional_hooks()

Subclasses may call this method to give their subclasses an opportunity to run custom code.

clear_build_dir()

Clear the build directory of any residue from previous builds.

copy_additional_files()

Copy additional files to the build directory, as specified in the additional-files key.

copy_source()

Copy source files into the build directory.

get_metadata_map()

Generate the content of the METADATA / PKG-INFO file.

iter_source_files()

Iterate over the files in the source directory.

parse_additional_files(*entries)

Copy additional files to the build directory, by parsing MANIFEST.in-style entries.

parse_authors()

Parse the project.authors and maintainers fields into Author, Maintainer-Email etc.

report_copied(source, target)

Report that a file has been copied into the build directory.

report_removed(removed_file)

Reports the removal of a file from the build directory.

report_written(written_file)

Report that a file has been written to the build directory.

write_license(dest_dir[, dest_filename])

Write the LICENSE file.

write_metadata(metadata_file, metadata_mapping)

Write Core Metadata to the given file.

archive_name

The archive name, without the tag

abstract build()[source]

Build the distribution.

Return type

str

Returns

The filename of the created archive.

build_dir

The (temporary) build directory.

call_additional_hooks()[source]

Subclasses may call this method to give their subclasses an opportunity to run custom code.

For example, the wheel builder calls this as the final step before adding files to the archive, giving an opportunity for subclasses of WheelBuilder to include additional steps without having to override the entire build_wheel() method.

clear_build_dir()[source]

Clear the build directory of any residue from previous builds.

property code_directory

The directory containing the code in the build directory.

Return type

str

colour

Whether to use coloured output.

config

Type:    Dict[str, Any]

Configuration parsed from pyproject.toml.

copy_additional_files()[source]

Copy additional files to the build directory, as specified in the additional-files key.

copy_source()[source]

Copy source files into the build directory.

property default_build_dir

Provides a default for the build_dir argument.

Return type

PathPlus

property default_out_dir

Provides a default for the out_dir argument.

Return type

PathPlus

get_metadata_map()[source]

Generate the content of the METADATA / PKG-INFO file.

Return type

MetadataMapping

iter_source_files()[source]

Iterate over the files in the source directory.

Return type

Iterator[PathPlus]

out_dir

The output directory.

parse_additional_files(*entries)[source]

Copy additional files to the build directory, by parsing MANIFEST.in-style entries.

Parameters

*entries (AdditionalFilesEntry)

parse_authors()[source]

Parse the project.authors and maintainers fields into Author, Maintainer-Email etc.

Return type

Dict[str, str]

Returns

A mapping of field names to values.

Possible field names are Author, Author-Email, Maintainer, and Maintainer-Email.

project_dir

Type:    PathPlus

The pyproject.toml directory

report_copied(source, target)[source]

Report that a file has been copied into the build directory.

The format is:

Copying {source} -> {target.relative_to(self.build_dir)}
Parameters
  • source (Path) – The source file

  • target (Path) – The file in the build directory.

report_removed(removed_file)[source]

Reports the removal of a file from the build directory.

The format is:

Removing {removed_file.relative_to(self.build_dir)}
Parameters

removed_file (Path)

report_written(written_file)[source]

Report that a file has been written to the build directory.

The format is:

Writing {written_file.relative_to(self.build_dir)}
Parameters

written_file (Path)

verbose

Whether to enable verbose output.

write_license(dest_dir, dest_filename='LICENSE')[source]

Write the LICENSE file.

Parameters
  • dest_dir (PathPlus) – The directory to write the file into.

  • dest_filename (str) – The name of the file to write in dest_dir. Default 'LICENSE'.

write_metadata(metadata_file, metadata_mapping)[source]

Write Core Metadata to the given file.

Parameters

metadata_file (PathPlus)

class SDistBuilder(project_dir, config, build_dir=None, out_dir=None, *args, verbose=False, colour=None, **kwargs)[source]

Bases: AbstractBuilder

Builds source distributions using metadata read from pyproject.toml.

Parameters
  • project_dir (PathPlus) – The project to build the distribution for.

  • build_dir (Union[str, Path, PathLike, None]) – The (temporary) build directory. Default <project_dir>/build/sdist.

  • out_dir (Union[str, Path, PathLike, None]) – The output directory. Default <project_dir>/dist.

  • verbose (bool) – Enable verbose output. Default False.

Methods:

build()

Build the source distribution.

build_sdist()

Build the source distribution.

create_sdist_archive()

Create the sdist archive.

write_pyproject_toml()

Write the pyproject.toml file.

write_readme()

Write the README.* file.

Attributes:

code_directory

The directory containing the code in the build and project directories.

default_build_dir

Provides a default for the build_dir argument.

build()

Build the source distribution.

Return type

str

Returns

The filename of the created archive.

build_sdist()[source]

Build the source distribution.

Return type

str

Returns

The filename of the created archive.

property code_directory

The directory containing the code in the build and project directories.

Return type

str

create_sdist_archive()[source]

Create the sdist archive.

Return type

str

Returns

The filename of the created archive.

property default_build_dir

Provides a default for the build_dir argument.

Return type

PathPlus

write_pyproject_toml()[source]

Write the pyproject.toml file.

write_readme()[source]

Write the README.* file.

class WheelBuilder(project_dir, config, build_dir=None, out_dir=None, *args, verbose=False, colour=None, **kwargs)[source]

Bases: AbstractBuilder

Builds wheel binary distributions using metadata read from pyproject.toml.

Parameters
  • project_dir (PathPlus) – The project to build the distribution for.

  • build_dir (Union[str, Path, PathLike, None]) – The (temporary) build directory. Default <project_dir>/build/wheel.

  • out_dir (Union[str, Path, PathLike, None]) – The output directory. Default <project_dir>/dist.

  • verbose (bool) – Enable verbose output. Default False.

Methods:

build()

Build the binary wheel distribution.

build_editable()

Build an editable wheel.

build_wheel()

Build the binary wheel distribution.

create_editables_files()

Generate files with editables for use in a PEP 660 wheel.

create_wheel_archive()

Create the wheel archive.

get_source_epoch()

Returns the parsed value of the SOURCE_DATE_EPOCH environment variable, or None if unset.

write_entry_points()

Write the list of entry points to the wheel, as specified in [project.scripts], [project.gui-scripts] and [project.entry-points]

write_wheel()

Write the metadata to the WHEEL file.

Attributes:

default_build_dir

Provides a default for the build_dir argument.

dist_info

The *.dist-info directory in the build directory.

generator

The value for the Generator field in *.dist-info/WHEEL.

tag

The tag for the wheel.

build()

Build the binary wheel distribution.

Return type

str

Returns

The filename of the created archive.

build_editable()[source]

Build an editable wheel.

An “editable” wheel uses the wheel format not for distribution but as ephemeral communication between the build system and the front end. This avoids having the build backend install anything directly. This wheel must not be exposed to end users, nor cached, nor distributed.

You should use a different build_dir and out_dir to those used for standard wheel builds.

The default implementation of this method does not call copy_source() or copy_additional_files().

Attention

This method has the following additional requirement:

editables>=0.2

This can be installed as follows:

python -m pip install whey[editable]
Return type

str

Returns

The filename of the created archive.

build_wheel()[source]

Build the binary wheel distribution.

Return type

str

Returns

The filename of the created archive.

create_editables_files()[source]

Generate files with editables for use in a PEP 660 wheel.

Attention

This method has the following additional requirement:

editables>=0.2

This can be installed as follows:

python -m pip install whey[editable]
Return type

Iterator[ComparableRequirement]

Returns

An iterator of additional runtime requirements which should be added to the wheel’s METADATA file.

create_wheel_archive()[source]

Create the wheel archive.

Return type

str

Returns

The filename of the created archive.

property default_build_dir

Provides a default for the build_dir argument.

Return type

PathPlus

property dist_info

The *.dist-info directory in the build directory.

Return type

PathPlus

property generator

The value for the Generator field in *.dist-info/WHEEL.

Return type

str

static get_source_epoch()[source]

Returns the parsed value of the SOURCE_DATE_EPOCH environment variable, or None if unset.

See https://reproducible-builds.org/specs/source-date-epoch/ for the specification.

Raises

ValueError – if the value is in an invalid format.

Return type

Optional[datetime]

property tag

The tag for the wheel.

Return type

str

write_entry_points()[source]

Write the list of entry points to the wheel, as specified in [project.scripts], [project.gui-scripts] and [project.entry-points]

write_wheel()[source]

Write the metadata to the WHEEL file.