or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-commands.mdindex.mdpackage-conversion.mdtag-management.mdwheelfile-ops.md
tile.json

tessl/pypi-wheel

Command line tool for manipulating wheel files

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/wheel@0.46.x

To install, run

npx @tessl/cli install tessl/pypi-wheel@0.46.0

index.mddocs/

Wheel

A command-line tool and Python library for manipulating Python wheel files (.whl) as defined in PEP 427. Provides utilities for unpacking, repacking, converting legacy package formats, and modifying wheel metadata without requiring the full Python packaging ecosystem.

Package Information

  • Package Name: wheel
  • Language: Python
  • Installation: pip install wheel
  • Python Requirements: >=3.9

Core Imports

import wheel

For working with wheel files programmatically:

from wheel.wheelfile import WheelFile, WheelError

For command functions:

from wheel._commands.unpack import unpack
from wheel._commands.pack import pack
from wheel._commands.convert import convert
from wheel._commands.tags import tags

Deprecated (Issues warning):

# Issues DeprecationWarning - copy functions instead
from wheel.metadata import safe_name, safe_extra, convert_requirements

Setuptools Integration (Deprecated):

# Issues DeprecationWarning - use setuptools.command.bdist_wheel instead
from wheel.bdist_wheel import bdist_wheel

Basic Usage

Command Line Interface

# Unpack a wheel file
wheel unpack my_package-1.0-py3-none-any.whl

# Repack an unpacked wheel directory
wheel pack my_package-1.0/ --dest-dir dist/

# Convert .egg files to wheels
wheel convert *.egg --dest-dir dist/

# Modify wheel tags
wheel tags --python-tag py38.py39 my_package-1.0-py3-none-any.whl

Programming Interface

from wheel.wheelfile import WheelFile

# Read wheel file with hash verification
with WheelFile('package-1.0-py3-none-any.whl', 'r') as wf:
    # Extract a file
    with wf.open('package/__init__.py') as f:
        content = f.read()
    
    # List contents
    for info in wf.filelist:
        print(info.filename)

# Create a new wheel file
with WheelFile('new_package-1.0-py3-none-any.whl', 'w') as wf:
    # Write files from directory
    wf.write_files('build/lib/')
    
    # Write individual file
    wf.writestr('package/data.txt', 'Hello, world!')

Architecture

The wheel package consists of several key components:

  • WheelFile: Core class extending zipfile.ZipFile with wheel-specific functionality and hash verification
  • Command Interface: CLI parser and command functions for wheel manipulation operations
  • Metadata Tools: Utilities for converting between metadata formats (deprecated public API)
  • Platform Support: macOS library analysis tools for deployment target detection (internal)

The design prioritizes reliability through hash verification, reproducible builds via SOURCE_DATE_EPOCH support, and comprehensive wheel standard compliance.

Capabilities

WheelFile Operations

Core functionality for reading, writing, and manipulating wheel archives with integrated hash verification and wheel format compliance.

class WheelFile(ZipFile):
    def __init__(self, file, mode="r", compression=ZIP_DEFLATED): ...
    def open(self, name_or_info, mode="r", pwd=None): ...
    def write_files(self, base_dir): ...
    def writestr(self, zinfo_or_arcname, data, compress_type=None): ...

WheelFile Operations

Command-Line Interface

Complete CLI for wheel manipulation including unpack, repack, convert, and tag modification operations.

def main() -> int: ...
def parser() -> argparse.ArgumentParser: ...

Command-Line Interface

Package Conversion

Convert legacy Python package formats (.egg files and Windows installers) to modern wheel format.

def convert(files: list[str], dest_dir: str, verbose: bool) -> None: ...

Package Conversion

Wheel Tag Management

Modify wheel filename tags for Python version, ABI, and platform compatibility without rebuilding.

def tags(
    wheel: str,
    python_tags: str | None = None,
    abi_tags: str | None = None,
    platform_tags: str | None = None,
    build_tag: str | None = None,
    remove: bool = False,
) -> str: ...

Wheel Tag Management

Setuptools Integration (Deprecated)

Legacy setuptools bdist_wheel command integration. This functionality has been moved to setuptools.

# Deprecated - raises ImportError if setuptools < v70.1
from wheel.bdist_wheel import bdist_wheel

Note: The wheel.bdist_wheel module issues a DeprecationWarning and has been removed. Use setuptools.command.bdist_wheel instead.

Types

class WheelError(Exception):
    """Exception raised for wheel-related errors."""
    pass

WHEEL_INFO_RE: re.Pattern[str]
"""Regex pattern for parsing wheel filenames."""

MINIMUM_TIMESTAMP: int
"""Minimum timestamp for wheel files (315532800 = 1980-01-01 00:00:00 UTC)"""