0
# Command Classes
1

2
Setuptools command system providing extensible build, installation, and distribution functionality through specialized command classes for every aspect of Python package lifecycle management. These commands can be executed via setup.py or used programmatically.
3

4
## Capabilities
5

6
### Build Commands
7

8
Commands for building Python packages and their components, including modules, extensions, and libraries.
9

10
```python { .api }
11
class build(Command):
12
    """
13
    Enhanced build command that coordinates all build operations.
14

15
    Builds all components of the package including Python modules,
16
    C extensions, and data files.
17

18
    Options:
19
    - build-base: Base directory for build files
20
    - build-lib: Directory for built Python modules
21
    - build-scripts: Directory for built scripts
22
    - build-temp: Directory for temporary build files
23
    - debug: Compile with debugging information
24
    - force: Force rebuild of everything
25
    - executable: Path to Python interpreter
26
    """
27

28
class build_py(Command):
29
    """
30
    Enhanced Python module builder with package discovery.
31

32
    Builds pure Python modules and packages, handling package
33
    data and namespace packages.
34

35
    Options:
36
    - build-lib: Directory to build modules
37
    - compile: Compile .py to .pyc files
38
    - optimize: Optimization level for .pyc files
39
    - force: Force rebuild
40
    """
41

42
class build_ext(Command):
43
    """
44
    Enhanced C/C++ extension builder with Cython support.
45

46
    Builds C/C++ extension modules with enhanced features like
47
    Cython compilation and improved error handling.
48

49
    Options:
50
    - build-lib: Directory for built extensions
51
    - build-temp: Directory for temporary files
52
    - inplace: Build extensions in-place
53
    - include-dirs: Include directories
54
    - library-dirs: Library directories
55
    - libraries: Libraries to link against
56
    - debug: Build with debug information
57
    - force: Force rebuild
58
    - compiler: Compiler to use
59
    - swig: Path to SWIG executable
60
    - swig-opts: SWIG options
61
    - user: Install to user site-packages
62
    - parallel: Number of parallel build jobs
63
    """
64

65
class build_clib(Command):
66
    """
67
    C library builder for building static libraries.
68

69
    Builds C/C++ libraries that can be used by extensions
70
    in the same package.
71

72
    Options:
73
    - build-clib: Directory for built libraries
74
    - build-temp: Directory for temporary files
75
    - include-dirs: Include directories
76
    - libraries: Library definitions
77
    - debug: Build with debug information
78
    - force: Force rebuild
79
    - compiler: Compiler to use
80
    """
81
```
82

83
### Distribution Commands
84

85
Commands for creating distributable packages in various formats.
86

87
```python { .api }
88
class bdist_wheel(Command):
89
    """
90
    Build wheel distribution (.whl files).
91

92
    Creates binary distribution wheels that can be installed
93
    quickly without compilation.
94

95
    Options:
96
    - bdist-dir: Temporary directory for building
97
    - dist-dir: Directory for final wheel files
98
    - skip-build: Skip build step
99
    - relative: Force relative paths in wheel
100
    - owner: Owner for files in wheel
101
    - group: Group for files in wheel
102
    - universal: Create universal wheel
103
    - python-tag: Python tag for wheel filename
104
    - plat-name: Platform name for wheel
105
    """
106

107
class bdist_egg(Command):
108
    """
109
    Build egg distribution (legacy format).
110

111
    Creates .egg files for distribution. This format is
112
    largely superseded by wheels.
113

114
    Options:
115
    - bdist-dir: Temporary directory for building
116
    - dist-dir: Directory for final egg files
117
    - skip-build: Skip build step
118
    - keep-temp: Keep temporary files
119
    - exclude-source-files: Don't include source in egg
120
    """
121

122
class sdist(Command):
123
    """
124
    Enhanced source distribution builder.
125

126
    Creates source distributions (.tar.gz) with improved
127
    file discovery and MANIFEST.in support.
128

129
    Options:
130
    - template: MANIFEST template file
131
    - manifest: MANIFEST file
132
    - use-defaults: Include default files
133
    - prune: Remove files/directories
134
    - manifest-only: Only regenerate MANIFEST
135
    - force-manifest: Force MANIFEST regeneration
136
    - formats: Archive formats to create
137
    - keep-temp: Keep temporary directory
138
    - dist-dir: Directory for distributions
139
    - owner: Owner for files
140
    - group: Group for files
141
    """
142

143
class bdist_rpm(Command):
144
    """
145
    Build RPM distribution for Red Hat-based systems.
146

147
    Creates .rpm packages for installation on Red Hat,
148
    CentOS, Fedora, and similar systems.
149

150
    Options:
151
    - bdist-base: Base directory for building
152
    - rpm-base: Base directory for RPM building
153
    - dist-dir: Directory for final RPM files
154
    - python: Python executable path
155
    - fix-python: Fix Python shebangs
156
    - spec-only: Only create .spec file
157
    - source-only: Only create source RPM
158
    - binary-only: Only create binary RPM
159
    - use-bzip2: Use bzip2 compression
160
    - distribution-name: Distribution name
161
    - group: RPM package group
162
    - release: RPM release number
163
    - serial: RPM serial number
164
    - vendor: RPM vendor
165
    - packager: RPM packager
166
    - doc-files: Documentation files
167
    - changelog: RPM changelog
168
    - icon: RPM icon file
169
    - provides: RPM provides
170
    - requires: RPM requires
171
    - conflicts: RPM conflicts
172
    - build-requires: RPM build requires
173
    - obsoletes: RPM obsoletes
174
    - keep-temp: Keep temporary files
175
    - no-keep-temp: Don't keep temporary files
176
    - use-rpm-opt-flags: Use RPM optimization flags
177
    - no-autoreq: Disable automatic dependency detection
178
    - force-arch: Force architecture
179
    """
180
```
181

182
### Installation Commands
183

184
Commands for installing packages and their components in various modes.
185

186
```python { .api }
187
class install(Command):
188
    """
189
    Enhanced install command with improved path handling.
190

191
    Installs the package with setuptools enhancements like
192
    automatic script generation and entry point handling.
193

194
    Options:
195
    - home: Install to specific home directory
196
    - prefix: Install prefix
197
    - user: Install to user site-packages
198
    - root: Install root directory
199
    - install-base: Base installation directory
200
    - install-platbase: Platform-specific installation base
201
    - install-lib: Installation directory for modules
202
    - install-platlib: Installation directory for platform-specific modules
203
    - install-purelib: Installation directory for pure Python modules
204
    - install-headers: Installation directory for headers
205
    - install-scripts: Installation directory for scripts
206
    - install-data: Installation directory for data files
207
    - compile: Compile .py files
208
    - optimize: Optimization level
209
    - force: Force installation
210
    - skip-build: Skip build step
211
    - record: Record installed files
212
    - single-version-externally-managed: Single version mode
213
    """
214

215
class develop(Command):
216
    """
217
    Development installation (editable install).
218

219
    Installs the package in development mode where changes
220
    to source files are immediately available without reinstall.
221

222
    Options:
223
    - install-dir: Installation directory
224
    - script-dir: Script installation directory
225
    - exclude-scripts: Don't install scripts
226
    - always-copy: Always copy files (don't link)
227
    - always-unzip: Always unzip eggs
228
    - user: Install to user site-packages
229
    - egg-path: Path to egg-link file
230
    - multi-version: Multi-version mode
231
    - upgrade: Upgrade existing installation
232
    - uninstall: Uninstall development installation
233
    """
234

235
class easy_install(Command):
236
    """
237
    Easy install command for dependency installation.
238

239
    Installs packages and their dependencies with automatic
240
    dependency resolution.
241

242
    Options:
243
    - zip-ok: Allow zip files
244
    - multi-version: Multi-version mode
245
    - upgrade: Upgrade existing packages
246
    - install-dir: Installation directory
247
    - script-dir: Script installation directory
248
    - exclude-scripts: Don't install scripts
249
    - always-copy: Always copy files
250
    - index-url: PyPI index URL
251
    - find-links: Additional package locations
252
    - build-directory: Build directory
253
    - optimize: Optimization level
254
    - record: Record installed files
255
    - always-unzip: Always unzip eggs
256
    - site-dirs: Additional site directories
257
    - editable: Editable installation
258
    - no-deps: Don't install dependencies
259
    - allow-hosts: Allowed download hosts
260
    - local-snapshots-ok: Allow local snapshots
261
    - user: Install to user site-packages
262
    """
263

264
class install_lib(Command):
265
    """Install Python modules and packages."""
266

267
class install_scripts(Command):
268
    """Install executable scripts."""
269

270
class install_egg_info(Command):
271
    """Install egg metadata files."""
272
```
273

274
### Metadata Commands
275

276
Commands for generating and managing package metadata.
277

278
```python { .api }
279
class egg_info(Command):
280
    """
281
    Generate egg metadata.
282

283
    Creates .egg-info directory with package metadata
284
    including dependencies, entry points, and file lists.
285

286
    Options:
287
    - egg-base: Base directory for egg-info
288
    - tag-build: Tag to append to version
289
    - tag-date: Add date tag to version
290
    - no-date: Don't add date tag
291
    - tag-svn-revision: Add SVN revision to version
292
    - no-svn-revision: Don't add SVN revision
293
    """
294

295
class dist_info(Command):
296
    """
297
    Generate dist-info metadata (PEP 376).
298

299
    Creates .dist-info directory with standardized
300
    package metadata for modern Python packaging.
301

302
    Options:
303
    - egg-base: Base directory for dist-info
304
    - tag-build: Tag to append to version
305
    - tag-date: Add date tag to version
306
    """
307

308
class editable_wheel(Command):
309
    """
310
    Build editable wheels for PEP 660 compliance.
311

312
    Creates wheel files that install packages in editable
313
    mode following PEP 660 standards.
314

315
    Options:
316
    - wheel-dir: Directory for wheel files
317
    - build-number: Build number for wheel
318
    """
319
```
320

321
### Configuration Commands
322

323
Commands for managing setuptools configuration and command options.
324

325
```python { .api }
326
class alias(Command):
327
    """
328
    Define command aliases.
329

330
    Create shortcuts for commonly used command combinations.
331

332
    Options:
333
    - global-config: Store in global configuration
334
    - user-config: Store in user configuration
335
    - filename: Configuration file to use
336
    """
337

338
class saveopts(Command):
339
    """
340
    Save command options to configuration file.
341

342
    Stores command options for reuse in future runs.
343

344
    Options:
345
    - global-config: Save to global configuration
346
    - user-config: Save to user configuration
347
    - filename: Configuration file to use
348
    """
349

350
class setopt(Command):
351
    """
352
    Set command options in configuration file.
353

354
    Directly set option values in configuration files.
355

356
    Options:
357
    - global-config: Set in global configuration
358
    - user-config: Set in user configuration
359
    - filename: Configuration file to use
360
    """
361

362
class rotate(Command):
363
    """
364
    Rotate old distribution files.
365

366
    Remove old distribution files, keeping only the most
367
    recent versions.
368

369
    Options:
370
    - match: Pattern for files to rotate
371
    - dist-dir: Directory containing distributions
372
    - keep: Number of files to keep
373
    """
374
```
375

376
## Usage Examples
377

378
### Running Commands via setup.py
379

380
```bash
381
# Build commands
382
python setup.py build
383
python setup.py build_py
384
python setup.py build_ext --inplace
385

386
# Distribution commands
387
python setup.py sdist
388
python setup.py bdist_wheel
389
python setup.py bdist_egg
390

391
# Installation commands
392
python setup.py install
393
python setup.py develop
394
python setup.py install --user
395

396
# Metadata commands
397
python setup.py egg_info
398
python setup.py dist_info
399

400
# Configuration commands
401
python setup.py alias --global-config test "pytest tests/"
402
python setup.py saveopts build --user-config
403
```
404

405
### Custom Command Implementation
406

407
```python
408
from setuptools import setup, Command
409
import subprocess
410
import os
411

412
class TestCommand(Command):
413
    """Custom test command."""
414
    
415
    description = 'Run tests with pytest'
416
    user_options = [
417
        ('test-args=', 'a', 'Arguments to pass to pytest'),
418
        ('coverage', 'c', 'Run with coverage'),
419
    ]
420

421
    def initialize_options(self):
422
        self.test_args = ''
423
        self.coverage = False
424

425
    def finalize_options(self):
426
        if self.test_args:
427
            self.test_args = self.test_args.split()
428
        else:
429
            self.test_args = []
430

431
    def run(self):
432
        cmd = ['pytest']
433
        if self.coverage:
434
            cmd.extend(['--cov=src', '--cov-report=html'])
435
        cmd.extend(self.test_args)
436
        
437
        self.announce(f'Running: {" ".join(cmd)}')
438
        subprocess.check_call(cmd)
439

440
setup(
441
    name='my-package',
442
    cmdclass={
443
        'test': TestCommand,
444
    },
445
)
446
```
447

448
### Build Extension with Custom Options
449

450
```python
451
from setuptools import setup, Extension
452
from setuptools.command.build_ext import build_ext
453
import numpy
454

455
class CustomBuildExt(build_ext):
456
    """Custom build_ext with additional features."""
457
    
458
    def build_extensions(self):
459
        # Custom logic before building
460
        for ext in self.extensions:
461
            ext.include_dirs.append(numpy.get_include())
462
        
463
        # Call parent build
464
        super().build_extensions()
465

466
extensions = [
467
    Extension(
468
        'my_package.fast_module',
469
        sources=['src/fast_module.c'],
470
        extra_compile_args=['-O3'],
471
    )
472
]
473

474
setup(
475
    name='my-package',
476
    ext_modules=extensions,
477
    cmdclass={
478
        'build_ext': CustomBuildExt,
479
    },
480
)
481
```
482

483
### Development Workflow
484

485
```bash
486
# Initial development setup
487
python setup.py develop
488

489
# Build C extensions in-place for development
490
python setup.py build_ext --inplace
491

492
# Run tests during development
493
python setup.py test
494

495
# Create source distribution for release
496
python setup.py sdist
497

498
# Create wheel distribution
499
python setup.py bdist_wheel
500

501
# Upload to PyPI (with twine)
502
twine upload dist/*
503
```
504

505
### Command Chaining
506

507
```bash
508
# Chain multiple commands
509
python setup.py build bdist_wheel
510

511
# Build and install in one step
512
python setup.py build install
513

514
# Create both source and wheel distributions
515
python setup.py sdist bdist_wheel
516
```
517

518
### Configuration Management
519

520
```bash
521
# Set up command aliases
522
python setup.py alias --global-config build_all "build bdist_wheel"
523
python setup.py alias --user-config test "pytest tests/ -v"
524

525
# Save build options
526
python setup.py saveopts build_ext --user-config --include-dirs=/usr/local/include
527

528
# Use saved configuration
529
python setup.py build_ext  # Uses saved options automatically
530
```