Zum Inhalt

Entwicklungsumgebung

Es gibt für die Entwicklung zwei Möglichkeiten, wie die Abhängigkeiten installiert werden können. Das ist deshalb kompliziert, weil wir auf Graphviz als separate Abhängigkeit zugreifen. Graphviz ist nicht in Python als Package vorhanden, sondern muss über das Paketmanagement des jeweiligen Betriebssystems installiert werden. Entweder kann also Graphviz global installiert werden oder wir installieren es in die jeweilige Ordnerumgebung. Erstere Variante ist die einfachere, zweitere ist deutlich komplizierter. In beiden Fällen muss das Repository geclont werden.

Variante 1

Für das Management der Abhängigkeiten nutzen wir Poetry. Falls du das Tool noch nicht kennst, lies bitte zuerst den Abschnitt für die grundlegende Nutzung. Für die Installation auf deinem System siehe bitte hier. Nachdem das erledigt ist, manövriere im Terminal deiner Wahl in das geclonte Verzeichnis von dsstools. Darin führe Folgendes aus:

poetry install --all-extras --with=dev

Das installiert neben den standardmäßigen Abhängigkeiten auch pygraphviz und alle für die Tests nötigen Abhängigkeiten in deine lokale Umgebung. Danach sollte folgender Befehl im Terminal euch eine Version für pytest wiedergeben:

poetry run pytest --version
> pytest 7.2.1

Danach hast du alle nötigen Tools, um mit der Entwicklung zu beginnen. Sollte irgendetwas nicht funktionieren, wende dich bitte an David. Viel Erfolg!

Variante 2

Dafür nutzen wir experimentell devenv, ein Tool zur Erzeugung deklarativer und reproduzierbarer Umgebungen über die Grenzen einer Programmiersprache hinaus. Im Inneren umschließt es aber ebenso den Poetry Paket Manager.

Warnung

Für Einsteiger:innen empfiehlt sich diese Methode eher weniger. Vorhandene Kenntnisse in der Kommandozeile sind für diese Methode Voraussetzung.

  1. Zuerst den Nix Paketmanager installieren (https://nixos.org/download/).
  2. Relevante Konfiguration für Flakes aktivieren: 
    mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
  3. Repository von dsstools clonen
  4. cd <repository> und dann nix develop --impure. Das installiert alle benötigten Abhängigkeiten.
  5. [OPTIONAL] Nutze direnv für die automatische Aktivierung der Umgebung.

Type hinting

We use type hinting in this project to provide clarity for both users and developers. For Users, type hinting helps to understand what kind of information is expected when calling methods from our project. We, as developers, utilize type hinting to avoid bugs due to type errors.

Formatting and Linting

We adhere to the recommendations set by PEP8 and PEP257. Several tools are helping us in achieving this: Pylint, docformatter and Black. Pylint and docformatter are installed with the dev group through Poetry, Black needs to be globally installed through your local package manager.

Pylint

Running pylint on a file returns hints about improvements or problems with the given code (Doc). Executing is rather straightforward and will give you a list of recommendations:

# Inside the root of the repository
pylint dsstools/
# Executing single modules is also possible
pylint dsstools/inputs.py

Integrations for IDEs are available.

Docformatter

Black does not touch docstrings so these require a separate tool: docformatter. The configuration is already done through the pyproject.toml. Running it is as easy as:

docformatter dsstools/inputs.py
# Using the -i flag will apply the configuration
docformatter -i dsstools/inputs.py

Hinweis

An integration for PyCharm exists: https://docformatter.readthedocs.io/en/latest/usage.html#use-as-a-pycharm-file-watcher

Black

Running Black on a file will reformat the file or directory:

black path/to/file_or_directory
# Setting the flag --check will show a preview of potential changes 
black --check path/to/file_or_directory

Please put Black changes in a separate commit after everything else is done.