Metadata-Version: 2.4
Name: hcpip
Version: 0.0.1
Summary: 通用 Python 项目打包 / 离线安装工具（源码 wheel / 离线 bundle zip / 安装器）。
Author-email: Bo Fang <1163646804@qq.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: setuptools>=61.0
Requires-Dist: wheel>=0.40
Requires-Dist: build>=1.0
Requires-Dist: packaging>=23.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Provides-Extra: publish
Requires-Dist: twine>=7.0.0; extra == "publish"
Dynamic: license-file

# hcpip 使用指南

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

> 使用 hcpip 看本文。改 hcpip 本身，见 [DEVELOPMENT.md](docs/DEVELOPMENT.md)。

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

| 命令 | 产物 | 适用场景 |
|---|---|---|
| `hcpip build --wheel` | 源码 wheel（跨平台 `py3-none-any`）+ 安装脚本 `install_bundle.py` | 有外网：目标机 `python install_bundle.py <whl>` 或 `pip install` 即装 |
| `hcpip build --bundle` | 项目 wheel + 全部依赖 wheel 的离线 zip + 安装脚本 `install_bundle.py` | 无外网：一次拉齐依赖，目标机离线安装 |
| `hcpip install <制品>` | — | 安装项目 .whl 或离线 bundle .zip |
| `hcpip self-pack` | hcpip 自身 wheel | 把 hcpip 装进目标项目 venv |
| `hcpip doctor` | 环境诊断 | 检查打包环境 |
| `hcpip init` | 生成最小 pyproject.toml | 老项目起步 |
| `hcpip pip <参数...>` | — | 透传任意 pip 命令 |

## 三种使用环境

| 环境 | 是否安装 hcpip | 作用 |
|---|---|---|
| 项目开发环境 | hcpip 源码（本仓库） | 开发 / 修改 hcpip 本身（见 DEVELOPMENT.md） |
| 编译打包环境 | 是：`pip install hcpip`（hcpip wheel） | 在业务项目根跑 `hcpip build --wheel` / `--bundle`，产出 wheel / zip 并附 `install_bundle.py` |
| 目标部署环境 | 否：**不装 hcpip** | 只拿产物（.whl / .zip）与其附带的 `install_bundle.py`，`python install_bundle.py <制品>` 直接安装 |

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

## 安装

```bash
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，有外网部署）

```bash
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）：

```bash
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，无外网部署）

```bash
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）

```bash
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）

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

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

```bash
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

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

## 部署流程

### 在线部署（wheel）

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

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

### 离线部署（bundle）

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

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

### 升级迭代（依赖不变）

```bash
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/` 制品。
