PythonWheelBuilder

class starlark_tugger.PythonWheelBuilder

The PythonWheelBuilder type facilitates creating Python wheels (.whl files) from settings and file content.

Python wheels are zip files with some well-defined files describing the wheel and the entity that is packaged. See PEP 427 for more on the wheel format and how it works.

By default, new instances target the compatibility tag py3-none-any. This is suitable for a wheel containing pure Python code (.py files) and no binary files. If your wheel contains binary files or is limited in the Python compatibility in any way, you should modify the compatibility tag by setting instance attributes accordingly.

By default, the .dist-info/WHEEL, .dist-info/METADATA, and .dist-info/RECORD files will be derived automatically from settings upon wheel creation. It is possible to provide your own custom file content for the .dist-info/WHEEL and .dist-info/METADATA files by calling PythonWheelBuilder.add_file_dist_info(). A custom .dist-info/RECORD file, if provided, will be ignored.

__init__(distribution: str, version: str) → PythonWheelBuilder

Construct a new instance to produce a wheel for a given distribution (read: Python package) and version of that distribution.

build_tag

(Optional[str])

The build tag for this wheel. This constitutes an extra component in the wheel’s filename and metadata.

Build tags are typically not set on released versions: only for in-development, pre-release versions.

tag

(str)

The compatibility tag for this wheel.

This is equivalent to {python_tag}-{abi_tag}-{platform_tag}.

python_tag

(str)

The Python tag component of the wheel’s compatibility tag. This should be a value like py3 or py39.

abi_tag

(str)

The ABI tag component of the wheel’s compatibility tag. This should be a value like none, abi3, or cp39.

platform_tag

(str)

The platform tag component of the wheel’s compatibility tag. This should be a value like any, linux_x86_64, manylinux2010_x86_64, macosx_10_9_x86_64, etc.

generator

(str)

Describes the thing that constructed the wheel. This value is added to the default .dist-info/WHEEL file produced for this instance.

root_is_purelib

(bool)

The value for the Root-Is-Purelib setting for the wheel.

If True, the wheel is extracted to Python’s purelib directory. If False, to platlib.

This should be set to True if the wheel contains pure Python files (no binary files).

modified_time

(int)

The file modification time for files in wheel zip archives in seconds since UNIX epoch.

Default value is the time this instance was created.

wheel_file_name

(read-only str)

The file name the wheel should be materialized as.

Wheel filenames are derived from the distribution, version, build tag, and compatibility tag.

add_file_dist_info(file: FileContent, path: Optional[str] = None, directory: Optional[str] = None)

Add a FileContent to the wheel in the .dist-info/ directory for the distribution being packaged.

If neither path nor directory are specified, the file will be materialized in the .dist-info/ directory with the filename given by FileContent.filename.

If path is provided, it defines the exact path under .dist-info/ to use.

If directory is provided, the path is effectively os.path.join(directory, file.filename).

add_file_data(destination: str, file: FileContent, path: Optional[str] = None, directory: Optional[str] = None)

Add a FileContent to the wheel in a .data/<destination>/ directory.

destination represents a known Python installation directory. Recognized values include purelib, platlib, headers, scripts, data. destination effectively maps different file types to appropriate installation paths on wheel installation.

If neither path nor directory are specified, the file will be materialized in the .data/<destination>> directory with the filename given by FileContent.filename.

If path is provided, it defines the exact path under .data/<destination> to use.

If directory is provided, the path is effectively os.path.join(directory, file.filename).

add_file(file: FileContent, path: Optional[str] = None, directory: Optional[str] = None)

Add a FileContent to the wheel.

If neither path nor directory are specified, the file will be materialized in the root directory with the filename given by FileContent.filename.

If path is provided, it defines the exact path in the wheel.

If directory is provided, the path is effectively os.path.join(directory, file.filename).

to_file_content() → FileContent

Obtain a FileContent representing the built wheel.

The returned instance will have its FileContent.filename set to the appropriate name for this wheel given current settings. The data in the file should be a zip archive containing a well-formed Python wheel.

write_to_directory(path: str) → str

Write a .whl file to the given directory (specified by path) with the current state in this builder instance.

Returns the path of the written file.

build(target: str) → ResolvedTarget

Build the instance.

This is equivalent to PythonWheelBuilder.write_to_directory(), writing out the wheel to the build directory for the named target.