Django 4.0 release notes

zoneinfo default timezone implementation

The Python standard library's zoneinfo is now the default timezone implementation in Django.

This is the next step in the migration from using pytz to using zoneinfo. Django 3.2 allowed the use of non-pytz time zones. Django 4.0 makes zoneinfo the default implementation. Support for pytz is now deprecated and will be removed in Django 5.0.

zoneinfo is part of the Python standard library from Python 3.9. The backports.zoneinfo package is automatically installed alongside Django if you are using Python 3.8.

The move to zoneinfo should be largely transparent. Selection of the current timezone, conversion of datetime instances to the current timezone in forms and templates, as well as operations on aware datetimes in UTC are unaffected.

However, if you are working with non-UTC time zones, and using the pytz normalize() and localize() APIs, possibly with the TIME_ZONE setting, you will need to audit your code, since pytz and zoneinfo are not entirely equivalent.

To give time for such an audit, the transitional USE_DEPRECATED_PYTZ setting allows continued use of pytz during the 4.x release cycle. This setting will be removed in Django 5.0.

In addition, a pytz_deprecation_shim package, created by the zoneinfo author, can be used to assist with the migration from pytz. This package provides shims to help you safely remove pytz, and has a detailed migration guide showing how to move to the new zoneinfo APIs.

Using pytz_deprecation_shim and the USE_DEPRECATED_PYTZ transitional setting is recommended if you need a gradual update path.

Functional unique constraints

The new *expressions positional argument of UniqueConstraint() enables creating functional unique constraints on expressions and database functions. For example:

from django.db import models
from django.db.models import UniqueConstraint
from django.db.models.functions import Lower


class MyModel(models.Model):
    first_name = models.CharField(max_length=255)
    last_name = models.CharField(max_length=255)

    class Meta:
        constraints = [
            UniqueConstraint(
                Lower('first_name'),
                Lower('last_name').desc(),
                name='first_last_name_unique',
            ),
        ]

Functional unique constraints are added to models using the Meta.constraints option.

scrypt password hasher

The new scrypt password hasher is more secure and recommended over PBKDF2. However, it's not the default as it requires OpenSSL 1.1+ and more memory.

Redis cache backend

The new django.core.cache.backends.redis.RedisCache cache backend provides built-in support for caching with Redis. redis-py 3.0.0 or higher is required. For more details, see the documentation on caching with Redis in Django.

Template based form rendering

Forms, Formsets, and ErrorList are now rendered using the template engine to enhance customization. See the new render(), get_context(), and template_name for Form and formset rendering for Formset.

次要特性

数据库后端 API

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

• DatabaseOperations.year_lookup_bounds_for_date_field() and year_lookup_bounds_for_datetime_field() methods now take the optional iso_year argument in order to support bounds for ISO-8601 week-numbering years.
• The second argument of DatabaseSchemaEditor._unique_sql() and _create_unique_sql() methods is now fields instead of columns.

django.contrib.gis

• Support for PostGIS 2.3 is removed.
• Support for GDAL 2.0 and GEOS 3.5 is removed.

Dropped support for PostgreSQL 9.6

Upstream support for PostgreSQL 9.6 ends in November 2021. Django 4.0 supports PostgreSQL 10 and higher.

Also, the minimum supported version of psycopg2 is increased from 2.5.4 to 2.8.4, as psycopg2 2.8.4 is the first release to support Python 3.8.

Dropped support for Oracle 12.2 and 18c

Upstream support for Oracle 12.2 ends in March 2022 and for Oracle 18c it ends in June 2021. Django 3.2 will be supported until April 2024. Django 4.0 officially supports Oracle 19c.

SecurityMiddleware no longer sets the X-XSS-Protection header

The SecurityMiddleware no longer sets the X-XSS-Protection header if the SECURE_BROWSER_XSS_FILTER setting is True. The setting is removed.

Most modern browsers don't honor the X-XSS-Protection HTTP header. You can use Content-Security-Policy without allowing 'unsafe-inline' scripts instead.

If you want to support legacy browsers and set the header, use this line in a custom middleware:

response.headers.setdefault('X-XSS-Protection', '1; mode=block')

Migrations autodetector changes

The migrations autodetector now uses model states instead of model classes. Also, migration operations for ForeignKey and ManyToManyField fields no longer specify attributes which were not passed to the fields during initialization.

As a side-effect, running makemigrations might generate no-op AlterField operations for ManyToManyField and ForeignKey fields in some cases.

DeleteView changes

DeleteView now uses FormMixin to handle POST requests. As a consequence, any custom deletion logic in delete() handlers should be moved to form_valid(), or a shared helper method, if required.

Table and column naming scheme changes on Oracle

Django 4.0 inadvertently changed the table and column naming scheme on Oracle. This causes errors for models and fields with names longer than 30 characters. Unfortunately, renaming some Oracle tables and columns is required. Use the upgrade script in 33789 to generate RENAME statements to change naming scheme.

杂项

• Support for cx_Oracle < 7.0 is removed.
• To allow serving a Django site on a subpath without changing the value of STATIC_URL, the leading slash is removed from that setting (now 'static/') in the default startproject template.
• The AdminSite method for the admin index view is no longer decorated with never_cache when accessed directly, rather than via the recommended AdminSite.urls property, or AdminSite.get_urls() method.
• Unsupported operations on a sliced queryset now raise TypeError instead of AssertionError.
• The undocumented django.test.runner.reorder_suite() function is renamed to reorder_tests(). It now accepts an iterable of tests rather than a test suite, and returns an iterator of tests.
• Calling FileSystemStorage.delete() with an empty name now raises ValueError instead of AssertionError.
• Calling EmailMultiAlternatives.attach_alternative() or EmailMessage.attach() with an invalid content or mimetype arguments now raise ValueError instead of AssertionError.
• assertHTMLEqual() no longer considers a non-boolean attribute without a value equal to an attribute with the same name and value.
• Tests that fail to load, for example due to syntax errors, now always match when using test --tag.
• The undocumented django.contrib.admin.utils.lookup_needs_distinct() function is renamed to lookup_spawns_duplicates().
• The undocumented HttpRequest.get_raw_uri() method is removed. The HttpRequest.build_absolute_uri() method may be a suitable alternative.
• The object argument of undocumented ModelAdmin.log_addition(), log_change(), and log_deletion() methods is renamed to obj.
• RssFeed, Atom1Feed, and their subclasses now emit elements with no content as self-closing tags.
• NodeList.render() no longer casts the output of render() method for individual nodes to a string. Node.render() should always return a string as documented.
• The where_class property of django.db.models.sql.query.Query and the where_class argument to the private get_extra_restriction() method of ForeignObject and ForeignObjectRel are removed. If needed, initialize django.db.models.sql.where.WhereNode instead.
• The filter_clause argument of the undocumented Query.add_filter() method is replaced by two positional arguments filter_lhs and filter_rhs.
• CsrfViewMiddleware now uses request.META['CSRF_COOKIE_NEEDS_UPDATE'] in place of request.META['CSRF_COOKIE_USED'], request.csrf_cookie_needs_reset, and response.csrf_cookie_set to track whether the CSRF cookie should be sent. This is an undocumented, private API.
• The undocumented TRANSLATOR_COMMENT_MARK constant is moved from django.template.base to django.utils.translation.template.
• The real_apps argument of the undocumented django.db.migrations.state.ProjectState.__init__() method must now be a set if provided.
• RadioSelect and CheckboxSelectMultiple widgets are now rendered in <div> tags so they are announced more concisely by screen readers. If you need the previous behavior, override the widget template with the appropriate template from Django 3.2.
• The floatformat template filter no longer depends on the USE_L10N setting and always returns localized output. Use the u suffix to disable localization.
• The default value of the USE_L10N setting is changed to True. See the Localization section above for more details.
• As part of the move to zoneinfo, django.utils.timezone.utc is changed to alias datetime.timezone.utc.
• The minimum supported version of asgiref is increased from 3.3.2 to 3.4.1.

Use of pytz time zones

As part of the move to zoneinfo, use of pytz time zones is deprecated.

Accordingly, the is_dst arguments to the following are also deprecated:

• django.db.models.query.QuerySet.datetimes()
• django.db.models.functions.Trunc()
• django.db.models.functions.TruncSecond()
• django.db.models.functions.TruncMinute()
• django.db.models.functions.TruncHour()
• django.db.models.functions.TruncDay()
• django.db.models.functions.TruncWeek()
• django.db.models.functions.TruncMonth()
• django.db.models.functions.TruncQuarter()
• django.db.models.functions.TruncYear()
• django.utils.timezone.make_aware()

Support for use of pytz will be removed in Django 5.0.

Time zone support

In order to follow good practice, the default value of the USE_TZ setting will change from False to True, and time zone support will be enabled by default, in Django 5.0.

Note that the default settings.py file created by django-admin startproject includes USE_TZ = True since Django 1.4.

You can set USE_TZ to False in your project settings before then to opt-out.

杂项

• SERIALIZE test setting is deprecated as it can be inferred from the databases with the serialized_rollback option enabled.
• The undocumented django.utils.baseconv module is deprecated.
• The undocumented django.utils.datetime_safe module is deprecated.
• The default sitemap protocol for sitemaps built outside the context of a request will change from 'http' to 'https' in Django 5.0.
• The extra_tests argument for DiscoverRunner.build_suite() and DiscoverRunner.run_tests() is deprecated.
• The ArrayAgg, JSONBAgg, and StringAgg aggregates will return None when there are no rows instead of [], [], and '' respectively in Django 5.0. If you need the previous behavior, explicitly set default to Value([]), Value('[]'), or Value('').
• The django.contrib.gis.admin.GeoModelAdmin and OSMGeoAdmin classes are deprecated. Use ModelAdmin and GISModelAdmin instead.
• Since form rendering now uses the template engine, the undocumented BaseForm._html_output() helper method is deprecated.
• The ability to return a str from ErrorList and ErrorDict is deprecated. It is expected these methods return a SafeString.