我要评论下面用一个完整、可运行的示例，从零开始演示：
- 如何自己构建一个 python 包
- 如何打包成
.whl文件 - 如何用
.whl文件安装这个包
会覆盖到常用的配置文件、目录结构和具体命令。
一、准备一个最简单的包示例
假设我们要发布一个叫做 mypackage 的包，里面只有一个函数：add(a, b)，返回两个数的和。
1. 创建项目目录
在任意目录下创建项目根目录，例如：
mkdir mypackage-project cd mypackage-project
项目最终结构大致如下（先给一个概览，后面逐个创建）：
mypackage-project/ ├─ src/ │ └─ mypackage/ │ ├─ __init__.py │ └─ core.py ├─ tests/ │ └─ test_core.py # 可选 ├─ pyproject.toml ├─ readme.md └─ license # 可选
说明：
- 使用
src/目录结构是目前官方推荐的做法，能避免一些导入问题。mypackage是发布后用户import时用到的包名。
二、编写包的源码
1. 创建src/mypackage目录
mkdir -p src/mypackage
2. 创建__init__.py
__init__.py 表示这是一个包，并且可以在这里定义对外暴露的接口。
src/mypackage/__init__.py：
""" mypackage 一个示例 python 包，用于演示如何打包并生成 whl 文件。 """ from .core import add __all__ = ["add"] __version__ = "0.1.0"
3. 创建核心模块core.py
src/mypackage/core.py：
def add(a: float, b: float) -> float:
"""返回两个数字的和"""
return a + b
三、配置打包：pyproject.toml
从 python 3.8+ 开始，推荐使用 pep 517/518 的 pyproject.toml 来管理构建配置，这也是目前最主流、官方推荐的方式，比老的 setup.py 更简单清晰。
在项目根目录创建 pyproject.toml：
[build-system]
# 指定构建后端，常用的有 setuptools、hatchling、poetry 等
# 这里使用 setuptools 作为示例
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "mypackage" # 包名（发布到 pypi 时的名字）
version = "0.1.0" # 版本号
description = "a simple demo package for building wheel files."
readme = "readme.md" # 项目说明文件
requires-python = ">=3.8"
license = {text = "mit"} # 简单写法，也可以引用 license 文件
authors = [
{ name="your name", email="you@example.com" }
]
# 安装此包时所需的依赖
dependencies = [
# "requests>=2.0.0", # 示例：如果你的包依赖 requests
]
# 给工具和用户看的分类信息，可选
classifiers = [
"programming language :: python :: 3",
"programming language :: python :: 3 :: only",
"license :: osi approved :: mit license",
"operating system :: os independent",
]
# 可选：项目主页、代码仓库等
[project.urls]
"homepage" = "https://example.com/mypackage"
"source" = "https://github.com/yourname/mypackage"
核心点：
[build-system]告诉pip等工具如何构建你的包。[project]描述这个包的元数据（名字、版本号、依赖等）。
四、可选：readme.md和license
在项目根目录下创建一个简单的 readme.md（安装后在 pypi 上会展示）：
readme.md：
# mypackage 一个示例 python 包，用于演示如何从零构建并生成 `.whl` 文件。 ## 安装 ```bash pip install mypackage
五、使用
from mypackage import add print(add(1, 2)) # 输出: 3
许可证 `license` 可以写常见的 mit、apache-2.0 等，这里略过内容。 --- ## 五、可选：添加简单测试 虽然不是构建 whl 必需的，但建议有基本测试。 ```bash mkdir tests
tests/test_core.py：
from mypackage import add
def test_add():
assert add(1, 2) == 3
assert add(-1, 1) == 0
可以用 pytest 来跑测试：
pip install pytest pytest
六、构建.whl文件
1. 安装构建工具
推荐使用 build（官方推荐构建前端）：
pip install build
2. 在项目根目录执行构建命令
确保当前路径是 mypackage-project 的根目录（和 pyproject.toml 同级）：
python -m build
执行成功后，你会看到类似输出，并在项目目录下生成两个目录：
dist/
mypackage-0.1.0-py3-none-any.whl
mypackage-0.1.0.tar.gz
其中：
.whl是你想要的 “轮子” 文件（wheel）.tar.gz是源码包（source distribution）
如果只想生成 wheel，可以：
python -m build --wheel
七、使用.whl文件安装包
1. 在本机安装
假设当前仍在 mypackage-project 目录下：
pip install dist/mypackage-0.1.0-py3-none-any.whl
安装后可以在任意地方使用：
>>> from mypackage import add >>> add(2, 5) 7
2. 在另一台机器或离线环境安装
只需要把 dist/mypackage-0.1.0-py3-none-any.whl 拷贝到目标机器上，然后执行：
pip install mypackage-0.1.0-py3-none-any.whl
不需要源代码，也不需要联网（前提是你的包没有需要在线安装的新依赖，或者依赖也通过 whl 提前准备好）。
八、常见配置文件和写法汇总
1. 必需文件（最简）
pyproject.tomlsrc/mypackage/__init__.py- 你的实际代码文件（如
src/mypackage/core.py）
2. 推荐增加的文件
readme.mdlicensetests/目录（配合 pytest）
3.pyproject.toml常见字段说明（setuptools 方式）
[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "mypackage"
version = "0.1.0"
description = "..."
readme = "readme.md"
requires-python = ">=3.8"
license = {text = "mit"}
authors = [
{ name="your name", email="you@example.com" }
]
dependencies = [
"requests>=2.0.0",
"numpy>=1.24",
]
classifiers = [
"programming language :: python :: 3",
"license :: osi approved :: mit license",
]
[project.urls]
"homepage" = "..."
"source" = "..."
"bug tracker" = "..."
九、补充：使用传统setup.py的方式（可选了解）
虽然现在更推荐 pyproject.toml，但很多老项目仍在用 setup.py。
如果你想了解一下传统方式，可以这样：
1. 创建setup.py
在项目根目录创建 setup.py：
from setuptools import setup, find_packages
setup(
name="mypackage",
version="0.1.0",
description="a simple demo package for building wheel files.",
author="your name",
author_email="you@example.com",
packages=find_packages(where="src"),
package_dir={"": "src"},
python_requires=">=3.8",
install_requires=[
# "requests>=2.0.0",
],
)
2. 构建 whl
pip install wheel setuptools python setup.py bdist_wheel
会在 dist/ 下生成 .whl 文件，同样可以用 pip install 安装。
注意：
新项目优先用pyproject.toml，setup.py更适合作为兼容旧项目的方式。
十、完整示例小结
- 创建目录结构：
mypackage-project/ ├─ src/ │ └─ mypackage/ │ ├─ __init__.py │ └─ core.py ├─ pyproject.toml ├─ readme.md └─ tests/...
pyproject.toml用 setuptools 作为构建后端- 写好代码和
__init__.py - 安装构建工具：
pip install build - 在项目根执行：
python -m build --wheel - 在
dist/中得到.whl文件 - 使用
pip install dist/xxx.whl安装使用
总结
到此这篇关于python构建包打包.whl文件及使用.whl文件安装包的文章就介绍到这了,更多相关python打包.whl文件及使用内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！
发表评论