• 3.1
  • Версия документации: 6.1

Примечания к выпуску Django 5.2

2 апреля 2025 г.

Добро пожаловать в Джанго 5.2!

В этих примечаниях к выпуску описаны новые функции, а также некоторые обратно несовместимые изменения, о которых вам следует знать при обновлении с Django 5.1 или более ранней версии. Мы начали процесс прекращения поддержки некоторых функций.

См. руководство Обновление Django до новой версии, если вы обновляете существующий проект.

Django 5.2 обозначен как выпуск с долгосрочной поддержкой. Он будет получать обновления безопасности в течение как минимум трех лет после выпуска. Поддержка предыдущей версии LTS, Django 4.2, закончится в апреле 2026 года.

Совместимость версий Python

Django 5.2 поддерживает Python 3.10, 3.11, 3.12, 3.13 и 3.14 (начиная с версии 5.2.8). Мы настоятельно рекомендуем и официально поддерживаем только последнюю версию каждой серии.

Что нового в Джанго 5.2

Автоматический импорт моделей в оболочку

Команда управления shell теперь автоматически импортирует модели из всех установленных приложений. Вы можете просмотреть дополнительную информацию об импортированных объектах, установив для флага --verbosity значение 2 или более:

$ python -Wall manage.py shell --verbosity=2
6 objects imported automatically, including:

  from django.contrib.admin.models import LogEntry
  from django.contrib.auth.models import Group, Permission, User
  from django.contrib.contenttypes.models import ContentType
  from django.contrib.sessions.models import Session

...\> py -Wall manage.py shell --verbosity=2
6 objects imported automatically, including:

  from django.contrib.admin.models import LogEntry
  from django.contrib.auth.models import Group, Permission, User
  from django.contrib.contenttypes.models import ContentType
  from django.contrib.sessions.models import Session

Это поведение можно настроить для добавления или удаления автоматического импорта.

Составные первичные ключи

Новый django.db.models.CompositePrimaryKey позволяет создавать таблицы с первичным ключом, состоящим из нескольких полей.

Чтобы использовать составной первичный ключ, при определении модели установите для атрибута pk значение CompositePrimaryKey:

from django.db import models


class Release(models.Model):
    pk = models.CompositePrimaryKey("version", "name")
    version = models.IntegerField()
    name = models.CharField(max_length=20)

Дополнительную информацию см. в Составные первичные ключи.

Упрощенное переопределение BoundField

До версии 5.2 переопределение Field.get_bound_field() было единственным вариантом использования пользовательского BoundField. Django теперь поддерживает указание следующих атрибутов для настройки рендеринга форм:

Например, чтобы настроить BoundField класса Form:

from django import forms


class CustomBoundField(forms.BoundField):

    custom_class = "custom"

    def css_classes(self, extra_classes=None):
        result = super().css_classes(extra_classes)
        if self.custom_class not in result:
            result += f" {self.custom_class}"
        return result.strip()


class CustomForm(forms.Form):
    bound_field_class = CustomBoundField

    name = forms.CharField(
        label="Your Name",
        max_length=100,
        required=False,
        widget=forms.TextInput(attrs={"class": "name-input-class"}),
    )
    email = forms.EmailField(label="Your Email")

При рендеринге экземпляра CustomForm включается следующий HTML-код:

<div class="custom">
  <label for="id_name">Your Name:</label>
  <input type="text" name="name" class="name-input-class" maxlength="100" id="id_name">
</div>

<div class="custom">
  <label for="id_email">Your Email:</label>
  <input type="email" name="email" maxlength="320" required="" id="id_email">
</div>

См. Настройка BoundField для получения более подробной информации об этой функции.

Минорные изменения

django.contrib.admin

  • В шаблоне admin/base.html теперь есть новый блок extrabody для добавления пользовательского кода перед закрывающим тегом </body>.

  • Значение URLField теперь отображается как ссылка.

django.contrib.admindocs

  • Ссылки на компоненты в строках документации теперь поддерживают настраиваемый текст ссылки в формате :role:`link text <link>`. Дополнительную информацию смотрите в разделе помощники по документации.

  • Страницы модели <admindocs-model-reference> теперь доступны только пользователям с соответствующими разрешениями на просмотр или изменение.

django.contrib.auth

django.contrib.gis

django.contrib.syndicate

  • Все классы SyndictionFeed теперь поддерживают атрибут stylesheets. Если указано, <? xml-stylesheet ?> инструкция обработки будет добавлена ​​в начало документа для каждой таблицы стилей в данном списке. Дополнительную информацию см. в разделе Таблицы стилей фидов.

Серверные базы данных

  • Соединения MySQL теперь по умолчанию используют набор символов utf8mb4 вместо utf8, который является псевдонимом устаревшего набора символов utf8mb3.

  • Серверные части Oracle теперь поддерживают пулы соединений, установив "pool" в части OPTIONS конфигурации вашей базы данных.

Декораторы

  • method_decorator() теперь поддерживает перенос методов асинхронного представления.

Электронная почта

  • Элементы кортежей EmailMessage.attachments и EmailMultiAlternatives.attachments теперь называются кортежами, а не обычными кортежами.

  • EmailMultiAlternatives.alternatives теперь представляет собой список именованных кортежей, а не обычных кортежей.

  • Новый метод body_contains() возвращает логическое значение, указывающее, содержится ли предоставленный текст в body электронного письма и во всех прикрепленных альтернативах MIME-типа text/*.

Отчеты об ошибках

Формы

  • Новый виджет формы ColorInput предназначен для ввода цвета в шестнадцатеричном формате rrggbb и отображается как <input type="color" ...>. Некоторые браузеры поддерживают визуальный интерфейс выбора цвета для этого типа ввода.

  • Новый виджет формы SearchInput предназначен для ввода поисковых запросов и отображается как <input type="search" ...>.

  • Новый виджет формы TelInput предназначен для ввода телефонных номеров и отображается как <input type="tel" ...>.

  • Новый аргумент field_id для :class:~django.forms.ErrorList позволяет добавить атрибут HTML id в шаблон ошибки. Подробности смотрите в ErrorList.field_id.

  • Свойство aria_describedby добавлено в BoundField, чтобы упростить использование этого HTML-атрибута в шаблонах.

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

  • Новый объект ресурса Script доступен для добавления пользовательских HTML-атрибутов в JavaScript в медиа-форме. Дополнительную информацию см. в разделе «Пути как объекты <form-media-asset-objects>».

Команды управления

  • При запуске runserver отображается новое предупреждение, указывающее, что он непригоден для производства. Это предупреждение можно подавить, установив для переменной среды DJANGO_RUNSERVER_HIDE_WARNING значение "true".

  • Команды makemigrations и migrate имеют новый атрибут Command.autodetector, который можно переопределить подклассами, чтобы использовать собственный класс автодетектора.

  • Новый метод BaseCommand.get_check_kwargs() можно переопределить в пользовательских командах для управления выполнением системных проверок, например. чтобы выбрать проверки, зависящие от базы данных.

Миграции

  • Новая операция AlterConstraint — это пустая операция, которая изменяет ограничения без удаления и повторного создания ограничений в базе данных.

Модели

  • Предложение SELECT, созданное при использовании QuerySet.values() и QuerySet.values_list(), теперь соответствует указанному порядку выражений, на которые ссылаются. Раньше порядок основывался на наборе нелогичных правил, которые делали комбинирование запросов с помощью таких методов, как QuerySet.union(), непредсказуемым.

  • Добавлена ​​поддержка проверки ограничений модели, использующих GeneratedField.

  • Новый атрибут Expression.set_returning указывает, что выражение содержит функцию, возвращающую множество, обеспечивающую оценку подзапроса. Это необходимо для многих функций Postgres, возвращающих множество.

  • CharField.max_length больше не требуется устанавливать в SQLite, который поддерживает неограниченное количество столбцов VARCHAR.

  • QuerySet.explain() теперь поддерживает опции memory и serialize в PostgreSQL 17+.

  • Новая функция базы данных JSONArray принимает список имен полей или выражений и возвращает массив JSON, содержащий эти значения.

  • Новый атрибут Expression.allows_composite_expressions указывает, что выражение позволяет составным выражениям, например, поддерживать составные первичные ключи.

Запросы и ответы

  • Новое свойство HttpResponse.text обеспечивает строковое представление HttpResponse.content.

  • Новый метод HttpRequest.get_preferred_type() можно использовать для запроса предпочтительного типа носителя, который принимает клиент.

  • Новый аргумент preserve_request для HttpResponseRedirect и HttpResponsePermanentRedirect определяет, используются ли коды состояния HTTP 302/307 или 301/308 соответственно.

  • Новый аргумент preserve_request для redirect() позволяет указать пользовательскому агенту повторно использовать метод и тело HTTP во время перенаправления с использованием определенных кодов состояния.

Сериализация

  • Каждый формат сериализации теперь определяет класс Deserializer, а не функцию, чтобы улучшить расширяемость при определении пользовательского формата сериализации <custom-serialization-formats>`.

Шаблоны

  • Новый декоратор simple_block_tag() позволяет создавать простые теги блоков, которые могут принимать и использовать раздел шаблона.

Тесты

  • Фреймы стека из пользовательских утверждений Django теперь скрыты. Это облегчает чтение ошибок теста и позволяет test --pdb напрямую войти в метод теста, который дал сбой.

  • Данные, загруженные из fixtures и из миграций, включенных с помощью serialized_rollback=True, теперь доступны во время TransactionTestCase.setUpClass().

URL-адреса

  • reverse() и reverse_lazy() теперь принимают ключевые аргументы query и fragment, что позволяет добавлять строку запроса и/или идентификатор фрагмента в сгенерированный URL-адрес соответственно.

Утилиты

  • SafeString теперь возвращает NotImplemented в __add__ для нестроковых значений в правой части. Это соответствует поведению добавления str и позволяет использовать __radd__, если он доступен.

  • format_html_join() теперь поддерживает итерацию отображений, передавая их содержимое в качестве аргументов ключевого слова в format_html().

Изменения обратной несовместимости в версии 5.2

Серверный API базы данных

В этом разделе описаны изменения, которые могут потребоваться в сторонних базах данных.

  • Новый метод Model._is_pk_set() позволяет проверить, определен ли первичный ключ экземпляра модели.

  • BaseDatabaseOperations.adapt_decimalfield_value() теперь не выполняет никаких операций и просто возвращает заданное значение.

django.contrib.gis

  • Поддержка PostGIS 3.0 удалена.

  • Поддержка GDAL 3.0 удалена.

Прекращена поддержка PostgreSQL 13.

Поддержка исходной версии PostgreSQL 13 заканчивается в ноябре 2025 года. Django 5.2 поддерживает PostgreSQL 14 и выше.

Изменен набор символов соединения MySQL по умолчанию.

Соединения MySQL теперь по умолчанию используют набор символов utf8mb4 вместо utf8, который является псевдонимом устаревшего набора символов utf8mb3. utf8mb3 можно указать в разделе OPTIONS параметра DATABASES, если это необходимо для устаревших баз данных.

Разнообразный

Функции, устаревшие в версии 5.2

Разнообразный

  • Аргумент all для функции django.contrib.staticfiles.finders.find() устарел в пользу аргумента find_all.

  • Резервные варианты к request.user и request.auser(), когда user имеет значение None в django.contrib.auth.login() и django.contrib.auth.alogin() соответственно, считаются устаревшими.

  • Аргумент ключевого слова ordering для специальных функций агрегации PostgreSQL django.contrib.postgres.aggregates.ArrayAgg, django.contrib.postgres.aggregates.JSONBAgg и django.contrib.postgres.aggregates.StringAgg устарел в пользу аргументаorder_by.

  • Поддержка подклассов RemoteUserMiddleware, которые переопределяют process_request() без переопределения aprocess_request(), устарела.

Back to Top