pip包的发布

不同的分发格式

在 python setup.py sdist bdist_wheel 中，sdist 和 bdist_wheel 是两种不同的 Python 包分发格式，它们的含义如下：

1. sdist（Source Distribution）

sdist 表示 源代码分发包，它是包含项目源代码的压缩文件（通常是 .tar.gz 或 .zip 格式）。

特点

包含项目的完整源码，例如 .py 文件、配置文件、文档等。
通常依赖于 setup.py 或 pyproject.toml 文件中定义的安装脚本。
用户在安装时会通过源代码构建包，适合需要在安装时编译或生成文件的项目（如包含 C 扩展模块）。

生成文件

运行以下命令：

python setup.py sdist

生成的文件会存放在 dist/ 目录下，例如：

dist/
├── file-sync-tool-0.1.0.tar.gz

2. bdist_wheel（Binary Distribution Wheel）

bdist_wheel 表示 二进制分发包，它生成的是 Wheel 格式的包（文件扩展名为 .whl），这是现代 Python 包的标准分发格式。

特点

Wheel 包是一种预编译的格式，包含项目的打包文件和元数据，适合直接安装。
安装速度快，因为它不需要在安装时构建，只需解压并放置到目标目录即可。
适合纯 Python 项目或已编译的二进制模块（如 C 扩展）。

生成文件

运行以下命令：

python setup.py bdist_wheel

生成的文件会存放在 dist/ 目录下，例如：

dist/
├── file_sync_tool-0.1.0-py3-none-any.whl

文件名解释：

file_sync_tool: 包的名称。
0.1.0: 包的版本。
py3: 支持的 Python 版本。
none: 平台标识（表示与平台无关）。
any: 适用于任何操作系统。

3. 两者的区别

特性	Source Distribution (sdist)	Wheel (bdist_wheel)
文件格式	`.tar.gz` 或 `.zip`	`.whl`
是否包含源码	包含完整的源码	通常不包含源码，包含已编译文件
安装时是否需构建	需要构建（如编译 C 扩展）	不需要构建，安装速度快
适用场景	开发者需要源码或自定义构建环境	适用于分发和快速安装
兼容性	更通用	针对特定 Python 版本和平台优化
依赖工具	依赖 `setup.py` 和 `pip`	需要 `wheel` 库支持

4. 使用建议

开发和调试：
- 使用 sdist，因为它包含源码，方便调试和修改。
发布和分发：
- 使用 bdist_wheel，因为 Wheel 包更轻量、安装速度更快。
混合发布：
- 通常会同时生成 sdist 和 bdist_wheel，以满足不同的用户需求。命令：
```
python setup.py sdist bdist_wheel
```

5. 现代工具替代（推荐）

现代 Python 构建工具（如 build）简化了包的生成流程，无需直接运行 setup.py，推荐如下：

安装 build：
```
pip install build
```
使用 build 构建包：
```
python -m build
```
输出：
- dist/ 目录下会生成 .tar.gz 和 .whl 文件。

总结

sdist：生成源代码分发包（.tar.gz），包含项目的所有源码文件。
bdist_wheel：生成二进制分发包（.whl），优化安装速度和兼容性。
推荐使用现代工具（如 build）来生成和管理分发包。

通过生成 sdist 和 bdist_wheel，你可以将包发布到 PyPI，让用户根据需要选择最适合的安装方式。

发布全流程

以下是发布一个 Python 包到 PyPI 的完整流程总结，涵盖从项目准备到发布的所有关键步骤：

1. 准备项目代码

确保项目代码符合标准的 Python 包结构。一个典型的目录结构如下：

my_project/
├── my_package/               # 主包目录
│   ├── __init__.py           # 包初始化文件
│   ├── module1.py            # 模块1
│   └── module2.py            # 模块2
├── setup.py                  # 包的元数据和构建配置
├── README.md                 # 包的说明文档
├── LICENSE                   # 开源许可证
├── pyproject.toml            # 构建配置（可选，推荐）
└── tests/                    # 测试目录（可选）
    ├── test_module1.py
    └── test_module2.py

文件说明

my_package/：主包目录，存放实际代码模块。
__init__.py：初始化文件，标识该目录是一个 Python 包。
setup.py：定义包的元数据和依赖项。
README.md：描述包的用途和安装使用方法，用于 PyPI 页面显示。
LICENSE：指定开源协议（如 MIT、Apache 2.0）。
pyproject.toml（推荐）：构建工具的配置文件。
tests/：包含测试代码，确保包的质量。

2. 编写 `setup.py` 文件

setup.py 是包的构建和发布核心文件，示例如下：

from setuptools import setup, find_packages

setup(
    name="my_package",                     # 包的名称（pip install my_package）
    version="0.1.0",                       # 版本号，遵循语义化版本（MAJOR.MINOR.PATCH）
    description="A description of my package",  # 简短描述
    long_description=open("README.md").read(),  # 详细描述，从 README.md 中读取
    long_description_content_type="text/markdown",  # README 的格式
    author="Your Name",                    # 作者名
    author_email="your_email@example.com", # 作者邮箱
    url="https://github.com/yourusername/my_project",  # 项目主页（如 GitHub）
    license="MIT",                         # 开源许可证
    packages=find_packages(),              # 自动发现包
    install_requires=[                     # 必需的依赖项
        "requests>=2.25.0",
        "numpy",
    ],
    classifiers=[                          # 分类信息
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires=">=3.6",               # 支持的 Python 版本
)

3. 可选的 `pyproject.toml` 文件

pyproject.toml 是推荐的新构建标准，用于替代部分 setup.py 功能。示例：

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

4. 准备打包工具

确保安装了以下工具，用于构建和发布包：

pip install setuptools wheel twine

5. 打包项目

在项目根目录，运行以下命令以生成分发文件：

python setup.py sdist bdist_wheel

输出的文件会存放在 dist/ 目录下，例如：

dist/
├── my_package-0.1.0.tar.gz  # 源代码分发包（sdist）
└── my_package-0.1.0-py3-none-any.whl  # 二进制分发包（Wheel）

6. 测试包（可选）

在上传到 PyPI 前，可以在本地或 Test PyPI 环境中测试包的安装。

安装本地包

pip install dist/my_package-0.1.0-py3-none-any.whl

上传到 Test PyPI

上传到 Test PyPI：

twine upload --repository-url https://test.pypi.org/legacy/ dist/*

从 Test PyPI 安装：

pip install -i https://test.pypi.org/simple/ my_package

7. 上传到 PyPI

1. 确保已经注册 PyPI 账户

注册 PyPI 账号：PyPI 官网
安装 twine：
```
pip install twine
```

2. 上传包到 PyPI

twine upload dist/*

上传成功后，包会在 PyPI 的项目页面上可见。

8. 用户安装和验证

用户可以通过 pip 安装发布的包：

pip install my_package

验证包的功能是否正常运行。

9. 发布后的维护

更新包

修改代码并更新版本号（例如从 0.1.0 更新到 0.2.0）。

重新打包并上传：

python setup.py sdist bdist_wheel
twine upload dist/*

发布文档

在 GitHub 或 ReadTheDocs 上维护完整的使用文档。
更新 README.md，让用户了解新功能或修复。

监控使用情况

定期查看 PyPI 的下载数据。
收集用户反馈，修复问题或添加新功能。

完整流程总结

准备项目代码：确保代码结构清晰，包含必要的元数据文件。
编写 setup.py 和 pyproject.toml：定义包的元信息、依赖和构建规则。
安装构建工具：安装 setuptools、wheel 和 twine。
生成分发包：使用 python setup.py sdist bdist_wheel 打包。
测试包：在本地或 Test PyPI 环境中测试包的安装和运行。
发布到 PyPI：使用 twine upload 将包上传到 PyPI。
安装和验证：通过 pip install 测试包的安装和功能。
维护更新：根据用户反馈迭代更新包。

通过以上步骤，你可以将自己的 Python 包发布到 PyPI，并让全球的开发者通过 pip 安装和使用你的工具！

posted @ 2024-11-22 22:58 Gold_stein 阅读(5) 评论(0) 编辑收藏举报

刷新页面返回顶部

pip包的发布

pip包的发布

不同的分发格式

1. sdist（Source Distribution）

特点

生成文件

2. bdist_wheel（Binary Distribution Wheel）

特点

生成文件

3. 两者的区别

4. 使用建议

5. 现代工具替代（推荐）

总结

发布全流程

1. 准备项目代码

文件说明

2. 编写 setup.py 文件

3. 可选的 pyproject.toml 文件

4. 准备打包工具

5. 打包项目

6. 测试包（可选）

安装本地包

上传到 Test PyPI

7. 上传到 PyPI

1. 确保已经注册 PyPI 账户

2. 上传包到 PyPI

8. 用户安装和验证

9. 发布后的维护

更新包

发布文档

监控使用情况

完整流程总结

公告

2. 编写 `setup.py` 文件

3. 可选的 `pyproject.toml` 文件