0
# Setuptools
1

2
Setuptools is a comprehensive Python package management and distribution library that serves as the foundational tooling for building, packaging, and distributing Python packages. It provides essential functionality for package discovery, dependency resolution, entry point management, and installation automation, while extending Python's built-in distutils with enhanced capabilities including namespace packages, automatic package discovery, console script generation, and extensible command interfaces.
3

4
## Package Information
5

6
- **Package Name**: setuptools
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install setuptools`
10

11
## Core Imports
12

13
```python
14
import setuptools
15
from setuptools import setup, find_packages, Extension, Distribution, Command
16
```
17

18
For build backend functionality:
19
```python
20
import setuptools.build_meta
21
```
22

23
For specific components:
24
```python
25
from setuptools.command import build_py, build_ext, install, develop
26
from setuptools.extension import Extension, Library
27
from setuptools.dist import Distribution
28
```
29

30
## Basic Usage
31

32
```python
33
from setuptools import setup, find_packages
34

35
# Basic package setup
36
setup(
37
    name="my-package",
38
    version="1.0.0",
39
    description="My Python package",
40
    author="Author Name",
41
    author_email="author@example.com",
42
    packages=find_packages(),
43
    install_requires=[
44
        "requests>=2.0.0",
45
    ],
46
    entry_points={
47
        'console_scripts': [
48
            'my-command=my_package.cli:main',
49
        ],
50
    },
51
    classifiers=[
52
        "Development Status :: 4 - Beta",
53
        "Intended Audience :: Developers",
54
        "License :: OSI Approved :: MIT License",
55
        "Programming Language :: Python :: 3",
56
        "Programming Language :: Python :: 3.8",
57
        "Programming Language :: Python :: 3.9",
58
        "Programming Language :: Python :: 3.10",
59
        "Programming Language :: Python :: 3.11",
60
        "Programming Language :: Python :: 3.12",
61
    ],
62
)
63
```
64

65
Package discovery:
66
```python
67
from setuptools import find_packages, find_namespace_packages
68

69
# Automatically find all packages
70
packages = find_packages()
71

72
# Find PEP 420 namespace packages
73
namespace_packages = find_namespace_packages()
74

75
# Find packages with exclusions
76
packages = find_packages(exclude=['tests*', 'docs*'])
77
```
78

79
## Architecture
80

81
Setuptools extends Python's built-in distutils with a layered architecture:
82

83
- **Core Setup**: The `setup()` function and `Distribution` class handle package metadata and configuration
84
- **Package Discovery**: Automated discovery of Python packages and modules through `find_packages()` and namespace package support
85
- **Command System**: Extensible command framework for building, installing, and distributing packages
86
- **Build Backend**: PEP 517/518 compliant build system for modern Python packaging workflows
87
- **Extension Building**: Enhanced C/C++ extension compilation with Cython support
88
- **Entry Points**: Automatic script generation and plugin discovery mechanisms
89

90
This design enables setuptools to serve as both a traditional setup.py-based build tool and a modern pyproject.toml-based build backend, providing backward compatibility while supporting current Python packaging standards.
91

92
## Capabilities
93

94
### Core Setup Functions
95

96
The fundamental setuptools functionality for package configuration, including the main setup() function and package discovery utilities that form the foundation of Python package building.
97

98
```python { .api }
99
def setup(**attrs):
100
    """
101
    Configure and build a Python package.
102

103
    Parameters:
104
    - name: Package name
105
    - version: Package version
106
    - description: Short package description
107
    - long_description: Detailed package description
108
    - author: Package author name
109
    - author_email: Author email address
110
    - url: Package homepage URL
111
    - packages: List of packages to include
112
    - py_modules: List of individual modules to include
113
    - install_requires: List of required dependencies
114
    - extras_require: Dictionary of optional dependencies
115
    - entry_points: Dictionary defining entry points and console scripts
116
    - classifiers: List of package classifiers
117
    - python_requires: Python version requirements
118
    - package_data: Dictionary of package data files
119
    - data_files: List of data files to install
120
    - scripts: List of script files
121
    - ext_modules: List of C/C++ extension modules
122
    - cmdclass: Dictionary of custom command classes
123
    - zip_safe: Whether package can be run from a zip file
124
    - include_package_data: Whether to include package data from MANIFEST.in
125
    - **other_attrs: Additional attributes
126

127
    Returns:
128
    None (configures package for building/installation)
129
    """
130

131
def find_packages(where='.', exclude=(), include=('*',)):
132
    """
133
    Automatically discover Python packages.
134

135
    Parameters:
136
    - where (str): Directory to search for packages (default: '.')
137
    - exclude (tuple): Glob patterns for packages to exclude
138
    - include (tuple): Glob patterns for packages to include (default: ('*',))
139

140
    Returns:
141
    list: List of discovered package names
142
    """
143

144
def find_namespace_packages(where='.', exclude=(), include=('*',)):
145
    """
146
    Discover PEP 420 implicit namespace packages.
147

148
    Parameters:
149
    - where (str): Directory to search for packages (default: '.')
150
    - exclude (tuple): Glob patterns for packages to exclude
151
    - include (tuple): Glob patterns for packages to include (default: ('*',))
152

153
    Returns:
154
    list: List of discovered namespace package names
155
    """
156

157
def findall(dir='.'):
158
    """
159
    Find all files under a directory.
160

161
    Parameters:
162
    - dir (str): Directory to search (default: '.')
163

164
    Returns:
165
    list: List of file paths
166
    """
167
```
168

169
[Core Setup Functions](./core-setup.md)
170

171
### Core Classes
172

173
Essential setuptools classes that provide the foundation for package building, extension compilation, and command execution.
174

175
```python { .api }
176
class Distribution:
177
    """
178
    Enhanced version of distutils.Distribution for package metadata.
179

180
    Key Methods:
181
    - parse_config_files(): Parse configuration files
182
    - get_command_class(command): Get command class by name
183
    - run_command(command): Execute a command
184
    - get_command_obj(command): Get command instance
185
    """
186

187
class Command:
188
    """
189
    Base class for all setuptools commands.
190

191
    Required Methods:
192
    - initialize_options(): Set default option values
193
    - finalize_options(): Validate and process options
194
    - run(): Execute the command
195
    """
196

197
class Extension:
198
    """
199
    Enhanced C/C++ extension module descriptor.
200

201
    Parameters:
202
    - name (str): Extension module name
203
    - sources (list): List of source files
204
    - include_dirs (list): Include directories
205
    - library_dirs (list): Library directories
206
    - libraries (list): Libraries to link against
207
    - extra_compile_args (list): Additional compiler arguments
208
    - extra_link_args (list): Additional linker arguments
209
    - language (str): Programming language ('c' or 'c++')
210
    - py_limited_api (bool): Whether to use stable ABI
211
    """
212

213
class Library:
214
    """
215
    Like Extension but built as a library instead of a module.
216

217
    Parameters: Same as Extension
218
    """
219
```
220

221
[Core Classes](./core-classes.md)
222

223
### Build Backend API
224

225
PEP 517/518 compliant build backend functions for modern Python packaging workflows, enabling setuptools to work with build tools like pip, build, and other PEP 517 frontends.
226

227
```python { .api }
228
def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
229
    """
230
    Build a wheel distribution.
231

232
    Parameters:
233
    - wheel_directory (str): Directory to write wheel file
234
    - config_settings (dict): Build configuration settings
235
    - metadata_directory (str): Directory containing metadata
236

237
    Returns:
238
    str: Filename of built wheel
239
    """
240

241
def build_sdist(sdist_directory, config_settings=None):
242
    """
243
    Build a source distribution.
244

245
    Parameters:
246
    - sdist_directory (str): Directory to write sdist file
247
    - config_settings (dict): Build configuration settings
248

249
    Returns:
250
    str: Filename of built sdist
251
    """
252

253
def build_editable(wheel_directory, config_settings=None, metadata_directory=None):
254
    """
255
    Build an editable wheel distribution.
256

257
    Parameters:
258
    - wheel_directory (str): Directory to write wheel file
259
    - config_settings (dict): Build configuration settings
260
    - metadata_directory (str): Directory containing metadata
261

262
    Returns:
263
    str: Filename of built editable wheel
264
    """
265
```
266

267
[Build Backend API](./build-backend.md)
268

269
### Command Classes
270

271
Setuptools command system providing extensible build, installation, and distribution functionality through specialized command classes for every aspect of Python package lifecycle management.
272

273
```python { .api }
274
# Build Commands
275
class build: # Enhanced build command
276
class build_py: # Python module builder
277
class build_ext: # C extension builder
278
class build_clib: # C library builder
279

280
# Distribution Commands  
281
class bdist_egg: # Build .egg distribution
282
class bdist_wheel: # Build wheel distribution
283
class bdist_rpm: # Build RPM distribution
284
class sdist: # Source distribution builder
285

286
# Installation Commands
287
class install: # Enhanced install command
288
class develop: # Development installation
289
class easy_install: # Easy install functionality
290

291
# Metadata Commands
292
class egg_info: # Generate egg metadata
293
class dist_info: # Generate dist-info metadata
294
class editable_wheel: # Build editable wheels
295
```
296

297
[Command Classes](./commands.md)
298

299
### Exception Classes
300

301
Comprehensive exception hierarchy for error handling in setuptools operations, including both setuptools-specific errors and re-exported distutils errors for compatibility.
302

303
```python { .api }
304
class SetuptoolsDeprecationWarning(Warning):
305
    """Base class for setuptools deprecation warnings."""
306

307
class BaseError(Exception):
308
    """Root error class for setuptools errors."""
309

310
class InvalidConfigError(BaseError):
311
    """Invalid configuration errors."""
312

313
class RemovedConfigError(BaseError):
314
    """Deprecated configuration usage."""
315

316
class PackageDiscoveryError(BaseError):
317
    """Package discovery issues."""
318

319
class SetupRequirementsError(BaseError):
320
    """Setup requirement installation issues."""
321
```
322

323
[Exception Handling](./exceptions.md)
324

325
### Utility Functions
326

327
Additional utility functions for archive handling, file operations, and other common setuptools operations.
328

329
```python { .api }
330
def unpack_archive(filename, extract_dir='.', drivers=None):
331
    """Extract various archive formats."""
332

333
def unpack_zipfile(filename, extract_dir='.'):
334
    """Extract ZIP files."""
335

336
def unpack_tarfile(filename, extract_dir='.'):
337
    """Extract TAR files."""
338

339
class sic(str):
340
    """String class for literal treatment."""
341
```
342

343
[Utilities](./utilities.md)
344

345
### pkg_resources (Deprecated)
346

347
Legacy package resource API for runtime package discovery and resource access. Though deprecated in favor of importlib.resources and importlib.metadata, it remains widely used for backward compatibility.
348

349
```python { .api }
350
def require(*requirements):
351
    """Ensure distributions matching requirements are available."""
352

353
def get_distribution(requirement):
354
    """Get Distribution object for installed package."""
355

356
def resource_string(package, resource_name):
357
    """Return resource file contents as bytes."""
358

359
def resource_filename(package, resource_name):  
360
    """Return filesystem path to resource."""
361

362
def load_entry_point(dist, group, name):
363
    """Load and return entry point."""
364

365
class WorkingSet:
366
    """Set of active distributions in runtime environment."""
367

368
class Distribution:
369
    """Metadata and resource access for installed package."""
370
```
371

372
[pkg_resources API](./pkg-resources.md)
373

374
## Types
375

376
```python { .api }
377
# Version information
378
__version__: str  # Current setuptools version
379

380
# Package discovery classes
381
class PackageFinder:
382
    """Standard package discovery."""
383
    @classmethod
384
    def find(cls, where='.', exclude=(), include=('*',)): ...
385

386
class PEP420PackageFinder(PackageFinder):
387
    """PEP 420 namespace package discovery."""
388
    @classmethod
389
    def find(cls, where='.', exclude=(), include=('*',)): ...
390

391
class ModuleFinder:
392
    """Discovery for standalone Python modules."""
393
    @classmethod
394
    def find(cls, where='.', exclude=(), include=('*',)): ...
395

396
class ConfigDiscovery:
397
    """Automatic configuration discovery for setuptools."""
398
    def __init__(self, distribution=None): ...
399
    def __call__(self, dist=None): ...
400

401
# Requirement management
402
class Require:
403
    """Represents a prerequisite for building or installing."""
404
    def __init__(self, name, requested_version, module_name, homepage='', attribute=None, format=None): ...
405
    def version_ok(self, version): ...
406
    def get_version(self, paths=None, default='unknown'): ...
407
    def is_present(self, paths=None): ...
408
    def is_current(self, paths=None): ...
409
```