Как обновить Django до более новой версии

Что необходимо прочитать

Если вы обновляете Django впервые, полезно прочитать руководство о различных процессах выпуска.

Затем ознакомьтесь с изменениями, внесёнными в новую версию Django (или новые версии Django):

• Прочитайте примечания к выпуску для каждого окончательного выпуска, начиная с версии, следующей за вашей текущей версией Django, и заканчивая версией, до которой вы планируете обновиться.
• Изучите график устаревания для соответствующих версий.

Особое внимание уделите несовместимым с предыдущими версиями изменениям, чтобы чётко понимать, что потребуется для успешного обновления.

Если вы обновляетесь через несколько версий с новыми возможностями (например, с 2.0 до 2.2), обычно проще обновляться постепенно через каждый выпуск с новыми возможностями (с 2.0 до 2.1, затем до 2.2), а не вносить сразу все изменения для каждого такого выпуска. Для каждого выпуска используйте последний выпуск с исправлениями (например, для 2.1 — 2.1.15).

При обновлении с одной версии LTS до следующей также рекомендуется выполнять обновление постепенно.

Зависимости

В большинстве случаев потребуется также обновить зависимости, связанные с Django, до последних версий. Если версия Django выпущена недавно или некоторые ваши зависимости плохо поддерживаются, они могут пока не поддерживать новую версию Django. В таких случаях, возможно, придётся подождать выхода новых версий этих зависимостей.

Устранение предупреждений об устаревании

Перед обновлением рекомендуется устранить все предупреждения об устаревании, которые выдаёт ваш проект при работе с текущей версией Django. Устранение этих предупреждений до обновления поможет определить участки кода, которые необходимо изменить.

В Python предупреждения об устаревании по умолчанию отключены. Чтобы включить их, используйте параметр командной строки Python -Wa или переменную окружения PYTHONWARNINGS. Например, чтобы показывать предупреждения при запуске тестов:

$ python -Wa manage.py test

...\> py -Wa manage.py test

Если вы не используете средство запуска тестов Django, возможно, вам также потребуется убедиться, что вывод в консоль не перехватывается, поскольку в противном случае предупреждения об устаревании будут скрыты. Например, если вы используете pytest:

$ PYTHONWARNINGS=always pytest tests --capture=no

Прежде чем продолжить обновление, устраните все предупреждения об устаревании, возникающие при работе с текущей версией Django.

Сторонние приложения могут использовать устаревшие API для поддержки нескольких версий Django, поэтому предупреждения об устаревании в установленных пакетах не обязательно указывают на проблему. Если пакет не поддерживает последнюю версию Django, рассмотрите возможность сообщить об этом или отправить для него запрос на включение изменений.

Установка

Когда будете готовы, пора установить новую версию Django. Если вы используете virtual environment и выполняете крупное обновление, возможно, стоит сначала создать новое окружение со всеми зависимостями.

Если вы установили Django с помощью pip, можно использовать флаг --upgrade или -U:

$ python -m pip install -U Django

...\> py -m pip install -U Django

Тестирование

Когда новое окружение будет готово, запустите полный набор тестов приложения. Как и прежде, полезно включить предупреждения об устаревании, чтобы они отображались в выводе тестов (этот флаг можно использовать и при ручном тестировании приложения с помощью manage.py runserver):

$ python -Wa manage.py test

...\> py -Wa manage.py test

После запуска тестов устраните все ошибки. Пока вы ещё хорошо помните примечания к выпуску, можно также воспользоваться новыми возможностями Django и переработать код, чтобы устранить все предупреждения об устаревании.

Развёртывание

Когда вы будете достаточно уверены, что приложение работает с новой версией Django, можно развернуть обновлённый проект Django.

Если вы используете кэширование, предоставляемое Django, рекомендуется очистить кэш после обновления. В противном случае могут возникнуть проблемы, например, если вы кэшируете объекты в формате pickle: не гарантируется, что такие объекты будут совместимы с pickle в разных версиях Django. Ранее несовместимость возникала при кэшировании объектов HttpResponse в формате pickle — напрямую или косвенно с помощью декоратора cache_page().