Getting Started¶

Prerequisites¶

Python 3.11+: check with python --version
uv: fast Python package manager
just: task runner (optional but recommended)

Project layout¶

src/python_template/   # Your source code goes here
tests/                    # Tests (pytest)
scripts/                  # Standalone scripts (data processing, training, etc.)
docs/                     # Documentation source (MkDocs)

Development workflow¶

Setup¶

just setup    # install deps + pre-commit hooks

Daily commands¶

just check     # run lint + typecheck + test (same as CI)
just fix       # auto-fix lint and formatting issues
just test      # run tests only
just docs      # preview docs locally at http://127.0.0.1:8000/

Adding dependencies¶

# Runtime dependency
uv add requests

# Dev dependency
uv add --group dev httpx

After adding dependencies, uv.lock is updated automatically. Commit it for reproducible builds.

Writing tests¶

Tests live in tests/ and use pytest. Shared fixtures go in tests/conftest.py.

def test_my_feature() -> None:
    result = my_function(42)
    assert result == expected

Run specific tests:

just test -k test_my_feature    # by name
just test tests/test_main.py    # by file
just coverage                   # with coverage report

Type annotations¶

All code must have type annotations: mypy runs in strict mode. Use Google-style docstrings for documentation:

def process_data(path: Path, *, normalize: bool = True) -> pd.DataFrame:
    """Load and process data from a file.

    Args:
        path: Path to the input data file.
        normalize: Whether to normalize values to [0, 1].

    Returns:
        Processed DataFrame ready for analysis.

    Raises:
        FileNotFoundError: If the input file doesn't exist.
    """

Docstrings are auto-rendered as API documentation by mkdocstrings.

Next steps¶

Add your runtime dependencies to pyproject.toml
Run just init-remote to create the GitHub repo, push, configure branch protection, and enable Pages
Connect Codecov for PR coverage reports
See Contributing for the full development guide