Quick Start Guide

A step-by-step guide to get productive with this Python project template.

Prerequisites

Python 3.10-3.13 (3.11 recommended)
Git
uv (recommended) or poetry

Step 1: Install a package manager

Option A: uv (recommended)

uv is a blazing-fast Python package manager written in Rust.

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

# Verify
uv --version

Option B: poetry

pip install poetry
poetry --version

Step 2: Create a new project

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

# Optional: reset git history
rm -rf .git
git init

Step 3: Configure the project

make configure-project
# or run directly
python scripts/configure_project.py

The script asks for: - Project name (e.g., my-awesome-project) - Project description (e.g., An awesome Python project)

What it does: 1. Update pyproject.toml [project] and [tool.poetry] 2. Update .github/workflows/release-please.yml 3. Create README.md 4. Clear CHANGELOG.md

Example output:

Project name: my-awesome-project
Project description: An awesome Python project
✓ Updated pyproject.toml
✓ Updated .github/workflows/release-please.yml

✨ Project configuration completed!

Step 4: Install dependencies

With uv

# All extras (dev + docs)
uv sync --all-extras

# Dev only
uv sync --dev

With poetry

poetry install

Step 5: Set up Git hooks

pre-commit install
pre-commit run --all-files

Step 6: Verify setup

# Using Makefile
make test

# Or directly
uv run pytest
poetry run pytest

Test report:

make report

Step 7: Start developing

Project layout

src/
├── core/          # Core logic
└── api/           # API layer
tests/
├── conftest.py             # pytest config
├── test_configure_project.py  # config script tests
└── test_*.py               # other tests

Current tests

tests/test_configure_project.py verifies the config script.

Run tests:

make test
# or
uv run pytest

Add new features

Add code under src/
Add matching tests under tests/
Run tests

Example test:

# tests/test_my_module.py
def test_my_function():
    """Test my function."""
    from src.my_module import my_function
    assert my_function() == expected_value

Add dependencies

Using uv:

uv add numpy pandas          # runtime deps
uv add --dev pytest-cov      # dev deps
uv add --dev mkdocs          # docs deps

Using poetry:

poetry add numpy pandas
poetry add --group dev pytest-cov

Run code

uv run python src/your_script.py
poetry run python src/your_script.py

# Or activate virtual env
uv shell
poetry shell

Step 8: Code quality

Multi-version testing

make tox                      # Python 3.10-3.13
make tox-e pyversion=py311    # specific version
make tox-list                 # list envs

Automated checks

pre-commit run --all-files
pre-commit run black --all-files
pre-commit run flake8 --all-files
pre-commit run interrogate --all-files

Manual tools

black .
ruff format .
flake8 src/
mypy src/
interrogate src/

Next steps

FAQ

uv or poetry?

uv is faster (Rust). poetry is mature. The template supports both.

Where is the virtualenv?

uv: .venv by default
poetry: manages its own venv

Check paths:

uv info
poetry env info

Add more Python versions?

Edit tox.ini envlist:

envlist = py310, py311, py312, py313

Generate docs?

uv run mkdocs serve
uv run mkdocs build

Docs output to site/.

Publish to PyPI?

See Deployment for the PyPI section.