UV Python Repository Template

中文文档

Python project template powered by UV with fully automated CI/CD workflows, enabling developers to focus on code

🚀 Core Features

• ⚡ Blazing-fast Dependency Management - Next-gen toolchain powered by UV
• 🤖 Automatic Version Control - Semantic versioning based on Conventional Commits
• 🔒 Quality Gates - Automated checks on every commit:
  • ✅ Code Formatting (Black)
  • ✅ Linting (Flake8)
  • ✅ Unit Testing (Pytest)
• 🛠️ Smart Workflow Management - Visual GitHub Actions control

🛠️ Environment Setup

Prerequisites

1. Install UV:

• MacOS:

  brew install uv

• Linux (Debian/Ubuntu/WSL):

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

💡 Verify installation with uv --version (should return 0.5.x or higher). Full installation guide at UV documentation.

2. System Support:

• ✅ Linux
• ✅ macOS
• ⚠️ Windows (WSL supported)

🏁 Quick Start

Initial Setup (First-time Use)

bash ./scripts/init.sh

The initialization script will:

1. Configure project metadata
2. Create Python virtual environment (in .venv)
3. Install Git Hooks (pre-commit & commit-msg)

✍️ Commit Convention

Message Format

<type>([scope]): <subject>

Type Reference

Type	Version Impact	Example Scenarios
feat	Minor ↑	Add user authentication
fix	Patch ↑	Fix payment timeout
BREAKING CHANGE	Major ↑	Remove legacy API (use ! or body)
docs/style/test	No impact	Documentation updates, code formatting, test cases

Examples

• feat: Add user registration API ➔ Minor version bump (v1.2.3 → v1.3.0)
• fix: Resolve password validation ➔ Patch version bump (v1.2.3 → v1.2.4)
• feat!: Remove deprecated API ➔ Major version bump (v1.2.3 → v2.0.0)
• docs: Update API documentation ➔ No version change
• style: Code formatting ➔ No version change
• test: Add unit tests ➔ No version change

💡 Use ! in commit message or include BREAKING CHANGE: in body for breaking changes

🏷️ Version Tagging

Generate semantic version tags:

uv run poe tag

This command automatically:

1. Calculates version number (based on commit history)
2. Generates CHANGELOG
3. Commits tag

🔄 Code Push

Standard push commands:

git push origin main # Push main branch
git push --tags # Push tags

💡 Ensure tags are pushed to remote to trigger GitHub Actions workflows

🤖 GitHub Actions Management

Workflow List

View available workflows:

uv run poe action list

Default workflows: release, publish, lint-test

Workflow Control

Enable/disable workflows:

uv run poe action toggle --enable release --commit # Enable release workflow and commit
uv run poe action toggle --disable release --commit # Disable release workflow and commit
uv run poe action toggle --enable publish # Enable publish workflow
uv run poe action toggle --disable publish # Disable publish workflow

⚠️ System will prompt for required environment variables when enabling workflows

Acknowledgments

Original inspiration and base template from python-repo-template.

Collaborators

Jarlor Zhang