hcpip 使用指南

通用 Python 项目打包 / 离线安装工具（HCAC soft department）。

使用 hcpip 看本文。改 hcpip 本身，见 DEVELOPMENT.md。

在业务项目根目录下执行 hcpip，可产出两类制品：

三种使用环境

两类构建产物（wheel / bundle zip）都会在产物目录附带独立安装脚本 install_bundle.py （仅标准库，随产物拷到目标机即可，不依赖 hcpip）。

安装

pip install hcpip          # 有网环境直接装
pip install hcpip-0.0.1-py3-none-any.whl   # 离线：hcpip self-pack 产出的 wheel 拷到目标机装

hcpip 是纯打包工具（不编译/加密源码），依赖打包工具链 setuptools / wheel / build / packaging，安装时自动带上。构建 --bundle 拉取依赖需要网络（一次），之后产物可离线部署。

业务项目要求

• 项目需有 pyproject.toml（含 [project] 的 name / version）；没有时 hcpip build 会自动生成最小模板（等价于先跑 hcpip init）；
• 源码布局 src/ 或平铺均可，包/模块由 setuptools 自动发现（python -m build / pip wheel 自行读取配置）；
• 第三方依赖在 [project].dependencies 声明，打包 / 安装时自动处理。

命令参考

hcpip build --wheel（源码 wheel，有外网部署）

hcpip build --wheel                    # 当前目录项目
hcpip build --wheel -p /path/to/proj   # 指定项目
hcpip build --wheel -o dist/           # 指定产物目录

产物：dist/<name>-<ver>-py3-none-any.whl（跨平台）+ dist/install_bundle.py（安装脚本，仅标准库）。

目标机部署（有外网、无需安装 hcpip）：

python install_bundle.py dist/<name>-<ver>-py3-none-any.whl    # 用附带的脚本安装
pip install dist/<name>-<ver>-*.whl                            # 或直接 pip 安装

脚本按后缀自动判别：.whl 走在线 pip install，支持 -i <pip 源> 与透传 pip 参数 （--upgrade / --target 等）；.zip 走 --no-index 离线安装。依赖由 pip 从源解析。

hcpip build --bundle（离线 bundle zip，无外网部署）

hcpip build --bundle                   # 当前目录项目
hcpip build --bundle --index-url https://mirrors.cloud.tencent.com/pypi/simple/   # 指定 pip 源
hcpip build --bundle --allow-sdist     # 允许源码包（个别依赖无预编译 wheel 时）

• 构建机需联网一次：pip wheel 拉取项目自身 wheel + 全部第三方依赖 wheel；
• 产物：dist/<name>-wheels-<ver>-<platform>.zip + dist/install_bundle.py（离线部署脚本，仅标准库）+ dist/SHA256SUMS；
• 目标机（离线）解压 zip 后 pip install --no-index --find-links=<解压目录> <全部wheel>，或直接用随 zip 交付的 install_bundle.py。

hcpip install（安装 wheel / 离线 zip）

hcpip install dist/<name>-<ver>-py3-none-any.whl     # 在线安装（拉依赖）
hcpip install dist/<name>-wheels-<ver>-win_amd64.zip  # 离线安装（--no-index）
hcpip install <whl> -i https://mirrors.cloud.tencent.com/pypi/simple/   # 在线安装指定源
hcpip install <whl> --upgrade                        # 其余参数原样透传 pip

按后缀自动判别：.whl 走在线 pip install；.zip 解压后 pip install --no-index --find-links 离线安装。制品之外的参数原样透传给 pip（--upgrade / --target / --user / --no-deps 等都能直接用）。

产物目录里附带的 install_bundle.py 与 hcpip install 是同一套安装逻辑——目标部署环境 不装 hcpip 时，把产物与脚本一起拷过去，python install_bundle.py <whl|zip> 即可完成同样安装。

hcpip self-pack（hcpip 自身打包成 wheel）

hcpip self-pack                    # 在 hcpip 源码根（含 pyproject.toml）执行
hcpip self-pack -s /path/to/hcpip -o dist/   # 指定源码根 / 产物目录

产出 dist/hcpip-0.0.1-py3-none-any.whl，拷到目标机器：

python -m venv .venv
.venv\Scripts\activate          # Linux: source .venv/bin/activate
pip install hcpip-0.0.1-py3-none-any.whl     # 之后 hcpip 命令可用

hcpip doctor / init / pip

hcpip doctor          # 检查 Python / pip 源 / setuptools / wheel / build / packaging
hcpip init            # 生成最小 pyproject.toml（自动探测包/模块，--force 覆盖）
hcpip pip install requests       # 等价于 python -m pip install requests

部署流程

在线部署（wheel）

# 构建机
pip install hcpip
hcpip build --wheel

# 目标机（需 Python + 网络）
pip install dist/<name>-<ver>-*.whl

离线部署（bundle）

# 构建机（与目标机同平台、联网一次）
hcpip build --bundle

# 目标机（离线，已装 Python）
python install_bundle.py dist/<name>-wheels-<ver>-<platform>.zip
# 或手动：解压 zip 后 pip install --no-index --find-links=<解压目录> <全部 wheel>

升级迭代（依赖不变）

pip install --upgrade --no-deps dist/<name>-<ver>-*.whl   # 只换项目 wheel，不重装依赖

注意事项

• bundle 需与目标机同平台构建（依赖 wheel 平台绑定）；源码 wheel 跨平台通用；
• 镜像源故障：pip 报 403 Forbidden 或 Could not find a version that satisfies 时换源即可：hcpip build --bundle --index-url <镜像>、hcpip install <whl> --index-url <镜像>；hcpip doctor 可查看当前 pip 源。可用镜像：腾讯云 https://mirrors.cloud.tencent.com/pypi/simple/、阿里云 https://mirrors.aliyun.com/pypi/simple/；
• hcpip build 完成后自动清理 build/ 与 *.egg-info 等中间产物，仅保留 dist/ 制品。