0
# Command-Line Interface
1
2
Complete command-line interface for wheel manipulation operations. Provides subcommands for unpacking, repacking, converting, and modifying wheel files.
3
4
## Capabilities
5
6
### Main CLI Entry Point
7
8
Primary entry point for the wheel command-line tool with subcommand dispatching. Installed as console script `wheel = "wheel._commands:main"`.
9
10
```python { .api }
11
def main() -> int:
12
"""
13
Main CLI entry point.
14
15
Returns:
16
Exit code (0 for success, 1 for error)
17
"""
18
19
def parser() -> argparse.ArgumentParser:
20
"""
21
Create argument parser for CLI commands.
22
23
Returns:
24
Configured ArgumentParser with all subcommands
25
"""
26
```
27
28
### Unpack Command
29
30
Extract wheel contents to a directory for inspection or modification.
31
32
```python { .api }
33
def unpack(path: str, dest: str = ".") -> None:
34
"""
35
Unpack a wheel file to a directory.
36
37
Parameters:
38
- path: Path to wheel file
39
- dest: Destination directory (default: current directory)
40
41
Creates directory: {dest}/{name}-{version}/
42
Preserves file permissions from wheel archive
43
"""
44
```
45
46
#### CLI Usage
47
48
```bash
49
# Unpack wheel to current directory
50
wheel unpack package-1.0-py3-none-any.whl
51
52
# Unpack to specific directory
53
wheel unpack package-1.0-py3-none-any.whl --dest /tmp/wheels/
54
55
# Short form
56
wheel unpack package-1.0-py3-none-any.whl -d /tmp/wheels/
57
```
58
59
### Pack Command
60
61
Repack a previously unpacked wheel directory into a new wheel file.
62
63
```python { .api }
64
def pack(directory: str, dest_dir: str, build_number: str | None) -> None:
65
"""
66
Repack wheel from unpacked directory.
67
68
Parameters:
69
- directory: Path to unpacked wheel directory
70
- dest_dir: Destination directory for new wheel
71
- build_number: Optional build tag to set/modify
72
73
Raises:
74
- WheelError: If no .dist-info directory found or multiple found
75
- WheelError: If WHEEL file has no tags
76
"""
77
78
def compute_tagline(tags: list[str]) -> str:
79
"""
80
Compute tagline from list of wheel tags.
81
82
Parameters:
83
- tags: List of tag strings (format: python-abi-platform)
84
85
Returns:
86
Combined tagline (format: python.abi.platform)
87
"""
88
```
89
90
#### CLI Usage
91
92
```bash
93
# Repack wheel directory
94
wheel pack package-1.0/ --dest-dir dist/
95
96
# Set build number
97
wheel pack package-1.0/ --dest-dir dist/ --build-number 20231201
98
99
# Short form
100
wheel pack package-1.0/ -d dist/
101
```
102
103
### Convert Command
104
105
Convert legacy package formats (.egg files and Windows installers) to wheel format.
106
107
```python { .api }
108
def convert(files: list[str], dest_dir: str, verbose: bool) -> None:
109
"""
110
Convert .egg files and Windows installers to wheels.
111
112
Parameters:
113
- files: List of file patterns to convert
114
- dest_dir: Output directory for converted wheels
115
- verbose: Print conversion progress
116
117
Supports:
118
- .egg files (zipped and directory)
119
- .exe Windows installers (bdist_wininst)
120
"""
121
```
122
123
#### CLI Usage
124
125
```bash
126
# Convert all .egg files in current directory
127
wheel convert *.egg --dest-dir wheels/
128
129
# Convert specific files with verbose output
130
wheel convert package-1.0-py2.7.egg --dest-dir wheels/ --verbose
131
132
# Short form
133
wheel convert *.egg -d wheels/ -v
134
```
135
136
### Tags Command
137
138
Modify wheel tags (Python version, ABI, platform) without rebuilding the package.
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
Modify wheel tags and create new wheel file.
151
152
Parameters:
153
- wheel: Path to wheel file
154
- python_tags: Python version tags (e.g., "py38.py39")
155
- abi_tags: ABI tags (e.g., "cp38.cp39")
156
- platform_tags: Platform tags (e.g., "linux_x86_64.macosx_10_9_x86_64")
157
- build_tag: Build tag (must start with digit)
158
- remove: Delete original wheel file
159
160
Returns:
161
New wheel filename
162
163
Tag modification rules:
164
- Tags starting with '+' are appended
165
- Tags starting with '-' are removed
166
- Other tags replace existing tags
167
- Tags can be dot-separated for multiple values
168
"""
169
```
170
171
#### CLI Usage
172
173
```bash
174
# Add Python versions
175
wheel tags --python-tag +py311 package-1.0-py3-none-any.whl
176
177
# Replace platform tags
178
wheel tags --platform-tag linux_x86_64.macosx_10_9_x86_64 package.whl
179
180
# Remove specific tags
181
wheel tags --python-tag -py37 package.whl
182
183
# Multiple modifications with build tag
184
wheel tags --python-tag py39.py310 --build 20231201 package.whl
185
186
# Remove original file
187
wheel tags --python-tag py311 --remove package.whl
188
```
189
190
### Version Command
191
192
Display wheel package version information.
193
194
```python { .api }
195
def version_f(args: argparse.Namespace) -> None:
196
"""
197
Print wheel version and exit.
198
"""
199
```
200
201
#### CLI Usage
202
203
```bash
204
wheel version
205
# Output: wheel 0.46.1
206
```
207
208
### Help Command
209
210
Display command help information.
211
212
#### CLI Usage
213
214
```bash
215
wheel help
216
# Displays full help information for all commands
217
```
218
219
### Utility Functions
220
221
Helper functions for CLI argument parsing and validation.
222
223
```python { .api }
224
def parse_build_tag(build_tag: str) -> str:
225
"""
226
Validate and parse build tag string.
227
228
Parameters:
229
- build_tag: Build tag string
230
231
Returns:
232
Validated build tag
233
234
Raises:
235
- ArgumentTypeError: If tag doesn't start with digit or contains '-'
236
"""
237
```
238
239
### Command Handler Functions
240
241
Internal functions that bridge CLI arguments to implementation functions.
242
243
```python { .api }
244
def unpack_f(args: argparse.Namespace) -> None:
245
"""Handler for unpack command."""
246
247
def pack_f(args: argparse.Namespace) -> None:
248
"""Handler for pack command."""
249
250
def convert_f(args: argparse.Namespace) -> None:
251
"""Handler for convert command."""
252
253
def tags_f(args: argparse.Namespace) -> None:
254
"""Handler for tags command."""
255
256
def version_f(args: argparse.Namespace) -> None:
257
"""Handler for version command."""
258
259
def help_f(args: argparse.Namespace) -> None:
260
"""Handler for help command."""
261
```
262
263
### Usage Examples
264
265
#### Programmatic CLI Access
266
267
```python
268
from wheel._commands import main, parser
269
import sys
270
271
# Run CLI programmatically
272
sys.argv = ['wheel', 'unpack', 'package-1.0-py3-none-any.whl']
273
exit_code = main()
274
275
# Parse arguments without executing
276
p = parser()
277
args = p.parse_args(['pack', 'unpacked-wheel/', '-d', 'dist/'])
278
print(f"Command: {args.func.__name__}")
279
print(f"Directory: {args.directory}")
280
```
281
282
#### Error Handling
283
284
```python
285
from wheel._commands import main
286
from wheel.wheelfile import WheelError
287
import sys
288
289
try:
290
sys.argv = ['wheel', 'unpack', 'invalid-wheel.whl']
291
exit_code = main()
292
except WheelError as e:
293
print(f"Wheel error: {e}")
294
sys.exit(1)
295
```
296
297
## Types
298
299
```python { .api }
300
import argparse
301
from typing import Literal
302
303
class ArgumentTypeError(Exception):
304
"""Exception raised for invalid command-line arguments."""
305
pass
306
307
# CLI Help Text
308
TAGS_HELP: str
309
"""
310
Help text for the tags command explaining tag modification syntax.
311
"""
312
```