外观
14 - 怎样把脚本交给别人运行:项目结构、依赖声明与打包
摘要
日志统计脚本在作者目录能运行,复制到另一台机器却找不到模块。本文把脚本整理成可安装的命令行工具,解释源码布局、构建系统、wheel 与依赖锁定,并用隔离安装验证交付边界。
版本范围:示例项目声明 Python 3.13 及以上,专栏主线为 CPython 3.14。构建后端固定
setuptools==80.9.0,运行时无第三方依赖。独立函数示例在 CPython 3.14.0 与 3.13.7 通过;wheel 构建、隔离安装及入口验证使用 Windows x64 的完整 CPython 3.13.7。
1. 场景:源码路径帮你隐藏了安装缺陷
教学场景中,日志工具通过 from series_logcount.cli import count_levels 导入统计函数。作者在项目目录运行成功,复制文件后导入失败。原因可能是当前目录恰好进入导入搜索路径,而交付物没有包含真正的包;也可能是依赖装在另一个解释器、资源文件遗漏,或用户用错误入口启动。 可进一步阅读systemd启动就绪与时间基础:启动环境和进程托管影响已安装服务。
先把这次成功归到正确层:源码函数可运行、wheel包含所需文件、新环境可导入、安装入口可调用,是四份不同证据。前一项成立不会自动推出后一项。本篇沿“源码→构建产物→目标环境→公开入口”追踪同一个日志工具;每跨一步,就核对代码来自哪里、依赖由谁提供、用户实际启动了什么。只提醒别人改sys.path或复制整份虚拟环境,仍会把作者机器的偶然条件带到交付边界。
本篇将前面日志脚本变成小型 distribution(分发包,供安装工具识别的交付单元)。用户安装后获得 series-logcount 命令,无需知道源码路径。为了把结构机制讲清楚,运行时依赖保持为空;构建工具则单独声明并固定版本。
2. import package 与 distribution 不是同一名称空间
import package(导入包)是 import series_logcount 使用的名称;分发包名是安装工具与元数据中的标识,例如 python-series-logcount。二者不必相同,一个分发包可以提供多个导入包,名称里的连字符也不能直接作为普通导入标识符使用。
遇到“装了却导入不了”,先用这两个名称定位失效层:安装元数据识别的是分发包,import寻找的是它提供的模块。python-series-logcount已安装,不代表存在同名带连字符的导入包;本例应验证 series_logcount。接着确认安装和执行使用同一解释器,再看产物内容与实际模块位置。反复尝试拼写变体,只会把名称映射和环境错误混在一起。
示例采用 src layout(源码放在 src 目录中的布局),将项目根与导入包位置分开。直接站在项目根并不自动让 src/series_logcount 成为可导入包,必须安装或显式设置开发路径。这个小障碍可以揭露“只有源码目录碰巧支持,安装后却失败”的问题。
__init__.py 标识本例的普通包,保持内容简单,避免导入时执行外部操作。命令入口在 cli.py,纯统计函数与参数解析分开,方便独立调用和验证。更大项目可以进一步分模块,但不需要一开始创建空的 controller、service、repository 层级来表现规范。
3. pyproject.toml 把构建与项目元数据分开
pyproject.toml 使用 TOML 格式,是现代 Python 项目的常见配置入口。[build-system] 声明构建需要哪些包,以及由哪个 backend(构建后端)把源码变成交付物。frontend(构建前端)如 pip 调用后端协议,通常在隔离构建环境中准备后端依赖。Packaging 官方指南解释了这两个配置职责。
[project] 声明项目名称、版本、支持的 Python 范围和运行依赖。[project.scripts] 声明安装时生成的命令入口,右侧指向 模块:可调用对象。它不是把整个 Python 源码编译成原生可执行程序,而是由安装工具生成启动脚本或平台相关启动器,调用指定函数。
构建依赖和运行依赖必须区分。示例构建需要 setuptools,但统计函数只用标准库;用户运行工具不必因此依赖 setuptools 的全部构建功能。开发测试工具同样不应该无条件进入运行依赖,否则用户安装会带入不必要组件,也可能扩大升级冲突。
隔离构建不等于隔离所有风险。前端仍然需要取得声明的构建依赖;源码包构建会运行后端代码。应从可信来源取得依赖,固定必要版本,并记录来源。网络不可达时不能将“代码语法正确”写成已经验证安装。
4. 最小项目的全部文件
目录 examples/14_project/pyproject.toml 包含以下结构:
text
14_project/
├── pyproject.toml
└── src/
└── series_logcount/
├── __init__.py
└── cli.pypyproject.toml 完整内容:
toml
[build-system]
requires = ["setuptools==80.9.0"]
build-backend = "setuptools.build_meta"
[project]
name = "python-series-logcount"
version = "0.1.0"
description = "A bounded log counting example"
requires-python = ">=3.13"
dependencies = []
[project.scripts]
series-logcount = "series_logcount.cli:main"
[tool.setuptools.packages.find]
where = ["src"]__init__.py 内容如下:
python
"""日志统计教学包,无外部运行时依赖。"""cli.py 的完整代码如下:
python
"""支持安装后的命令入口,也支持 python -m 调用。"""
import argparse
import json
from pathlib import Path
def count_levels(path):
counts = {}
with Path(path).open(encoding="utf-8") as source:
for line in source:
if not line.strip():
continue
level = line.split(maxsplit=1)[0]
counts[level] = counts.get(level, 0) + 1
return counts
def main():
parser = argparse.ArgumentParser(description="Count log levels")
parser.add_argument("path", type=Path)
args = parser.parse_args()
print(json.dumps(count_levels(args.path), sort_keys=True))
if __name__ == "__main__":
main()统计规则保持有限:忽略空行,将第一段作为级别,不验证级别是否属于固定集合。这用于安装实验,不冒充通用日志解析器。真实格式应规定字段、编码、单行长度和错误处理,用户输入文件路径也需要符合业务授权边界。
5. 先对比源码执行,再验证真实安装
从仓库根运行以下命令,虚拟环境只创建到示例项目内;若网络需要代理,应按实际环境配置安装工具,不绕过证书检查:
powershell
python -m venv docs/python/examples/14_project/.venv
docs/python/examples/14_project/.venv/Scripts/python.exe -m pip wheel --no-deps --wheel-dir docs/python/examples/14_project/dist docs/python/examples/14_project
docs/python/examples/14_project/.venv/Scripts/python.exe -m pip install --no-deps docs/python/examples/14_project/dist/python_series_logcount-0.1.0-py3-none-any.whlpip wheel 需要获得声明的构建依赖;默认构建隔离使后端与运行环境分开。--no-deps 只是不为项目额外处理运行依赖,不等于禁止获取构建依赖。此处无运行依赖,因此参数适用于实验;真实项目不能盲目加它导致依赖遗漏。
生成演示文件并从源码树外调用,Windows 命令如下:
powershell
$demoLog = Join-Path $env:TEMP 'python-series-demo.log'
[System.IO.File]::WriteAllText($demoLog, "INFO boot`nERROR timeout`nERROR reset`n", [System.Text.UTF8Encoding]::new($false))
$logcountPython = (Resolve-Path 'docs/python/examples/14_project/.venv/Scripts/python.exe').Path
Push-Location $env:TEMP
try {
& $logcountPython -m series_logcount.cli $demoLog
} finally {
Pop-Location
}预期输出是 {"ERROR": 2, "INFO": 1}。安装入口也可通过 .venv/Scripts/series-logcount.exe 调用同一文件。Linux 与 macOS 的虚拟环境可执行文件位于 bin,启动脚本名称没有 Windows 的 .exe 后缀;不要将平台路径当成打包协议的一部分。
先预测一个更有区分力的结果:如果把命令入口指向不存在的模块,wheel还能构建和安装吗?后面的坏产物实验会回答:可以,安装零退出,调用入口却失败。因此这里从src目录导入成功只覆盖源码层;正例必须在新环境安装实际wheel,并站到源码树外调用公开入口。这条路径揭露包发现与入口错误,但没有验证的Python、OS和原生扩展平台仍不能称为兼容。
实际验证中,pip wheel 使用隔离构建环境生成 python_series_logcount-0.1.0-py3-none-any.whl,随后以 --no-index --no-deps 安装该文件。在另一个临时目录分别调用模块入口和安装生成的 series-logcount.exe,两者都输出 {"ERROR": 2, "INFO": 1};导入位置位于虚拟环境的 site-packages,而非源码树。这是本机产物与安装验证,不扩展为所有 Python 版本或平台都已测试。
另有 examples/14_packaging.py 提供不依赖构建网络的独立函数冒烟实验:
python
"""独立冒烟示例;真正的安装实战见旁边的 14_project。"""
import runpy
from pathlib import Path
from tempfile import TemporaryDirectory
if __name__ == "__main__":
module = runpy.run_path(str(Path(__file__).parent / "14_project/src/series_logcount/cli.py"))
with TemporaryDirectory() as directory:
path = Path(directory) / "demo.log"
path.write_text("INFO boot\nERROR timeout\nERROR reset\n", encoding="utf-8")
counts = module["count_levels"](path)
assert counts == {"INFO": 1, "ERROR": 2}
print("counts:", counts)执行 python docs/python/examples/14_packaging.py,预期得到两类计数。这个示例故意通过文件定位执行源码,它只验证函数,不证明 wheel 包含正确模块;不能拿它替代前面的安装实验。
6. wheel、sdist 与 editable 的不同证据
wheel 是一种已构建分发格式,安装时主要展开文件并处理元数据和入口。sdist(源码分发包)包含供后端构建的源码与配置,安装过程通常还需要构建。纯 Python wheel 常见标签是 py3-none-any;含原生扩展的 wheel 则可能绑定解释器 ABI 与平台,不能随便复制到其他环境。
editable install(可编辑安装)常用于开发,让源码修改直接反映到导入行为。它很方便,但可能掩盖正常 wheel 缺少资源、包发现错误或布局问题。因此开发期间可以使用 pip install -e,交付验收仍应至少安装一次实际构建产物。
资源文件也是容易遗漏的部分。源码目录中的模板、配置与数据不一定自动进入 wheel,包配置要明确包含范围。安装后读取资源应通过适当的包资源接口,不要假设当前工作目录是项目根,也不要沿相对路径寻找作者机器上的源码。
版本号是交付身份,不应只修改本地文件却复用同一个发布版本让缓存产生歧义。正式流程还要保存产物校验值和来源,但本篇不发布任何包。构建与本地隔离安装已经足以验证教学入口。
7. 依赖声明不是完整锁文件
依赖约束表达允许的版本范围,lock file(锁文件)表达某次解析得到的具体依赖集合,并可能记录哈希、来源和平台条件。库通常需要合理兼容范围,使下游应用能够组合依赖;应用部署则更关注实际选中的版本能否稳定复现。
本例明确 dependencies = [],因此没有第三方运行时依赖需要锁定;构建后端的直接版本已固定。但固定后端不等于生成了完整构建锁:Python、安装前端、后端的间接依赖以及包来源仍可能影响构建。不要把 == 写在一处就称为完全可复现。
pip freeze 展示当前环境的安装集合,可以帮助记录现场,但它可能混入无关开发工具,也不完整描述各平台条件、构建环境与来源。真实项目使用哪种锁定工具,应按部署方式和团队流程选择,并核验工具版本与锁文件行为。本文不推荐未验证的通用“一条命令保证复现”。
离线部署需要提前下载匹配平台的包,保存可信来源与哈希,再使用受控索引或本地目录安装。安装时 --no-index 禁止远端索引,--find-links 提供本地候选;这些参数必须与实际准备的依赖集合一致,缺包就应明确失败,不能临时放宽安全与版本约束。
7.1 产物验收比环境截图更直接
构建成功只说明后端完成了一次操作,不证明所有需要的代码和资源进入产物。可以用标准库 zipfile 查看 wheel 的文件列表,确认导入包、元数据和入口描述都存在。之后在新环境里安装,只调用公开入口,避免验收脚本依赖仓库的内部路径。这两个阶段分别覆盖产物内容与安装行为。
构建产物通常包含 .dist-info 元数据目录,其中描述分发身份、依赖与入口等信息。导入包可以没有与分发包同名的目录,不能因此判断 wheel 损坏。反过来,看到一个包目录也不证明入口元数据正确。检查时将名称、版本、支持的 Python 和脚本入口与配置逐项对应。
对于本例纯 Python 工具,可在目标解释器下验证导入、命令输入、错误文件路径和空日志。正式业务项目还要覆盖配置加载与包资源。错误输入是否返回非零退出状态、标准输出是否保持机器可解析、错误信息是否输出到合适通道,都属于 CLI(命令行接口)的交付契约。
7.2 安装工具属于环境的一部分
同一个 Python 版本搭配不同安装前端,可能出现不同的构建功能、诊断信息和解析结果。记录 python -m pip --version 可以确认工具来自哪个解释器,也帮助解释“同样命令在另一台机器行为不同”。这不要求永远冻结所有工具,但升级构建链应经过同样产物验收,而不是仅依靠版本兼容声明。
嵌入式 Python 发行版、受系统包管理器管理的环境和普通安装版,可能有不同的安装约束。不是每个解释器都自带 pip 与 venv,也不是每个环境都允许修改全局包。选择受支持的隔离环境构建,不应将缺少安装工具理解为项目源码错误。专栏运行用的隔离解释器与项目打包环境也可以分别记录。
本篇安装命令使用项目内虚拟环境,避免将依赖写入读者全局 Python。网络离线时应保留明确失败状态,准备后端包后再构建。若已经通过受控本地 wheel 仓库验证,应记录仓库来源;若只执行了函数冒烟,就如实说明尚未验证构建,不能把不同证据合并。
7.3 相对路径与用户输入要分别处理
源码中的相对路径通常相对当前工作目录,而不是当前模块所在目录。用户传入的 demo.log 也应根据 CLI 的约定解析,通常尊重用户工作目录。内置模板则应通过包资源定位。这两类路径若混用,工具可能在作者目录正确、调度器目录失败,或悄悄读取到错误文件。
把工作目录换成临时目录,只改变一项条件:撤掉源码树给import和相对路径提供的帮助。若模块仍来自site-packages,命令仍能处理指定日志,说明这次参与运行的确是安装产物。然后再改变用户输入文件的位置,检查读取目标跟随CLI参数,而非模块目录。内置资源走包资源定位、用户文件遵守命令参数,两条路径有不同所有者,不能共用“当前目录应该没变”的假设。
产物验收还应避免可编辑安装残留。如果环境之前装过源码映射,新 wheel 缺少文件却可能仍能从源码位置导入。因此本篇强调新建虚拟环境,且安装前确认没有同名分发残留。失败时查看导入模块的 __file__ 和分发元数据,能判断实际执行来自哪一份文件;只看输出正确无法证明被验收的产物真的参与运行。
当工具需要升级时,保留旧版本输入样本,对新 wheel 运行相同契约测试。这样目录结构重构、依赖更新和入口修改都能接受同一组验收。打包质量最终体现在用户环境中的行为,而不是配置文件长短。
纯 Python 项目也可能因文件系统大小写、默认编码或路径处理在不同平台出错。wheel 标签表示安装兼容范围,不表示业务已经在所有平台实际验证。本篇显式 UTF-8、使用 Path 并说明平台命令差异,减少常见变量;仍需要在目标部署系统运行同一入口,才能确认完整兼容性。
8. 踩坑与面试延伸
装在虚拟环境里为什么仍导入失败? 先核对 sys.executable,确保运行解释器就是安装目标,再确认分发包提供的导入名称与 wheel 内容。不要只根据命令提示符是否显示环境名判断。
为什么 src 布局有用? 它减少项目根直接提供导入路径的偶然成功,迫使开发与验证关注安装关系。但布局本身不保证打包正确,仍需产物安装实验。
库依赖要全部固定吗? 下游库与部署应用目标不同;约束、锁定和产物记录要分开设计。过度固定库依赖可能造成冲突,完全不固定应用部署则增加解析漂移。
最常见的坑是用 sys.path.append 补救缺失安装,或者让命令依赖当前目录。前者把开发机器路径带入代码,后者让调度器、容器入口和用户目录改变时失败。正确入口应由安装生成,资源定位与业务输入路径分别处理。
安装成功后,怎样验证命令入口
继续使用同一项目和同一日志,仅将console script目标从 series_logcount.cli:main 改成不存在的 series_logcount.missing:main。14_artifact_failure.py在临时副本构建真实wheel,并在全新venv安装。沿前面的四层逐项观察:构建成功、安装成功,直到命令启动器导入目标模块才遇到ModuleNotFoundError。恢复正确入口,在另一个新环境重复同一路径,计数正确且模块来自site-packages。差异落在入口映射,不能用安装成功替它作保证。
powershell
python docs/python/examples/14_artifact_failure.py本实验已在CPython3.13.7、setuptools80.9.0执行通过,坏入口退出1、修复入口退出0。刻意使用 --no-build-isolation,调用环境必须已安装pyproject指定的setuptools;这是坏产物实验的受控选择,不能解释成默认构建隔离不重要。构建与安装还指定--no-index并禁用pip联网版本检查,本机首次版本检查等待导致90秒超时,改为完全离线路径后通过。更多执行范围见工程实践与验收手册。产物安装验证应该在源码树外完成,否则工作目录的同名包可能遮蔽缺失内容,让损坏包看起来正常。
独立能力任务:保留坏wheel安装成功与命令失败的两个退出码,再修复元数据,在全新环境重复完整路径。验收不能只写import成功,还要调用分发声明的命令,确认import位置。资源文件遗漏属于同一产物完整性类别,但本次实测选择入口损坏,不虚称资源遗漏实验也执行了。真实服务部署进一步对照HTTP与ASGI,安装健康和服务健康是不同检查。
完整坏产物对照脚本:
python
"""真实 wheel 的坏入口/修复入口对照:只操作临时副本。"""
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile
import venv
def run(arguments, cwd, expect=0):
result = subprocess.run(arguments, cwd=cwd, capture_output=True, text=True,
timeout=90, encoding="utf-8", errors="replace")
if expect == 0:
assert result.returncode == 0, result.stdout + result.stderr
else:
assert result.returncode != 0, "broken artifact unexpectedly worked"
return result
def main():
source = Path(__file__).with_name("14_project")
with tempfile.TemporaryDirectory() as directory:
work = Path(directory)
project = work / "project"
shutil.copytree(source, project, ignore=shutil.ignore_patterns("build", "*.egg-info", "__pycache__"))
original = (project / "pyproject.toml").read_text(encoding="utf-8")
for label, config in [("bad", original.replace("series_logcount.cli:main", "series_logcount.missing:main")),
("good", original)]:
(project / "pyproject.toml").write_text(config, encoding="utf-8")
wheels = work / f"wheels-{label}"
# 实验刻意关闭构建隔离,调用环境须已安装固定 setuptools。
run([sys.executable, "-m", "pip", "--disable-pip-version-check", "wheel", "--no-index", "--no-build-isolation", "--no-deps",
"--wheel-dir", str(wheels), str(project)], work)
environment = work / f"venv-{label}"
venv.EnvBuilder(with_pip=True).create(environment)
scripts = environment / ("Scripts" if sys.platform == "win32" else "bin")
python = scripts / ("python.exe" if sys.platform == "win32" else "python")
run([str(python), "-m", "pip", "--disable-pip-version-check", "install", "--no-index", str(next(wheels.glob("*.whl")))], work)
command = scripts / ("series-logcount.exe" if sys.platform == "win32" else "series-logcount")
log = work / "sample.log"
log.write_text("ERROR broken\nINFO ready\n", encoding="utf-8")
result = run([str(command), str(log)], work, expect=1 if label == "bad" else 0)
if label == "bad":
assert "ModuleNotFoundError" in result.stderr
else:
assert '"ERROR": 1' in result.stdout
location = run([str(python), "-c", "import series_logcount; print(series_logcount.__file__)"], work)
assert "site-packages" in location.stdout
print(label, "wheel installation succeeds; entry exit:", result.returncode)
if __name__ == "__main__":
main()9. 结尾
可交付的 Python 项目需要明确导入、构建、安装和入口边界,再用真实产物的隔离运行验证这些约定。
- 导入包名与分发包名不同,源码运行成功不证明安装正确。
- 构建依赖、运行依赖和开发工具分开声明,wheel 安装验证应覆盖入口与资源。
- 版本约束与锁定职责不同,复现还需要环境、来源和产物信息。