Development Flow

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

Core Tools

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 the official 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"

Pre-commit hooks run automatically at this point — they autofix lint violations with ruff check --fix, reformat with ruff format, and update uv.lock and requirements.txt if needed. If a hook modifies a file, the commit is aborted; re-stage the changes and commit again.

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

Demo Files and Git History

The template ships with a set of demo files to help you get started:

These files are deliberately excluded from the initial git commit by the post-generation hook. They exist in your working tree so you have something to reference, but they won't appear in your project's history. Replace or delete them as you build out your own code.

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.

Project Scaffolding

Besides the code, the template generates the supporting files a maintained project is expected to have. Most need one edit from you at some point:

DevContainer

.devcontainer/ defines a reproducible container environment for VS Code Dev Containers and GitHub Codespaces. Opening the project in a supported editor offers to reopen it in the container.

It is based on the official Microsoft Python image and, on creation, installs uv, runs uv sync, and installs the pre-commit hooks. The VS Code settings point the Python interpreter and pytest at the in-container .venv, so test discovery works without further configuration.

Use it when you want the toolchain isolated from your machine, or to give a collaborator a working environment without a setup call. It is entirely optional — delete the directory if you develop natively.

AI Coding Agents

The generated project includes a .claude/CLAUDE.md describing its own structure: the package layout, the path variables and save() helper, the testing and doctest conventions, the linting rules, and how template updates work. Agents that read repository instructions pick this up automatically, which saves re-explaining the project's shape in every session.

It ships with a TBD placeholder at the top, along with an instruction telling the agent to interview you about the project's purpose and conventions and rewrite that section before doing anything else. Fill it in early — the rest of the file describes the template, but only you know what the project is for.

See Also

• Package Conventions - Path variables, logging, save()
• Code Quality - Linting, type checking, testing
• Task Automation - Available tasks
• Documentation - Building docs
• GitHub Actions - CI/CD pipeline

Further Reading

• Python Packaging Guide
• pytest Docs
• Sphinx Docs