Python setup.py 快速入门指南：构建、打包和分发你的 Python 项目
setup.py 是 Python 项目的核心构建文件，它使用 setuptools 库定义了项目的元数据、依赖关系以及构建、打包和分发指令。理解和正确使用 setup.py 对于共享你的代码、创建可安装的包以及简化项目管理至关重要。本文将深入探讨 setup.py 的各个方面，从基础概念到高级用法，助你快速掌握构建和分发 Python 项目的技巧。
1. setuptools：构建 Python 包的基石
setuptools 是 Python 的一个增强版构建系统，它扩展了 distutils 的功能，提供了更强大、灵活的打包和分发机制。在使用 setup.py 之前，你需要确保已经安装了 setuptools：
bash
pip install setuptools
2. setup.py 的核心：setup() 函数
setup.py 文件的核心是 setup() 函数，它接收一系列关键字参数，用于描述项目的各种属性。以下是一些常用的参数：
- name: 项目名称，必须唯一。
- version: 项目版本号，遵循语义化版本规范。
- author: 项目作者。
- author_email: 项目作者邮箱。
- description: 项目的简短描述。
- long_description: 项目的详细描述，可以读取 README 文件的内容。
- long_description_content_type: long_description 的内容类型，例如 ‘text/markdown’、’text/x-rst’ 等。
- url: 项目主页 URL。
- packages: 项目包含的 Python 包列表，可以使用
find_packages()自动发现。 - install_requires: 项目依赖的第三方库列表。
- classifiers: 项目的分类信息，例如操作系统、编程语言、许可证等。
- entry_points: 定义命令行入口点，方便用户直接调用项目中的脚本。
- python_requires: 指定项目支持的 Python 版本范围。
- keywords: 项目的关键词，方便用户搜索。
- license: 项目的许可证。
- include_package_data: 包含包中的非 Python 文件，例如数据文件、配置文件等。
- data_files: 包含项目中其他文件或目录，例如文档、示例代码等。
- scripts: 包含项目中可执行的脚本文件。
- ext_modules: 包含 C/C++ 扩展模块。
3. 编写一个简单的 setup.py 示例
假设你的项目结构如下：
myproject/
├── mypackage/
│ └── __init__.py
└── setup.py
mypackage/__init__.py 文件内容如下：
python
def greet(name):
print(f"Hello, {name}!")
setup.py 文件内容如下：
“`python
from setuptools import setup, find_packages
setup(
name=’myproject’,
version=’0.1.0′,
author=’Your Name’,
author_email=’[email protected]’,
description=’A simple example project’,
long_description=’A longer description of the project.’,
long_description_content_type=’text/markdown’, # 如果 long_description 是 Markdown 格式
url=’https://github.com/yourusername/myproject’,
packages=find_packages(),
install_requires=[], # 如果没有依赖，可以留空
classifiers=[
‘Programming Language :: Python :: 3’,
‘License :: OSI Approved :: MIT License’,
‘Operating System :: OS Independent’,
],
python_requires=’>=3.6′,
)
“`
4. 常用命令：构建、安装和分发
-
构建源码发行版 (sdist):
python setup.py sdist创建一个包含项目源码的压缩包 (例如.tar.gz或.zip)，可以用于分发或在其他环境中安装。 -
构建二进制发行版 (wheel):
python setup.py bdist_wheel创建一个 wheel 文件 (.whl)，它是一种预编译的发行版，可以更快地安装。 -
安装项目:
python setup.py install将项目安装到当前 Python 环境中。 -
上传到 PyPI:
twine upload dist/*将构建好的发行版上传到 Python Package Index (PyPI)，方便其他用户通过pip install安装你的项目。 (需要先安装 twine:pip install twine)
5. find_packages() 的妙用：自动发现包
find_packages() 函数可以自动查找项目中所有的 Python 包，避免手动列出所有包。你还可以使用 exclude 参数排除特定的包：
“`python
from setuptools import find_packages
packages = find_packages(exclude=[‘tests’, ‘docs’])
“`
6. include_package_data：包含非 Python 文件
如果你的包中包含非 Python 文件，例如数据文件、配置文件等，可以使用 include_package_data 参数将其包含在发行版中:
python
setup(
...
include_package_data=True,
package_data={
'mypackage': ['data/*.txt', 'config.ini'],
},
...
)
7. data_files：包含其他文件或目录
data_files 参数可以包含项目中其他文件或目录，例如文档、示例代码等:
python
setup(
...
data_files=[('my_data', ['data/data1.txt', 'data/data2.txt'])],
...
)
8. entry_points：创建命令行入口点
entry_points 参数允许你创建命令行入口点，方便用户直接调用项目中的脚本:
python
setup(
...
entry_points={
'console_scripts': [
'mycommand = mypackage.module:function',
],
},
...
)
安装后，用户就可以直接在命令行中运行 mycommand。
9. 管理依赖关系：install_requires
install_requires 参数指定项目依赖的第三方库，setuptools 会在安装过程中自动安装这些依赖：
python
setup(
...
install_requires=[
'requests>=2.20.0',
'numpy',
],
...
)
10. 高级用法：条件依赖和 extras_require
你可以使用 environment markers 定义条件依赖，例如：
“`python
install_requires=[
“requests>=2.20.0; python_version<‘3.8′”,
“requests>=3.0.0; python_version>=’3.8′”,
],
“`
extras_require 参数可以定义可选的依赖，例如：
python
extras_require={
'dev': ['pytest', 'flake8'],
'docs': ['sphinx', 'sphinx_rtd_theme'],
},
用户可以使用 pip install myproject[dev] 安装开发相关的依赖。
11. 保持 setup.py 简洁：使用 setup.cfg
为了保持 setup.py 文件的简洁，你可以将一些静态元数据信息移动到 setup.cfg 文件中：
“`ini
[metadata]
name = myproject
version = 0.1.0
author = Your Name
author_email = [email protected]
description = A simple example project
long_description = file: README.md
long_description_content_type = text/markdown
url = https://github.com/yourusername/myproject
license = MIT
classifiers =
Programming Language :: Python :: 3
License :: OSI Approved :: MIT License
Operating System :: OS Independent
[options]
packages = find:
install_requires =
requests>=2.20.0
numpy
python_requires = >=3.6
[options.package_data]
mypackage = data/*.txt, config.ini
[options.entry_points]
console_scripts =
mycommand = mypackage.module:function
“`
然后在 setup.py 中只需要简单的调用 setup() 函数即可：
“`python
from setuptools import setup
setup()
“`
通过合理使用 setup.py 和 setup.cfg，你可以有效地管理你的 Python 项目，并轻松地与他人分享你的代码。 本文涵盖了 setup.py 的核心概念和常用技巧，希望能够帮助你更好地理解和使用它。 记住，持续学习和实践是掌握任何工具的关键。 不断探索 setuptools 的更多功能，你将能够构建更强大、更专业的 Python 项目。