Django 4.1 release notes

Asynchronous handlers for class-based views

View subclasses may now define async HTTP method handlers:

import asyncio
from django.http import HttpResponse
from django.views import View

class AsyncView(View):
    async def get(self, request, *args, **kwargs):
        # Perform view logic using await.
        await asyncio.sleep(1)
        return HttpResponse("Hello async world!")

See Asynchronous class-based views for more details.

Asynchronous ORM interface

QuerySet now provides an asynchronous interface for all data access operations. These are named as-per the existing synchronous operations but with an a prefix, for example acreate(), aget(), and so on.

The new interface allows you to write asynchronous code without needing to wrap ORM operations in sync_to_async():

async for author in Author.objects.filter(name__startswith="A"):
    book = await author.books.afirst()

Note that, at this stage, the underlying database operations remain synchronous, with contributions ongoing to push asynchronous support down into the SQL compiler, and integrate asynchronous database drivers. The new asynchronous queryset interface currently encapsulates the necessary sync_to_async() operations for you, and will allow your code to take advantage of developments in the ORM's asynchronous support as it evolves.

See Asynchronous queries for details and limitations.

Validation of Constraints

Check, unique, and exclusion constraints defined in the Meta.constraints option are now checked during model validation.

Form rendering accessibility

In order to aid users with screen readers, and other assistive technology, new <div> based form templates are available from this release. These provide more accessible navigation than the older templates, and are able to correctly group related controls, such as radio-lists, into fieldsets.

The new templates are recommended, and will become the default form rendering style when outputting a form, like {{ form }} in a template, from Django 5.0.

In order to ease adopting the new output style, the default form and formset templates are now configurable at the project level via the FORM_RENDERER setting.

See the Forms section (below) for full details.

次要特性

数据库后端 API

本节介绍了第三方数据库后端可能需要的更改。

• BaseDatabaseFeatures.has_case_insensitive_like is changed from True to False to reflect the behavior of most databases.
• DatabaseIntrospection.get_key_columns() is removed. Use DatabaseIntrospection.get_relations() instead.
• DatabaseOperations.ignore_conflicts_suffix_sql() method is replaced by DatabaseOperations.on_conflict_suffix_sql() that accepts the fields, on_conflict, update_fields, and unique_fields arguments.
• The ignore_conflicts argument of the DatabaseOperations.insert_statement() method is replaced by on_conflict that accepts django.db.models.constants.OnConflict.
• DatabaseOperations._convert_field_to_tz() is replaced by DatabaseOperations._convert_sql_to_tz() that accepts the sql, params, and tzname arguments.
• Several date and time methods on DatabaseOperations now take sql and params arguments instead of field_name and return 2-tuple containing some SQL and the parameters to be interpolated into that SQL. The changed methods have these new signatures:
  • DatabaseOperations.date_extract_sql(lookup_type, sql, params)
  • DatabaseOperations.datetime_extract_sql(lookup_type, sql, params, tzname)
  • DatabaseOperations.time_extract_sql(lookup_type, sql, params)
  • DatabaseOperations.date_trunc_sql(lookup_type, sql, params, tzname=None)
  • DatabaseOperations.datetime_trunc_sql(self, lookup_type, sql, params, tzname)
  • DatabaseOperations.time_trunc_sql(lookup_type, sql, params, tzname=None)
  • DatabaseOperations.datetime_cast_date_sql(sql, params, tzname)
  • DatabaseOperations.datetime_cast_time_sql(sql, params, tzname)

django.contrib.gis

• Support for GDAL 2.1 is removed.
• Support for PostGIS 2.4 is removed.

Dropped support for PostgreSQL 10

Upstream support for PostgreSQL 10 ends in November 2022. Django 4.1 supports PostgreSQL 11 and higher.

Dropped support for MariaDB 10.2

Upstream support for MariaDB 10.2 ends in May 2022. Django 4.1 supports MariaDB 10.3 and higher.

Admin changelist searches spanning multi-valued relationships changes

Admin changelist searches using multiple search terms are now applied in a single call to filter(), rather than in sequential filter() calls.

For multi-valued relationships, this means that rows from the related model must match all terms rather than any term. For example, if search_fields is set to ['child__name', 'child__age'], and a user searches for 'Jamal 17', parent rows will be returned only if there is a relationship to some 17-year-old child named Jamal, rather than also returning parents who merely have a younger or older child named Jamal in addition to some other 17-year-old.

See the 跨多值关联 topic for more discussion of this difference. In Django 4.0 and earlier, get_search_results() followed the second example query, but this undocumented behavior led to queries with excessive joins.

Reverse foreign key changes for unsaved model instances

In order to unify the behavior with many-to-many relations for unsaved model instances, a reverse foreign key now raises ValueError when calling related managers for unsaved objects.

杂项

• Related managers for ForeignKey, ManyToManyField, and GenericRelation are now cached on the Model instance to which they belong. This change was reverted in Django 4.1.2.
• The Django test runner now returns a non-zero error code for unexpected successes from tests marked with unittest.expectedFailure().
• CsrfViewMiddleware no longer masks the CSRF cookie like it does the CSRF token in the DOM.
• CsrfViewMiddleware now uses request.META['CSRF_COOKIE'] for storing the unmasked CSRF secret rather than a masked version. This is an undocumented, private API.
• The ModelAdmin.actions and inlines attributes now default to an empty tuple rather than an empty list to discourage unintended mutation.
• The type="text/css" attribute is no longer included in <link> tags for CSS form media.
• formset:added and formset:removed JavaScript events are now pure JavaScript events and don't depend on jQuery. See 内联表单事件 for more details on the change.
• The exc_info argument of the undocumented django.utils.log.log_response() function is replaced by exception.
• The size argument of the undocumented django.views.static.was_modified_since() function is removed.
• The admin log out UI now uses POST requests.
• The undocumented InlineAdminFormSet.non_form_errors property is replaced by the non_form_errors() method. This is consistent with BaseFormSet.
• As per above, the cached template loader is now enabled in development. You may specify OPTIONS['loaders'] to override this, if necessary.
• The undocumented django.contrib.auth.views.SuccessURLAllowedHostsMixin mixin is replaced by RedirectURLMixin.
• BaseConstraint subclasses must implement validate() method to allow those constraints to be used for validation.
• The undocumented URLResolver._is_callback(), URLResolver._callback_strs, and URLPattern.lookup_str() are moved to django.contrib.admindocs.utils.
• The Model.full_clean() method now converts an exclude value to a set. It’s also preferable to pass an exclude value as a set to the Model.clean_fields(), Model.full_clean(), Model.validate_unique(), and Model.validate_constraints() methods.
• The minimum supported version of asgiref is increased from 3.4.1 to 3.5.2.

Log out via GET

Logging out via GET requests to the built-in logout view is deprecated. Use POST requests instead.

If you want to retain the user experience of an HTML link, you can use a form that is styled to appear as a link:

<form id="logout-form" method="post" action="{% url 'admin:logout' %}">
  {% csrf_token %}
  <button type="submit">{% translate "Log out" %}</button>
</form>

#logout-form {
  display: inline;
}
#logout-form button {
  background: none;
  border: none;
  cursor: pointer;
  padding: 0;
  text-decoration: underline;
}

杂项

• The context for sitemap index templates of a flat list of URLs is deprecated. Custom sitemap index templates should be updated for the adjusted context variables, expecting a list of objects with location and optional lastmod attributes.

• CSRF_COOKIE_MASKED transitional setting is deprecated.

• The name argument of django.utils.functional.cached_property() is deprecated as it's unnecessary as of Python 3.6.

• The opclasses argument of django.contrib.postgres.constraints.ExclusionConstraint is deprecated in favor of using OpClass() in ExclusionConstraint.expressions. To use it, you need to add 'django.contrib.postgres' in your INSTALLED_APPS.

  After making this change, makemigrations will generate a new migration with two operations: RemoveConstraint and AddConstraint. Since this change has no effect on the database schema, the SeparateDatabaseAndState operation can be used to only update the migration state without running any SQL. Move the generated operations into the state_operations argument of SeparateDatabaseAndState. For example:

  class Migration(migrations.Migration):
      ...
  
      operations = [
          migrations.SeparateDatabaseAndState(
              database_operations=[],
              state_operations=[
                  migrations.RemoveConstraint(
                      ...
                  ),
                  migrations.AddConstraint(
                      ...
                  ),
              ],
          ),
      ]

• The undocumented ability to pass errors=None to SimpleTestCase.assertFormError() and assertFormsetError() is deprecated. Use errors=[] instead.

• django.contrib.sessions.serializers.PickleSerializer is deprecated due to the risk of remote code execution.

• The usage of QuerySet.iterator() on a queryset that prefetches related objects without providing the chunk_size argument is deprecated. In older versions, no prefetching was done. Providing a value for chunk_size signifies that the additional query per chunk needed to prefetch is desired.

• Passing unsaved model instances to related filters is deprecated. In Django 5.0, the exception will be raised.

• created=True is added to the signature of RemoteUserBackend.configure_user(). Support for RemoteUserBackend subclasses that do not accept this argument is deprecated.

• The django.utils.timezone.utc alias to datetime.timezone.utc is deprecated. Use datetime.timezone.utc directly.

• Passing a response object and a form/formset name to SimpleTestCase.assertFormError() and assertFormsetError() is deprecated. Use:

  assertFormError(response.context['form_name'], …)
  assertFormsetError(response.context['formset_name'], …)

  or pass the form/formset object directly instead.

• The undocumented django.contrib.gis.admin.OpenLayersWidget is deprecated.

• django.contrib.auth.hashers.CryptPasswordHasher is deprecated.

• The ability to pass nulls_first=False or nulls_last=False to Expression.asc() and Expression.desc() methods, and the OrderBy expression is deprecated. Use None instead.

• The "django/forms/default.html" and "django/forms/formsets/default.html" templates which are a proxy to the table-based templates are deprecated. Use the specific template instead.

• The undocumented LogoutView.get_next_page() method is renamed to get_success_url().