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.
既存のプロジェクトをアップデートするときは、 How to upgrade Django to a newer version ガイドに従ってください。
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.
Django 3.2 supports Python 3.6, 3.7, 3.8, 3.9, and 3.10 (as of 3.2.9). We highly recommend and only officially support the latest release of each series.
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.
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.
When changing the value of DEFAULT_AUTO_FIELD, migrations for the
primary key of existing auto-created through tables cannot be generated
currently. See the DEFAULT_AUTO_FIELD docs for details on migrating
such tables.
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.
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¶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.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¶GDALRaster.transform() method now supports
SpatialReference.DataSource class now supports
pathlib.Path.LayerMapping class now supports
pathlib.Path.django.contrib.postgres¶ExclusionConstraint.include attribute allows creating
covering exclusion constraints on PostgreSQL 12+.ExclusionConstraint.opclasses attribute allows setting
PostgreSQL operator classes.JSONBAgg.ordering attribute determines the ordering of the
aggregated elements.JSONBAgg.distinct attribute determines if aggregated values
will be distinct.CreateExtension operation
now checks that the extension already exists in the database and skips the
migration if so.CreateCollation and
RemoveCollation operations
allow creating and dropping collations on PostgreSQL. See
Managing collations using migrations for more details.ArrayField now allow
(non-nested) arrays containing expressions as right-hand sides.OpClass()
expression allows creating functional indexes on expressions with a custom
operator class. See Functional indexes for more details.django.contrib.sitemaps¶Sitemap attributes
alternates,
languages and
x_default allow
generating sitemap alternates to localized versions of your pages.django.contrib.syndication¶item_comments hook allows specifying a comments URL per feed
item.DatabaseFeatures.django_test_skips and
django_test_expected_failures attributes.no_append_slash() decorator
allows individual views to be excluded from APPEND_SLASH URL
normalization.ExceptionReporter subclasses can now
define the html_template_path
and text_template_path
properties to override the templates used to render exception reports.FileUploadHandler.upload_interrupted()
callback allows handling interrupted uploads.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.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.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.Operation.migration_name_fragment property allows providing a
filename fragment that will be used to name a migration containing only that
operation.pathlib, and os.PathLike instances.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.Index.include and UniqueConstraint.include
attributes allow creating covering indexes and covering unique constraints on
PostgreSQL 11+.UniqueConstraint.opclasses attribute allows setting
PostgreSQL operator classes.QuerySet.update() method now respects the order_by() clause on
MySQL and MariaDB.FilteredRelation() now supports
nested relations.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.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.Collate function allows
filtering and ordering by specified database collations.field_name argument of QuerySet.in_bulk() now accepts
distinct fields if there's only one field specified in
QuerySet.distinct().tzinfo parameter of the
TruncDate and
TruncTime database functions allows
truncating datetimes in a specific timezone.db_collation argument for
CharField and
TextField allows setting a
database collation for the field.Random database function.F(),
OuterRef(), and other expressions now
allow using transforms. See Expressions can reference transforms for
details.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.JSONObject database function.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.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.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 Protecting complex data structures for more
details.
Also, signing.dumps() and
loads() become shortcuts for
TimestampSigner.sign_object() and
unsign_object().
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.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.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.depth parameter of django.utils.timesince.timesince() and
django.utils.timesince.timeuntil() functions allows specifying the number
of adjacent time units to return.params argument
of a raised ValidationError. This allows
custom error messages to use the %(value)s placeholder.ValidationError equality operator now ignores messages and
params ordering.This section describes changes that may be needed in third-party database backends.
DatabaseFeatures.introspected_field_types property replaces these
features:can_introspect_autofieldcan_introspect_big_integer_fieldcan_introspect_binary_fieldcan_introspect_decimal_fieldcan_introspect_duration_fieldcan_introspect_ip_address_fieldcan_introspect_positive_integer_fieldcan_introspect_small_integer_fieldcan_introspect_time_fieldintrospected_big_auto_field_typeintrospected_small_auto_field_typeintrospected_boolean_field_typeIndex.include) and covering
unique constraints (UniqueConstraint.include), set
DatabaseFeatures.supports_covering_indexes to True.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().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¶?p=1 instead of ?p=0.AdminSite.final_catch_all_view to False,
disabling the catch-all view. See What's new in Django 3.2 for more details.ModelAdmin.prepopulated_fields no longer strips English stop words,
such as 'a' or 'an'.django.contrib.gis¶Upstream support for PostgreSQL 9.5 ends in February 2021. Django 3.2 supports PostgreSQL 9.6 and higher.
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.
copy.deepcopy() to class attributes in
TestCase.setUpTestData() is deprecated.BaseCommand.requires_system_checks is
deprecated. Use '__all__' instead of True, and [] (an empty list)
instead of False.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.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.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.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.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.8月 03, 2022