Python Project Template

English | 中文

A modern Python project template with batteries included: tooling, docs, tests, CI, and packaging.

Quick Start

1) Install uv (recommended) or poetry

# Install uv (recommended, faster)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or install poetry
pip install poetry

2) Create a new project

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

# Initialize the project (configure name/description)
make setup

# Manual configuration (optional, if make setup is skipped)
make configure-project          # auto-detects package manager
# or run directly (requires deps installed)
python scripts/configure_project.py

What the config script does

• Update [project] and [tool.poetry] in pyproject.toml
• Update GitHub workflow config
• Create/update README.md
• Clear CHANGELOG.md

The script will ask for

• Project name: used in package/config
• Project description: short project summary

Optional: install dependencies only

uv sync --all-extras  # using uv
# or
poetry install        # using poetry

3) Develop

# Run tests
make test

# View test report
make report

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

Project Structure

.
├── src/                    # Source code
│   ├── api/                # API layer
│   ├── core/               # Core logic
│   └── __init__.py
├── tests/                  # Tests
│   ├── conftest.py         # pytest config
│   └── helper.py           # test helpers
├── config/                 # Configuration
│   └── config.yaml         # Main config
├── data/                   # Data assets
├── docs/                   # Documentation
├── examples/               # Examples
├── scripts/                # Utility scripts
│   └── configure_project.py
├── pyproject.toml          # Project config (uv/poetry)
├── tox.ini                 # Multi-Python testing
├── makefile                # Make shortcuts
└── README.md               # This file

Features

1. Makefile automation
2. Hydra-friendly config management
3. pytest unit tests
4. allure reports
5. nbstripout for notebooks (keep outputs)
6. pre-commit for linting
7. mkdocs for docs
8. uv package manager (poetry compatible)
9. interrogate doc coverage
10. Jupyter for analysis
11. snakeviz profiling
12. isort imports
13. flake8 linting
14. ruff linting
15. black formatting
16. mypy type checking
17. coverage reports
18. tox for Python 3.10-3.13 matrix
19. release-please versioning
20. mkdocs-material theme

Common Commands

Dev workflow

# Install all deps (auto-detect uv or poetry)
make setup

# Run tests
make test

# Matrix tests (Python 3.10-3.13)
make tox

# Test report
make report

# Configure project metadata
make configure-project

# Serve docs
make docs

Note: The Makefile auto-detects uv first, then poetry. If neither is installed, it prints install hints.

Using uv (recommended)

# Install deps
uv sync --all-extras

# Run tests
uv run pytest

# Run any Python command
uv run python your_script.py

# Add a dependency
uv add package-name

# Add a dev dependency
uv add --dev package-name

Using poetry (alternative)

# Install deps
poetry install

# Run tests
poetry run pytest

# Add a dependency
poetry add package-name

Code quality

# Install pre-commit hooks
pre-commit install

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

# Run specific checks
pre-commit run flake8 --all-files
pre-commit run black --all-files
pre-commit run interrogate --all-files  # doc coverage

Multi-Python testing

# All versions (via Makefile)
make tox

# Specific version
make tox-e pyversion=py311

# List envs
make tox-list

# Direct tox
tox                  # all versions
tox -e py311         # Python 3.11
tox list             # show envs
tox -p               # parallel

Documentation

!!! info "Online docs" Visit Online Docs for the full site.

View docs locally

# Dev server with live reload
make docs

# Or run directly
uv run mkdocs serve
poetry run mkdocs serve  # via poetry

Open http://127.0.0.1:8000.

Build docs

make docs-build
# or
uv run mkdocs build

Deploy docs to GitHub Pages

Docs are deployed by GitHub Actions:

1. Push to main
2. Actions build automatically
3. Pages deploy

URL: https://songshgeo.github.io/project_template/

Doc sections

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

FAQ

Q: uv or poetry?

A: uv is faster and modern; poetry is mature. Choose based on preference.

Q: How to start a new project?

A: Run make setup to configure and install deps.

Q: How to add dependencies?

uv add package-name          # runtime deps
uv add --dev package-name    # dev deps

Q: How to run tests?

make test        # via Make
uv run pytest    # direct

Contributing

Contributions welcome! Steps:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit (git commit -m 'feat: add amazing feature')
4. Push (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure:

• All linters pass
• Tests are added/updated
• Docs are updated
• Follow coding guidelines

License

MIT License. See LICENSE.

Author

• SongshGeo - GitHub - Website