Struct python_packaging::wheel_builder::WheelBuilder

pub struct WheelBuilder { /* fields omitted */ }

Define and build a Python wheel from raw components.

Python wheels are glorified zip files with some special files annotating the Python component therein.

Wheel Level Parameters

Wheels are defined by a distribution (e.g. a Python package name), a version, a compatibility tag, and an optional build tag.

The compatibility tag defines the Python, ABI, and platform compatibility of the wheel. See PEP 425 (https://www.python.org/dev/peps/pep-0425/) for an overview of the components of the compatibility tag and their potential values.

Our default compatibility tag value is py3-none-any. This is appropriate for a wheel containing pure Python code that is compatible with Python 3. If your wheel has binary executables or extension modules, you will want to update the compatibility tag to reflect the appropriate binary compatibility.

.dist-info/WHEEL File

Wheel archives must have a WHEEL file describing the wheel itself.

This file is an email header like MIME document with various well-defined fields.

By default, we will automatically derive a minimal WHEEL file based on parameters passed into Self::new and defaults.

If you want to provide your own WHEEL file, simply define its content by adding a custom file through Self::add_file_dist_info.

.dist-info/METADATA File

Wheel archives must have a METADATA file describing the thing being distributed.

This file is an email header like MIME document with various well-defined fields.

By default, we will automatically derive a minimal METADATA file based on builder state.

If you want to provide your own METADATA file, simply define its content by adding a custom file through Self::add_file_dist_info.

Adding Files

Files in wheels go in 1 of 3 locations:

1. The .dist-info/ directory (added via Self::add_file_dist_info).
2. Special .data/<location>/ directories (added via Self::add_file_data).
3. Everywhere else (added via Self::add_file).

Files in .dist-info/ describe the wheel itself and the entity being distributed.

Files in .data/<location>/ are moved to the indicated <location> when the wheel is installed. <location> here is the name of a Python installation directory, such as purelib (pure Python modules and bytecode), platlib (platform-specific / binary Python extension modules and other binaries), scripts (executable scripts), and more.

Files in all other locations in the archive are not treated specially and are extracted directly to purelib or platlib, depending on the value of Root-Is-Purelib.

Building Wheels

Once you have modified settings and registered files, it is time to create your wheel.

If you want to materialize a .whl file with the proper file name, call Self::write_wheel_into_directory.

If you want to just materialize the zip content of the wheel, call Self::write_wheel_data.

If you want to obtain a collection of all the files that constitute the wheel before zip file generation, call Self::build_file_manifest.

To obtain the name of the .whl file given current settings, call Self::wheel_file_name.

Wheel zip archive content is deterministic for the same builder instance. For separate builder instances, content can be made identical by calling Self::set_modified_time to set the modified time and using identical input settings/files. (The modified time of files in zip files defaults to the time when the builder instance was created, which is obviously not deterministic.)

Validation

This type generally performs little to no validation of input data. It is up to the caller to supply settings and content that constitutes a well-formed wheel.

Supplementary tools like auditwheel (https://pypi.org/project/auditwheel/) can be useful for validating the content of wheels.

Implementations

impl WheelBuilder

pub fn new(distribution: impl ToString, version: impl ToString) -> Self

Create a new instance with a package name and version.

pub fn build_tag(&self) -> Option<&str>

Obtain the build tag for this wheel.

pub fn set_build_tag(&mut self, v: impl ToString)

Set the build tag for this wheel.

pub fn tag(&self) -> String

Obtain the compatibility tag.

pub fn set_tag(&mut self, tag: impl ToString) -> Result<()>

Set the compatibility tag from a value.

pub fn python_tag(&self) -> &str

Obtain the Python component of the compatibility tag.

pub fn set_python_tag(&mut self, v: impl ToString)

Set the Python component of the compatibility tag.

pub fn abi_tag(&self) -> &str

Obtain the ABI component of the compatibility tag.

pub fn set_abi_tag(&mut self, v: impl ToString)

Set the ABI component of the compatibility tag.

pub fn platform_tag(&self) -> &str

Obtain the platform component of the compatibility tag.

pub fn set_platform_tag(&mut self, v: impl ToString)

Set the platform component of the compatibility tag.

pub fn generator(&self) -> &str

Obtain the Generator value for the WHEEL file.

pub fn set_generator(&mut self, v: impl ToString)

Set the Generator value for the WHEEL file.

pub fn root_is_purelib(&self) -> bool

Obtain the Root-Is-Purelib value.

pub fn set_root_is_purelib(&mut self, v: bool)

Set the value for Root-Is-Purelib.

If true, the wheel archive is extracted directly into purelib. If false, it is extracted to platlib.

pub fn modified_time(&self) -> OffsetDateTime

Obtain the modified time for files in the wheel archive.

pub fn set_modified_time(&mut self, v: OffsetDateTime)

Set the modified time for files in the wheel archive.

pub fn add_file(
    &mut self,
    path: impl AsRef<Path>,
    file: impl Into<FileEntry>
) -> Result<()>

Add a file to the wheel at the given path.

No validation of the path is performed.

pub fn add_file_dist_info(
    &mut self,
    path: impl AsRef<Path>,
    file: impl Into<FileEntry>
) -> Result<()>

Add a file to the .dist-info/ directory.

Attempts to add the RECORD file will work. However, the content will be ignored and regenerated as part of wheel building.

pub fn add_file_data(
    &mut self,
    destination: impl ToString,
    path: impl AsRef<Path>,
    file: impl Into<FileEntry>
) -> Result<()>

Add a file to a .data/<destination>/ directory.

destination is the name of a well-known Python installation directory. e.g. {purelib, platlib, headers, scripts, data}. When the wheel is installed, files in these .data/<destination>/ directories are moved to the corresponding path location within the targeted environment.

No validation of the destination values is performed.

pub fn derive_record_file(&self, manifest: &FileManifest) -> Result<String>

Derive the content of a .dist-info/RECORD file in a wheel.

This iterates the contents of a FileManifest and derives digests and other metadata and assembles it into the appropriate format.

pub fn wheel_file_name(&self) -> String

Obtain the file name for this wheel, as currently configured.

The file name of a wheel is of the form {distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl, per PEP 427. Each component is escaped with a regular expression.

pub fn build_file_manifest(&self) -> Result<FileManifest>

Obtain a FileManifest holding the contents of the built wheel.

This function does most of the work to construct the built wheel. It will derive special files like .dist-info/WHEEL and .dist-info/RECORD and join them with files already registered in the builder.

pub fn write_wheel_data(&self, writer: &mut impl Write + Seek) -> Result<()>

Writes the contents of a wheel file to a writable destination.

Wheels are zip files. So this function effectively materializes a zip file to the specified writer.

pub fn write_wheel_into_directory(
    &self,
    directory: impl AsRef<Path>
) -> Result<PathBuf>

Write the wheel file into a given directory, which must exist.

Returns the path of the written wheel file on success.

The wheel file isn’t created until after wheel content generation. So the only scenario in which the file would exist but not have appropriate content is if some kind of I/O error occurred.