将Python项目封装为Python库(wheel)

核心关键词: Python，SDK，pip，路径依赖

1.前言

在开发过程中，我们常常需要复用代码和功能，而Python库（Python Package）正是为了实现这一目的而诞生的。Python库将开发者编写的代码模块集合在一起，通过标准化的方式进行分发，使得导入库变得更加便捷、优雅。

1.1 什么是Python库，为何要使用Python库

1.1.1 什么是Python库

Python Wheel（.whl）是一种打包格式，是Python社区推荐的现代化发布格式，它是为了提升包的安装速度和简化安装过程而设计的。Wheel 是与源代码分发相比的一个优化格式，因为 Wheel 是预编译的，所以用户不需要在安装时进行编译过程，从而大大减少了安装时间。

对于我们的应用场景来说，Python Wheel更像是一种集合工具，它可以将我们编写的库通过pip install后放在site-packages下自动进行路径解析，用来替代传统代码导包而需要不断寻找项目依赖路径的工具。

1.1.2 为何要使用Python Wheel？

安装速度快：Wheel 是一个二进制格式，安装时不需要编译，可以节省大量的时间，特别是对于有C扩展的库。
兼容性：Wheel 提供了跨平台的支持。它能根据不同的 Python 版本、操作系统架构（如 x86、x64）自动选择合适的 Wheel 文件进行安装。
更好的用户体验：Wheel 能让用户快速安装库，避免了编译时的依赖和配置问题，简化了安装过程。
方便分发：将项目打包为 Wheel 文件后，便于分发，且可以通过 PyPI 或其他渠道发布，用户可以用 pip 轻松安装。

2. 将Python项目封装为Wheel格式的pip包

2.1 准备工作

你可以使用 pip 安装 setuptools 的最新版本：

pip install --upgrade setuptools[core]

你也可以：

pip install --upgrade build

每个 Python 包必须提供一个 pyproject.toml 并指定它想要使用的后端（构建系统）。然后可以使用任何提供 build sdist -类功能的工具来生成该分发。

请注意：由于恶意代码和受限于python版本，setup.py的构建方式已经被社区标注为弃用。

项目结构：标准的 Python 项目结构通常如下：

my_package/
├── my_package/
│   ├── __init__.py
│   └── your_module.py
├── pyproject.toml
├── README.md
└── LICENSE

编写 pyproject.toml 文件：pyproject.toml 是打包和发布到 PyPI 时的核心文件，它定义了项目的元数据和安装需求。一个简单的 pyproject.toml 文件如下：

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

[tool.setuptools.packages.find]
include = ["data_evaluation.*"] # 库包含的目录
exclude = ["logs", "test.py", ".gitignore"] # 库不包含的目录

[project]
name = "data_evaluation" # 项目名
version = "0.0.1" # 版本号
description = "Implementation of VLA datasets evaluation" # 描述
readme = "README.md" # 说明文件
requires-python = ">=3.5" # python版本
license = { text = "MIT" }  # license
classifiers = [
    'Intended Audience :: Developers',
    'Operating System :: OS Independent',
    'Programming Language :: Python :: 3',
    'License :: OSI Approved :: MIT License'
] # 分类
dependencies = [
    "opencv-python>=4.5.1",
    "numpy>=1.21.0",
    "pandas>=1.3.0",
    "matplotlib>=3.4.0",
    "openai>=0.11.0",
    "scikit-learn>=0.24.0",
    "scikit-image>=0.18.0",
    "scipy>=1.7.0",
    "dashscope>=0.0.3",
    "oss2>=2.15.0",
    "pyyaml>=5.4.1",
    "tqdm>=4.61.0"
] # 依赖

[tool.setuptools.sdist]
formats = ["zip", "tar.gz"]

[tool.setuptools.package_data]
"data_evaluation" = [
    "README.md",
    "LICENSE"
]

# [tool.setuptools.entry_points]
# If you have any CLI commands to add, uncomment and adjust
# console_scripts = [
#     "data-evaluation-cli = data_evaluation.cli:main"
# ]

# [tool.setuptools.options]
# Ensure it generates correct package
# packages = find:

编写 __init__.py 文件：__init__.py 文件使 my_package 目录成为一个包，可以为空，但可以包含一些初始化代码。

2.2 构建Wheel包

接下来，我们将项目构建为 Wheel 格式的包。确保你已经在第一步安装了必要的构建工具：

构建Wheel包：使用以下命令构建 Wheel 格式的包：

python -m build

这条命令会生成一个 dist/ 目录，里面包含了 .tar.gz 源代码包和 .whl 二进制包。

2.3 测试

接下来你可以在一个新的环境中使用

pip install .\dist\data_evaluation-0.0.1-py3-none-any.whl

来尝试这个依赖，按照正常流程，这个wheel会按照我们在pyproject.toml中写的依赖进行安装。

随后测试该包的dir

import data_evaluation

print(dir(data_evaluation))

['**doc**', '**file**', '**loader**', '**name**', '**package**', '**path**', '**spec**', 'evaluation', 'modules', 'utils']

至此我们已经可以对该包文件进行分发。

3.发布到PyPI(可选)

完成构建后，我们将 Wheel 文件上传到 PyPI，让其他开发者能够方便地使用 pip 安装。

安装 twine：twine 是一个用于安全上传包到 PyPI 的工具。安装命令：
```
pip install twine
```
上传Wheel包到PyPI：使用 twine 上传构建好的包：
```
twine upload dist/*
```
如果上传成功，其他用户可以通过以下命令安装你的包：
```
pip install my_package
```

#Python #Pip #Wheel