0
# Wheel
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: wheel
7
- **Language**: Python
8
- **Installation**: `pip install wheel`
9
- **Python Requirements**: >=3.9
10
11
## Core Imports
12
13
```python
14
import wheel
15
```
16
17
For working with wheel files programmatically:
18
19
```python
20
from wheel.wheelfile import WheelFile, WheelError
21
```
22
23
For command functions:
24
25
```python
26
from wheel._commands.unpack import unpack
27
from wheel._commands.pack import pack
28
from wheel._commands.convert import convert
29
from wheel._commands.tags import tags
30
```
31
32
**Deprecated (Issues warning):**
33
34
```python
35
# Issues DeprecationWarning - copy functions instead
36
from wheel.metadata import safe_name, safe_extra, convert_requirements
37
```
38
39
**Setuptools Integration (Deprecated):**
40
41
```python
42
# Issues DeprecationWarning - use setuptools.command.bdist_wheel instead
43
from wheel.bdist_wheel import bdist_wheel
44
```
45
46
## Basic Usage
47
48
### Command Line Interface
49
50
```bash
51
# Unpack a wheel file
52
wheel unpack my_package-1.0-py3-none-any.whl
53
54
# Repack an unpacked wheel directory
55
wheel pack my_package-1.0/ --dest-dir dist/
56
57
# Convert .egg files to wheels
58
wheel convert *.egg --dest-dir dist/
59
60
# Modify wheel tags
61
wheel tags --python-tag py38.py39 my_package-1.0-py3-none-any.whl
62
```
63
64
### Programming Interface
65
66
```python
67
from wheel.wheelfile import WheelFile
68
69
# Read wheel file with hash verification
70
with WheelFile('package-1.0-py3-none-any.whl', 'r') as wf:
71
# Extract a file
72
with wf.open('package/__init__.py') as f:
73
content = f.read()
74
75
# List contents
76
for info in wf.filelist:
77
print(info.filename)
78
79
# Create a new wheel file
80
with WheelFile('new_package-1.0-py3-none-any.whl', 'w') as wf:
81
# Write files from directory
82
wf.write_files('build/lib/')
83
84
# Write individual file
85
wf.writestr('package/data.txt', 'Hello, world!')
86
```
87
88
## Architecture
89
90
The wheel package consists of several key components:
91
92
- **WheelFile**: Core class extending zipfile.ZipFile with wheel-specific functionality and hash verification
93
- **Command Interface**: CLI parser and command functions for wheel manipulation operations
94
- **Metadata Tools**: Utilities for converting between metadata formats (deprecated public API)
95
- **Platform Support**: macOS library analysis tools for deployment target detection (internal)
96
97
The design prioritizes reliability through hash verification, reproducible builds via SOURCE_DATE_EPOCH support, and comprehensive wheel standard compliance.
98
99
## Capabilities
100
101
### WheelFile Operations
102
103
Core functionality for reading, writing, and manipulating wheel archives with integrated hash verification and wheel format compliance.
104
105
```python { .api }
106
class WheelFile(ZipFile):
107
def __init__(self, file, mode="r", compression=ZIP_DEFLATED): ...
108
def open(self, name_or_info, mode="r", pwd=None): ...
109
def write_files(self, base_dir): ...
110
def writestr(self, zinfo_or_arcname, data, compress_type=None): ...
111
```
112
113
[WheelFile Operations](./wheelfile-ops.md)
114
115
### Command-Line Interface
116
117
Complete CLI for wheel manipulation including unpack, repack, convert, and tag modification operations.
118
119
```python { .api }
120
def main() -> int: ...
121
def parser() -> argparse.ArgumentParser: ...
122
```
123
124
[Command-Line Interface](./cli-commands.md)
125
126
### Package Conversion
127
128
Convert legacy Python package formats (.egg files and Windows installers) to modern wheel format.
129
130
```python { .api }
131
def convert(files: list[str], dest_dir: str, verbose: bool) -> None: ...
132
```
133
134
[Package Conversion](./package-conversion.md)
135
136
### Wheel Tag Management
137
138
Modify wheel filename tags for Python version, ABI, and platform compatibility without rebuilding.
139
140
```python { .api }
141
def tags(
142
wheel: str,
143
python_tags: str | None = None,
144
abi_tags: str | None = None,
145
platform_tags: str | None = None,
146
build_tag: str | None = None,
147
remove: bool = False,
148
) -> str: ...
149
```
150
151
[Wheel Tag Management](./tag-management.md)
152
153
### Setuptools Integration (Deprecated)
154
155
Legacy setuptools bdist_wheel command integration. This functionality has been moved to setuptools.
156
157
```python { .api }
158
# Deprecated - raises ImportError if setuptools < v70.1
159
from wheel.bdist_wheel import bdist_wheel
160
```
161
162
**Note**: The `wheel.bdist_wheel` module issues a DeprecationWarning and has been removed. Use `setuptools.command.bdist_wheel` instead.
163
164
## Types
165
166
```python { .api }
167
class WheelError(Exception):
168
"""Exception raised for wheel-related errors."""
169
pass
170
171
WHEEL_INFO_RE: re.Pattern[str]
172
"""Regex pattern for parsing wheel filenames."""
173
174
MINIMUM_TIMESTAMP: int
175
"""Minimum timestamp for wheel files (315532800 = 1980-01-01 00:00:00 UTC)"""
176
```