A modern Python project template with best practices for development and collaboration.
- 🚀 Fast dependency management with uv
- ✨ Code formatting with ruff
- 🔍 Type checking with mypy
- 🧪 Testing with pytest
- 🐳 Docker support for development and deployment
- 👷 CI/CD with GitHub Actions
This template requires Python 3.9 or higher and defaults to Python 3.12. To use a different version:
# List available Python versions
uv python list
# Use a specific version (e.g., 3.11)
make setup PYTHON_VERSION=3.11 # or UV_PYTHON_VERSION=3.11 make setup
# View installed Python versions
uv python list --installeduv will automatically download and manage Python versions as needed.
# Clone this repo and change directory
git clone git@github.com:safurrier/python-collab-template.git my-project-name
cd my-project-name
# Initialize a new project
make init
# Follow the prompts to configure your projectThis will:
- Configure project metadata (name, description, author)
- Handle example code (keep, simplify, or remove)
- Initialize a fresh git repository
- Set up development environment
- Configure pre-commit hooks (optional, enabled by default)
Pre-commit hooks will automatically run these checks before each commit:
- Type checking (mypy)
- Linting (ruff)
- Formatting (ruff)
- Tests (pytest)
Alternatively, you can set up manually:
# Install dependencies and set up the environment
make setup
# Run the suite of tests and checks
make check
# Optional: Remove example code to start fresh
make clean-examplemake check # Run all checks (test, mypy, lint, format)
make test # Run tests with coverage
make mypy # Run type checking
make lint # Run linter
make format # Run code formatterThe repository includes a simple example showing:
- Type hints
- Dataclasses
- Unit tests
- Modern Python practices
To remove the example code and start fresh:
make clean-examplemake dev-env # Start a development containerThis creates a container with:
- All dependencies installed
- Source code mounted (changes reflect immediately)
- Development tools ready to use
make build-image # Build production image
make push-image # Push to container registry.
├── src/ # Source code
├── tests/ # Test files
├── docker/ # Docker configuration
├── .github/ # GitHub Actions workflows
├── pyproject.toml # Project configuration
└── Makefile # Development commands
- Fork the repository
- Create a feature branch
- Make your changes
- Run
make checkto ensure all tests pass - Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.