A modern Python project template using uv for ultra-fast package management.
- Lightning Fast: uv provides 10-100x faster package resolution than pip
- Built-in Python: Automatic Python version management
- Lock Files: Reproducible builds with
uv.lock - Virtual Environments: Automatic
.venvcreation and management
- CodeQL Analysis: Automated security vulnerability scanning
- Dependency Review: Checks for vulnerable or malicious dependencies
- Input Validation: Example module with comprehensive validation
- XSS Prevention: HTML escaping demonstrations for web contexts
- 52+ Tests: Comprehensive test suite with parameterized testing
- GitHub Actions: Automated CI pipeline with multiple checks
- Code Quality: Pre-configured for ruff, black, and mypy
- PR Automation: Auto-labeling and release drafting
Includes a production-ready example module demonstrating:
- Type hints and validation
- Google-style docstrings
- Error handling with helpful messages
- Security best practices
- CLI interface
Install uv (if not already installed):
curl -LsSf https://astral.sh/uv/install.sh | sh-
Clone and install dependencies:
git clone <your-repo> cd <your-repo> uv sync --all-extras --dev
-
Run tests:
uv run pytest
-
Try the example module:
# Run interactive demo uv run python src/example.py # Use CLI interface uv run python src/cli.py greet "Your Name" uv run python src/cli.py add 10 20
| Workflow | Purpose | Trigger |
|---|---|---|
| CI | Run tests and quality checks | Push, PR |
| CodeQL | Security vulnerability scanning | Push, PR, Schedule |
| Dependency Review | Check for vulnerable dependencies | PR |
| PR Labeler | Auto-label PRs based on files changed | PR |
| Release Drafter | Generate release notes automatically | Push to main |
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=src
# Run specific test file
uv run pytest tests/test_example_module.py -v# Linting with ruff
uv run ruff check .
# Formatting with black
uv run black .
# Type checking with mypy
uv run mypy ..
├── .github/
│ ├── workflows/ # CI/CD workflows
│ └── labeler.yml # PR labeling config
├── src/
│ ├── __init__.py
│ ├── example.py # Example module with best practices
│ ├── cli.py # CLI interface
│ └── README.md # Module documentation
├── tests/
│ └── test_example_module.py # Comprehensive test suite
├── pyproject.toml # Project configuration
└── uv.lock # Locked dependencies
- Enable GitHub Actions (Settings → Actions)
- Enable Dependabot (Settings → Security & analysis)
- Set up branch protection for
main:- Require PR reviews
- Require status checks to pass
- Require branches to be up to date
- Add CODEOWNERS file for automatic PR reviewers
- Configure GitHub Pages for documentation
- Set up PyPI publishing workflow
- Add Docker support
The template includes a fully-featured example module demonstrating:
from src.example import greet, add_numbers
# Type-safe functions with validation
greeting = greet("Alice") # ✓ Valid
greeting = greet("") # ✗ Raises ValueError
result = add_numbers(5, 3) # ✓ Valid
result = add_numbers(5.5, 3) # ✗ Raises TypeError with helpful messagefrom src.example import greet_for_web
# Automatic HTML escaping for web contexts
safe_output = greet_for_web("<script>alert('XSS')</script>")
# Output: "Hello, <script>alert('XSS')</script>..."from src.example import safe_greet
# Graceful fallback on errors
message = safe_greet(None) # Returns "Hello, Guest!" instead of raising- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests (
uv run pytest) - Commit with conventional commits (
git commit -m 'feat: Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open a Pull Request
This template is open source and available under the MIT License.
- uv - Ultra-fast Python package manager
- pytest - Testing framework
- ruff - Fast Python linter
- GitHub Actions for CI/CD automation
Built with ❤️ using modern Python tooling