Django 4.0 release notes

    Welcome to Django 4.0!

    These release notes cover the new features, as well as some you’ll want to be aware of when upgrading from Django 3.2 or earlier. We’ve begun the deprecation process for some features.

    如果你要更新现有的项目，请看 指南。

    Django 4.0 supports Python 3.8, 3.9, and 3.10. We highly recommend and only officially support the latest release of each series.

    The Django 3.2.x series is the last to support Python 3.6 and 3.7.

    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 . 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 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 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 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 enables creating functional unique constraints on expressions and database functions. For example:

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

    scrypt password hasher

    Redis cache backend

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

    Template based form rendering

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

    次要特性

    • The admin/base.html template now has a new block header which contains the admin site header.
    • The new ModelAdmin.get_formset_kwargs() method allows customizing the keyword arguments passed to the constructor of a formset.
    • The navigation sidebar now has a quick filter toolbar.
    • The new context variable model which contains the model class for each model is added to the method.
    • The new ModelAdmin.search_help_text attribute allows specifying a descriptive text for the search box.
    • The attribute now fallbacks to the InlineModelAdmin.verbose_name + 's'.
    • jQuery is upgraded from version 3.5.1 to 3.6.0.

    django.contrib.admindocs

    • The admindocs now allows esoteric setups where is not a string.
    • The model section of the admindocs now shows cached properties.

    • The default iteration count for the PBKDF2 password hasher is increased from 260,000 to 320,000.
    • The new LoginView.next_page attribute and method allow customizing the redirect after login.

    • Added support for SpatiaLite 5.
    • GDALRaster now allows creating rasters in any GDAL virtual filesystem.
    • The new class allows customizing the widget used for GeometryField. This is encouraged instead of deprecated GeoModelAdmin and OSMGeoAdmin.

    • The new AddConstraintNotValid operation allows creating check constraints on PostgreSQL without verifying that all existing rows satisfy the new constraint.
    • The new operation allows validating check constraints which were created using AddConstraintNotValid on PostgreSQL.
    • The new expression allows using subqueries to construct lists of values on PostgreSQL.
    • The new trigram_word_similar lookup, and the and TrigramWordSimilarity() expressions allow using trigram word similarity.

    django.contrib.staticfiles

    • now replaces paths to JavaScript source map references with their hashed counterparts.
    • The new manifest_storage argument of ManifestFilesMixin and allows customizing the manifest file storage.

    缓存

    • The new async API for django.core.cache.backends.base.BaseCache begins the process of making cache backends async-compatible. The new async methods all have a prefixed names, e.g. aadd(), aget(), aset(), aget_or_set(), or adelete_many().

      Going forward, the a prefix will be used for async variants of methods generally.

    CSRF

    • CSRF protection now consults the Origin header, if present. To facilitate this, some changes to the setting are required.

    表单

    • now includes the provided value in the params argument of a raised ValidationError for the invalid_choice error message. This allows custom error messages to use the %(value)s placeholder.
    • now renders non-form errors with an additional class of nonform to help distinguish them from form-specific errors.
    • BaseFormSet now allows customizing the widget used when deleting forms via by setting the deletion_widget attribute or overriding method.

    国际化

    • Added support and translations for the Malay language.

    通用视图

    • DeleteView now uses , allowing you to provide a Form subclass, with a checkbox for example, to confirm deletion. In addition, this allows DeleteView to function with .

      In accordance with FormMixin, object deletion for POST requests is handled in form_valid(). Custom delete logic in delete() handlers should be moved to form_valid(), or a shared helper method, as needed.

    日志

    • The alias of the database used in an SQL call is now passed as extra context along with each message to the logger.

    管理命令

    • The management command now supports the --skip-checks option.
    • On PostgreSQL, now supports specifying a password file.
    • The shell command now respects at startup. This allows loading shell history between interactive sessions. As a consequence, readline is no longer loaded if running in isolated mode.
    • The new BaseCommand.suppressed_base_arguments attribute allows suppressing unsupported default command options in the help output.
    • The new and startproject —exclude options allow excluding directories from the template.

    模型

    • New QuerySet.contains(obj) method returns whether the queryset contains the given object. This tries to perform the query in the simplest and fastest way possible.
    • The new precision argument of the database function allows specifying the number of decimal places after rounding.
    • QuerySet.bulk_create() now sets the primary key on objects when using SQLite 3.35+.
    • now supports multiplying and dividing by scalar values on SQLite.
    • QuerySet.bulk_update() now returns the number of objects updated.
    • The new attribute allows specifying a value to return when the function is used over an empty result set.
    • The skip_locked argument of QuerySet.select_for_update() is now allowed on MariaDB 10.6+.
    • expressions may now be used in QuerySet annotations, aggregations, and directly in filters.
    • The new default argument for built-in aggregates allows specifying a value to be returned when the queryset (or grouping) contains no entries, rather than None.

    请求和响应

    • The SecurityMiddleware now adds the header with a value of 'same-origin' to prevent cross-origin popups from sharing the same browsing context. You can prevent this header from being added by setting the SECURE_CROSS_ORIGIN_OPENER_POLICY setting to None.

    信号

    • The new stdout argument for pre_migrate() and signals allows redirecting output to a stream-like object. It should be preferred over sys.stdout and when emitting verbose output in order to allow proper capture when testing.

    模板

    • template filter now allows using the u suffix to force disabling localization.

    测试

    • The new serialized_aliases argument of determines which DATABASES aliases test databases should have their state serialized to allow usage of the feature.
    • Django test runner now supports a --buffer option with parallel tests.
    • The new logger argument to allows a Python logger to be used for logging.
    • The new method provides a way to log messages that uses the DiscoverRunner.logger, or prints to the console if not set.
    • Django test runner now supports a --shuffle option to execute tests in a random order.
    • The option now supports the value auto to run one test process for each processor core.
    • TestCase.captureOnCommitCallbacks() now captures new callbacks added while executing callbacks.

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

    • 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.

    • 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.

    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.

    CSRF_TRUSTED_ORIGINS changes

    Format change

    Values in the CSRF_TRUSTED_ORIGINS setting must include the scheme (e.g. 'http://' or 'https://') instead of only the hostname.

    Also, values that started with a dot, must now also include an asterisk before the dot. For example, change to 'https://*.example.com'.

    A system check detects any required changes.

    Configuring it may now be required

    As CSRF protection now consults the Origin header, you may need to set CSRF_TRUSTED_ORIGINS, particularly if you allow requests from subdomains by setting (or SESSION_COOKIE_DOMAIN if is enabled) to a value starting with a dot.

    SecurityMiddleware no longer sets the X-XSS-Protection header

    The 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.

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

    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 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.

    杂项

    • Support for cx_Oracle < 7.0 is removed.
    • To allow serving a Django site on a subpath without changing the value of , the leading slash is removed from that setting (now 'static/') in the default startproject template.
    • The 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 .
    • 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.
    • , 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.
    • 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 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 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 , django.utils.timezone.utc is changed to alias .
    • 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 , use of time zones is deprecated.

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

    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 includes USE_TZ = True since Django 1.4.

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

    Localization

    In order to follow good practice, the default value of the USE_L10N setting is changed from False to True.

    Moreover USE_L10N is deprecated as of this release. Starting with Django 5.0, by default, any date or number displayed by Django will be localized.

    The {% localize %} tag and the / unlocalize filters will still be honored by Django.

    • SERIALIZE test setting is deprecated as it can be inferred from the 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 and DiscoverRunner.run_tests() is deprecated.
    • The , JSONBAgg, and 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 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.

    These features have reached the end of their deprecation cycle and are removed in Django 4.0.

    See 在 3.0 中被废弃的功能 for details on these changes, including how to remove usage of these features.

    • django.utils.http.urlquote(), urlquote_plus(), urlunquote(), and urlunquote_plus() are removed.
    • django.utils.encoding.force_text() and smart_text() are removed.
    • django.utils.translation.ugettext(), ugettext_lazy(), ugettext_noop(), ungettext(), and ungettext_lazy() are removed.
    • django.views.i18n.set_language() doesn’t set the user language in request.session (key _language).
    • alias=None is required in the signature of django.db.models.Expression.get_group_by_cols() subclasses.
    • django.utils.text.unescape_entities() is removed.
    • django.utils.http.is_safe_url() is removed.

    See for details on these changes, including how to remove usage of these features.

    • The PASSWORD_RESET_TIMEOUT_DAYS setting is removed.
    • The isnull lookup no longer allows using non-boolean values as the right-hand side.
    • The django.db.models.query_utils.InvalidQuery exception class is removed.
    • The django-admin.py entry point is removed.
    • The HttpRequest.is_ajax() method is removed.
    • Support for the pre-Django 3.1 encoding format of cookies values used by django.contrib.messages.storage.cookie.CookieStorage is removed.
    • Support for the pre-Django 3.1 password reset tokens in the admin site (that use the SHA-1 hashing algorithm) is removed.
    • Support for the pre-Django 3.1 encoding format of sessions is removed.
    • Support for the pre-Django 3.1 django.core.signing.Signer signatures (encoded with the SHA-1 algorithm) is removed.
    • Support for the pre-Django 3.1 django.core.signing.dumps() signatures (encoded with the SHA-1 algorithm) in django.core.signing.loads() is removed.
    • Support for the pre-Django 3.1 user sessions (that use the SHA-1 algorithm) is removed.
    • The get_response argument for django.utils.deprecation.MiddlewareMixin.__init__() is required and doesn’t accept None.
    • The providing_args argument for django.dispatch.Signal is removed.
    • The length argument for django.utils.crypto.get_random_string() is required.
    • The list message for ModelMultipleChoiceField is removed.
    • Support for passing raw column aliases to QuerySet.order_by() is removed.
    • The NullBooleanField model field is removed, except for support in historical migrations.
    • django.conf.urls.url() is removed.
    • The django.contrib.postgres.fields.JSONField model field is removed, except for support in historical migrations.
    • django.contrib.postgres.fields.jsonb.KeyTransform and django.contrib.postgres.fields.jsonb.KeyTextTransform are removed.
    • django.contrib.postgres.forms.JSONField is removed.
    • The {% ifequal %} and {% ifnotequal %} template tags are removed.
    • The DEFAULT_HASHING_ALGORITHM transitional setting is removed.