Python项目打包与分发：从结构到发布全流程
项目目录规范设计
合理的项目结构是成功打包的基础。推荐采用以下布局：
my_project/
├── my_project/ # 实际Python包，名称仅含字母、数字和下划线
│ ├── __init__.py
│ └── core.py # 主要功能实现
├── setup.py # 构建脚本
├── requirements.txt # 第三方依赖清单
├── README.md # 项目说明文档
└── tests/ # 单元测试代码
注意：若将模块文件直接置于顶层目录（如my-project/core.py），且未在setup.py中正确配置，则安装后可能无法通过包名导入模块。
requirements.txt 与 setup.py 的角色区分
requirements.txt用于快速部署开发环境，内容示例如下：
# requirements.txt
requests==2.31.0
openpyxl>=3.0.0
用户克隆项目后可通过以下命令一键安装依赖：
pip install -r requirements.txt
setup.py则定义了如何构建和发布包，其核心作用是生成可分发的安装包。基本模板如下：
from setuptools import setup
setup(
name='my-project',
version='0.2.1',
description='A tool for processing Excel-based APIs',
author='Zhang Wei',
author_email='zhangwei@example.com',
license='MIT',
url='https://github.com/zhangwei/my-project',
install_requires=[
'requests',
'openpyxl'
],
)
当他人使用pip install my-project时，系统会自动解析并安装所列依赖项。
setup() 函数关键参数详解
| 参数 | 用途 | 示例 |
|---|---|---|
name |
PyPI 上的包名（支持连字符） | 'my-project' |
version |
版本号，遵循语义化版本规范 | '1.0.0' |
packages |
需包含的子包列表 | ['my_project'] |
install_requires |
运行时依赖 | ['requests', 'click'] |
entry_points |
注册命令行入口 | {'console_scripts': ['run-excel = my_project.core:main']} |
long_description |
读取README.md作为详细描述 | open('README.md').read() |
classifiers |
分类标签，帮助用户检索 | ['Programming Language :: Python :: 3'] |
常用功能实现示例
动态加载README内容
import os
def read_readme():
with open('README.md', 'r', encoding='utf-8') as f:
return f.read()
setup(
name='my-project',
long_description=read_readme(),
long_description_content_type='text/markdown'
)
创建可执行命令行工具
通过entry_points将函数暴露为终端命令：
setup(
entry_points={
'console_scripts': [
'excel-run = my_project.core:start_execution'
]
}
)
假设core.py中定义了start_execution()函数，安装后即可在终端运行excel-run触发该函数。
常见操作命令汇总
本地构建与安装
python setup.py build：编译源码，生成build/目录python setup.py install：安装至当前Python环境python setup.py develop：开发模式安装，修改源码即时生效
等价替代方案：
pip install .
pip install -e . # 对应 develop 模式
生成分发包
python setup.py sdist：生成源码压缩包（.tar.gz）
python setup.py bdist_wheel建议同时生成两种格式以兼容更多场景：
python setup.py sdist bdist_wheel
输出文件位于dist/目录，可被其他用户通过pip install 文件路径安装。
发布至PyPI
推荐使用twine进行安全上传：
pip install twine
twine upload dist/*
首次发布前需在PyPI注册账户，并妥善保管凭证。
使用 setup.cfg 替代硬编码
为减少脚本复杂度，可将配置移至setup.cfg文件：
[metadata]
name = my-project
version = 0.2.1
author = Zhang Wei
description = Run API tests from Excel files
long_description = file: README.md
long_description_content_type = text/markdown
[options]
packages = find:
python_requires = >=3.7
install_requires =
requests
openpyxl
[options.entry_points]
console_scripts =
excel-run = my_project.core:start_execution
此时setup.py可简化为：
from setuptools import setup
setup()
向 pyproject.toml 迁移趋势
现代Python项目逐渐采用pyproject.toml统一管理构建流程，但传统setup.py仍广泛适用。过渡阶段可保留原有结构，逐步迁移。
