跳转到内容
Nick Blogs

setuptools使用手册

1. 简介

Section titled “1. 简介”

setuptools 是 Python 社区中用于 打包 (packaging)、分发 (distribution) 和 安装 (installation) Python 项目的标准工具集。

2. 配置参数

Section titled “2. 配置参数”

2.1. setup() 核心配置参数表

Section titled “2.1. setup() 核心配置参数表”
参数作用说明常见配置示例值
name包的发布名称，在 PyPI 上的唯一标识。'requests'
version版本号，推荐遵循 语义化版本规范（如 X.Y.Z）。'1.0.5'
description单行简短摘要介绍。'A short description'
long_description详细说明，常读取 README.md 的内容呈现。open('README.md').read()
url项目官方主页或 GitHub 托管仓库地址。'https://github.com/...'
author, author_email作者信息 与联系邮箱。'Your Name', 'email@example.com'
license开源协议声明。'MIT', 'GPLv3'
packages需要被打包的子包目录列表。通常使用 setuptools.find_packages() 自动扫描所有含 __init__.py 文件夹。find_packages()
py_modules如果项目非常简单仅包含 单个 .py 文件，则使用该参数声明。['mymodule']
install_requires生产环境依赖包列表。用户 pip install 你的包时，依赖会被自动下载。['pandas', 'jinja2>=3.0']
python_requires项目所要求的 Python 解释器最低版本。'>=3.6'
entry_points注册 CLI 终端命令或者是插件系统挂载点。见下文示例
include_package_data是否打包 非代码静态资源，需配合 MANIFEST.in 使用。True

2.2. 声明式配置 (Declarative Config)

Section titled “2.2. 声明式配置 (Declarative Config)”

这是 setuptools 推荐的配置进化方案：将元数据与外部配置静态化写入 setup.cfg 或 pyproject.toml 中，保证 setup.py 文件足够干净简洁：

setup.py
from setuptools import setup


setup()

2.3. 现代配置标准 (pyproject.toml)

Section titled “2.3. 现代配置标准 (pyproject.toml)”

遵循 PEP 517/518 标准的配置文件，旨在统一整个 Python 社区中打包（Setuptools、Poetry、Hatch）、格式化、Lint 工具的配置入口。

3. 常用打包命令对比

Section titled “3. 常用打包命令对比”
传统历史命令作用说明现代替代标准命令 (推荐)
python setup.py install将项目直接安装到当前环境的 site-packages 下。pip install .
python setup.py sdist构建 源码分发包（生成 .tar.gz 压缩文件）。python -m build
python setup.py bdist_wheel构建 二进制轮子包（生成跨平台安装的 .whl 文件）。python -m build
python setup.py clean清理编译过程中生成的 build/dist 临时文件夹。无标准命令，通常手动 rm 清理。
python setup.py develop可编辑开发模式（本地代码修改立刻生效，无需重新打包）。pip install -e .

4. 复杂项目打包编译实例 (Cython 与 NumPy 集成)

Section titled “4. 复杂项目打包编译实例 (Cython 与 NumPy 集成)”

本示例展示了如何编译 Cython 核心扩展模块，并通过 setuptools 构建分发包。

import numpy
from setuptools import setup, Extension, find_packages
from Cython.Build import cythonize


# ----------------------------------------------------------------------
# 步骤 1: 定义需要编译的 Cython 扩展模块
# ----------------------------------------------------------------------


# 假设您的 Cython 源文件结构位于包名：[项目 X] 内
# name 参数定义了导入路径 (例如: import [项目 X].core)
extensions = [
    Extension(
        name="[项目X].core",
        # Cython 源码实际路径
        sources=["[项目X]/core.pyx"],
        # 若编译时需要链接系统数学库：libraries = ["m"]
        # 优化编译器指令：extra_compile_args = ["-O3"]


        # 必须传入包含的 NumPy 头文件路径以进行 C-API 交互
        include_dirs=[numpy.get_include()]
    )
]


# ----------------------------------------------------------------------
# 步骤 2: 编写 setup 配置
# ----------------------------------------------------------------------


setup(
    name="[项目X]",
    version="0.1.0",
    description="A project with protected Cython modules for alerting.",
    author="Your Name",


    # 自动定位项目中的子包，并显式排查其他杂项文件夹，防止触发 flat-layout 命名冲突错误
    packages=find_packages(
        exclude=['logs', 'runs', 'temp', 'result', 'static', 'test', 'docs']
    ),


    # 交给 Cython 进行编译转化
    ext_modules=cythonize(
        extensions,
        compiler_directives={'language_level': "3"}, # 指定支持 Python 3 语法
        quiet=True                                   # 简化终端编译输出
    ),


    include_dirs=[numpy.get_include()],


    # pip 安装当前包时，必须自动补齐的第三方依赖
    install_requires=[
        'numpy>=1.16',
    ],


    # 本地编译打包时（例如执行构建时）本身所需要的模块依赖
    setup_requires=[
        'Cython>=0.29',
        'numpy>=1.16'
    ],


    license="MIT",
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
)

5. 进阶打包设计指南与避坑建议

Section titled “5. 进阶打包设计指南与避坑建议”

6. 参考资料

Section titled “6. 参考资料”