Skip to content

Development Flow

This template provides a full, modern development environment with integrated tools for testing, code quality, and documentation.

Core Tools

Tool Purpose
uv Dependency & environment manager
Ruff Linting & formatting
ty Type checking
pytest Testing & coverage
Just Task automation
Sphinx Documentation

Getting Started

I recommend you to use uv as a dependency and environment manager. Read the corresponding section of the documentation. In your project's directory, run the following commands 

uv venv

source .venv/bin/activate

uv sync --dev
just qa                    # Verify setup

uv venv

.\.venv\Scripts\activate

uv sync --dev
just qa                    # Verify setup

To get more familiar with uv, I recommend you to have a look at their documentation.

A typical Development Workflow

1. Write Code

Edit source code in src/mypackage/:

def user_data(name: str, age: int) -> dict: # (1)!
    """Process user data.

    Parameters
    ----------
    name : str
        User's full name
    age : int
        User's age in years
    """ # (2)!
    return {name: age}
  1. Always make use of type hints
  2. Give your functions meaningful docstrings, including parameter information and (if it helps the understanding) examples.

2. Write Tests

Add tests in tests/:

def test_user_data():
    assert user_data("Albert", 30) == {"Albert": 30}

3. Run Quality Checks

just qa            # Format → Lint → Type check → Test

4. Commit

git add .
git commit -m "Add user_data function"

Best practice

Make atomic commits. That is, commit every logical "bite" that does something meaningful in your code. Use "active" language, i.e. describe what the commit does when applied.

5. Update Documentation

Keep your project's documentation up-to-date. Edit the markdown files in docs/ and preview the rendered version, running 

just docs-serve    # View at http://localhost:8000

6. Push to Github

git push

GitHub Actions automatically runs CI/CD. See GitHub Actions.
If GitHub pages is configured, your documentation will be served online on https://<your-username>.github.io/<package-slug>.

Common Tasks

Task Command
Add dependency uv add package-name
Add dev dependency uv add --group dev package
Run specific test just test tests/test_foo.py
Format code uv run ruff format .
Type check uv run ty check .
Build package just build
Clean artifacts just clean

Project Structure

The src/ layout ensures tests run against installed package.

├── src/mypackage/
├── tests/
├── docs/
├── notebooks/      # Jupyter notebooks for data exploration (1)
├── reports/        # Data reports, figures, etc. (2)
├── pyproject.toml  # (3)!
├── ruff.toml
└── justfile  # (4)!
  1. Only present if is_research_project is answered with yes
  2. Only present if is_research_project is answered with yes
  3. Most of the project's configuration is in here
  4. The justfile holds default tasks that can run simply like just docs.

See Also

Further Reading