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

Фасетные фильтры в админке¶

Количество фасетов теперь отображается для примененных фильтров в списке изменений в админке при включении через пользовательский интерфейс. Это поведение можно изменить с помощью нового атрибута ModelAdmin.show_facets. Для получения дополнительной информации смотрите Грани.

Упрощенные шаблоны для отрисовки полей формы¶

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

Например, шаблон ниже:

<form>
...
<div>
  {{ form.name.label_tag }}
  {% if form.name.help_text %}
    <div class="helptext" id="{{ form.name.auto_id }}_helptext">
      {{ form.name.help_text|safe }}
    </div>
  {% endif %}
  {{ form.name.errors }}
  {{ form.name }}
  <div class="row">
    <div class="col">
      {{ form.email.label_tag }}
      {% if form.email.help_text %}
        <div class="helptext" id="{{ form.email.auto_id }}_helptext">
          {{ form.email.help_text|safe }}
        </div>
      {% endif %}
      {{ form.email.errors }}
      {{ form.email }}
    </div>
    <div class="col">
      {{ form.password.label_tag }}
      {% if form.password.help_text %}
        <div class="helptext" id="{{ form.password.auto_id }}_helptext">
          {{ form.password.help_text|safe }}
        </div>
      {% endif %}
      {{ form.password.errors }}
      {{ form.password }}
    </div>
  </div>
</div>
...
</form>

Теперь это можно упростить до:

<form>
...
<div>
  {{ form.name.as_field_group }}
  <div class="row">
    <div class="col">{{ form.email.as_field_group }}</div>
    <div class="col">{{ form.password.as_field_group }}</div>
  </div>
</div>
...
</form>

<<<По умолчанию as_field_group() отображает поля с шаблоном "django/forms/field.html" и может быть настроен для каждого проекта, каждого поля или каждого запроса. Смотрите Шаблоны групп полей многократного использования.

Значения по умолчанию, рассчитанные на основе базы данных¶

Новый параметр Field.db_default устанавливает значение по умолчанию, вычисленное по базе данных. Например:

from django.db import models
from django.db.models.functions import Now, Pi


class MyModel(models.Model):
    age = models.IntegerField(db_default=18)
    created = models.DateTimeField(db_default=Now())
    circumference = models.FloatField(db_default=2 * Pi())

Поле модели, созданное в базе данных¶

Новый GeneratedField позволяет создавать колонки, генерируемые базой данных. Это поле можно использовать во всех поддерживаемых бэкендах баз данных для создания поля, которое всегда вычисляется из других полей. Например:

from django.db import models
from django.db.models import F


class Square(models.Model):
    side = models.IntegerField()
    area = models.GeneratedField(
        expression=F("side") * F("side"),
        output_field=models.BigIntegerField(),
        db_persist=True,
    )

Больше возможностей для объявления вариантов полей¶

Field.choices (для полей модели) и ChoiceField.choices (для полей формы) позволяют более гибко подходить к объявлению их значений. В предыдущих версиях Django, choices должен был быть либо списком из двух кортежей, либо подклассом Типы перечисления, но последний требовал обращения к атрибуту .choices для предоставления значений в ожидаемой форме:

from django.db import models

Medal = models.TextChoices("Medal", "GOLD SILVER BRONZE")

SPORT_CHOICES = [
    ("Martial Arts", [("judo", "Judo"), ("karate", "Karate")]),
    ("Racket", [("badminton", "Badminton"), ("tennis", "Tennis")]),
    ("unknown", "Unknown"),
]


class Winner(models.Model):
    name = models.CharField(...)
    medal = models.CharField(..., choices=Medal.choices)
    sport = models.CharField(..., choices=SPORT_CHOICES)

В Django 5.0 добавлена поддержка приема отображения или callable вместо iterable, а также больше не требуется использовать .choices напрямую для расширения enumeration types:

from django.db import models

Medal = models.TextChoices("Medal", "GOLD SILVER BRONZE")

SPORT_CHOICES = {  # Using a mapping instead of a list of 2-tuples.
    "Martial Arts": {"judo": "Judo", "karate": "Karate"},
    "Racket": {"badminton": "Badminton", "tennis": "Tennis"},
    "unknown": "Unknown",
}


def get_scores():
    return [(i, str(i)) for i in range(10)]


class Winner(models.Model):
    name = models.CharField(...)
    medal = models.CharField(..., choices=Medal)  # Using `.choices` not required.
    sport = models.CharField(..., choices=SPORT_CHOICES)
    score = models.IntegerField(choices=get_scores)  # A callable is allowed.

Под капотом предоставленные choices нормализуются в список из 2 кортежей в качестве канонической формы каждый раз, когда значение choices обновляется. Для получения дополнительной информации, пожалуйста, ознакомьтесь с model field reference on choices.

Незначительные особенности¶

API бэкенда базы данных¶

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

• DatabaseFeatures.supports_expression_defaults следует установить значение False, если база данных не поддерживает использование функций базы данных в качестве значений по умолчанию.
• DatabaseFeatures.supports_default_keyword_in_insert следует установить значение False, если база данных не поддерживает ключевое слово DEFAULT в запросах INSERT.
• DatabaseFeatures.supports_default_keyword_in_bulk_insert следует установить значение False, если база данных не поддерживает ключевое слово DEFAULT в массовых INSERT запросах.

django.contrib.gis¶

• Поддержка GDAL 2.2 и 2.3 удалена.
• Поддержка GEOS 3.6 и 3.7 удалена.

django.contrib.sitemaps¶

• Функция django.contrib.sitemaps.ping_google() и команда управления ping_google удалены, так как конечная точка Google Sitemaps ping устарела и будет удалена в январе 2024 года.
• Класс исключений django.contrib.sitemaps.SitemapNotFound удален.

Прекращена поддержка MySQL < 8.0.11¶

Убрана поддержка предварительных выпусков MySQL серии 8.0.x. Django 5.0 поддерживает MySQL 8.0.11 и выше.

Использование create_defaults__exact теперь может потребоваться при использовании QuerySet.update_or_create().¶

QuerySet.update_or_create() теперь поддерживает параметр create_defaults. Как следствие, все модели, имеющие поле с именем create_defaults, которое используется с update_or_create(), должны указывать это поле в поиске с помощью create_defaults__exact.

Перенос существующих UUIDField на MariaDB 10.7+¶

В MariaDB 10.7+, UUIDField теперь создается как UUID столбец, а не CHAR(32). Как следствие, любой UUIDField, созданный в Django < 5.0, должен быть заменен на подкласс UUIDField, поддерживаемый CHAR(32):

class Char32UUIDField(models.UUIDField):
    def db_type(self, connection):
        return "char(32)"

    def get_db_prep_value(self, value, connection, prepared=False):
        value = super().get_db_prep_value(value, connection, prepared)
        if value is not None:
            value = value.hex
        return value

Например:

class MyModel(models.Model):
    uuid = models.UUIDField(primary_key=True, default=uuid.uuid4)

Должно стать:

class Char32UUIDField(models.UUIDField): ...


class MyModel(models.Model):
    uuid = Char32UUIDField(primary_key=True, default=uuid.uuid4)

Выполнение команды makemigrations приведет к созданию миграции, содержащей безоперационную операцию AlterField.

Разное¶

• Аргумент instance недокументированного метода BaseModelFormSet.save_existing() переименован в obj.
• Недокументированный django.contrib.admin.helpers.checkbox удален.
• Целочисленные поля теперь проверяются как 64-битные целые числа на SQLite, чтобы соответствовать поведению sqlite3.
• Недокументированный атрибут Query.annotation_select_mask заменен с набора строк на упорядоченный список строк.
• ImageField.update_dimension_fields() больше не вызывается по сигналу post_init, если width_field и height_field не установлены.
• <<<Функция базы данных Now теперь использует LOCALTIMESTAMP вместо CURRENT_TIMESTAMP на Oracle.
• AdminSite.site_header теперь отображается в теге <div> вместо <h1>. Пользователи программ чтения с экрана полагаются на элементы заголовков для навигации по странице. Наличие двух элементов <h1> приводило к путанице, а заголовок сайта не помогал, так как повторялся на всех страницах.
• Чтобы улучшить доступность, область основного содержимого админки и область содержимого заголовка теперь отображаются в тегах <main> и <header> вместо <div>.
• В базах данных без встроенной поддержки оператора SQL XOR, ^ как исключительный оператор или (XOR) теперь возвращает строки, которые соответствуют нечетному числу операндов, а не одному операнду. Это соответствует поведению MySQL, MariaDB и Python.
• Минимальная поддерживаемая версия asgiref увеличена с 3.6.0 до 3.7.0.
• Минимальная поддерживаемая версия selenium увеличена с 3.8.0 до 4.8.0.
• Исключения AlreadyRegistered и NotRegistered перенесены из django.contrib.admin.sites в django.contrib.admin.exceptions.
• Минимальная поддерживаемая версия SQLite увеличена с 3.21.0 до 3.27.0.
• Убрана поддержка cx_Oracle < 8.3.
• Выполнение SQL-запросов до того, как реестр приложений будет полностью заполнен, теперь вызывает ошибку RuntimeWarning.
• BadRequest будет поднят для запросов с типом содержимого application/x-www-form-urlencoded в кодировке неUTF-8. Более подробную информацию см. в разделе RFC 1866.
• Минимальная поддерживаемая версия colorama увеличена до 0.4.6.
• Минимальная поддерживаемая версия docutils увеличена до 0.19.
• Фильтрация наборов запросов от переполненных целочисленных значений теперь всегда возвращает пустой набор запросов. Как следствие, в таких случаях вам может потребоваться использовать арифметику от ExpressionWrapper() до explicitly wrap для целочисленных полей.

Разное¶

• Рендеры переходных форм DjangoDivFormRenderer и Jinja2DivFormRenderer устарели.
• Передача позиционных аргументов name и violation_error_message в BaseConstraint устарела в пользу аргументов, состоящих только из ключевых слов.
• request добавляется к сигнатуре ModelAdmin.lookup_allowed(). Поддержка подклассов ModelAdmin, которые не принимают этот аргумент, устарела.
• Метод get_joining_columns() в ForeignObject и ForeignObjectRel устарел. Начиная с версии Django 6.0, django.db.models.sql.datastructures.Join больше не будет возвращаться к get_joining_columns(). Вместо этого подклассы должны реализовывать get_joining_fields().
• Метод ForeignObject.get_reverse_joining_columns() устарел.
• Схема по умолчанию для forms.URLField будет изменена с "http" на "https" в Django 6.0. Установите переходную настройку FORMS_URLFIELD_ASSUME_HTTPS на True, чтобы отказаться от использования "https" во время цикла выпуска Django 5.x.
• Переходная установка FORMS_URLFIELD_ASSUME_HTTPS устарела.
• Поддержка вызова format_html() без передачи args или kwargs будет удалена.
• Поддержка cx_Oracle устарела в пользу драйвера oracledb 1.3.2+ Python.
• DatabaseOperations.field_cast_sql() устарел в пользу DatabaseOperations.lookup_cast(). Начиная с версии Django 6.0, BuiltinLookup.process_lhs() больше не будет вызывать field_cast_sql(). Сторонние бэкенды баз данных должны реализовывать lookup_cast() вместо этого.
• Метакласс django.db.models.enums.ChoicesMeta переименован в ChoicesType.
• Метод Prefetch.get_current_queryset() устарел.
• Метод get_prefetch_queryset() для связанных менеджеров и дескрипторов устарел. Начиная с версии Django 6.0, get_prefetcher() и prefetch_related_objects() больше не будут возвращаться к get_prefetch_queryset(). Вместо этого подклассы должны реализовывать get_prefetch_querysets().