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 callingPythonWheelBuilder.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) andversion
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
orpy39
.
- abi_tag¶
(
str
)The ABI tag component of the wheel’s compatibility tag. This should be a value like
none
,abi3
, orcp39
.
- 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’spurelib
directory. IfFalse
, toplatlib
.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
nordirectory
are specified, the file will be materialized in the.dist-info/
directory with the filename given byFileContent.filename
.If
path
is provided, it defines the exact path under.dist-info/
to use.If
directory
is provided, the path is effectivelyos.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 includepurelib
,platlib
,headers
,scripts
,data
.destination
effectively maps different file types to appropriate installation paths on wheel installation.If neither
path
nordirectory
are specified, the file will be materialized in the.data/<destination>>
directory with the filename given byFileContent.filename
.If
path
is provided, it defines the exact path under.data/<destination>
to use.If
directory
is provided, the path is effectivelyos.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
nordirectory
are specified, the file will be materialized in the root directory with the filename given byFileContent.filename
.If
path
is provided, it defines the exact path in the wheel.If
directory
is provided, the path is effectivelyos.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 bypath
) 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.