Django 3.2 release notes

April 6, 2021

Welcome to Django 3.2!

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

如果你要更新现有的项目，请看 升级 Django 到最新的版本 指南。

Django 3.2 is designated as a long-term support release. It will receive security updates for at least three years after its release. Support for the previous LTS, Django 2.2, will end in April 2022.

Python 兼容性

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

What’s new in Django 3.2

Automatic AppConfig discovery

Most pluggable applications define an AppConfig subclass in an apps.py submodule. Many define a default_app_config variable pointing to this class in their __init__.py.

When the apps.py submodule exists and defines a single AppConfig subclass, Django now uses that configuration automatically, so you can remove default_app_config.

default_app_config made it possible to declare only the application’s path in INSTALLED_APPS (e.g. 'django.contrib.admin') rather than the app config’s path (e.g. 'django.contrib.admin.apps.AdminConfig'). It was introduced for backwards-compatibility with the former style, with the intent to switch the ecosystem to the latter, but the switch didn’t happen.

With automatic AppConfig discovery, default_app_config is no longer needed. As a consequence, it’s deprecated.

See 配置应用程序 for full details.

Customizing type of auto-created primary keys

When defining a model, if no field in a model is defined with primary_key=True an implicit primary key is added. The type of this implicit primary key can now be controlled via the DEFAULT_AUTO_FIELD setting and AppConfig.default_auto_field attribute. No more needing to override primary keys in all models.

Maintaining the historical behavior, the default value for DEFAULT_AUTO_FIELD is AutoField. Starting with 3.2 new projects are generated with DEFAULT_AUTO_FIELD set to BigAutoField. Also, new apps are generated with AppConfig.default_auto_field set to BigAutoField. In a future Django release the default value of DEFAULT_AUTO_FIELD will be changed to BigAutoField.

To avoid unwanted migrations in the future, either explicitly set DEFAULT_AUTO_FIELD to AutoField:

DEFAULT_AUTO_FIELD = 'django.db.models.AutoField'

or configure it on a per-app basis:

from django.apps import AppConfig
class MyAppConfig(AppConfig):
    default_auto_field = 'django.db.models.AutoField'
    name = 'my_app'

or on a per-model basis:

from django.db import models
class MyModel(models.Model):
    id = models.AutoField(primary_key=True)

In anticipation of the changing default, a system check will provide a warning if you do not have an explicit setting for DEFAULT_AUTO_FIELD.

Functional indexes

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

from django.db import models
from django.db.models import F, Index, Value
from django.db.models.functions import Lower, Upper
class MyModel(models.Model):
    first_name = models.CharField(max_length=255)
    last_name = models.CharField(max_length=255)
    height = models.IntegerField()
    weight = models.IntegerField()
    class Meta:
        indexes = [
            Index(
                Lower('first_name'),
                Upper('last_name').desc(),
                name='first_last_name_idx',
            ),
            Index(
                F('height') / (F('weight') + Value(5)),
                name='calc_idx',
            ),
        ]

Functional indexes are added to models using the Meta.indexes option.

pymemcache support

The new django.core.cache.backends.memcached.PyMemcacheCache cache backend allows using the pymemcache library for memcached. pymemcache 3.4.0 or higher is required. For more details, see the documentation on caching in Django.

New decorators for the admin site

The new display() decorator allows for easily adding options to custom display functions that can be used with list_display or readonly_fields.

Likewise, the new action() decorator allows for easily adding options to action functions that can be used with actions.

Using the @display decorator has the advantage that it is now possible to use the @property decorator when needing to specify attributes on the custom method. Prior to this it was necessary to use the property() function instead after assigning the required attributes to the method.

Using decorators has the advantage that these options are more discoverable as they can be suggested by completion utilities in code editors. They are merely a convenience and still set the same attributes on the functions under the hood.

次要特性

django.contrib.admin

• ModelAdmin.search_fields now allows searching against quoted phrases with spaces.

• Read-only related fields are now rendered as navigable links if target models are registered in the admin.

• The admin now supports theming, and includes a dark theme that is enabled according to browser settings. See Theming support for more details.

• ModelAdmin.autocomplete_fields now respects ForeignKey.to_field and ForeignKey.limit_choices_to when searching a related model.

• The admin now installs a final catch-all view that redirects unauthenticated users to the login page, regardless of whether the URL is otherwise valid. This protects against a potential model enumeration privacy issue.

  Although not recommended, you may set the new AdminSite.final_catch_all_view to False to disable the catch-all view.

django.contrib.auth

• The default iteration count for the PBKDF2 password hasher is increased from 216,000 to 260,000.

• The default variant for the Argon2 password hasher is changed to Argon2id. memory_cost and parallelism are increased to 102,400 and 8 respectively to match the argon2-cffi defaults.

  Increasing the memory_cost pushes the required memory from 512 KB to 100 MB. This is still rather conservative but can lead to problems in memory constrained environments. If this is the case, the existing hasher can be subclassed to override the defaults.

• The default salt entropy for the Argon2, MD5, PBKDF2, SHA-1 password hashers is increased from 71 to 128 bits.

django.contrib.contenttypes

• The new absolute_max argument for generic_inlineformset_factory() allows customizing the maximum number of forms that can be instantiated when supplying POST data. See Limiting the maximum number of instantiated forms for more details.
• The new can_delete_extra argument for generic_inlineformset_factory() allows removal of the option to delete extra forms. See can_delete_extra for more information.

django.contrib.gis

• The GDALRaster.transform() method now supports SpatialReference.
• The DataSource class now supports pathlib.Path.
• The LayerMapping class now supports pathlib.Path.

django.contrib.postgres

• The new ExclusionConstraint.include attribute allows creating covering exclusion constraints on PostgreSQL 12+.
• The new ExclusionConstraint.opclasses attribute allows setting PostgreSQL operator classes.
• The new JSONBAgg.ordering attribute determines the ordering of the aggregated elements.
• The new JSONBAgg.distinct attribute determines if aggregated values will be distinct.
• The CreateExtension operation now checks that the extension already exists in the database and skips the migration if so.
• The new CreateCollation and RemoveCollation operations allow creating and dropping collations on PostgreSQL. See Managing collations using migrations for more details.
• Lookups for ArrayField now allow (non-nested) arrays containing expressions as right-hand sides.
• The new OpClass() expression allows creating functional indexes on expressions with a custom operator class. See Functional indexes for more details.

django.contrib.sitemaps

• The new Sitemap attributes alternates, languages and x_default allow generating sitemap alternates to localized versions of your pages.

django.contrib.syndication

• The new item_comments hook allows specifying a comments URL per feed item.

Database backends

• Third-party database backends can now skip or mark as expected failures tests in Django’s test suite using the new DatabaseFeatures.django_test_skips and django_test_expected_failures attributes.

Decorators

• The new no_append_slash() decorator allows individual views to be excluded from APPEND_SLASH URL normalization.

错误报告

• Custom ExceptionReporter subclasses can now define the html_template_path and text_template_path properties to override the templates used to render exception reports.

文件上传

• The new FileUploadHandler.upload_interrupted() callback allows handling interrupted uploads.

表单

• The new absolute_max argument for formset_factory(), inlineformset_factory(), and modelformset_factory() allows customizing the maximum number of forms that can be instantiated when supplying POST data. See Limiting the maximum number of instantiated forms for more details.
• The new can_delete_extra argument for formset_factory(), inlineformset_factory(), and modelformset_factory() allows removal of the option to delete extra forms. See can_delete_extra for more information.
• BaseFormSet now reports a user facing error, rather than raising an exception, when the management form is missing or has been tampered with. To customize this error message, pass the error_messages argument with the key 'missing_management_form' when instantiating the formset.

Generic Views

• The week_format attributes of WeekMixin and WeekArchiveView now support the '%V' ISO 8601 week format.

管理命令

• loaddata now supports fixtures stored in XZ archives (.xz) and LZMA archives (.lzma).
• dumpdata now can compress data in the bz2, gz, lzma, or xz formats.
• makemigrations can now be called without an active database connection. In that case, check for a consistent migration history is skipped.
• BaseCommand.requires_system_checks now supports specifying a list of tags. System checks registered in the chosen tags will be checked for errors prior to executing the command. In previous versions, either all or none of the system checks were performed.
• Support for colored terminal output on Windows is updated. Various modern terminal environments are automatically detected, and the options for enabling support in other cases are improved. See 语法着色 for more details.

迁移

• The new Operation.migration_name_fragment property allows providing a filename fragment that will be used to name a migration containing only that operation.
• Migrations now support serialization of pure and concrete path objects from pathlib, and os.PathLike instances.

模型

• The new no_key parameter for QuerySet.select_for_update(), supported on PostgreSQL, allows acquiring weaker locks that don’t block the creation of rows that reference locked rows through a foreign key.
• When() expression now allows using the condition argument with lookups.
• The new Index.include and UniqueConstraint.include attributes allow creating covering indexes and covering unique constraints on PostgreSQL 11+.
• The new UniqueConstraint.opclasses attribute allows setting PostgreSQL operator classes.
• The QuerySet.update() method now respects the order_by() clause on MySQL and MariaDB.
• FilteredRelation() now supports nested relations.
• The of argument of QuerySet.select_for_update() is now allowed on MySQL 8.0.1+.
• Value() expression now automatically resolves its output_field to the appropriate Field subclass based on the type of its provided value for bool, bytes, float, int, str, datetime.date, datetime.datetime, datetime.time, datetime.timedelta, decimal.Decimal, and uuid.UUID instances. As a consequence, resolving an output_field for database functions and combined expressions may now crash with mixed types when using Value(). You will need to explicitly set the output_field in such cases.
• The new QuerySet.alias() method allows creating reusable aliases for expressions that don’t need to be selected but are used for filtering, ordering, or as a part of complex expressions.
• The new Collate function allows filtering and ordering by specified database collations.
• The field_name argument of QuerySet.in_bulk() now accepts distinct fields if there’s only one field specified in QuerySet.distinct().
• The new tzinfo parameter of the TruncDate and TruncTime database functions allows truncating datetimes in a specific timezone.
• The new db_collation argument for CharField and TextField allows setting a database collation for the field.
• Added the Random database function.
• 聚合函数, F(), OuterRef(), and other expressions now allow using transforms. See Expressions can reference transforms for details.
• The new durable argument for atomic() guarantees that changes made in the atomic block will be committed if the block exits without errors. A nested atomic block marked as durable will raise a RuntimeError.
• Added the JSONObject database function.

分页

• The new django.core.paginator.Paginator.get_elided_page_range() method allows generating a page range with some of the values elided. If there are a large number of pages, this can be helpful for generating a reasonable number of page links in a template.

请求和响应

• Response headers are now stored in HttpResponse.headers. This can be used instead of the original dict-like interface of HttpResponse objects. Both interfaces will continue to be supported. See 设置头字段 for details.
• The new headers parameter of HttpResponse, SimpleTemplateResponse, and TemplateResponse allows setting response headers on instantiation.

安全

• The SECRET_KEY setting is now checked for a valid value upon first access, rather than when settings are first loaded. This enables running management commands that do not rely on the SECRET_KEY without needing to provide a value. As a consequence of this, calling configure() without providing a valid SECRET_KEY, and then going on to access settings.SECRET_KEY will now raise an ImproperlyConfigured exception.

• The new Signer.sign_object() and Signer.unsign_object() methods allow signing complex data structures. See 保护复杂的数据结构 for more details.

  Also, signing.dumps() and loads() become shortcuts for TimestampSigner.sign_object() and unsign_object().

序列化

• The new JSONL serializer allows using the JSON Lines format with dumpdata and loaddata. This can be useful for populating large databases because data is loaded line by line into memory, rather than being loaded all at once.

信号

• Signal.send_robust() now logs exceptions.

模板

• floatformat template filter now allows using the g suffix to force grouping by the THOUSAND_SEPARATOR for the active locale.
• Templates cached with Cached template loaders are now correctly reloaded in development.

测试

• Objects assigned to class attributes in TestCase.setUpTestData() are now isolated for each test method. Such objects are now required to support creating deep copies with copy.deepcopy(). Assigning objects which don’t support deepcopy() is deprecated and will be removed in Django 4.1.
• DiscoverRunner now enables faulthandler by default. This can be disabled by using the test --no-faulthandler option.
• DiscoverRunner and the test management command can now track timings, including database setup and total run time. This can be enabled by using the test --timing option.
• Client now preserves the request query string when following 307 and 308 redirects.
• The new TestCase.captureOnCommitCallbacks() method captures callback functions passed to transaction.on_commit() in a list. This allows you to test such callbacks without using the slower TransactionTestCase.
• TransactionTestCase.assertQuerysetEqual() now supports direct comparison against another queryset rather than being restricted to comparison against a list of string representations of objects when using the default value for the transform argument.

实用程序

• The new depth parameter of django.utils.timesince.timesince() and django.utils.timesince.timeuntil() functions allows specifying the number of adjacent time units to return.

验证器

• Built-in validators now include the provided value in the params argument of a raised ValidationError. This allows custom error messages to use the %(value)s placeholder.
• The ValidationError equality operator now ignores messages and params ordering.

Backwards incompatible changes in 3.2

数据库后端 API

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

• The new DatabaseFeatures.introspected_field_types property replaces these features:
  • can_introspect_autofield
  • can_introspect_big_integer_field
  • can_introspect_binary_field
  • can_introspect_decimal_field
  • can_introspect_duration_field
  • can_introspect_ip_address_field
  • can_introspect_positive_integer_field
  • can_introspect_small_integer_field
  • can_introspect_time_field
  • introspected_big_auto_field_type
  • introspected_small_auto_field_type
  • introspected_boolean_field_type
• To enable support for covering indexes (Index.include) and covering unique constraints (UniqueConstraint.include), set DatabaseFeatures.supports_covering_indexes to True.
• Third-party database backends must implement support for column database collations on CharFields and TextFields or set DatabaseFeatures.supports_collation_on_charfield and DatabaseFeatures.supports_collation_on_textfield to False. If non-deterministic collations are not supported, set supports_non_deterministic_collations to False.
• DatabaseOperations.random_function_sql() is removed in favor of the new Random database function.
• DatabaseOperations.date_trunc_sql() and DatabaseOperations.time_trunc_sql() now take the optional tzname argument in order to truncate in a specific timezone.
• DatabaseClient.runshell() now gets arguments and an optional dictionary with environment variables to the underlying command-line client from DatabaseClient.settings_to_cmd_args_env() method. Third-party database backends must implement DatabaseClient.settings_to_cmd_args_env() or override DatabaseClient.runshell().
• Third-party database backends must implement support for functional indexes (Index.expressions) or set DatabaseFeatures.supports_expression_indexes to False. If COLLATE is not a part of the CREATE INDEX statement, set DatabaseFeatures.collate_as_index_expression to True.

django.contrib.admin

• Pagination links in the admin are now 1-indexed instead of 0-indexed, i.e. the query string for the first page is ?p=1 instead of ?p=0.
• The new admin catch-all view will break URL patterns routed after the admin URLs and matching the admin URL prefix. You can either adjust your URL ordering or, if necessary, set AdminSite.final_catch_all_view to False, disabling the catch-all view. See What’s new in Django 3.2 for more details.
• Minified JavaScript files are no longer included with the admin. If you require these files to be minified, consider using a third party app or external build tool. The minified vendored JavaScript files packaged with the admin (e.g. jquery.min.js) are still included.
• ModelAdmin.prepopulated_fields no longer strips English stop words, such as 'a' or 'an'.

django.contrib.gis

• Support for PostGIS 2.2 is removed.
• The Oracle backend now clones polygons (and geometry collections containing polygons) before reorienting them and saving them to the database. They are no longer mutated in place. You might notice this if you use the polygons after a model is saved.

Dropped support for PostgreSQL 9.5

Upstream support for PostgreSQL 9.5 ends in February 2021. Django 3.2 supports PostgreSQL 9.6 and higher.

Dropped support for MySQL 5.6

The end of upstream support for MySQL 5.6 is April 2021. Django 3.2 supports MySQL 5.7 and higher.

杂项

• Django now supports non-pytz time zones, such as Python 3.9+’s zoneinfo module and its backport.

• The undocumented SpatiaLiteOperations.proj4_version() method is renamed to proj_version().

• slugify() now removes leading and trailing dashes and underscores.

• The intcomma and intword template filters no longer depend on the USE_L10N setting.

• Support for argon2-cffi < 19.1.0 is removed.

• The cache keys no longer includes the language when internationalization is disabled (USE_I18N = False) and localization is enabled (USE_L10N = True). After upgrading to Django 3.2 in such configurations, the first request to any previously cached value will be a cache miss.

• ForeignKey.validate() now uses _base_manager rather than _default_manager to check that related instances exist.

• When an application defines an AppConfig subclass in an apps.py submodule, Django now uses this configuration automatically, even if it isn’t enabled with default_app_config. Set default = False in the AppConfig subclass if you need to prevent this behavior. See What’s new in Django 3.2 for more details.

• Instantiating an abstract model now raises TypeError.

• Keyword arguments to setup_databases() are now keyword-only.

• The undocumented django.utils.http.limited_parse_qsl() function is removed. Please use urllib.parse.parse_qsl() instead.

• django.test.utils.TestContextDecorator now uses addCleanup() so that cleanups registered in the setUp() method are called before TestContextDecorator.disable().

• SessionMiddleware now raises a SessionInterrupted exception instead of SuspiciousOperation when a session is destroyed in a concurrent request.

• The django.db.models.Field equality operator now correctly distinguishes inherited field instances across models. Additionally, the ordering of such fields is now defined.

• The undocumented django.core.files.locks.lock() function now returns False if the file cannot be locked, instead of raising BlockingIOError.

• The password reset mechanism now invalidates tokens when the user email is changed.

• makemessages command no longer processes invalid locales specified using makemessages --locale option, when they contain hyphens ('-').

• The django.contrib.auth.forms.ReadOnlyPasswordHashField form field is now disabled by default. Therefore UserChangeForm.clean_password() is no longer required to return the initial value.

• The cache.get_many(), get_or_set(), has_key(), incr(), decr(), incr_version(), and decr_version() cache operations now correctly handle None stored in the cache, in the same way as any other value, instead of behaving as though the key didn’t exist.

  Due to a python-memcached limitation, the previous behavior is kept for the deprecated MemcachedCache backend.

• The minimum supported version of SQLite is increased from 3.8.3 to 3.9.0.

• CookieStorage now stores messages in the RFC 6265 compliant format. Support for cookies that use the old format remains until Django 4.1.

• The minimum supported version of asgiref is increased from 3.2.10 to 3.3.2.

Features deprecated in 3.2

杂项

• Assigning objects which don’t support creating deep copies with copy.deepcopy() to class attributes in TestCase.setUpTestData() is deprecated.
• Using a boolean value in BaseCommand.requires_system_checks is deprecated. Use '__all__' instead of True, and [] (an empty list) instead of False.
• The whitelist argument and domain_whitelist attribute of EmailValidator are deprecated. Use allowlist instead of whitelist, and domain_allowlist instead of domain_whitelist. You may need to rename whitelist in existing migrations.
• The default_app_config application configuration variable is deprecated, due to the now automatic AppConfig discovery. See What’s new in Django 3.2 for more details.
• Automatically calling repr() on a queryset in TransactionTestCase.assertQuerysetEqual(), when compared to string values, is deprecated. If you need the previous behavior, explicitly set transform to repr.
• The django.core.cache.backends.memcached.MemcachedCache backend is deprecated as python-memcached has some problems and seems to be unmaintained. Use django.core.cache.backends.memcached.PyMemcacheCache or django.core.cache.backends.memcached.PyLibMCCache instead.
• The format of messages used by django.contrib.messages.storage.cookie.CookieStorage is different from the format generated by older versions of Django. Support for the old format remains until Django 4.1.