Skip to content

quick-start.md

Latest commit

 

History

History
301 lines (207 loc) · 5.97 KB

quick-start.md

File metadata and controls

301 lines (207 loc) · 5.97 KB
Raw

快速开始指南

中文 | English

这是一个详细的快速开始指南，帮助您从零开始使用这个 Python 项目模板。

前提条件

在开始之前，请确保您的系统已安装：

  • Python 3.10-3.13（推荐使用 3.11）
  • Git
  • uv（本模板仅使用 uv）

步骤 1：安装 uv

uv 是一个极快的 Python 包管理器，由 Rust 编写。

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 验证安装
uv --version

步骤 2：创建新项目

# 克隆模板仓库
git clone https://github.com/SongshGeo/project_template.git my-project
cd my-project

# 删除旧的 git 历史（可选）
rm -rf .git
git init

步骤 3：配置项目

运行配置脚本来自定义项目信息：

make configure-project

或者手动运行：

python scripts/configure_project.py

脚本会提示您输入：

  • 项目名称：将在包名和配置中使用（例如：my-awesome-project）
  • 项目描述：项目的简要描述（例如：An awesome Python project）

配置脚本会自动执行以下操作：

  1. 更新 pyproject.toml

    • 更新 [project] 段的 name 和 description

  2. 更新 GitHub Workflow

    • 更新 .github/workflows/release-please.yml 中的项目名称

  3. 创建 README.md

    • 使用项目名称和描述创建新的 README.md

  4. 清空 CHANGELOG.md

    • 为您的项目准备一个新的变更日志

示例输出：

$ make configure-project
项目名称: my-awesome-project
项目描述: An awesome Python project
✓ 已更新 pyproject.toml
✓ 已更新 .github/workflows/release-please.yml

✨ 项目配置已完成!

配合 Claude Code 使用

如果你使用 Claude Code，整个初始化流程可以交给一个 skill 自动完成，而无需手动逐条运行命令：

  1. 从本模板创建你的项目，并用 Claude Code 打开。
  2. 运行 setup-project skill，它会：
    • 配置项目名称和描述；
    • 使用 uv sync --all-extras 安装依赖；
    • 安装 pre-commit hooks；
    • 执行 npx skills@latest add SongshGeo/skills 安装推荐的外部 skill；
    • 初始化 memory-bank/；
    • 运行测试套件以验证一切正常。

已有一个用旧模板生成的老项目？运行 upgrade-project skill 即可将其迁移到新的 uv-only + Claude Code 工作流。

!!! tip "协作上下文中枢" 根目录的 CLAUDE.md（权威的编码规范与 skill 索引）与顶层的 memory-bank/ 是与 Claude Code 协作的共享上下文中枢。

步骤 4：安装依赖

# 安装所有依赖（包括开发依赖和文档依赖）
uv sync --all-extras

# 或只安装开发依赖
uv sync --dev

安装完成后，依赖会被安装到虚拟环境中。

步骤 5：设置 Git hooks

# 安装 pre-commit hooks
pre-commit install

# 首次运行所有检查
pre-commit run --all-files

步骤 6：验证安装

运行测试以确保一切正常：

# 使用 Makefile
make test

# 或直接运行
uv run pytest

查看测试报告：

make report

步骤 7：开始开发

项目结构

src/
├── core/          # 核心业务逻辑
└── api/           # API 接口
├── conftest.py             # pytest 配置
├── test_configure_project.py  # 配置脚本测试
└── test_*.py               # 其他测试文件

当前测试

项目模板已包含基础测试：

  • tests/test_configure_project.py - 测试项目配置脚本

运行测试：

make test
# 或
uv run pytest

添加新功能

  1. 在 src/ 目录下添加您的代码
  2. 在 tests/ 目录下添加对应的测试文件
  3. 运行测试确保功能正常

测试示例：

# tests/test_my_module.py
def test_my_function():
    """Test my function."""
    from src.my_module import my_function
    assert my_function() == expected_value

添加新依赖

# 添加运行时依赖
uv add numpy pandas

# 添加开发依赖
uv add --optional dev pytest-cov

# 添加文档依赖
uv add --optional docs mkdocs

运行代码

# 使用 uv 运行
uv run python src/your_script.py

# 或激活虚拟环境
uv shell

步骤 8：代码质量检查

运行多版本测试

使用 tox 测试代码在不同 Python 版本的兼容性：

# 测试所有版本（3.10-3.13）
make tox

# 测试特定版本
make tox-e pyversion=py311

# 查看可用环境
make tox-list

自动检查（推荐）

每次提交时会自动运行检查。如果需要手动运行：

# 运行所有检查
pre-commit run --all-files

# 运行特定检查
pre-commit run black --all-files
pre-commit run flake8 --all-files
pre-commit run interrogate --all-files

手动运行工具

# 代码格式化
black .
ruff format .

# 代码检查
flake8 src/
mypy src/

# 文档覆盖率
interrogate src/

下一步

常见问题

Q: 本模板使用哪个包管理器？

A: 本模板仅使用 uv。uv 由 Rust 编写，速度极快，在一个工具中统一管理虚拟环境、依赖和打包。

Q: 虚拟环境在哪里？

A: uv 默认使用 .venv 目录。

查看虚拟环境位置：

uv info

Q: 如何添加 Python 版本测试？

A: 编辑 tox.ini，修改 envlist 行：

envlist = py310, py311, py312, py313

Q: 如何生成文档？

A:

# 启动文档服务器
uv run mkdocs serve

# 构建静态文档
uv run mkdocs build

文档将生成在 site/ 目录。

Q: 如何发布到 PyPI？

A: 参考 部署指南 中的 PyPI 发布章节。