Code-Qualität mit Lintern und Formattern

In diesem Notebook schauen wir uns an, wie wir die Qualität unseres Codes automatisch sicherstellen können. Wir analysieren dazu das Skript code_quality.py, welches absichtlich verschiedene Fehler und Stil-Mängel enthält.

Worum es geht. Werkzeuge, die den Code lesen, ohne ihn auszuführen: Formatter, Linter und Type Checker. Vorgeführt werden sie an einer absichtlich mangelhaften Datei; am Ende steht die Konfiguration, die man in eigene Projekte übernimmt.

Was Sie danach können. Formatter, Linter und Type Checker auseinanderhalten und sagen, welche Art von Fehler jeder findet; ruff an die Stelle von Black, isort und Flake8 setzen; eine Mypy-Meldung einordnen, auch wenn sie von einer untypisierten Bibliothek stammt; und das Ganze per pre-commit und CI verbindlich machen, statt es der Disziplin zu überlassen.

Die Java-Entsprechung in einem Satz. Ruff übernimmt gleichzeitig die Rollen von Checkstyle, SpotBugs und dem Formatter — und Mypy ist der Teil des Compilers, den es in Python nicht gibt, weshalb er optional, nachträglich und unvollständig bleibt.

Formatter¶

Black¶

Formatter kümmern sich um das Aussehen des Codes (PEP 8). Black ist der bekannteste “uncompromising” Formatter. Wir schauen uns mit --diff an, was Black ändern würde, ohne die Datei direkt zu überschreiben.

Wir wollen den Output von Black zur Weiterverarbeitung sichern:

Wenn sich nichts ändert, kann man das auch in Continuous Integration einbauen, indem man mit --check Änderungen vermeidet:

Man kann mit Black auch Jupyter Notebooks reformatieren:

isort¶

Aus Java-IDEs kennt man vielleicht noch ‘Organize Imports’, was die import-Statements in eine kanonische Reihenfolge bringt (und ungenutzte Imports herauswirft - das passiert hier nicht).

Konfigurations-Formatter und Linter¶

Wenn man die Projektdaten in einer pyproject.toml verwaltet (wie sich das heutzutage gehört), möchte man diese auch versionieren. Dabei wäre es ungünstig, wenn Permutationen der Zeilenreihenfolge oder Whitespace-Änderungen die Commit History zukleistern und damit die tatsächliche History schwierig nachvollziehbar machen. Um das zu vermeiden, normalisiert man die Reihenfolge und die Whitespace-Platzierungen, entweder per Konvention die von Allen eingehalten werden muss, oder durch ein Programm: einen Konfigurations-Linter bzw. Konfigurations-Formatter (siehe den folgenden Abschnitt für Python-Code-Linter).

Geeignet sind taplo (für Syntax und Formatierung) und toml-sort (für eine alphabetisch konsistente Ordnung), das sind generisch TOML-Werkzeuge. Spezifisch ist pyproject-fmt für diese Aufgabe. Der Allrounder ruff (s.u.) kann die pyproject.toml nur lintern (Fehler aufdecken), nicht formatieren.

Linter¶

Linter suchen nach logischen Fehlern, ungenutzten Imports oder gefährlichen Patterns (wie dem bare except:).

Flake8¶

Wir betrachten erstmal den Klassiker flake8, der PyFlakes, pycodestyle und McCabe-Komplexitätsanalyse bündelt.

Die Fehlercodes F401 und E501 kommen von pycodestyle, wobei E für einen Style Error steht und F für einen Fehler, den PyFlakes eingeführt hat. Es gibt zudem noch z.B. I für Probleme mit imports (isort), D für Docstring-Probleme (pydocstyle), UP für Upgrade-Empfehlungen (pyugrade).

Wir können auch schauen, welche Warnungen wir bereits durch die Formatierung mit Black erledigt haben:

Autoflake¶

Das Werkzeug Autoflake soll manche Probleme automatisch beheben:

Pylint¶

Ein eher pedantisches Werkzeug, um Konventionen zu prüfen. Vergibt eine Punktzahl, sodass man vergleichen kann, ob Änderungen am Code die so gemessene Code-Qualität verbessern oder verschlechtern.

Dabei haben wir sogar einige sehr nervige Meldungen unterdrückt, indem in der pyproject.toml dieser Abschnitt steht:

[tool.pylint.messages_control]
disable = [
    "missing-module-docstring",   # C0114
    "missing-class-docstring",    # C0115
    "missing-function-docstring", # C0116
    "too-few-public-methods",     # R0903
    "invalid-name",               # C0103
]

Und wir können auch Inline im Code Pylint-Warnungen unterdrücken, wie in diesem Beispiel:

def alte_funktion(a, b, c, d, e, f, g): # pylint: disable=too-many-arguments
    # pylint: disable=invalid-name
    x = a + b
    return x

Das ist dann sinnvoll, wenn wir z.B. die Methodensignatur nicht ändern können, weil eine alte API das so vorgibt.

Die Fehlercodes von Pylint sind nicht genau die selben wie bei Flake8, so steht z.B. C für Code Convention (also Stil), was bei Pylint bzw. pycodestyle E und F waren. Refactoring-Empfehlungen beginnen mit R.

FawltyDeps¶

FawltyDeps ist ein Dependency Linter. Es wird systematisch in .py und .ipynb nach Import-Deklarationen gesucht und mit Projektdateien wie requirements.txt oder pyproject.toml abgeglichen. Damit findet man Pakete, die man noch nicht explizit als Abhängigkeit deklariert hatte, sowie Pakete, deren Abhängigkeit im Code gar nicht gegeben ist, aber fälschlicherweise für das Paket deklariert wurde.

uvx fawltydeps

Bandit¶

Es gibt auch ‘Linter’ mit dem Ziel, Sicherheitslücken bzw. problematische Muster wie hartkodierte Passwörter zu finden. Wir stellen fest, dass der bisher besprochene Code nicht problematisch ist:

Das folgende ist ein Beispiel für Probleme, die Bandit aufdecken kann:

Interrogate¶

Wir hatten zuvor die pedantischen Meldungen über Docstrings abgeschaltet, würden aber evtl. doch eine Übersicht haben wollen, wie viel des Projekts dokumentiert ist:

Type Checker¶

Während Linters die Struktur prüfen, sichern Type-Checker die Typ-Konsistenz. Neben dem De-facto-Standard Mypy hat sich das von Microsoft entwickelte pyright durch extrem schnelle Analysezeiten etabliert. Jüngere Entwicklungen wie ty (astral-sh/ty) von den Machern von uv/ruff oder das darauf aufbauende pyrefly (Vergleich) experimentieren mit noch besserer Performance und tieferer Integration in moderne Toolchains (ähnlich wie Ruff es für Flake8/Black getan hat). Dabei geht der Trend zu eher strengeren Typ-Überprüfungen.

Wenn man die grundlegende Logik von mypy verstanden hat, lässt sich ein Projekt später leicht auf pyrefly umstellen. Generell kann man als Faustregel nutzen: sollen andere Entwickler den Code nutzen (als import), so sollte man eher strenge Typenchecks verwenden, ansonsten kann man es auch etwas lockerer handhaben.

Mypy¶

Damit wir uns nicht von der Fehlermeldung verwirren lassen, betrachten wir eine Version ohne den Fehler (wo die fehlende Exception deklariert ist):

Wir erinnern uns aber daran, dass der Code z.B. diese Zeile enthält:

def execute_trade(self, product, quantity: int, unit_price):

Da fehlen offensichtlich Type Hints bei product und unit_price, aber Mypy hat sich nicht beschwert (und bisher auch sonst kein Linter). Das lässt sich explizit einfordern:

Wir können auch Codeblöcke explizit von den Typechecker Warnungen ausschließen, wie in diesem Beispiel:

final_state = run_simulation(100.0, "10.0") # type: ignore[arg-type]

Vier Fallen, über die jeder einmal stolpert¶

Die Fehlermeldungen oben waren echte Funde. In der Praxis erzeugt Mypy daneben eine zweite Sorte Meldungen, die keine Fehler im eigenen Code sind. Wer die nicht einordnen kann, schaltet entnervt alles ab — und verliert damit auch die echten Funde.

1. Untypisierte Bibliotheken. error: Skipping analyzing "irgendwas": module is installed, but missing library stubs or py.typed marker. Das heißt nicht, dass Sie etwas falsch gemacht haben, sondern dass das Paket keine Typinformationen mitliefert (siehe den Abschnitt über py.typed). Drei Auswege, in dieser Reihenfolge:

# In pyproject.toml — pauschal, aber ehrlich:
[tool.mypy]
ignore_missing_imports = true

# Besser: nur für die Pakete, die es wirklich betrifft
[[tool.mypy.overrides]]
module = ["pygame.*", "joblib.*"]
ignore_missing_imports = true

Am besten wäre, Stubs zu installieren, falls es sie gibt (types-requests, pandas-stubs und Verwandte). Dann prüft Mypy die Aufrufe wirklich, statt sie als Any durchzuwinken.

2. # type: ignore zu grob. Ein nacktes # type: ignore schaltet in dieser Zeile alle Prüfungen ab — auch die, die später einmal einen echten Fehler melden würden. Schreiben Sie den Code dazu: # type: ignore[arg-type]. Welchen Code Sie brauchen, steht in der Meldung in eckigen Klammern. Mit warn_unused_ignores = true meldet Mypy Ihnen außerdem, wenn eine Unterdrückung überflüssig geworden ist — das passiert häufiger, als man denkt, etwa nachdem eine Bibliothek Typen nachgeliefert hat.

3. Die Python-Version nicht festgelegt. Mypy prüft gegen die Version des Interpreters, unter dem es selbst läuft. Das heißt: Auf Ihrem Rechner grün, in der CI rot, oder umgekehrt — und str | None ist unter der einen Version gültig und unter der anderen ein Syntaxfehler. Legen Sie die Version an drei Stellen konsistent fest:

# pyproject.toml
[project]
requires-python = ">=3.13"

[tool.mypy]
python_version = "3.13"

plus eine .python-version-Datei für uv (siehe Packaging).

4. Tests bleiben untypisiert. Typische Konfigurationen schließen tests/ aus — und genau dort steckt die Hälfte der Aufrufe der eigenen API. Wenn eine Funktionssignatur sich ändert, merkt es der Type Checker dann überall außer im Test. Nehmen Sie die Tests mit hinein; der Aufwand ist gering, weil Testfunktionen meist -> None zurückgeben.

Monkeytype¶

Da Python dynamisch ist, ist es schwierig über statische Analyse die Typen abzuleiten. Also führen wir das Programm doch einmal aus!

Das Modul Monkeytype versucht, während der Ausführung die Typinformation zu raten:

Da Monkeytype Code aus __main__ ignoriert, muss man einen Workaround nutzen, ein separates Runner Script:

Das fügt immer noch nicht alle Type Hints hinzu, die wir uns wünschen könnten, weil es Code gibt, der von unserem Runner nicht erreicht wird.

Laufzeit-Typüberprüfung¶

Mypy prüft Typen statisch, d.h. ohne Ausführung des Programms. In der Praxis stehen Dimensionen von Matrizen oder Tensoren manchmal erst zur Laufzeit fest. Die Bilbiothek typeguard erzwingt diese Checks während der Ausführung. Das Anwendungsgebiet von typeguard, Überprüfung, ist übrigens zu unterscheiden von der Konvertierung von Daten, wie es Pydantic macht (siehe späteres Kapitel).

Wenn man wirklich Array-Dimensionen spezifizieren möchte, kann jaxtyping hilfreich sein. Da die Typenprüfung von typeguard einer Liste der Länge $n$ in $O(n)$ läuft, verwendet man für große Daten eher den drop-in Ersatz beartype, in dem Listen nur stichprobenartig geprüft werden. Das ist zur Laufzeit oft hinreichend, während in einer kontrollierten Test-Umgebung dann wiederum typeguard aufgrund der Reproduzierbarkeit von Vorteil ist.

Ein (2, 1)-Array ist eine $2\times 1$-Matrix und kein flaches 1D-Array; die strikte Typüberprüfung verhindert hier ein fehlerhaftes, stillschweigendes numpy-Broadcasting. Der Output wäre ein (2, 2)-Array, also eine $2\times 2$-Matrix, kein 1D-Array. Ohne die Typüberprüfung kann das Broadcasting solche Fehler also weit weg transportieren.

Ruff¶

Ruff ist in Rust geschrieben und extrem schnell. Es ersetzt Flake8, isort, Black und viele mehr. In Projekten mit und ohne uv lässt es sich direkt via uvx ruff ausführen. Dabei ist ruff format als Drop-in Ersatz für den Formatter Black gedacht und ruff check ist der eigentliche Linter.

Man kann bei jedem brauchbaren Linter gezielt Warnungen deaktivieren, bei Ruff mit noqa: CODE, hier E722 für den Bare-Except-Fehler (noqa = No Quality Assurance):

Wie beim graduellen Hinzufügen von Typeninformationen kann man auch das Lintern des Codes nach und nach machen, indem man z.B. für eine ganze Datei Fehlercodes ausschließt mit einem Kommentar # ruff: noqa: CODE am Anfang der Datei.

Die Fehlercode-Systematik übernimmt Ruff von Flake8, wobei Pylint-Fehler auch mit dem Prefix PL verwendet werden können (etwa in noqa-Anweisungen).

Konfiguration zum Kopieren¶

Ruff wird über die pyproject.toml konfiguriert, mit der Sie ohnehin schon arbeiten. Der folgende Block ist ein sinnvoller Ausgangspunkt für ein Projekt in diesem Kurs — inklusive Mypy, damit beide Werkzeuge dieselbe Python-Version annehmen:

[tool.ruff]
line-length = 80
target-version = "py313"

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B"]
ignore = ["E501"]       # Zeilenlaenge meldet der Formatter, nicht der Linter

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["B011"]    # assert False ist in Tests in Ordnung

[tool.ruff.format]
quote-style = "double"

[tool.mypy]
python_version = "3.13"
ignore_missing_imports = true
warn_redundant_casts = true
warn_unused_ignores = true

Die fünf Regelgruppen hinter select sind bewusst knapp gehalten — sie decken den größten Teil des Nutzens ab, ohne dass man vor einer Wand aus Meldungen steht:

Wer mehr will, schaltet gruppenweise zu ("SIM" für Vereinfachungen, "RUF" für Ruff-eigene Regeln, "ANN" für fehlende Annotationen) — aber erst, wenn das Projekt mit den fünf oben sauber ist.

Dieses Skript selbst benutzt genau diesen Block. In seiner pyproject.toml stehen zusätzlich ein paar exclude-Einträge, jeweils mit einer Zeile Begründung daneben: Die absichtlich fehlerhaften Lehrbeispiele in diesem Kapitel und der KI-generierte Code aus Generierte Wirtschaftssimulation sollen nicht sauber sein — das ist ihr Zweck. exclude mit Begründung ist legitim, exclude ohne Begründung ist Aufschieben.

Bemerkenswert ist, was dort nicht steht: strict = true für Mypy. Der Abschnitt oben lebt davon, den Unterschied zwischen einem normalen Lauf und --strict zu zeigen; eine projektweite Voreinstellung würde genau diesen Kontrast unsichtbar machen. Für Ihr eigenes Projekt ist strict = true trotzdem die Empfehlung — am besten von Anfang an, weil das nachträgliche Einschalten in einem gewachsenen Projekt hunderte Meldungen auf einmal produziert.

UP als Modernisierer¶

Die Regelgruppe UP verdient eine eigene Erwähnung, weil sie etwas anderes tut als der Rest: Sie meldet nicht, dass etwas falsch ist, sondern dass es alt ist. Damit wird Ruff zu einem Werkzeug für fremden, gewachsenen Code — das Verfahren, mit dem man ein Projekt von 2013 in wenigen Minuten auf heutige Syntax hebt.

Hier eine Datei, wie man sie in älteren Projekten findet:

--diff zeigt nur, was passieren würde; --fix schreibt es in die Datei. Die Empfehlung für fremden Code lautet: erst --diff lesen, dann --fix, und das Ergebnis als eigenen Commit — getrennt von jeder inhaltlichen Änderung. Sonst versteckt sich die eine Zeile, die wirklich etwas ändert, zwischen zweihundert Zeilen Modernisierung.

Zwei Details, die das Beispiel zeigt:

• Dict/List/Optional aus typing sind seit Python 3.9 bzw. 3.10 durch dict, list und | ersetzt. Ruff weiß das nur, weil target-version gesetzt ist — ohne diese Angabe bleibt es vorsichtig und meldet nichts.

• Die Meldung “1 additional fix available with --unsafe-fixes” betrifft das "%s/%s" % (...). Ruff nennt eine Korrektur unsafe, wenn sie das Verhalten in Randfällen ändern könnte. Solche Korrekturen sieht man sich einzeln an, statt sie pauschal durchzuwinken — und genau dafür gibt es die Trennung.

Was UP nicht kann: Es modernisiert Syntax, nicht Architektur. Ein Projekt, das nach ruff check --select UP --fix durchläuft, benutzt aktuelle Schreibweisen — ob es sinnvoll geschnitten ist, steht auf einem anderen Blatt.

Automatisierung¶

Wir wollen Code-Qualitätstests nicht bei jeder Änderung manuell im Terminal anstoßen. In der Praxis greifen Automatisierungen auf verschiedenen Ebenen ineinander:

• IDE-Integration: Moderne Entwicklungsumgebungen formatieren den Code oft bereits beim Speichern (Format on Save), wenn man das möchte. Dadurch werden Stil-Konflikte (unnötige Diffs) in der Versionskontrolle minimiert.

• Lokale Automatisierung (Pre-Commit-Hooks): Um zu verhindern, dass Linter-Fehler überhaupt erst in die Versionskontrolle gelangen, verankert man die Checks im Git-Workflow.

• Serverseitige Automatisierung (CI/CD): CI-Systeme wie GitLab CI oder GitHub Actions führen Linter und Tests bei jedem Push in sauberen Containern aus. Das garantiert Reproduzierbarkeit unabhängig vom Rechner der Entwickler*innen.

pre-commit¶

Das Tool pre-commit verwaltet Skripte, die Git automatisch vor jedem git commit ausführt. Schlägt ein Test fehl, wird der Commit abgebrochen. Die Konfiguration erfolgt über eine Datei namens .pre-commit-config.yaml im Hauptverzeichnis des Projekts.

Ein typisches Setup, das Standard-Fehler behebt und Ruff für Linting und Formatierung nutzt, sieht so aus:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-added-large-files

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.4
    hooks:
      # Linter ausführen (und beheben, falls möglich)
      - id: ruff
        args: [ --fix ]
      # Formatter ausführen
      - id: ruff-format

und uvx pre-commit install installiert den pre-commit-hook so, dass git commit ihn auslöst.

Continuous Integration¶

Serverseitig wird z.B. die .gitlab-ci.yml so konfiguriert:

stages:
  - lint

lint_code:
  stage: lint
  image: python:3.13-slim
  script:
    - pip install uv
    - uv pip install --system ruff mypy
    
    # Checks durchführen (Fehler führen zum Abbruch der Pipeline)
    - ruff check .
    - ruff format --check .
    - mypy .

Dabei ist python:3.13-slim ein Docker-Image, also reproduzierbar und sandboxed.

Zum Ende des Notebooks räumen wir die temporären Dateien wieder auf:

Zusammenfassung und Kontrollfragen¶

1. Die drei Werkzeugklassen beantworten verschiedene Fragen: Ein Formatter entscheidet über das Aussehen, ein Linter erkennt verdächtige Muster, ein Type Checker prüft die Verträglichkeit von Typen.

2. Formatierung hört auf, ein Review-Thema zu sein, sobald sie automatisiert ist — deshalb hat ein Formatter das beste Verhältnis von Aufwand zu vermiedenem Streit.

3. ruff ersetzt Black, isort und Flake8 in einem Programm und ist dabei um Größenordnungen schneller; die Regelgruppen schaltet man einzeln zu, statt alles auf einmal.

4. Mypy prüft nur, was annotiert ist: Fehlende Type Hints sind im Standardlauf unsichtbar und werden erst mit --strict zum Fehler.

5. Verbindlich wird all das erst durch Automatisierung — pre-commit lokal vor dem Commit, die CI als letzte Instanz, die niemand vergessen kann.

Kontrollfragen

1. Mypy meldet für eine Funktion ohne Type Hints keinen Fehler. Ist die Funktion deshalb typsicher? Welcher Schalter ändert die Antwort, und warum ist er nicht die Voreinstellung dieses Skripts?

2. In welcher Reihenfolge wenden Sie ruff format, ruff check --fix und mypy auf ein fremdes Projekt an? Warum gehört das Ergebnis in einen eigenen Commit?

3. Eine Bibliothek liefert keine Typinformationen mit, und Mypy meldet das bei jedem Import. Welche Auswege gibt es, und welcher ist der bessere — mit Begründung?