shipcli 0.0.1__py3-none-any.whl

shipcli/scaffold.py

@@ -0,0 +1,411 @@
+"""shipcli 项目脚手架生成器。"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+
+def default_package_name(app_name: str) -> str:
+    """把应用名规范化为可用的 Python 包名。"""
+    package = app_name.strip().lower().replace("-", "_").replace(" ", "_")
+    package = re.sub(r"[^a-z0-9_]", "", package)
+    package = re.sub(r"_+", "_", package).strip("_")
+    return package or "mycli"
+
+
+def create_project(
+    target_dir: Path,
+    app_name: str,
+    package_name: str,
+    force: bool = False,
+) -> None:
+    """创建一个新的 CLI 项目骨架。"""
+    if target_dir.exists() and any(target_dir.iterdir()) and not force:
+        raise FileExistsError(f"目标目录非空：{target_dir}")
+
+    package_dir = target_dir / package_name
+    commands_dir = package_dir / "commands"
+    tests_dir = target_dir / "tests"
+    target_dir.mkdir(parents=True, exist_ok=True)
+    commands_dir.mkdir(parents=True, exist_ok=True)
+    tests_dir.mkdir(parents=True, exist_ok=True)
+
+    config = {
+        "app_name": app_name,
+        "entry": f"{package_name}/__main__.py",
+        "build_root": ".build",
+        "version": "0.1.0",
+        "build": 0,
+    }
+    (target_dir / "build.config.json").write_text(
+        json.dumps(config, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    (target_dir / "pyproject.toml").write_text(
+        _pyproject(app_name, package_name),
+        encoding="utf-8",
+    )
+    (target_dir / "README.md").write_text(
+        _readme(app_name, package_name),
+        encoding="utf-8",
+    )
+    (package_dir / "__init__.py").write_text(
+        '__all__ = ["__version__"]\n__version__ = "0.1.0"\n',
+        encoding="utf-8",
+    )
+    (package_dir / "__main__.py").write_text(
+        _main_py(package_name),
+        encoding="utf-8",
+    )
+    (package_dir / "cli.py").write_text(
+        _cli_py(app_name, package_name),
+        encoding="utf-8",
+    )
+    (commands_dir / "__init__.py").write_text("", encoding="utf-8")
+    (commands_dir / "help.py").write_text(_help_py(), encoding="utf-8")
+    (commands_dir / "version.py").write_text(
+        _version_py(app_name, package_name),
+        encoding="utf-8",
+    )
+    (commands_dir / "upgrade.py").write_text(
+        _upgrade_py(app_name),
+        encoding="utf-8",
+    )
+    (commands_dir / "uninstall.py").write_text(
+        _uninstall_py(app_name),
+        encoding="utf-8",
+    )
+    (tests_dir / "test_cli.py").write_text(
+        _test_cli(package_name),
+        encoding="utf-8",
+    )
+
+
+def _pyproject(app_name: str, package_name: str) -> str:
+    """生成项目 pyproject.toml。"""
+    return f"""[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "{app_name}"
+version = "0.1.0"
+description = "A Python CLI initialized by shipcli."
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  {{ name = "your-name" }}
+]
+
+[project.optional-dependencies]
+build = [
+  "build>=1.2.2"
+]
+publish = [
+  "twine>=5.1.0"
+]
+
+[project.scripts]
+{app_name} = "{package_name}.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["{package_name}*"]
+"""
+
+def _readme(app_name: str, package_name: str) -> str:
+    """生成项目 README。"""
+    return f"""# {app_name}
+
+一个由 `shipcli` 初始化的 Python CLI 项目。
+
+## 运行
+
+```bash
+python3 -m {package_name} --help
+python3 -m {package_name} help
+python3 -m {package_name} version
+python3 -m {package_name} upgrade
+python3 -m {package_name} uninstall
+```
+"""
+
+
+def _main_py(package_name: str) -> str:
+    """生成模块入口文件。"""
+    return f'''"""{package_name} 模块入口。"""
+
+from __future__ import annotations
+
+import sys
+
+from {package_name}.cli import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+'''
+
+
+def _cli_py(app_name: str, package_name: str) -> str:
+    """生成最小 CLI 分发器。"""
+    return f'''"""{package_name} CLI 主入口。"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from {package_name}.commands.help import run_help
+from {package_name}.commands.uninstall import run_uninstall
+from {package_name}.commands.upgrade import run_upgrade
+from {package_name}.commands.version import run_version
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """构造顶层参数解析器。"""
+    parser = argparse.ArgumentParser(prog="{app_name}", description="{app_name} CLI")
+    parser.add_argument("--version", action="store_true", help="显示版本号")
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    sub.add_parser("help", help="显示帮助信息")
+    sub.add_parser("version", help="输出当前版本")
+    upgrade = sub.add_parser("upgrade", help="升级当前 CLI")
+    upgrade.add_argument("--version", default=None, help="升级到指定版本")
+    upgrade.add_argument("--local", default=None, help="从本地项目路径的 build 产物升级")
+    sub.add_parser("uninstall", help="卸载当前 CLI")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """解析命令行并分发子命令。"""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.version:
+        return run_version(args)
+    if args.command == "help":
+        return run_help(parser)
+    if args.command == "version":
+        return run_version(args)
+    if args.command == "upgrade":
+        return run_upgrade(args)
+    if args.command == "uninstall":
+        return run_uninstall(args)
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+'''
+
+
+def _help_py() -> str:
+    """生成示例 help 命令。"""
+    return '''"""示例 help 命令。"""
+
+from __future__ import annotations
+
+import argparse
+
+
+def run_help(parser: argparse.ArgumentParser) -> int:
+    """输出当前 CLI 的帮助信息。"""
+    parser.print_help()
+    return 0
+'''
+
+
+def _version_py(app_name: str, package_name: str) -> str:
+    """生成示例 version 命令。"""
+    return f'''"""示例 version 命令。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from {package_name} import __version__
+
+
+def run_version(args: Any) -> int:
+    """输出当前 CLI 的版本号。"""
+    print("{app_name} " + __version__)
+    return 0
+'''
+
+
+def _uninstall_py(app_name: str) -> str:
+    """生成示例 uninstall 命令：pip 卸载 + 清理本地痕迹。"""
+    return f'''"""示例 uninstall 命令。"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+APP_NAME = "{app_name}"
+
+
+def run_uninstall(args: Any) -> int:
+    """卸载当前 CLI：pip 卸载包，并清理本地安装目录与符号链接。"""
+    subprocess.run(
+        [sys.executable, "-m", "pip", "uninstall", "-y", APP_NAME, "--disable-pip-version-check"],
+        check=False,
+    )
+    install_dir = Path.home() / f".{{APP_NAME}}-cli"
+    for link_dir in (Path("/usr/local/bin"), Path.home() / ".local" / "bin"):
+        link_path = link_dir / APP_NAME
+        if link_path.exists() or link_path.is_symlink():
+            link_path.unlink(missing_ok=True)
+    if install_dir.exists():
+        shutil.rmtree(install_dir)
+    print(f"已卸载：{{APP_NAME}}")
+    return 0
+'''
+
+
+def _upgrade_py(app_name: str) -> str:
+    """生成示例 upgrade 命令：默认 PyPI，--local 走本地 build 产物。"""
+    return f'''"""示例 upgrade 命令。"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+APP_NAME = "{app_name}"
+
+
+def run_upgrade(args: Any) -> int:
+    """升级当前 CLI：默认从 PyPI 拉发布版，--local 从本地 build 产物装。"""
+    try:
+        if getattr(args, "local", None):
+            version = _upgrade_from_local(Path(args.local).resolve(), args.version)
+        else:
+            version = _upgrade_from_pypi(args.version)
+    except Exception as exc:  # noqa: BLE001
+        print(f"错误: {{exc}}")
+        return 1
+    print(f"升级完成：{{version}}")
+    return 0
+
+
+def _upgrade_from_pypi(version: str | None) -> str:
+    """从 PyPI 升级到最新或指定发布版本。"""
+    spec = [APP_NAME, "--upgrade"] if version is None else [f"{{APP_NAME}}=={{version}}"]
+    subprocess.run(
+        [sys.executable, "-m", "pip", "install", *spec, "--disable-pip-version-check"],
+        check=True,
+    )
+    return version or "latest"
+
+
+def _upgrade_from_local(project_root: Path, version: str | None) -> str:
+    """从本地项目的 build 产物升级；version 缺省取最新版本。"""
+    resolved = version or _latest_product_version(project_root)
+    wheel = _find_local_wheel(project_root, resolved)
+    subprocess.run(
+        [sys.executable, "-m", "pip", "install", "--force-reinstall", str(wheel), "--disable-pip-version-check"],
+        check=True,
+    )
+    return resolved
+
+
+def _find_local_wheel(project_root: Path, version: str) -> Path:
+    """定位本地某版本 build 产物中的 wheel 文件。"""
+    config_path = project_root / "build.config.json"
+    config = json.loads(config_path.read_text(encoding="utf-8"))
+    build_root = config.get("build_root", ".build")
+    dist_dir = project_root / build_root / "dist" / version / "dist"
+    wheels = sorted(dist_dir.glob("*.whl")) if dist_dir.is_dir() else []
+    if not wheels:
+        raise FileNotFoundError(
+            f"未找到本地 {{version}} 的 wheel：{{dist_dir}}，请先执行 build 构建"
+        )
+    return wheels[0]
+
+
+def _latest_product_version(project_root: Path) -> str:
+    """返回本地 build 产物目录中最新的版本。"""
+    config_path = project_root / "build.config.json"
+    config = json.loads(config_path.read_text(encoding="utf-8"))
+    build_root = config.get("build_root", ".build")
+    dist = project_root / build_root / "dist"
+    if not dist.is_dir():
+        raise FileNotFoundError(f"构建产物目录不存在：{{dist}}")
+    candidates = []
+    for sub in dist.iterdir():
+        if sub.is_dir() and (sub / "dist").is_dir() and any((sub / "dist").glob("*.whl")):
+            candidates.append(sub.name)
+    if not candidates:
+        raise FileNotFoundError(f"未找到可升级产物：{{dist}}")
+    candidates.sort(key=_version_sort_key)
+    return candidates[-1]
+
+
+def _version_sort_key(version_str: str) -> tuple:
+    """给 release/dev 版本字符串生成排序键（兼容 .devN 与 -devN）。"""
+    base = version_str
+    dev = 0
+    for sep in (".dev", "-dev"):
+        if sep in base:
+            base, dev_part = base.split(sep, 1)
+            dev = int(dev_part)
+            break
+    segments = base.split(".")
+    if len(segments) != 3 or not all(seg.isdigit() for seg in segments):
+        return (0, 0, 0, 0, 0)
+    major, minor, patch = (int(seg) for seg in segments)
+    is_release = 0 if (".dev" in version_str or "-dev" in version_str) else 1
+    return (major, minor, patch, is_release, dev)
+'''
+
+
+def _test_cli(package_name: str) -> str:
+    """生成最小命令测试。"""
+    return f'''import subprocess
+
+
+def test_help_runs():
+    out = subprocess.run(
+        ["python3", "-m", "{package_name}", "--help"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    text = out.stdout + out.stderr
+    assert "help" in text
+    assert "version" in text
+    assert "upgrade" in text
+    assert "uninstall" in text
+
+
+def test_help_command_runs():
+    out = subprocess.run(
+        ["python3", "-m", "{package_name}", "help"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    text = out.stdout + out.stderr
+    assert "help" in text
+    assert "version" in text
+    assert "upgrade" in text
+    assert "uninstall" in text
+
+
+def test_version_runs():
+    out = subprocess.run(
+        ["python3", "-m", "{package_name}", "version"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert "0.1.0" in out.stdout
+'''

shipcli/version.py

@@ -0,0 +1,95 @@
+"""shipcli 版本展示辅助。"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import shipcli
+
+
+def display_version() -> str:
+    """返回打包时写入的 CLI 展示版本。"""
+    return shipcli.__version__
+
+
+def install_mode() -> str:
+    """判断当前 shipcli 的安装形态：binary / editable / installed。
+
+    - binary:   PyInstaller 打包的可执行文件
+    - editable: pip editable 安装，命令直接跑源码目录
+    - installed: pip 正式安装，命令跑 site-packages 里的打包快照
+    """
+    if getattr(sys, "frozen", False):
+        return "binary"
+
+    package_file = getattr(shipcli, "__file__", None)
+    if not package_file:
+        return "installed"
+
+    package_path = Path(package_file).resolve()
+    site_packages = _site_packages()
+    in_site = any(_is_relative_to(package_path, sp) for sp in site_packages)
+
+    if not in_site:
+        # 源码目录（不在 site-packages）→ editable 开发安装。
+        return "editable"
+
+    # 在 site-packages 内：再区分 editable 与正式安装。
+    if _has_editable_marker(package_path):
+        return "editable"
+    return "installed"
+
+
+def display_version_with_mode() -> str:
+    """返回带安装形态标记的版本字符串。"""
+    return f"{display_version()} ({install_mode()})"
+
+
+def _site_packages() -> list[Path]:
+    """收集当前解释器的 site-packages 目录。"""
+    candidates: list[Path] = []
+    try:
+        import site
+
+        candidates.extend(Path(p).resolve() for p in site.getsitepackages())
+        candidates.append(Path(site.getusersitepackages()).resolve())
+    except Exception:  # noqa: BLE001 - 退化时按 sys.path 兜底
+        pass
+    candidates.extend(Path(p).resolve() for p in sys.path if p)
+    return candidates
+
+
+def _is_relative_to(path: Path, base: Path) -> bool:
+    """兼容旧 Python 的相对路径判断。"""
+    try:
+        path.relative_to(base)
+        return True
+    except ValueError:
+        return False
+
+
+def _has_editable_marker(package_path: Path) -> bool:
+    """判断 site-packages 内的包是否为 editable 安装。
+
+    editable 安装会留下 `__editable__.<name>-<ver>.pth` 或
+    `<name>-<ver>.dist-info/direct_url.json`（含 "dir" 字段）。
+    """
+    parent = package_path.parent
+    for entry in parent.iterdir():
+        name = entry.name
+        if name.startswith("__editable__") and name.endswith(".pth"):
+            return True
+        if entry.is_dir() and entry.name.endswith(".dist-info"):
+            direct_url = entry / "direct_url.json"
+            if direct_url.is_file():
+                try:
+                    import json
+
+                    data = json.loads(direct_url.read_text(encoding="utf-8"))
+                    if "dir" in data:
+                        return True
+                except Exception:  # noqa: BLE001 - 解析失败按非 editable 处理
+                    continue
+    return False
+

shipcli-0.0.1.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: shipcli
+Version: 0.0.1
+Summary: Pure Python CLI scaffold and delivery tool.
+Author: CaffeineOddity
+License-Expression: MIT
+Keywords: cli,scaffold,pyinstaller,release,tooling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: build
+Requires-Dist: pyinstaller>=6.0; extra == "build"
+Provides-Extra: publish
+Requires-Dist: twine>=5.1.0; extra == "publish"
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: pytest>=9.0.0; extra == "dev"
+Dynamic: license-file
+
+# 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 前，从本地仓库安装：
+
+```bash
+git clone <your-repo-url>
+cd shipcli
+python3 -m pip install -e .   # editable 安装，改代码即生效
+```
+
+安装完成后：
+
+```bash
+shipcli --help
+shipcli --version             # 形如：shipcli 0.0.1 (editable)
+```
+
+`--version` / `--help` 会标注当前安装形态：`editable`（editable 安装）、`installed`（pip 正式安装）、`binary`（PyInstaller 二进制）。
+
+### 安装 build 产物
+
+`shipcli build` 产出 wheel/sdist 后，可直接装本地 wheel（模拟用户从 PyPI 安装）：
+
+```bash
+shipcli build --release
+python3 -m pip install .build/dist/0.0.1/dist/*.whl
+```
+
+## 快速开始
+
+```bash
+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
+```
+
+也支持不切目录，直接指定目标项目：
+
+```bash
+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__`。
+
+```bash
+shipcli build                              # dev 构建
+shipcli build --release                    # release 构建
+shipcli build --increase patch             # patch+1 后 dev 构建
+shipcli build --increase minor --release   # minor+1 后 release 构建
+```
+
+产物目录结构：
+
+```text
+.build/dist/<version>/dist/
+├── <name>-<version>-py3-none-any.whl
+└── <name>-<version>.tar.gz
+```
+
+## 升级 shipcli 自身
+
+```bash
+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 版本
+
+```bash
+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` 后，默认会生成：
+
+```text
+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
+```
+
+## 开发验证
+
+```bash
+python3 -m pytest
+shipcli build --release
+```