Development Container Setup Guide

This document explains how you can use our development container (dev container) setup to contribute to the Python side of power-grid-model.

Note

A development container is a pre-configured container. It includes all necessary dependencies for an immediate development start. Most modern IDEs support development containers natively. This allows you to use your preferred editor and personal extensions directly inside the isolated environment.

Prerequisites

To start developing in the development container, you must clone the repository, install a container engine, and (optionally) configure an IDE or editor that supports remote container connections.

First, clone the repository:

git clone https://github.com/PowerGridModel/power-grid-model.git

For the container engine and the IDE/editor you have several options:

Container Engine:

  • Podman: Recommended (free for both private and commercial use)

  • Docker: (larger enterprises require a paid subscription)

IDE/Editor:

This is a non-exhaustive list, as other IDEs and editors support development containers too.

Container Engine

You must install one of the container engines listed below to use the development container.

Podman

Podman is an open-source container management tool featuring a command-line interface and an optional graphical user interface called Podman Desktop. Both tools are free for both private and commercial use. A key security advantage of Podman over other engines is its rootless architecture, meaning it operates entirely without root (admin) privileges.

  • Installation: Follow the official guides for Podman or Podman Desktop.

  • Initialization: If using Podman Desktop, open the application and click initialize and start. Once successful, the status will change to a green RUNNING indicator.

Docker

Docker consists of the core Docker engine and an optional graphical interface, Docker Desktop. Note that professional use of Docker Desktop in larger enterprises requires a paid subscription.

IDE/Editor

The following IDEs provide development container integration. Other editors that support development containers may also work but are not explicitly listed here.

Visual Studio Code

Visual Studio Code offers full, native integration with development containers.

Setup

  • Install the Dev Containers extension.

  • Open the cloned power-grid-model folder in VS Code.

  • Click the green Remote Indicator button in the bottom-left corner or open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)

  • Select Dev Containers: Reopen in Container.

Usage

Testing

Visual Studio Code has built-in support for the Python tests in power-grid-model. You can open the test view via View / Testing, which lists all available tests. From there, you can run or debug individual tests, or execute the entire test suite at once.

To debug a test, set a breakpoint and click the debug icon next to the test; the IDE will pause execution at your breakpoint. You can also launch tests directly from the source code by clicking the test icon in the gutter next to the test definition line.

Pre-Commit

power-grid-model automatically installs pre-commit inside the development container. This framework runs automated checks before each commit to ensure all tests pass, the source code is properly formatted, and certain quality standards are met.

Linting

The development container utilizes Visual Studio Code extensions to seamlessly integrate code linting for Python, TOML, Markdown, JSON, and other formats directly into the IDE.

PyCharm

PyCharm Professional provides native support for development containers. Note that the Professional edition is required to have native development container support in PyCharm.

Setup

  • Open the welcome screen of PyCharm.

  • Click Remote Development, choose Dev Containers and click the Create Dev Containers button.

  • Select your local path to the cloned repository and choose your container engine.