README.dev.md

zsc 开发者指南（构建 & 发布）

zsc（全称 zig slice code）。本文记录当前在本机如何开发、构建并发布 zsc 到 PyPI。

语言 / Language: 中文 | English

---

本地开发环境

• 要求：

  • Python ≥ 3.7
  • 已安装 uv

• 创建/激活虚拟环境：

cd zsc
uv venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

• 本地可编辑安装：

uv pip install -e .[test]

• 验证已发布版本（可选，全局工具安装示例）：

# 使用 pip
pip install -U zsc

# 使用 uv tool
uv tool install zsc
uv tool install zsc --upgrade

# 或使用 zsc 自带的升级入口（内部优先尝试 uv，再自动回退到 pip）：
zsc -U

---

运行测试

所有与 zsc init . 相关的测试在 tests/ 目录下：

pytest -q

确保在构建/发布前测试全部通过。

---

构建发布包

使用 pyproject.toml + setuptools 构建，通过 uv 执行：

uv build

构建完成后，产物在 dist/ 目录下（包含 .whl 和 .tar.gz）。

---

发布到 PyPI

使用 uv 构建并上传，无需单独安装 twine。

1. 准备 PyPI 凭证（免每次输入）

uv 不会读取 ~/.pypirc，发布时若未提供凭证会交互式询问。要免输密码，请用环境变量：

• 在 PyPI 账号 → API tokens 创建 token（若已有 ~/.pypirc，其中 password 即 token）。
• 在 shell 配置里写死一次（推荐），之后 uv publish 不再询问：

  # 写入 ~/.zshrc 或 ~/.bashrc
  export UV_PUBLISH_TOKEN=pypi-xxxxxxxx你的token

  保存后执行 source ~/.zshrc（或重新开终端）。
• 或当次终端有效：export UV_PUBLISH_TOKEN=pypi-xxx 再执行 uv publish。
• 或每次命令行传入：uv publish --token ppi-xxx（不推荐，易泄露到历史）。

2. 构建并上传

正式 PyPI（先确保版本号已更新）：

uv build
uv publish

先传到 TestPyPI 验证：

uv build
uv publish --index testpypi

TestPyPI 的 token 需在 TestPyPI 账号 创建，并通过 --token 或 UV_PUBLISH_TOKEN 传入。

---

发布前检查清单

• 版本号：确保 pyproject.toml 中的 project.version 已更新，且未在 PyPI 上使用过。
• 变更说明：如有需要，在 README.md / CHANGELOG 中补充版本变化。
• 测试通过：pytest 全绿。
• 构建产物：dist/ 中包含预期的 wheel 和 sdist 文件。