Python Project Template

A modern Python project template with a full toolchain and best practices baked in.

Highlights

🚀 Package management with uv (or poetry)
🧪 Testing with pytest, multi-version with tox
📊 Beautiful reports via allure
🔧 Code quality enforced by pre-commit
📝 Documentation with mkdocs
🎯 Doc coverage via interrogate
🔍 Code checks with ruff, flake8, mypy

Quick Start

1. Install uv (recommended)

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

2. Create a new project

# Clone the template
git clone https://github.com/SongshGeo/project_template.git my-project
cd my-project

# Initialize
make setup

3. Start developing

# Run tests
make test

# View test report
make report

# Run code checks
pre-commit run --all-files

Need help?

See the Quick Start Guide for details.

Project Structure

.
├── src/                    # Source code
├── tests/                  # Tests
├── config/                 # Config files
├── docs/                   # Documentation
├── scripts/                # Utility scripts
├── pyproject.toml          # Project config
├── makefile                # Shortcuts
└── README.md               # Project overview

Core Capabilities

Package managers

uv (recommended): extremely fast
poetry (alternative): mature ecosystem

Code quality

Black: formatting
Ruff: blazing-fast lint/format
Flake8: style checks
MyPy: type checks
Interrogate: doc coverage

Testing

Pytest: unit testing
Tox: Python 3.10-3.13 matrix
Allure: test reports
Coverage: coverage reports

Docs

MkDocs with Material theme

Jump to a section

📖 Quick Start - step-by-step tutorial
🔧 Tooling - tools and best practices
⚙️ Configuration - config walkthrough
📝 Development - coding standards
🚀 Deployment - release process

Feature Matrix

Feature	Tool	Notes
Package mgmt	uv, poetry	Modern dependency management
Formatting	Black, Ruff	Consistent style
Linting	Ruff, Flake8, MyPy	Multi-layer quality
Testing	Pytest, Tox	Comprehensive coverage
Reports	Allure	Visual test reports
Docs	MkDocs	Professional doc site
Doc coverage	Interrogate	Ensure docstrings
Git hooks	Pre-commit	Checks before commit
Versioning	Release Please	Automated releases
Typing	MyPy	Static typing
Profiling	Snakeviz	Performance visualization

Common Commands

# Install deps
make setup

# Run tests
make test

# View report
make report

# Configure project
make configure-project

License

MIT License.

Contributing

Contributions welcome. Typical steps:

Fork the repo
Create a feature branch
Commit changes
Push to your branch
Open a Pull Request