A modern Python repository template that provides a solid foundation for your next Python project. This template follows the src layout for better package management and includes essential tools for development, testing, and CI/CD.
- 🐍 Python Focused: Optimized for modern Python development (3.12+)
- 📁 Src Layout: Follows Python's recommended
srclayout - 📦 Modern Dependency Management: Powered by
uvfor lightning-fast package management - 🛠️ Linting & Formatting: Pre-configured with
ruff - 🔧 Modern Tooling: Pre-configured development workflow tools including Lefthook, Mise, Cocogitto, and Act
- 🏥 Community Health Files: Includes standard files for project governance
- 🤝 GitHub Integration: Pre-configured issue and pull request templates
-
Clone the repository:
git clone https://github.com/TheRealZurvan/python-project-template.git cd python-project-template -
Setup environment:
# Install mise (if not already installed) curl https://mise.run | sh # Install configured tools (python, uv, ruff, lefthook, cocogitto, act) mise install # Set up Python virtual environment and dependencies uv venv uv sync # Set up Git hooks lefthook install
If you have Docker installed, you can run GitHub Actions locally using act. This template includes a pre-configured mise task for testing pull request workflows:
mise run act-prThis command uses .github/act/pull_request.json to simulate a pull request event.
- Python: The core programming language (version specified in
.tool-versions). - UV: An extremely fast Python package and project manager, replacing
pip,pip-tools, andpoetry. - Ruff: An extremely fast Python linter and code formatter, written in Rust.
- Mise: Ensures consistent tool versions (python, uv, ruff, cocogitto, lefthook, act) across different environments.
- Lefthook: Git hooks manager that runs checks (like
ruff) before commits and pushes. - Cocogitto: Enforces Conventional Commits and automates changelog generation.
- Act: Runs GitHub Actions locally for faster feedback loops.
This project uses Lefthook for Git hooks and follows Conventional Commits.
- Commit-msg: Validates commit messages using
cog verify. - Pre-push: Runs checks before pushing to the remote repository.
This project follows the src layout.
.
├── .github/
│ ├── ISSUE_TEMPLATE/ # Structured issue templates
│ └── act/ # Local CI testing configuration
├── scripts/ # Helper scripts
├── src/ # Source code
│ └── main.py # Main entry point
├── tests/ # Test suite (if applicable)
├── .lefthook.yml # Git hooks configuration
├── .tool-versions # Mise tool versions
├── LICENSE # Apache License 2.0
├── pyproject.toml # Python project configuration and dependencies
├── README.md # You are here! 📍
├── SECURITY.md # Security policy
└── mise.toml # Mise tasks configuration
- Replace this content with information about your project.
- Include sections such as Project description, Usage examples, and API documentation.
- The template includes the Apache License 2.0.
- Update the copyright notice or replace the file with your preferred license.
- CODE_OF_CONDUCT.md: Update the contact information in the "Enforcement" section.
- SECURITY.md: Update contact details and supported versions policy.
- Issue Templates: Modify fields, labels, and descriptions in
.github/ISSUE_TEMPLATE/. - Pull Request Template: Adjust the checklist items in
.github/PULL_REQUEST_TEMPLATE.md.
Contributions are welcome! Please follow these steps:
- Fork the project
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes using Conventional Commits
- Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please see SECURITY.md for our security policy.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Happy coding! 🎉 If you find this template useful, please give it a ⭐️