如何构建 Python 包的源发行版

简介

本教程将指导你完成构建 Python 包源发行版的过程。无论你是在开发一个可复用的模块还是一个成熟的应用程序，了解如何打包和分发你的 Python 代码都是一项至关重要的技能。在本教程结束时，你将能够创建一个专业级别的 Python 包，其他人可以轻松地共享和安装它。

理解 Python 包

什么是 Python 包？

Python 包是按层次结构组织的 Python 模块的集合，它有助于实现更好的代码组织、可复用性和分发。包提供了一种将相关模块组合在一起的方式，使代码的管理和维护更加容易。

模块与包

Python 模块是一个包含定义和语句的单个 Python 文件。模块可以在其他 Python 脚本或程序中导入和使用。另一方面，包是一个包含一个或多个 Python 模块以及一个 __init__.py 文件的目录，该文件用于定义包的结构和行为。

使用包的优点

模块化：包允许你将代码组织成逻辑单元，使其更易于管理和维护。
可复用性：包使你能够在不同项目中复用代码，提高代码复用率和效率。
命名空间管理：包通过为模块提供层次结构来帮助管理命名空间冲突。
分发：包可以轻松地分发和安装，便于与他人共享你的代码。

Python 包的结构

一个 Python 包通常由以下元素组成：

__init__.py：该文件是一个目录被识别为包所必需的。它可以包含初始化代码、包级变量等。
module1.py：作为包一部分的一个 Python 模块文件。
module2.py：作为包一部分的另一个 Python 模块文件。
subpackage/：一个包含其他模块或子包的子目录。

graph TD
    package[my_package] --> init[__init__.py]
    package --> module1[module1.py]
    package --> module2[module2.py]
    package --> subpackage[subpackage/]
    subpackage --> submodule[submodule.py]

导入包和模块

要使用一个包或模块，你需要导入它。以下是一个示例：

## 导入整个包
import my_package

## 从包中导入特定模块
from my_package import module1

## 从模块中导入特定函数
from my_package.module2 import my_function

通过理解 Python 包的概念，你可以有效地组织代码，并将你的工作作为可复用组件进行分发。

打包你的 Python 模块

理解 setup.py 文件

setup.py 文件是 Python 包分发的核心。它包含有关你的包的元数据，例如名称、版本、作者、描述和依赖项。以下是一个 setup.py 文件的示例：

from setuptools import setup, find_packages

setup(
    name='my_package',
    version='1.0.0',
    description='A sample Python package',
    author='LabEx',
    packages=find_packages(),
    install_requires=[
        'numpy>=1.19.2',
        'pandas>=1.1.3',
    ],
)

创建源发行版

要创建你的 Python 包的源发行版，你可以使用 setuptools 库。请按以下步骤操作：

在你的包的根目录中创建 setup.py 文件。
打开终端并导航到你的包的根目录。
运行以下命令来创建源发行版：
```
python setup.py sdist
```
这将在你的包的根目录中创建一个 dist 目录，其中包含一个 .tar.gz 文件，这就是你的包的源发行版。

源发行版的结构

Python 包的源发行版通常包含以下文件：

my_package/：包含你的包的模块和子包的目录。
my_package.egg-info/：有关你的包的元数据，包括 PKG-INFO 文件。
setup.py：用于构建和分发你的包的文件。
MANIFEST.in：一个可选文件，用于指定要包含在发行版中的其他文件。

graph TD
    dist[dist/] --> tarball[my_package-1.0.0.tar.gz]
    root[my_package/] --> init[__init__.py]
    root --> module1[module1.py]
    root --> module2[module2.py]
    root --> setup[setup.py]
    root --> manifest[MANIFEST.in]
    root --> egginfo[my_package.egg-info/]
    egginfo --> pkginfo[PKG-INFO]

通过创建你的 Python 包的源发行版，你可以轻松地与他人共享你的代码并使其可供安装。

分发你的 Python 包

上传到 PyPI

Python 包索引（PyPI）是 Python 包的官方仓库。要在 PyPI 上分发你的包，请按以下步骤操作：

在 PyPI 网站上创建一个账户。
安装 twine 包，它用于将你的包上传到 PyPI：
```
pip install twine
```
运行以下命令来上传你的包：
```
python setup.py sdist
twine upload dist/*
```
这将创建源发行版，然后将其上传到 PyPI。

安装你的包

一旦你的包在 PyPI 上可用，用户可以使用 pip 命令安装它：

pip install my_package

这将从 PyPI 下载并安装你的包的最新版本。

版本控制与语义化版本控制

在分发你的包时，使用语义化版本控制来指示包中的更改级别非常重要。语义化版本控制遵循 MAJOR.MINOR.PATCH 格式，其中：

MAJOR 版本更改表示不兼容的 API 更改。
MINOR 版本更改表示以向后兼容的方式添加的新功能。
PATCH 版本更改表示错误修复或其他小更改。

这有助于用户了解你的包中的更改级别，并相应地计划他们的升级。

托管你自己的包仓库

如果你不想在 PyPI 上分发你的包，你可以托管自己的包仓库。有几种选择，例如：

通过托管自己的包仓库，你可以对你的包的分发和版本控制有更多的控制权。

通过遵循这些步骤，你可以成功地将你的 Python 包分发给更广泛的社区并使其可供安装。

总结

在这个全面的 Python 教程中，你已经学习了为你的 Python 包构建源发行版的基本步骤。从理解 Python 打包的基础知识到分发你的包，你现在已经掌握了将你的 Python 代码打包并与全世界分享的知识和工具。通过遵循这些最佳实践，你可以确保你的 Python 包对用户来说易于访问、安装和维护。