准备工作与环境配置
在开始发布Python包之前，需要确保开发环境满足基本要求。推荐使用Python 3.7+版本，并安装以下核心工具：
pip install --upgrade pip setuptools wheel twine
虚拟环境是隔离依赖的关键工具，建议使用以下命令创建：
python -m venv packaging_env
source packaging_env/bin/activate # Linux/macOS
packaging_env\Scripts\activate # Windows
项目结构与元数据配置
标准Python包应遵循特定目录结构：
my_package/
├── src/
│ └── my_package/
│ ├── __init__.py
│ └── module1.py
├── tests/
├── pyproject.toml
├── setup.cfg
├── LICENSE
└── README.md
现代Python打包推荐使用pyproject.toml作为核心配置文件：
[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "my-awesome-package"
version = "0.1.0"
description = "A sample Python package"
readme = "README.md"
requires-python = ">=3.7"
license = {text = "MIT"}
authors = [
{name = "Dev User", email = "[email protected]"}
]
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
]
构建与本地测试
使用以下命令构建分发包：
python -m build
这将生成dist/目录下的.tar.gz和.whl文件。本地安装测试推荐使用：
pip install --force-reinstall dist/my_awesome_package-0.1.0-py3-none-any.whl
PyPI发布流程
账户注册与API令牌
- 访问pypi.org注册账户
- 在账户设置中创建API令牌，作用域选择”整个账户”
- 在本地创建
~/.pypirc文件保存凭证：
[pypi]
username = __token__
password = pypi-your-api-token-here
上传与验证
使用twine进行安全上传：
twine upload dist/*
验证发布结果：
pip install --index-url https://pypi.org/simple/ --no-deps my-awesome-package
版本管理与时间戳解析
版本号应遵循PEP 440规范。对于时间戳1743666591的解析：
from datetime import datetime
timestamp = 1743666591
print(datetime.utcfromtimestamp(timestamp).strftime('%Y-%m-%d %H:%M:%S UTC'))
输出结果为2025-04-02 12:09:51 UTC，可用于构建版本号如2025.4.2.1209。
高级打包技术
二进制扩展构建
对于包含C扩展的包，需配置setup.py：
from setuptools import setup, Extension
module = Extension('mymodule', sources=['src/mymodule.c'])
setup(
ext_modules=[module],
# 其他配置...
)
多平台构建策略
使用manylinux标签保证跨平台兼容性：
docker run --rm -v `pwd`:/io quay.io/pypa/manylinux2014_x86_64 /io/build-wheels.sh
持续集成实践
GitHub Actions配置示例：
name: Publish Python Package
on:
release:
types: [published]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.x'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install build twine
- name: Build package
run: python -m build
- name: Publish
env:
TWINE_USERNAME: __token__
TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
run: twine upload dist/*
安全与最佳实践
-
依赖管理：精确指定依赖版本范围
dependencies = [ "requests>=2.25.0,<3.0.0", "numpy>=1.20.0; python_version>'3.7'" ] -
敏感信息保护：
- 永远不要将API令牌提交到版本控制
- 使用环境变量或密钥管理服务
-
发布前检查：
twine check dist/* python -m pip install --dry-run my-awesome-package
常见问题解决方案
版本冲突处理
当遇到依赖冲突时，可采用以下策略：
1. 使用pipdeptree分析依赖树
2. 在pyproject.toml中指定排除项：
[project]
dependencies = [
"package-a>=1.0",
"package-b>=2.0; not package-a==1.2.0"
]
发布失败恢复
若错误版本已发布：
1. 使用yank命令标记版本：
twine yank -r pypi my-awesome-package 0.1.0 --message "Broken release"
- 立即发布修正版本