上位机知识篇---setuptools

前言

本文仅仅简单介绍了Python中setuptools的模块的功能以及使用方法。

简介

setuptools 是 Python 生态中用于打包和分发项目的核心工具，它扩展了 Python 原生的 distutils 模块，提供了更强大的功能和更便捷的配置方式。以下从功能、用法和最佳实践三个维度进行详细说明：

一、核心功能

1.依赖管理

自动安装依赖

自动安装依赖：通过 install_requires 声明依赖，pip install 时会自动安装。

版本约束

版本约束：支持语义化版本（如 >=2.0,❤️.0）。

额外依赖组

额外依赖组：通过 extras_require 定义可选依赖（如测试、文档依赖）。

命令行工具

命令行工具：将 Python 函数映射为命令行命令（如 pip 自身即通过 entry point 实现）。

插件系统

插件系统：其他程序可通过 entry points 动态发现并加载你的包（如 pytest 插件）。

2.开发模式安装

pip install -e .：将包以“可编辑模式”安装，代码修改无需重新安装，直接生效。

3.资源文件管理

自动包含 package_data 中声明的非代码文件（如配置文件、模板）。

4.Egg 分发（已逐渐被 Wheel 取代）

提供 .egg 格式分发，支持二进制依赖（现推荐使用 wheel 格式）。

5.命名空间包

支持在多个项目中共享同一个包命名空间（如 google.cloud.storage 和 google.cloud.bigquery）。

二、基础用法

1. 项目结构示例

my_project/
├── src/  # 推荐使用 src 目录隔离源码
│   └── my_pkg/
│       ├── __init__.py
│       └── module.py
├── tests/
├── pyproject.toml  # 构建系统声明
├── setup.cfg       # 推荐：静态配置
└── setup.py        # 动态配置（可选，逐渐被 setup.cfg 替代）

2. 配置文件 setup.cfg

[metadata]
name = my_pkg
version = 1.0.0
author = Your Name
description = A sample package

[options]
package_dir = = src
packages = find:  # 自动查找包
install_requires =
    requests>=2.24.0
    numpy~=1.20.0

[options.extras_require]
test =
    pytest>=6.0
dev = %(test)s
    flake8>=3.8

[options.entry_points]
console_scripts =
    mycli = my_pkg.cli:main
pytest11 =
    myplugin = my_pkg.pytest_plugin

3. setup.py 最小化示例（现代项目可省略）

from setuptools import setup

setup()

4. 常用命令

#安装开发模式
pip install -e .

#构建源码包和 Wheel
python -m build

#上传到 PyPI
twine upload dist/*

三、进阶用法与最佳实践

1. 动态版本号

在 setup.cfg 中引用 __version__：

#my_pkg/__init__.py
__version__ = "1.2.3"

#setup.cfg
[metadata]
version = attr: my_pkg.__version__

2. 包含数据文件

[options]
include_package_data = True

[options.package_data]
my_pkg =
    data/*.json
    configs/*.yml

3. Cython 扩展

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

extensions = [
    Extension("my_pkg.optimized", ["src/my_pkg/optimized.pyx"])
]

setup(ext_modules=cythonize(extensions))

4. 兼容性标记

[metadata]
classifiers =
    Programming Language :: Python :: 3
    Programming Language :: Python :: 3.8
    Programming Language :: Python :: 3.9

5. 自定义构建命令

继承 setuptools.Command 实现自定义命令：

from setuptools import setup, Command

class CustomCommand(Command):
    def run(self):
        print("Running custom task...")

setup(cmdclass={'custom': CustomCommand})

四、常见问题解决

1.找不到包？

使用 package_dir 和 packages=find: 自动检测。
确保 init.py 存在于每个包目录。

2.资源文件未包含？

检查 MANIFEST.in 或 include_package_data=True。

3.Entry Point 不生效？

确认函数签名正确（如 def main():）。
重新安装包（pip install -e .）。

五、生态工具链整合

1.构建

构建：使用 build 替代 python setup.py sdist bdist_wheel

2.上传

上传：使用 twine 替代 setup.py upload

3.虚拟环境

虚拟环境：结合 virtualenv/venv

4.测试

测试：通过 tox 实现多环境测试

5.文档

文档：与 Sphinx 集成生成文档

通过合理使用 setuptools，可以实现从代码管理到分发的全流程标准化，建议结合 pyproject.toml (PEP 621) 实现更现代的配置方式。

总结

以上就是今天要讲的内容，本文仅仅简单介绍了Python中setuptools的模块的功能以及使用方法。