Ein Django-Projekt mit django-upgrade aktualisieren

Bevor wir django-upgrade in Aktion sehen, lohnt sich ein kurzer Blick auf den Release-Rhythmus von Django. Denn er bestimmt, auf welche Version du sinnvollerweise springst.

Wann lohnt sich ein Upgrade überhaupt?

Django bringt etwa alle acht Monate ein Feature-Release (A.B) mit neuen Funktionen heraus. Dazwischen erscheinen bei Bedarf Patch-Releases (A.B.C), die Fehler beheben und Sicherheitslücken schliessen. Jedes dritte Feature-Release ist ein LTS-Release (Long Term Support). Diese Versionen erhalten rund drei Jahre lang Sicherheits- und Datenverlust-Fixes. Normale Versionen werden dagegen nur bis zum übernächsten Release unterstützt.

Konkret sieht der Fahrplan aktuell so aus:

• 5.2 LTS ist die letzte langzeitunterstützte Version
• 6.0 ist das neueste offizielle Release
• 6.1 erscheint im August 2026
• 6.2 LTS folgt im April 2027

Für produktiv laufende Projekte sind die LTS-Versionen die natürlichen Sprungziele. Zuletzt war das 4.2, jetzt 5.2, als Nächstes 6.2. Wer nicht alle acht Monate aufs Neue upgraden will, fährt mit dieser Strategie am ruhigsten: lange Supportfenster, planbare Wartung, weniger Aufwand. Wichtig dabei ist, die LTS-Version immer mit den laufend herauskommenden Sicherheitsupdates zu versehen.

Im folgenden Tutorial zeige ich dir Schritt für Schritt, wie dich django-upgrade beim Sprung auf die nächste Version unterstützt.

Veraltete Funktionen mit django-upgrade aktualisieren

Mit jedem neuen Feature-Release stuft Django einige Funktionen als veraltet ein. Das macht eine Aktualisierung des Projekts nötig, was mühsam sein kann, wenn du diese Änderungen für alle betroffenen Dateien von Hand vornehmen musst. Hier kommt django-upgrade ins Spiel, das diese Arbeit automatisiert.

Funktionen, die Django als veraltet einstuft, werden bei jedem Ausführen des lokalen Runservers in der Konsole angezeigt.

Mit Version 3.0 wurde zum Beispiel die Funktion django.shortcuts.render_to_response() entfernt und definitiv durch render() ersetzt.

Dieser Aufruf:

from django.shortcuts import render_to_response
def my_view(request):
    return render_to_response("index.html", {"key": "value"})

Muss nun so geschrieben werden:

from django.shortcuts import render
 def my_view(request):
   return render(request, "index.html", {"key": "value"})

Genau solche mechanischen Umschreibungen nimmt dir django-upgrade mit einer einzigen Zeile in der Bash ab, du musst nicht jeden veralteten (deprecated) Code von Hand anpassen.

Der Einsatz von django-upgrade

Der Einsatz von django-upgrade ist denkbar einfach. Mit folgendem Befehl installierst du das Package:

pip install django-upgrade

Um eine einzelne Datei nach veraltetem Code zu durchforsten und automatisch anpassen zu lassen, führe folgenden Befehl aus:

django-upgrade example.py

Um auf eine spezifische Django-Version zu prüfen, benutze die Option --target-version. Zum Beispiel für Version 5.2:

django-upgrade --target-version 5.2 example.py

Von Haus aus kann django-upgrade nur einzelne Dateien überprüfen und anpassen. Es gibt aber einen "offiziellen" Workaround, wenn du dein Projekt mit Git versionierst. Mit diesem Befehl aus den Docs von django-upgrade kannst du alle Python-Dateien mit einem Befehl kontrollieren und konvertieren.

Für Mac und Linux:

git ls-files -z -- '*.py' | xargs -0r django-upgrade

Und für Windows-Powershell:

git ls-files -- '*.py' | %{django-upgrade $_}

Ist dein Projekt nicht mit Git versioniert, kannst du zum Beispiel das Kommandozeilen-Werkzeug find benutzen. Das könnte so aussehen:

find . -type f -name "*.py" -print0 | xargs -0r django-upgrade

Achte bei diesem Befehl darauf, dass sich deine virtuelle Umgebung ausserhalb des zu durchsuchenden Verzeichnisses befindet. Sonst würden auch alle Python-Dateien von fremden Paketen in venv, .venv, env, etc. geändert werden. Liegt deine virtuelle Umgebung im gleichen Ordner wie die Projektdateien, kannst du den Befehl so anpassen (ersetze venv durch den Namen deines virtuellen Verzeichnisses):

find . -type f -name "*.py" -not -path "*/venv/*" -print0 | xargs -0r django-upgrade

Mit -not -path wird das Verzeichnis venv von der Suche ausgeschlossen.

Automatisierung mit django-upgrade

Du kannst django-upgrade mit pre-commit (einem Framework zum Verwalten von pre-commit hooks) bei jedem Git-Commit automatisch laufen lassen und so sicherstellen, dass du keine veralteten Funktionen im Code hast. Wichtig ist, dass django-upgrade vor Formatierungstools wie Black und isort ausgeführt wird. So greift django-upgrade nicht in deinen Code-Style ein, weil seine Änderungen vor den in Black oder isort eingestellten Formatierungsoptionen laufen.

Das Konfigurationsfile von Adam Johnson dafür sieht so aus (die Versionsnummern sind nur ein Beispiel, passe --target-version auf deine eigene Ziel-Django-Version an, z.B. 5.2):

repos:
  - repo: https://github.com/asottile/pyupgrade
    rev: v2.26.0
    hooks:
      - id: pyupgrade
        args: [--py39-plus]
  - repo: https://github.com/adamchainz/django-upgrade
    rev: 1.2.0
    hooks:
      - id: django-upgrade
        args: [--target-version, "3.2"]
  - repo: https://github.com/psf/black
    rev: 21.8b0
    hooks:
      - id: black
  - repo: https://github.com/pycqa/isort
    rev: 5.9.3
    hooks:
      - id: isort
  - repo: https://github.com/PyCQA/flake8
    rev: 3.9.2
    hooks:
      - id: flake8

Zusammenfassung

django-upgrade nimmt dir die mühsamste Arbeit beim Django-Upgrade ab: das mechanische Umschreiben von veraltetem Code. In Kombination mit pre-commit läuft die Prüfung automatisch bei jedem Commit mit, ohne dass du sie manuell anstossen musst.

Konkrete Handlungsempfehlung: Setze dir als Ziel jeweils die nächste LTS-Version, aktuell 5.2, in Zukunft 6.2. Richte django-upgrade als pre-commit-Hook ein, bevor du das nächste Mal upgradest, dann läuft die Migration künftig laufend im Hintergrund mit statt als einmaliger Kraftakt.

Quellen

django-upgrade

Blogpost von Adam Johnson zu django-upgrade

pre-commit Framework

Django Deprecation Timeline