鸿蒙电脑开发 Python whl 打包

pip 能够确切通过命名来检索适合你的系统的 Python 软件分发包是什么，避免了下载不兼容包的问题。

制作第一个 whl 包

前面介绍了命名规范，我们可以简单理解，none-any形态的包是不依赖任何接口或 C 接口的，这次我们先介绍如何制作一个 none-any类型的包，这类包有充分的跨平台属性，不依赖任何 native 接口，仅需要依赖对应的 Python 运行时

环境准备

在鸿蒙电脑上制作 whl 包，需要具备 Python 环境和基础工具链，建议按照以下环境部署：

• 设备：我使用的 MateBook Pro 已经升级到 6.0.0.115版本，建议升级到该版本以上
• 工具链：应用市场安装 DevBox
• Python 环境：应用市场安装 Python 安装器

在终端中执行 python --version、git version、clang --version确保以上环境部署成功，如图所示

安装打包工具

接下来需要安装几个 python 的打包工具，在终端中依次执行下面的命令

• wheel

python -m pip install wheel 

看到以下结果证明安装成功，wheel 工具安装到 /storage/Users/currentUser/.local下

• build

python -m pip install build 

build 安装结果同理

• pytest

python -m pip install pytest 

pytest 安装结果同理

编写工程代码

我们编写一个典型案例 simple_math，包含加减乘除的封装库 工程结构如下：

simple_math/
├── src/ #源码顶层目录
│   └── simple_math/ #但功能模块目录
│       ├── __init__.py
│       ├── add.py #加法
│       ├── sub.py #减法
│       ├── mult.py #乘法
│       └── div.py #除法
├── test/
│   └── test_ops.py #测试程序
├── examples/
│   └── example.py #使用示例程序
├── README.md #说明文档
├── LICENSE #许可证
└── pyproject.toml #TOML 配置文件

分别编写这些文件

• src/simple_math/add.py

def add(a: float, b: float) -> float:
    """
    将两个数字相加
    Args:
        a (float): 第一个数字
        b (float): 第二个数字
    Returns:
        float: 两个数字的和
    """
    return float(a + b)

• src/simple_math/div.py

def div(a: float, b: float) -> float:
    """
    将第一个数字除以第二个数字
    Args:
        a (float): 被除数
        b (float): 除数
    Returns:
        float: 两个数字的商
    Raises:
        ZeroDivisionError: 当除数为零时抛出
    """
    if b == 0:
        raise ZeroDivisionError("除数不能为零")
    return float(a / b)

• src/simple_math/sub.py

def sub(a: float, b: float) -> float:
    return float(a - b)

• src/simple_math/mult.py

def mult(a: float, b: float) -> float:
    return float(a * b)

src/simple_math/init.py

""" 简单数学计算包 提供加减乘除基本运算 """
__version__ = "0.1.0"
# 导入所有功能，方便用户直接使用
from .add import add
from .sub import sub
from .mult import mult
from .div import div

• test/test_ops.py（可选）

import pytest
from simple_math.add import add
from simple_math.sub import sub
from simple_math.mult import mult
from simple_math.div import div

class TestAdd:
    """测试加法功能"""
    def test_add(self):
        assert add(2, 3) == 5.0

class TestSub:
    """测试减法功能"""
    def test_sub(self):
        assert sub(5, 3) == 2.0

class TestMult:
    """测试乘法功能"""
    def test_mult_positive_numbers(self):
        assert mult(2, 3) == 6.0

class TestDiv:
    """测试除法功能"""
    def test_div(self):
        assert div(6, 3) == 2.0
    def test_div_by_zero(self):
        with pytest.raises(ZeroDivisionError):
            div(5, 0)

• examples/example.py（可选）

#!/bin/env python3
from simple_math import add, sub, mult, div

def main():
    """演示所有功能的使用"""
    print("=== math_ops 包使用示例 ===\n")
    # 演示数学运算
    print("数学运算:")
    print(f"2 + 3 = {add(2, 3)}")
    print(f"5 - 3 = {sub(5, 3)}")
    print(f"2 * 3 = {mult(2, 3)}")
    print(f"6 / 3 = {div(6, 3)}")
    print("\n" + "="*40 + "\n")
    # 演示错误处理
    print("错误处理:")
    try:
        result = div(5, 0)
        print(f"5 / 0 = {result}")
    except ZeroDivisionError as e:
        print(f"错误：{e}")

if __name__ == "__main__":
    main()

编写打包信息

• pyproject.toml

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

[project]
name = "simple-math"
version = "0.1.0"
description = "一个简单的数学计算"
readme = "README.md"
requires-python = ">=3.8"
license = {text = "MIT"}
authors = [
    {name = "your_name", email = "[email protected]"}
]
keywords = ["math", "calculator", "hello-world", "example"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Education",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.8",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Topic :: Education",
    "Topic :: Software Development :: Libraries :: Python Modules",
]
dependencies = []

[project.urls]
Homepage = "https://example.com/yourusername/simple-math"
Documentation = "https://example.com/yourusername/simple-math#readme"
Repository = "https://example.com/yourusername/simple-math"
Issues = "https://example.com/yourusername/simple-math"

[tool.setuptools]
package-dir = {"" = "src"}

[tool.setuptools.packages.find]
where = ["src"]

# 配置测试命令
[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v"

这里对配置文件做下拆解

1、构建系统配置

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

作用：定义构建工具和依赖

• requires：构建项目所需的工具（如 setuptools 和 wheel）
• build-backend：指定构建后端（setuptools）

2、项目元数据

[project]
name = "simple-math"
version = "0.1.0"
description = "一个简单的数学计算"
readme = "README.md"
requires-python = ">=3.8"
license = {text = "MIT"}
authors = [
    {name = "your_name", email = "[email protected]"}
]
keywords = ["math", "calculator", "hello-world", "example"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Education",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.8",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Topic :: Education",
    "Topic :: Software Development :: Libraries :: Python Modules",
]
dependencies = []

• name/version：包名和版本号
• description：项目简介
• readme：README 文件路径
• requires-python：Python 版本要求（≥3.8）
• license：MIT 许可证
• authors：作者信息
• keywords：关键词标签
• classifiers：项目分类（如开发状态、目标用户、编程语言）
• dependencies：项目依赖（当前为空）

3、项目 URL

[project.urls]
Homepage = "https://example.com/yourusername/simple-math"
Documentation = "https://example.com/yourusername/simple-math#readme"
Repository = "https://example.com/yourusername/simple-math"
Issues = "https://example.com/yourusername/simple-math"

提供项目主页、文档、仓库和问题跟踪链接

4、包发现配置

[tool.setuptools]
package-dir = {"" = "src"}
[tool.setuptools.packages.find]
where = ["src"]

• package-dir：源码目录（src）
• packages.find：在 src 目录下查找包

5、测试配置

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v"

• testpaths：测试目录（tests）
• addopts：测试运行参数（详细输出 -v）

写好 README 和 LICENSE 文件（不详细介绍）

执行打包动作

完成上述所有动作就可以进行打包了

# 确保你在项目根目录（有 pyproject.toml 的目录）
cd simple_math
# 使用现代构建打包
python -m build --wheel

此时我们再次查看工程目录，可以看到多了一个 build 目录，包含 dist 和 lib 目录，这部分均为打包文件，生成的 whl 包在 dist 下，名称为 simple_math-0.1.0-py3-none-any.whl，属于我们期望的 none-any类型，另外 egg 也正常产生了

本地安装和运行测试

# 安装 wheel 包
python -m pip install dist/simple_math-0.1.0-py3-none-any.whl
# 测试安装是否成功
python -c "import simple_math; print(simple_math.__version__)"

结果如下则证明安装成功，simple-math安装到 ~/.local/lib/python3.12/site-packages/simple_math目录下

也可通过 pip 查询如下

python -m pip list | grep simple-math

# 运行测试
pytest

测试结果如下

卸载

通过 python -m pip uninstall <module>可以卸载我们安装的软件包

# 卸载模块
python -m pip uninstall simple_math

可以看到在用户同意后（Y），我们刚安装的 simple_math模块已经移除，在 pip list以及 ~/.local/lib/python3.12/site-packages目录下均无法查询到对应的模块

同样通过测试手法也无法成功

总结