VisiData 的 Windows 安装包构建全流程:WinPython + PyInstaller + Inno Setup 实战

原创2026-09-24 20:47:161,711 阅读
文章标签:数据分析CLI数据可视化数据集成开发工具

VisiData 的 Windows 安装包构建全流程:WinPython + PyInstaller + Inno Setup 实战

VisiData(终端下的多维表格工具)本身是跨平台 Python 程序,但要在 Windows 上把它交付给「没有 Python 环境」的普通用户,就需要产出一个独立的 .exe 安装包。本文以仓库中的 vdwin-installer.md 为操作主线,完整讲解「WinPython 便携环境 → pip 安装 VisiData → PyInstaller 打包单文件 exe → Inno Setup 编译 setup 安装程序」的构建链路,并结合作品自带的 vdwin.py、vdwin.spec 与 setup.py 源码,说明每一步的底层原因与可验证依据。读完你既能照单复现 Windows 安装包,也能理解为何 Windows 打包比 Linux/macOS 多出 curses 与图标这两道工序。

为什么 Windows 版需要专门的打包方案

VisiData 是终端界面程序,交互层依赖 curses。在 Linux/macOS 上 curses 是系统自带库,但 Windows 的 Python 标准库并不包含 curses,必须借助第三方包 windows-curses 补齐。这一点在 setup.py 中有明确实现:

if not sysconfig.get_platform().startswith("mingw"):  # 2757
    install_requires += ['windows-curses >= 2.4.1; platform_system == "Windows"']   # 2119

也就是说,VisiData 本体在 pip 安装时就会针对 Windows 平台自动引入 windows-curses(最低 2.4.1,对应 issue #2119;同时排除 MSYS2/mingw 环境,对应 issue #2757)。而 vdwin(VisiData on Windows)这套安装包方案解决的是更进一步的问题:让最终用户无需安装 Python、无需打开命令行执行 vd,直接双击即可运行。仓库根目录的 README.md 将 VisiData 定位为 "terminal spreadsheet multitool",Windows 安装包正是把这一工具以桌面软件形态交付给终端用户的桥梁。

此外,从 setup.py 可确认项目要求 python_requires=">=3.8",因此打包所选用的 WinPython 发行版只要内置 Python 3.8 及以上即可,原文档示例采用 WinPython 的 python-3.9.4.amd64 完全满足要求。

第一步:准备 WinPython 便携环境

原文档给出的第一条命令是安装 WinPython:https://winpython.github.io/。

选择 WinPython 而非系统级 Python 安装包,原因很实际:

  • 免管理员权限:WinPython 是绿色便携发行版,解压即用,适合在 CI 或隔离构建机上打包;
  • 自带 Scripts 目录:解压后的目录形如 WinPY\python-3.9.4.amd64,其中 Scripts 下直接就有 pip3.exe、pyinstaller.exe 等命令行工具,后续所有命令都以 ./Scripts/xxx.exe 形式调用;
  • 版本可控:与 VisiData 要求的 python_requires=">=3.8"(见 setup.py)可精确对齐,避免宿主机器 Python 版本漂移导致打包产物不可用。

下载并解压后,在 PowerShell 或 CMD 中进入该目录:

cd WinPY\python-3.9.4.amd64

后续所有 ./Scripts/... 命令均在此目录下执行。

第二步:安装 VisiData 本体

在 WinPython 环境中安装发布版 VisiData:

./Scripts/pip3.exe install visidata

该命令从 PyPI 拉取 visidata 及其依赖(如 python-dateutil,见 setup.py 的 install_requires)。安装完成后,Windows 下会注册 vd 与 visidata 两个命令行入口——它们在 setup.py 中通过 entry_points 声明:

entry_points={
    "console_scripts": ["vd=visidata.main:vd_cli",
                        "visidata=visidata.main:vd_cli"],
},

两者都指向 visidata/main.py 中的 vd_cli(),即 VisiData 的统一 CLI 入口。

安装 develop 开发版(可选)

如果需要跟踪开发分支(对应本仓库 3.5dev 的开发版本线,见 setup.py),原文档给出两条附加命令:

./Scripts/pip3.exe install git+https://github.com/saulpw/visidata.git@develop

pip 会先克隆该 git 仓库,再以本地源码方式执行 setup.py 完成安装。需要留意的是:开发分支是持续变动的,产物稳定性不如 PyPI 发布版,只建议在调试新特性、复现开发版缺陷时使用。若后续还想回到稳定版,用 ./Scripts/pip3.exe install -U visidata 即可覆盖回 PyPI 版本。

第三步:补齐 Windows 终端依赖 windows-curses

./Scripts/pip3.exe install windows-curses

虽然第二步安装 visidata 时,setup.py 的条件依赖机制理论上会自动带上 windows-curses,但原文档仍显式执行此步。原因在于:

  1. 兜底保证:如果 pip 解析条件依赖失败、或使用了不经过 setup.py 依赖声明的安装方式(如直接克隆源码运行),显式安装可确保 curses 层可用;
  2. PyInstaller 打包需要:打包时 PyInstaller 需要能实际导入 windows-curses 提供的 _curses 扩展模块才能将其收进产物,显式安装能减少 hidden import 遗漏的风险。

VisiData 在 Windows 上若缺少该包,启动时会在初始化 curses 界面处直接报错,因此这是打包前必须验证的一环。

第四步:安装 PyInstaller

./Scripts/pip3.exe install pyinstaller

PyInstaller 负责把 Python 解释器、VisiData 代码与全部依赖冻结成 Windows 可执行文件。它有两个典型产物模式:

  • --onefile:所有内容合并进单个 exe,便于分发,但启动时会先解压到临时目录,首启略慢;
  • 默认 one-dir 模式:生成一个包含 exe 与依赖 dll/库文件的目录,启动快,但需要整目录分发。

本仓库的 vdwin.spec 就是 PyInstaller 的 one-dir 模式配置(含 Analysis / PYZ / EXE / COLLECT 四段标准结构),它与命令行参数是同一打包引擎的两种表达方式,可作为理解 PyInstaller 内部结构的参考。

第五步:获取 vdwin 启动器与图标

原文档要求克隆 Windows 启动器项目:

git clone https://github.com/saulpw/vdwin.git WinPy/vdwin

vdwin 项目为 Windows 打包提供两样东西:

  1. 启动脚本(原文档中名为 visidata.py):一个极薄入口,其职责等价于本仓库 platform/windows/vdwin.py 的实现:
from visidata.main import vd_cli
from visidata import vd

vd_cli()

也就是导入 visidata/main.py 的 vd_cli() 并调用,与仓库自身的 python -m visidata 入口(见 visidata/main.py)行为一致。之所以需要一个独立脚本,是为了给 PyInstaller 一个明确的「程序入口文件」,让打包器能顺着 import 链收集全部依赖。

  1. 应用图标:vdicon.ico。本仓库 platform/windows/vdicon.ico 即是该图标文件(256×256),打包时通过 --icon 参数嵌入 exe,让生成的程序在资源管理器里显示 VisiData 自己的图标而非 Python 默认图标。

第六步:用 PyInstaller 生成单文件 exe

核心打包命令:

./Scripts/pyinstaller.exe --onefile/-F --icon/-i ..\vdwin\vdicon.ico --name/-n VisiData ..\vdwin\visidata.py

参数逐一说明:

参数 简写 作用
--onefile -F 生成单文件 exe,用户拿到一个文件即可运行
--icon ..\vdwin\vdicon.ico -i 把 vdicon.ico 嵌入 exe 作为程序图标
--name VisiData -n 指定输出程序名为 VisiData.exe
末尾的脚本路径 — 指定打包入口,即 vdwin 项目中的 visidata.py(本仓库对应 platform/windows/vdwin.py)

原文档给出的产物路径是:

dist/visidata/visidata.exe

具体路径形态取决于打包模式与 --name:--onefile 模式下通常得到 dist\VisiData.exe 单文件;若参考本仓库 vdwin.spec 的 one-dir 写法(name='VisiData' + COLLECT),则会得到 dist\VisiData\VisiData.exe 目录形态。无论哪种形态,验证标准一致:双击能正常启动 VisiData 界面。首次启动建议在命令行中运行以观察 stderr 输出,若提示缺模块,说明存在 hidden import 问题,需要在 spec 文件的 hiddenimports 中补充(vdwin.spec 中该项为空,即当前依赖收集已足够)。

第七步:用 Inno Setup 编译 VisiData-setup.exe

Inno Setup Compiler (6.1.2)
vd.iss

PyInstaller 产出的是免安装的绿色 exe,而面向普通用户的正式交付通常需要一个「安装向导」。这一步用 Inno Setup Compiler 6.1.2 打开 vdwin 项目提供的 vd.iss 脚本并编译:

  • vd.iss 是 Inno Setup 的安装脚本(此脚本由外部 vdwin 项目维护,不在本仓库内;*.iss 在本仓库无匹配文件),其中会声明安装程序名称(对应 VisiData-setup.exe)、许可协议、安装目录(如 %LocalAppData%\Programs\VisiData 或 Program Files)、开始菜单快捷方式等;
  • 编译前需要在脚本的 [Files] 段把 Source 指向第六步生成的 exe 路径,例如 dist\VisiData.exe 或 dist\VisiData\VisiData.exe;
  • 编译产物 VisiData-setup.exe 即为最终可分发的安装包,用户双击后经向导完成安装并生成快捷方式。

Inno Setup 与 PyInstaller 的分工可以概括为:PyInstaller 负责「把 Python 程序变成 Windows 程序」,Inno Setup 负责「把 Windows 程序变成带安装向导的正式软件包」。

构建流程总览与验证清单

完整链路如下:

WinPython 便携 Python
   │  ./Scripts/pip3.exe install visidata
   │  ./Scripts/pip3.exe install windows-curses
   │  ./Scripts/pip3.exe install pyinstaller
   ▼
vdwin 项目(visidata.py 入口 + vdicon.ico 图标)
   │  pyinstaller --onefile --icon ..\vdwin\vdicon.ico --name VisiData ..\vdwin\visidata.py
   ▼
VisiData.exe(单文件/目录两种形态)
   │  Inno Setup 打开 vd.iss 并编译
   ▼
VisiData-setup.exe(最终安装包)

打包完成后建议按以下清单验收:

  1. 依赖完整性:在 WinPython 中先直接运行 ./Scripts/vd.exe sample.tsv(可用仓库 sample_data/sample.tsv 验证),确认 curses 界面正常,再做 PyInstaller 打包,可大幅减少「能 pip 运行、打包后却缺库」的返工;
  2. 产物可启动:双击 exe,确认界面渲染、方向键移动、q 退出均正常;
  3. 图标生效:exe 在资源管理器中显示 VisiData 图标(对应 vdicon.ico);
  4. setup 安装/卸载:在干净 Windows 环境(无 Python)安装 VisiData-setup.exe,验证普通用户开箱即用;
  5. 版本与来源一致:发布版走 PyPI 安装、开发版走 develop 分支安装,二者不要混用,避免交付物行为与预期不符。

延伸:不打包也能用的替代方案

如果你的受众本身具备 Python 环境,其实无需整套打包流程,直接 pip install visidata 后使用 vd / visidata 命令即可(两个入口由 setup.py 注册)。打包方案的价值在于把终端工具「产品化」:用户无需接触命令行、无需理解 Python 依赖,双击安装包即可获得完整的 VisiData 体验——这正是 vdwin-installer.md 这份构建文档存在的意义。

登录后查看全文
visidata