setup.py配置说明 - 元素码农

发布时间: 2025-04-02 11:04

↑

# setup.py配置说明

本文详细介绍Python包的setup.py配置文件，包括基本配置、依赖管理、打包选项等内容。

## 配置来源与管理

setup.py配置文件是由setuptools工具管理的，它是Python官方推荐的包构建工具。setuptools提供了一套标准的配置规范，用于定义Python包的元数据、依赖关系和构建过程。

### 配置管理机制

1. setuptools工具
   - setuptools是Python包构建和分发的核心工具
   - 它提供了setup()函数作为配置入口
   - 负责解析和验证setup.py中的配置项

2. 与包管理工具的关系
   - pip在安装包时会执行setup.py
   - wheel工具使用setup.py生成分发包
   - 其他工具(如poetry)可以生成兼容的setup.py

3. 配置规范
   - PyPA(Python Packaging Authority)定义了配置标准
   - setuptools遵循PEP 517和PEP 518规范
   - 配置项需符合PyPI的元数据规范

## 基本配置

### 1. 最简配置

```python
from setuptools import setup, find_packages

setup(
    name="my_package",
    version="1.0.0",
    packages=find_packages(),
)
```

### 2. 完整配置

```python
from setuptools import setup, find_packages

setup(
    # 基本信息
    name="my_package",              # 包名称
    version="1.0.0",               # 版本号
    author="Your Name",            # 作者
    author_email="your@email.com", # 作者邮箱
    description="Package description", # 简短描述
    long_description=open("README.md").read(), # 详细描述
    long_description_content_type="text/markdown", # 描述文件格式
    url="https://github.com/username/project", # 项目主页
    
    # 包配置
    packages=find_packages(where="src"), # 自动发现包
    package_dir={"":"src"},      # 包目录配置
    include_package_data=True,    # 包含非Python文件
    
    # Python版本要求
    python_requires=">=3.6",
    
    # 项目分类信息
    classifiers=[
        "Development Status :: 5 - Production/Stable",
        "Intended Audience :: Developers",
        "License :: OSI Approved :: MIT License",
        "Programming Language :: Python :: 3",
        "Programming Language :: Python :: 3.6",
        "Programming Language :: Python :: 3.7",
        "Programming Language :: Python :: 3.8",
        "Programming Language :: Python :: 3.9",
    ],
)
```

## 依赖管理

### 1. 基本依赖

```python
setup(
    # ...
    install_requires=[
        "requests>=2.31.0",
        "Django>=4.2.0,<5.0.0",
        "pandas~=2.0.0",
    ],
)
```

### 2. 可选依赖

```python
setup(
    # ...
    extras_require={
        "dev": [
            "pytest>=7.0.0",
            "black>=23.0.0",
            "flake8>=6.0.0",
        ],
        "docs": [
            "sphinx>=7.0.0",
            "sphinx-rtd-theme>=1.0.0",
        ],
    },
)
```

### 3. 开发依赖

```python
setup(
    # ...
    setup_requires=[
        "pytest-runner",
        "wheel",
    ],
    tests_require=[
        "pytest",
        "pytest-cov",
    ],
)
```

## 包数据文件

### 1. 包含数据文件

```python
setup(
    # ...
    package_data={
        "my_package": [
            "data/*.json",
            "templates/*.html",
            "static/*",
        ],
    },
)
```

### 2. 排除文件

```python
setup(
    # ...
    exclude_package_data={
        "": ["*.pyc", "*.pyo", "*.pyd", "__pycache__"],
        "my_package": ["tests/*"],
    },
)
```

## 命令行工具

### 1. 基本配置

```python
setup(
    # ...
    entry_points={
        "console_scripts": [
            "my-command=my_package.cli:main",
        ],
    },
)
```

### 2. GUI应用配置

```python
setup(
    # ...
    entry_points={
        "gui_scripts": [
            "my-gui=my_package.gui:main",
        ],
    },
)
```

## 高级配置

### 1. 自定义命令

```python
from setuptools import Command

class CustomCommand(Command):
    description = "自定义命令描述"
    user_options = []
    
    def initialize_options(self):
        pass
        
    def finalize_options(self):
        pass
        
    def run(self):
        print("执行自定义命令")

setup(
    # ...
    cmdclass={
        "custom": CustomCommand,
    },
)
```

### 2. 条件依赖

```python
import sys

setup(
    # ...
    install_requires=[
        "pywin32>=306; sys_platform == 'win32'",
        "uvloop; sys_platform != 'win32'",
    ],
)
```

### 3. 动态版本号

```python
import os

def get_version():
    version_file = os.path.join("my_package", "version.txt")
    with open(version_file) as f:
        return f.read().strip()

setup(
    # ...
    version=get_version(),
)
```

## 最佳实践

### 1. 版本管理

- 使用语义化版本号
- 保持版本号一致性
- 考虑使用自动化工具管理版本

### 2. 依赖管理

- 明确指定依赖版本范围
- 分离开发和运行时依赖
- 使用条件依赖处理平台差异

### 3. 文件组织

- 使用src布局
- 合理组织包数据文件
- 注意文件权限设置

### 4. 打包建议

- 使用wheel格式
- 包含必要的元数据
- 提供完整的文档

## 现代化替代方案

### 1. setup.cfg

推荐使用setup.cfg替代setup.py进行静态配置：

```ini
[metadata]
name = my_package
version = 1.0.0

[options]
packages = find:
install_requires =
    requests>=2.31.0
    Django>=4.2.0
```

### 2. pyproject.toml

使用更现代的pyproject.toml配置：

```toml
[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my_package"
version = "1.0.0"
dependencies = [
    "requests>=2.31.0",
    "Django>=4.2.0",
]
```

## 总结

setup.py配置文件是Python包管理的核心，它：
1. 定义包的元数据和依赖
2. 控制包的构建和安装
3. 管理包的数据文件
4. 配置命令行工具

虽然现代Python包管理工具提供了更简洁的配置方式，但理解setup.py的配置仍然很重要，它可以帮助我们更好地管理Python包。