shipcli 0.0.1

Pure Python CLI scaffold and delivery tool.

shipcli

shipcli 是一个纯 Python 的 CLI 脚手架与交付工具，用来初始化、构建、发布、安装和升级命令行项目。

特性

• 用 shipcli init <path> 快速生成新的 Python CLI 项目
• 用 shipcli build / shipcli build --release 生成 dev 或 release 版的 wheel/sdist 分发文件
• 用 shipcli publish 把 release 版本发布到 GitHub Release 或 PyPI
• shipcli upgrade / uninstall 只管 shipcli 自身；项目 CLI（如 demo-cli）用其自带命令管理
• 默认以当前目录作为项目目录，也支持 --project <path> 跨目录操作
• 初始化后的项目默认包含 help、version、upgrade、uninstall 命令示例

命令作用范围

命令	作用对象
init / build / install / publish	目标项目（当前目录或 --project，如 demo-cli）
upgrade / uninstall	shipcli 自身

若要升级或卸载某个项目 CLI（如 demo-cli），应先 install 安装它，再用其自带命令：demo-cli upgrade / demo-cli uninstall。

安装

首次安装（开发）

shipcli 未发布到 PyPI 前，从本地仓库安装：

git clone <your-repo-url>
cd shipcli
python3 -m pip install -e .   # editable 安装，改代码即生效

安装完成后：

shipcli --help
shipcli --version             # 形如：shipcli 0.0.1 (editable)

--version / --help 会标注当前安装形态：editable（editable 安装）、installed（pip 正式安装）、binary（PyInstaller 二进制）。

安装 build 产物

shipcli build 产出 wheel/sdist 后，可直接装本地 wheel（模拟用户从 PyPI 安装）：

shipcli build --release
python3 -m pip install .build/dist/0.0.1/dist/*.whl

快速开始

shipcli init demo-cli

cd demo-cli
shipcli build                    # dev 构建，产出 <version>.devN
shipcli build --release          # release 构建，产出发布版 wheel/sdist
shipcli publish --github --pypi  # 发布到 GitHub Release + PyPI

也支持不切目录，直接指定目标项目：

shipcli build --project ./demo-cli
shipcli publish --project ./demo-cli --github --github-repo owner/demo-cli

构建

shipcli build 产出标准的 Python 分发文件（wheel/sdist），不再依赖 PyInstaller：

• dev 构建（shipcli build）：版本号 <base>.devN（如 0.0.1.dev1），build 号自动 +1。用于本地验证。
• release 构建（shipcli build --release）：版本号取配置中的 version（如 0.0.1）。
• 版本递增（--increase <major|minor|patch>）：构建前把版本号指定位 +1（低位归零）并重置 build，可与 --release 同用。

版本号唯一真源是 build.config.json 的 version；release 构建会自动同步到 pyproject.toml，构建时会写入包 __init__.py 的 __version__。

shipcli build                              # dev 构建
shipcli build --release                    # release 构建
shipcli build --increase patch             # patch+1 后 dev 构建
shipcli build --increase minor --release   # minor+1 后 release 构建

产物目录结构：

.build/dist/<version>/dist/
├── <name>-<version>-py3-none-any.whl
└── <name>-<version>.tar.gz

升级 shipcli 自身

shipcli upgrade                       # 从 PyPI 升级到最新发布版
shipcli upgrade --version 0.0.1       # 从 PyPI 升级到指定发布版
shipcli upgrade --local .             # 从本地项目 build 产物升级（取最新版本）
shipcli upgrade --local . --version 0.0.1.dev1   # 指定本地 build 产物版本
shipcli uninstall                     # 卸载 shipcli（pip 卸载 + 清理本地痕迹）

dev 版不上 PyPI，仅本地安装/升级：先 shipcli build 产出 dev wheel，再用 shipcli upgrade --local . 装上。

发布

• shipcli publish 只做发布，不负责构建
• 发布前先执行 shipcli build --release
• 发布到 GitHub Release：上传 wheel/sdist 及各自的 .sha256 校验文件
• 发布到 PyPI：上传 wheel/sdist
• GitHub 凭证只从环境变量读取：SHIPCLI_GITHUB_TOKEN 或 GITHUB_TOKEN
• GitHub 仓库可通过 --github-repo 传入，或设置 SHIPCLI_GITHUB_REPO / GITHUB_REPOSITORY
• PyPI 凭证只从环境变量读取：SHIPCLI_PYPI_TOKEN，也兼容现有 TWINE_PASSWORD
• publish 只支持 release 版本，不接受 dev 版本

cd demo-cli

# 发布本地已构建的 release 分发文件到 GitHub Release + PyPI
shipcli build --release
SHIPCLI_GITHUB_TOKEN=... SHIPCLI_PYPI_TOKEN=... \
shipcli publish --github --pypi --github-repo owner/demo-cli

初始化后的目录结构

执行 shipcli init demo-cli 后，默认会生成：

demo-cli/
├── build.config.json
├── README.md
├── demo_cli/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py
│   └── commands/
│       ├── __init__.py
│       ├── help.py
│       ├── version.py
│       ├── upgrade.py
│       └── uninstall.py
└── tests/
    └── test_cli.py

开发验证

python3 -m pytest
shipcli build --release