一个使用 uv 管理的现代 Python 项目模板

• 🚀 快速：使用 uv 包管理器，比 pip 快 10-100 倍
• 🔒 可靠：使用 uv.lock 确保可重现的依赖管理
• 🛠️ 完整工具链：集成代码格式化、检查和测试工具
• 🌏 中国友好：预配置国内镜像源，下载速度更快
• 📦 标准结构：遵循现代 Python 项目最佳实践

cursor-dirs/
├── src/
│   └── cursor_dirs/        # 项目源代码
│       ├── __init__.py
│       └── main.py
├── tests/                  # 测试代码
│   ├── __init__.py
│   └── test_main.py
├── pyproject.toml          # 项目配置和依赖
├── uv.lock                 # 锁定依赖版本
├── README.md               # 项目说明
└── .gitignore              # Git 忽略文件

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.sh | iex"

# 或者使用 pip
pip install uv

首次克隆项目后：

# 克隆项目
git clone <project-url>
cd cursor-dirs

# 安装所有依赖（包括开发依赖）
uv sync --group dev

# 运行项目
uv run python -m cursor_dirs.main

日常开发：

# 安装项目依赖（自动使用镜像源配置）
uv sync

# 添加新依赖
uv add requests

# 运行主程序
uv run python -m cursor_dirs.main

# 或者使用项目脚本
uv run cursor-dirs

⚠️ 注意：请使用 uv sync/uv add 而不是 uv pip install，这样才能享受项目配置的镜像源加速！

# 运行测试
uv run pytest

# 代码格式化
uv run black src/ tests/

# 代码检查
uv run ruff check src/ tests/

# 类型检查
uv run mypy src/

# 一键格式化和检查
uv run ruff check --fix src/ tests/ && uv run black src/ tests/

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

# 添加开发依赖
uv add --group dev pytest black

# 添加特定版本
uv add "django>=4.0,<5.0"

# 移除运行时依赖
uv remove requests

# 移除开发依赖
uv remove --group dev pytest

# 更新所有依赖
uv sync --upgrade

# 更新特定包
uv add requests@latest

项目已预配置中国镜像源以加速包下载：

• 主源：清华大学 PyPI 镜像 (https://pypi.tuna.tsinghua.edu.cn/simple)
• 备用源：阿里云、豆瓣镜像

配置位置：pyproject.toml 中的 [tool.uv] 部分

• 极速安装：比传统 pip 快 10-100 倍
• 确定性解析：lockfile 确保可重现的构建
• 统一工具：项目管理、依赖安装、脚本运行一体化
• 现代标准：完全兼容 PEP 621/517/518 等 Python 标准

操作	命令
初始化项目	uv init
安装依赖	uv sync
添加包	uv add <package>
移除包	uv remove <package>
运行脚本	uv run <script>
运行测试	uv run pytest
查看依赖树	uv tree
更新lockfile	uv lock

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开 Pull Request

本项目使用 MIT 许可证 - 查看 LICENSE 文件了解详情

• uv 官方文档
• Python 包装用户指南
• PEP 621 - Python 项目元数据

---

Happy Coding! 🐍✨