Debian Codegraph @

docs/releases/3.2.txt

raw
1 ========================
2 Django 3.2 release notes
3 ========================
4
5 *April 6, 2021*
6
7 Welcome to Django 3.2!
8
9 These release notes cover the :ref:`new features <whats-new-3.2>`, as well as
10 some :ref:`backwards incompatible changes <backwards-incompatible-3.2>` you'll
11 want to be aware of when upgrading from Django 3.1 or earlier. We've
12 :ref:`begun the deprecation process for some features
13 <deprecated-features-3.2>`.
14
15 See the :doc:`/howto/upgrade-version` guide if you're updating an existing
16 project.
17
18 Django 3.2 is designated as a :term:`long-term support release
19 <Long-term support release>`. It will receive security updates for at least
20 three years after its release. Support for the previous LTS, Django 2.2, will
21 end in April 2022.
22
23 Python compatibility
24 ====================
25
26 Django 3.2 supports Python 3.6, 3.7, 3.8, 3.9, and 3.10 (as of 3.2.9). We
27 **highly recommend** and only officially support the latest release of each
28 series.
29
30 .. _whats-new-3.2:
31
32 What's new in Django 3.2
33 ========================
34
35 Automatic :class:`~django.apps.AppConfig` discovery
36 ---------------------------------------------------
37
38 Most pluggable applications define an :class:`~django.apps.AppConfig` subclass
39 in an ``apps.py`` submodule. Many define a ``default_app_config`` variable
40 pointing to this class in their ``__init__.py``.
41
42 When the ``apps.py`` submodule exists and defines a single
43 :class:`~django.apps.AppConfig` subclass, Django now uses that configuration
44 automatically, so you can remove ``default_app_config``.
45
46 ``default_app_config`` made it possible to declare only the application's path
47 in :setting:`INSTALLED_APPS` (e.g. ``'django.contrib.admin'``) rather than the
48 app config's path (e.g. ``'django.contrib.admin.apps.AdminConfig'``). It was
49 introduced for backwards-compatibility with the former style, with the intent
50 to switch the ecosystem to the latter, but the switch didn't happen.
51
52 With automatic ``AppConfig`` discovery, ``default_app_config`` is no longer
53 needed. As a consequence, it's deprecated.
54
55 See :ref:`configuring-applications-ref` for full details.
56
57 Customizing type of auto-created primary keys
58 ---------------------------------------------
59
60 When defining a model, if no field in a model is defined with
61 :attr:`primary_key=True <django.db.models.Field.primary_key>` an implicit
62 primary key is added. The type of this implicit primary key can now be
63 controlled via the :setting:`DEFAULT_AUTO_FIELD` setting and
64 :attr:`AppConfig.default_auto_field <django.apps.AppConfig.default_auto_field>`
65 attribute. No more needing to override primary keys in all models.
66
67 Maintaining the historical behavior, the default value for
68 :setting:`DEFAULT_AUTO_FIELD` is :class:`~django.db.models.AutoField`. Starting
69 with 3.2 new projects are generated with :setting:`DEFAULT_AUTO_FIELD` set to
70 :class:`~django.db.models.BigAutoField`. Also, new apps are generated with
71 :attr:`AppConfig.default_auto_field <django.apps.AppConfig.default_auto_field>`
72 set to :class:`~django.db.models.BigAutoField`. In a future Django release the
73 default value of :setting:`DEFAULT_AUTO_FIELD` will be changed to
74 :class:`~django.db.models.BigAutoField`.
75
76 To avoid unwanted migrations in the future, either explicitly set
77 :setting:`DEFAULT_AUTO_FIELD` to :class:`~django.db.models.AutoField`::
78
79 DEFAULT_AUTO_FIELD = "django.db.models.AutoField"
80
81 or configure it on a per-app basis::
82
83 from django.apps import AppConfig
84
85
86 class MyAppConfig(AppConfig):
87 default_auto_field = "django.db.models.AutoField"
88 name = "my_app"
89
90 or on a per-model basis::
91
92 from django.db import models
93
94
95 class MyModel(models.Model):
96 id = models.AutoField(primary_key=True)
97
98 In anticipation of the changing default, a system check will provide a warning
99 if you do not have an explicit setting for :setting:`DEFAULT_AUTO_FIELD`.
100
101 When changing the value of :setting:`DEFAULT_AUTO_FIELD`, migrations for the
102 primary key of existing auto-created through tables cannot be generated
103 currently. See the :setting:`DEFAULT_AUTO_FIELD` docs for details on migrating
104 such tables.
105
106 .. _new_functional_indexes:
107
108 Functional indexes
109 ------------------
110
111 The new :attr:`*expressions <django.db.models.Index.expressions>` positional
112 argument of :class:`Index() <django.db.models.Index>` enables creating
113 functional indexes on expressions and database functions. For example::
114
115 from django.db import models
116 from django.db.models import F, Index, Value
117 from django.db.models.functions import Lower, Upper
118
119
120 class MyModel(models.Model):
121 first_name = models.CharField(max_length=255)
122 last_name = models.CharField(max_length=255)
123 height = models.IntegerField()
124 weight = models.IntegerField()
125
126 class Meta:
127 indexes = [
128 Index(
129 Lower("first_name"),
130 Upper("last_name").desc(),
131 name="first_last_name_idx",
132 ),
133 Index(
134 F("height") / (F("weight") + Value(5)),
135 name="calc_idx",
136 ),
137 ]
138
139 Functional indexes are added to models using the
140 :attr:`Meta.indexes <django.db.models.Options.indexes>` option.
141
142 ``pymemcache`` support
143 ----------------------
144
145 The new ``django.core.cache.backends.memcached.PyMemcacheCache`` cache backend
146 allows using the :pypi:`pymemcache` library for memcached. ``pymemcache`` 3.4.0
147 or higher is required. For more details, see the :doc:`documentation on caching
148 in Django </topics/cache>`.
149
150 New decorators for the admin site
151 ---------------------------------
152
153 The new :func:`~django.contrib.admin.display` decorator allows for easily
154 adding options to custom display functions that can be used with
155 :attr:`~django.contrib.admin.ModelAdmin.list_display` or
156 :attr:`~django.contrib.admin.ModelAdmin.readonly_fields`.
157
158 Likewise, the new :func:`~django.contrib.admin.action` decorator allows for
159 easily adding options to action functions that can be used with
160 :attr:`~django.contrib.admin.ModelAdmin.actions`.
161
162 Using the ``@display`` decorator has the advantage that it is now
163 possible to use the ``@property`` decorator when needing to specify attributes
164 on the custom method. Prior to this it was necessary to use the ``property()``
165 function instead after assigning the required attributes to the method.
166
167 Using decorators has the advantage that these options are more discoverable as
168 they can be suggested by completion utilities in code editors. They are merely
169 a convenience and still set the same attributes on the functions under the
170 hood.
171
172 Minor features
173 --------------
174
175 :mod:`django.contrib.admin`
176 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
177
178 * :attr:`.ModelAdmin.search_fields` now allows searching against quoted phrases
179 with spaces.
180
181 * Read-only related fields are now rendered as navigable links if target models
182 are registered in the admin.
183
184 * The admin now supports theming, and includes a dark theme that is enabled
185 according to browser settings. See :ref:`admin-theming` for more details.
186
187 * :attr:`.ModelAdmin.autocomplete_fields` now respects
188 :attr:`ForeignKey.to_field <django.db.models.ForeignKey.to_field>` and
189 :attr:`ForeignKey.limit_choices_to
190 <django.db.models.ForeignKey.limit_choices_to>` when searching a related
191 model.
192
193 * The admin now installs a final catch-all view that redirects unauthenticated
194 users to the login page, regardless of whether the URL is otherwise valid.
195 This protects against a potential model enumeration privacy issue.
196
197 Although not recommended, you may set the new
198 :attr:`.AdminSite.final_catch_all_view` to ``False`` to disable the
199 catch-all view.
200
201 :mod:`django.contrib.auth`
202 ~~~~~~~~~~~~~~~~~~~~~~~~~~
203
204 * The default iteration count for the PBKDF2 password hasher is increased from
205 216,000 to 260,000.
206
207 * The default variant for the Argon2 password hasher is changed to Argon2id.
208 ``memory_cost`` and ``parallelism`` are increased to 102,400 and 8
209 respectively to match the ``argon2-cffi`` defaults.
210
211 Increasing the ``memory_cost`` pushes the required memory from 512 KB to 100
212 MB. This is still rather conservative but can lead to problems in memory
213 constrained environments. If this is the case, the existing hasher can be
214 subclassed to override the defaults.
215
216 * The default salt entropy for the Argon2, MD5, PBKDF2, SHA-1 password hashers
217 is increased from 71 to 128 bits.
218
219 :mod:`django.contrib.contenttypes`
220 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
221
222 * The new ``absolute_max`` argument for
223 :func:`~django.contrib.contenttypes.forms.generic_inlineformset_factory`
224 allows customizing the maximum number of forms that can be instantiated when
225 supplying ``POST`` data. See :ref:`formsets-absolute-max` for more details.
226
227 * The new ``can_delete_extra`` argument for
228 :func:`~django.contrib.contenttypes.forms.generic_inlineformset_factory`
229 allows removal of the option to delete extra forms. See
230 :attr:`~.BaseFormSet.can_delete_extra` for more information.
231
232 :mod:`django.contrib.gis`
233 ~~~~~~~~~~~~~~~~~~~~~~~~~
234
235 * The :meth:`.GDALRaster.transform` method now supports
236 :class:`~django.contrib.gis.gdal.SpatialReference`.
237
238 * The :class:`~django.contrib.gis.gdal.DataSource` class now supports
239 :class:`pathlib.Path`.
240
241 * The :class:`~django.contrib.gis.utils.LayerMapping` class now supports
242 :class:`pathlib.Path`.
243
244 :mod:`django.contrib.postgres`
245 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
246
247 * The new :attr:`.ExclusionConstraint.include` attribute allows creating
248 covering exclusion constraints on PostgreSQL 12+.
249
250 * The new ``ExclusionConstraint.opclasses`` attribute allows setting PostgreSQL
251 operator classes.
252
253 * The new ``JSONBAgg.ordering`` attribute determines the ordering of the
254 aggregated elements.
255
256 * The new :attr:`.JSONBAgg.distinct` attribute determines if aggregated values
257 will be distinct.
258
259 * The :class:`~django.contrib.postgres.operations.CreateExtension` operation
260 now checks that the extension already exists in the database and skips the
261 migration if so.
262
263 * The new :class:`~django.contrib.postgres.operations.CreateCollation` and
264 :class:`~django.contrib.postgres.operations.RemoveCollation` operations
265 allow creating and dropping collations on PostgreSQL. See
266 :ref:`manage-postgresql-collations` for more details.
267
268 * Lookups for :class:`~django.contrib.postgres.fields.ArrayField` now allow
269 (non-nested) arrays containing expressions as right-hand sides.
270
271 * The new :class:`OpClass() <django.contrib.postgres.indexes.OpClass>`
272 expression allows creating functional indexes on expressions with a custom
273 operator class. See :ref:`new_functional_indexes` for more details.
274
275 :mod:`django.contrib.sitemaps`
276 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
277
278 * The new :class:`~django.contrib.sitemaps.Sitemap` attributes
279 :attr:`~django.contrib.sitemaps.Sitemap.alternates`,
280 :attr:`~django.contrib.sitemaps.Sitemap.languages` and
281 :attr:`~django.contrib.sitemaps.Sitemap.x_default` allow
282 generating sitemap *alternates* to localized versions of your pages.
283
284 :mod:`django.contrib.syndication`
285 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
286
287 * The new ``item_comments`` hook allows specifying a comments URL per feed
288 item.
289
290 Database backends
291 ~~~~~~~~~~~~~~~~~
292
293 * Third-party database backends can now skip or mark as expected failures
294 tests in Django's test suite using the new
295 ``DatabaseFeatures.django_test_skips`` and
296 ``django_test_expected_failures`` attributes.
297
298 Decorators
299 ~~~~~~~~~~
300
301 * The new :func:`~django.views.decorators.common.no_append_slash` decorator
302 allows individual views to be excluded from :setting:`APPEND_SLASH` URL
303 normalization.
304
305 Error Reporting
306 ~~~~~~~~~~~~~~~
307
308 * Custom :class:`~django.views.debug.ExceptionReporter` subclasses can now
309 define the :attr:`~django.views.debug.ExceptionReporter.html_template_path`
310 and :attr:`~django.views.debug.ExceptionReporter.text_template_path`
311 properties to override the templates used to render exception reports.
312
313 File Uploads
314 ~~~~~~~~~~~~
315
316 * The new :meth:`FileUploadHandler.upload_interrupted()
317 <django.core.files.uploadhandler.FileUploadHandler.upload_interrupted>`
318 callback allows handling interrupted uploads.
319
320 Forms
321 ~~~~~
322
323 * The new ``absolute_max`` argument for :func:`.formset_factory`,
324 :func:`.inlineformset_factory`, and :func:`.modelformset_factory` allows
325 customizing the maximum number of forms that can be instantiated when
326 supplying ``POST`` data. See :ref:`formsets-absolute-max` for more details.
327
328 * The new ``can_delete_extra`` argument for :func:`.formset_factory`,
329 :func:`.inlineformset_factory`, and :func:`.modelformset_factory` allows
330 removal of the option to delete extra forms. See
331 :attr:`~.BaseFormSet.can_delete_extra` for more information.
332
333 * :class:`~django.forms.formsets.BaseFormSet` now reports a user facing error,
334 rather than raising an exception, when the management form is missing or has
335 been tampered with. To customize this error message, pass the
336 ``error_messages`` argument with the key ``'missing_management_form'`` when
337 instantiating the formset.
338
339 Generic Views
340 ~~~~~~~~~~~~~
341
342 * The ``week_format`` attributes of
343 :class:`~django.views.generic.dates.WeekMixin` and
344 :class:`~django.views.generic.dates.WeekArchiveView` now support the
345 ``'%V'`` ISO 8601 week format.
346
347 Management Commands
348 ~~~~~~~~~~~~~~~~~~~
349
350 * :djadmin:`loaddata` now supports fixtures stored in XZ archives (``.xz``) and
351 LZMA archives (``.lzma``).
352
353 * :djadmin:`dumpdata` now can compress data in the ``bz2``, ``gz``, ``lzma``,
354 or ``xz`` formats.
355
356 * :djadmin:`makemigrations` can now be called without an active database
357 connection. In that case, check for a consistent migration history is
358 skipped.
359
360 * :attr:`.BaseCommand.requires_system_checks` now supports specifying a list of
361 tags. System checks registered in the chosen tags will be checked for errors
362 prior to executing the command. In previous versions, either all or none
363 of the system checks were performed.
364
365 * Support for colored terminal output on Windows is updated. Various modern
366 terminal environments are automatically detected, and the options for
367 enabling support in other cases are improved. See :ref:`syntax-coloring` for
368 more details.
369
370 Migrations
371 ~~~~~~~~~~
372
373 * The new ``Operation.migration_name_fragment`` property allows providing a
374 filename fragment that will be used to name a migration containing only that
375 operation.
376
377 * Migrations now support serialization of pure and concrete path objects from
378 :mod:`pathlib`, and :class:`os.PathLike` instances.
379
380 Models
381 ~~~~~~
382
383 * The new ``no_key`` parameter for :meth:`.QuerySet.select_for_update()`,
384 supported on PostgreSQL, allows acquiring weaker locks that don't block the
385 creation of rows that reference locked rows through a foreign key.
386
387 * :class:`When() <django.db.models.expressions.When>` expression now allows
388 using the ``condition`` argument with ``lookups``.
389
390 * The new :attr:`.Index.include` and :attr:`.UniqueConstraint.include`
391 attributes allow creating covering indexes and covering unique constraints on
392 PostgreSQL 11+.
393
394 * The new :attr:`.UniqueConstraint.opclasses` attribute allows setting
395 PostgreSQL operator classes.
396
397 * The :meth:`.QuerySet.update` method now respects the ``order_by()`` clause on
398 MySQL and MariaDB.
399
400 * :class:`FilteredRelation() <django.db.models.FilteredRelation>` now supports
401 nested relations.
402
403 * The ``of`` argument of :meth:`.QuerySet.select_for_update()` is now allowed
404 on MySQL 8.0.1+.
405
406 * :class:`Value() <django.db.models.Value>` expression now
407 automatically resolves its ``output_field`` to the appropriate
408 :class:`Field <django.db.models.Field>` subclass based on the type of
409 its provided ``value`` for :py:class:`bool`, :py:class:`bytes`,
410 :py:class:`float`, :py:class:`int`, :py:class:`str`,
411 :py:class:`datetime.date`, :py:class:`datetime.datetime`,
412 :py:class:`datetime.time`, :py:class:`datetime.timedelta`,
413 :py:class:`decimal.Decimal`, and :py:class:`uuid.UUID` instances. As a
414 consequence, resolving an ``output_field`` for database functions and
415 combined expressions may now crash with mixed types when using ``Value()``.
416 You will need to explicitly set the ``output_field`` in such cases.
417
418 * The new :meth:`.QuerySet.alias` method allows creating reusable aliases for
419 expressions that don't need to be selected but are used for filtering,
420 ordering, or as a part of complex expressions.
421
422 * The new :class:`~django.db.models.functions.Collate` function allows
423 filtering and ordering by specified database collations.
424
425 * The ``field_name`` argument of :meth:`.QuerySet.in_bulk()` now accepts
426 distinct fields if there's only one field specified in
427 :meth:`.QuerySet.distinct`.
428
429 * The new ``tzinfo`` parameter of the
430 :class:`~django.db.models.functions.TruncDate` and
431 :class:`~django.db.models.functions.TruncTime` database functions allows
432 truncating datetimes in a specific timezone.
433
434 * The new ``db_collation`` argument for
435 :attr:`CharField <django.db.models.CharField.db_collation>` and
436 :attr:`TextField <django.db.models.TextField.db_collation>` allows setting a
437 database collation for the field.
438
439 * Added the :class:`~django.db.models.functions.Random` database function.
440
441 * :ref:`aggregation-functions`, :class:`F() <django.db.models.F>`,
442 :class:`OuterRef() <django.db.models.OuterRef>`, and other expressions now
443 allow using transforms. See :ref:`using-transforms-in-expressions` for
444 details.
445
446 * The new ``durable`` argument for :func:`~django.db.transaction.atomic`
447 guarantees that changes made in the atomic block will be committed if the
448 block exits without errors. A nested atomic block marked as durable will
449 raise a ``RuntimeError``.
450
451 * Added the :class:`~django.db.models.functions.JSONObject` database function.
452
453 Pagination
454 ~~~~~~~~~~
455
456 * The new :meth:`django.core.paginator.Paginator.get_elided_page_range` method
457 allows generating a page range with some of the values elided. If there are a
458 large number of pages, this can be helpful for generating a reasonable number
459 of page links in a template.
460
461 Requests and Responses
462 ~~~~~~~~~~~~~~~~~~~~~~
463
464 * Response headers are now stored in :attr:`.HttpResponse.headers`. This can be
465 used instead of the original dict-like interface of ``HttpResponse`` objects.
466 Both interfaces will continue to be supported. See
467 :ref:`setting-header-fields` for details.
468
469 * The new ``headers`` parameter of :class:`~django.http.HttpResponse`,
470 :class:`~django.template.response.SimpleTemplateResponse`, and
471 :class:`~django.template.response.TemplateResponse` allows setting response
472 :attr:`~django.http.HttpResponse.headers` on instantiation.
473
474 Security
475 ~~~~~~~~
476
477 * The :setting:`SECRET_KEY` setting is now checked for a valid value upon first
478 access, rather than when settings are first loaded. This enables running
479 management commands that do not rely on the ``SECRET_KEY`` without needing to
480 provide a value. As a consequence of this, calling
481 :func:`~django.conf.settings.configure` without providing a valid
482 ``SECRET_KEY``, and then going on to access ``settings.SECRET_KEY`` will now
483 raise an :exc:`~django.core.exceptions.ImproperlyConfigured` exception.
484
485 * The new ``Signer.sign_object()`` and ``Signer.unsign_object()`` methods allow
486 signing complex data structures. See :ref:`signing-complex-data` for more
487 details.
488
489 Also, :func:`signing.dumps() <django.core.signing.dumps>` and
490 :func:`~django.core.signing.loads` become shortcuts for
491 :meth:`.TimestampSigner.sign_object` and
492 :meth:`~.TimestampSigner.unsign_object`.
493
494 Serialization
495 ~~~~~~~~~~~~~
496
497 * The new :ref:`JSONL <serialization-formats-jsonl>` serializer allows using
498 the JSON Lines format with :djadmin:`dumpdata` and :djadmin:`loaddata`. This
499 can be useful for populating large databases because data is loaded line by
500 line into memory, rather than being loaded all at once.
501
502 Signals
503 ~~~~~~~
504
505 * :meth:`Signal.send_robust() <django.dispatch.Signal.send_robust>` now logs
506 exceptions.
507
508 Templates
509 ~~~~~~~~~
510
511 * :tfilter:`floatformat` template filter now allows using the ``g`` suffix to
512 force grouping by the :setting:`THOUSAND_SEPARATOR` for the active locale.
513
514 * Templates cached with :ref:`Cached template loaders<template-loaders>` are
515 now correctly reloaded in development.
516
517 Tests
518 ~~~~~
519
520 * Objects assigned to class attributes in :meth:`.TestCase.setUpTestData` are
521 now isolated for each test method. Such objects are now required to support
522 creating deep copies with :py:func:`copy.deepcopy`. Assigning objects which
523 don't support ``deepcopy()`` is deprecated and will be removed in Django 4.1.
524
525 * :class:`~django.test.runner.DiscoverRunner` now enables
526 :py:mod:`faulthandler` by default. This can be disabled by using the
527 :option:`test --no-faulthandler` option.
528
529 * :class:`~django.test.runner.DiscoverRunner` and the
530 :djadmin:`test` management command can now track timings, including database
531 setup and total run time. This can be enabled by using the :option:`test
532 --timing` option.
533
534 * :class:`~django.test.Client` now preserves the request query string when
535 following 307 and 308 redirects.
536
537 * The new :meth:`.TestCase.captureOnCommitCallbacks` method captures callback
538 functions passed to :func:`transaction.on_commit()
539 <django.db.transaction.on_commit>` in a list. This allows you to test such
540 callbacks without using the slower :class:`.TransactionTestCase`.
541
542 * :meth:`TransactionTestCase.assertQuerysetEqual()
543 <django.test.TransactionTestCase.assertQuerySetEqual>` now supports direct
544 comparison against another queryset rather than being restricted to
545 comparison against a list of string representations of objects when using the
546 default value for the ``transform`` argument.
547
548 Utilities
549 ~~~~~~~~~
550
551 * The new ``depth`` parameter of ``django.utils.timesince.timesince()`` and
552 ``django.utils.timesince.timeuntil()`` functions allows specifying the number
553 of adjacent time units to return.
554
555 Validators
556 ~~~~~~~~~~
557
558 * Built-in validators now include the provided value in the ``params`` argument
559 of a raised :exc:`~django.core.exceptions.ValidationError`. This allows
560 custom error messages to use the ``%(value)s`` placeholder.
561
562 * The :class:`.ValidationError` equality operator now ignores ``messages`` and
563 ``params`` ordering.
564
565 .. _backwards-incompatible-3.2:
566
567 Backwards incompatible changes in 3.2
568 =====================================
569
570 Database backend API
571 --------------------
572
573 This section describes changes that may be needed in third-party database
574 backends.
575
576 * The new ``DatabaseFeatures.introspected_field_types`` property replaces these
577 features:
578
579 * ``can_introspect_autofield``
580 * ``can_introspect_big_integer_field``
581 * ``can_introspect_binary_field``
582 * ``can_introspect_decimal_field``
583 * ``can_introspect_duration_field``
584 * ``can_introspect_ip_address_field``
585 * ``can_introspect_positive_integer_field``
586 * ``can_introspect_small_integer_field``
587 * ``can_introspect_time_field``
588 * ``introspected_big_auto_field_type``
589 * ``introspected_small_auto_field_type``
590 * ``introspected_boolean_field_type``
591
592 * To enable support for covering indexes (:attr:`.Index.include`) and covering
593 unique constraints (:attr:`.UniqueConstraint.include`), set
594 ``DatabaseFeatures.supports_covering_indexes`` to ``True``.
595
596 * Third-party database backends must implement support for column database
597 collations on ``CharField``\s and ``TextField``\s or set
598 ``DatabaseFeatures.supports_collation_on_charfield`` and
599 ``DatabaseFeatures.supports_collation_on_textfield`` to ``False``. If
600 non-deterministic collations are not supported, set
601 ``supports_non_deterministic_collations`` to ``False``.
602
603 * ``DatabaseOperations.random_function_sql()`` is removed in favor of the new
604 :class:`~django.db.models.functions.Random` database function.
605
606 * ``DatabaseOperations.date_trunc_sql()`` and
607 ``DatabaseOperations.time_trunc_sql()`` now take the optional ``tzname``
608 argument in order to truncate in a specific timezone.
609
610 * ``DatabaseClient.runshell()`` now gets arguments and an optional dictionary
611 with environment variables to the underlying command-line client from
612 ``DatabaseClient.settings_to_cmd_args_env()`` method. Third-party database
613 backends must implement ``DatabaseClient.settings_to_cmd_args_env()`` or
614 override ``DatabaseClient.runshell()``.
615
616 * Third-party database backends must implement support for functional indexes
617 (:attr:`.Index.expressions`) or set
618 ``DatabaseFeatures.supports_expression_indexes`` to ``False``. If ``COLLATE``
619 is not a part of the ``CREATE INDEX`` statement, set
620 ``DatabaseFeatures.collate_as_index_expression`` to ``True``.
621
622 :mod:`django.contrib.admin`
623 ---------------------------
624
625 * Pagination links in the admin are now 1-indexed instead of 0-indexed, i.e.
626 the query string for the first page is ``?p=1`` instead of ``?p=0``.
627
628 * The new admin catch-all view will break URL patterns routed after the admin
629 URLs and matching the admin URL prefix. You can either adjust your URL
630 ordering or, if necessary, set :attr:`AdminSite.final_catch_all_view
631 <django.contrib.admin.AdminSite.final_catch_all_view>` to ``False``,
632 disabling the catch-all view. See :ref:`whats-new-3.2` for more details.
633
634 * Minified JavaScript files are no longer included with the admin. If you
635 require these files to be minified, consider using a third party app or
636 external build tool. The minified vendored JavaScript files packaged with the
637 admin (e.g. :ref:`jquery.min.js <contrib-admin-jquery>`) are still included.
638
639 * :attr:`.ModelAdmin.prepopulated_fields` no longer strips English stop words,
640 such as ``'a'`` or ``'an'``.
641
642 :mod:`django.contrib.gis`
643 -------------------------
644
645 * Support for PostGIS 2.2 is removed.
646
647 * The Oracle backend now clones polygons (and geometry collections containing
648 polygons) before reorienting them and saving them to the database. They are
649 no longer mutated in place. You might notice this if you use the polygons
650 after a model is saved.
651
652 Dropped support for PostgreSQL 9.5
653 ----------------------------------
654
655 Upstream support for PostgreSQL 9.5 ends in February 2021. Django 3.2 supports
656 PostgreSQL 9.6 and higher.
657
658 Dropped support for MySQL 5.6
659 -----------------------------
660
661 The end of upstream support for MySQL 5.6 is April 2021. Django 3.2 supports
662 MySQL 5.7 and higher.
663
664 Miscellaneous
665 -------------
666
667 * Django now supports non-``pytz`` time zones, such as Python 3.9+'s
668 :mod:`zoneinfo` module and its backport.
669
670 * The undocumented ``SpatiaLiteOperations.proj4_version()`` method is renamed
671 to ``proj_version()``.
672
673 * :func:`~django.utils.text.slugify` now removes leading and trailing dashes
674 and underscores.
675
676 * The :tfilter:`intcomma` and :tfilter:`intword` template filters no longer
677 depend on the ``USE_L10N`` setting.
678
679 * Support for ``argon2-cffi`` < 19.1.0 is removed.
680
681 * The cache keys no longer includes the language when internationalization is
682 disabled (``USE_I18N = False``) and localization is enabled
683 (``USE_L10N = True``). After upgrading to Django 3.2 in such configurations,
684 the first request to any previously cached value will be a cache miss.
685
686 * ``ForeignKey.validate()`` now uses
687 :attr:`~django.db.models.Model._base_manager` rather than
688 :attr:`~django.db.models.Model._default_manager` to check that related
689 instances exist.
690
691 * When an application defines an :class:`~django.apps.AppConfig` subclass in
692 an ``apps.py`` submodule, Django now uses this configuration automatically,
693 even if it isn't enabled with ``default_app_config``. Set ``default = False``
694 in the :class:`~django.apps.AppConfig` subclass if you need to prevent this
695 behavior. See :ref:`whats-new-3.2` for more details.
696
697 * Instantiating an abstract model now raises ``TypeError``.
698
699 * Keyword arguments to :func:`~django.test.utils.setup_databases` are now
700 keyword-only.
701
702 * The undocumented ``django.utils.http.limited_parse_qsl()`` function is
703 removed. Please use :func:`urllib.parse.parse_qsl` instead.
704
705 * ``django.test.utils.TestContextDecorator`` now uses
706 :py:meth:`~unittest.TestCase.addCleanup` so that cleanups registered in the
707 :py:meth:`~unittest.TestCase.setUp` method are called before
708 ``TestContextDecorator.disable()``.
709
710 * ``SessionMiddleware`` now raises a
711 :exc:`~django.contrib.sessions.exceptions.SessionInterrupted` exception
712 instead of :exc:`~django.core.exceptions.SuspiciousOperation` when a session
713 is destroyed in a concurrent request.
714
715 * The :class:`django.db.models.Field` equality operator now correctly
716 distinguishes inherited field instances across models. Additionally, the
717 ordering of such fields is now defined.
718
719 * The undocumented ``django.core.files.locks.lock()`` function now returns
720 ``False`` if the file cannot be locked, instead of raising
721 :exc:`BlockingIOError`.
722
723 * The password reset mechanism now invalidates tokens when the user email is
724 changed.
725
726 * :djadmin:`makemessages` command no longer processes invalid locales specified
727 using :option:`makemessages --locale` option, when they contain hyphens
728 (``'-'``).
729
730 * The ``django.contrib.auth.forms.ReadOnlyPasswordHashField`` form field is now
731 :attr:`~django.forms.Field.disabled` by default. Therefore
732 ``UserChangeForm.clean_password()`` is no longer required to return the
733 initial value.
734
735 * The ``cache.get_many()``, ``get_or_set()``, ``has_key()``, ``incr()``,
736 ``decr()``, ``incr_version()``, and ``decr_version()`` cache operations now
737 correctly handle ``None`` stored in the cache, in the same way as any other
738 value, instead of behaving as though the key didn't exist.
739
740 Due to a ``python-memcached`` limitation, the previous behavior is kept for
741 the deprecated ``MemcachedCache`` backend.
742
743 * The minimum supported version of SQLite is increased from 3.8.3 to 3.9.0.
744
745 * :class:`~django.contrib.messages.storage.cookie.CookieStorage` now stores
746 messages in the :rfc:`6265` compliant format. Support for cookies that use
747 the old format remains until Django 4.1.
748
749 * The minimum supported version of ``asgiref`` is increased from 3.2.10 to
750 3.3.2.
751
752 .. _deprecated-features-3.2:
753
754 Features deprecated in 3.2
755 ==========================
756
757 Miscellaneous
758 -------------
759
760 * Assigning objects which don't support creating deep copies with
761 :py:func:`copy.deepcopy` to class attributes in
762 :meth:`.TestCase.setUpTestData` is deprecated.
763
764 * Using a boolean value in :attr:`.BaseCommand.requires_system_checks` is
765 deprecated. Use ``'__all__'`` instead of ``True``, and ``[]`` (an empty list)
766 instead of ``False``.
767
768 * The ``whitelist`` argument and ``domain_whitelist`` attribute of
769 :class:`~django.core.validators.EmailValidator` are deprecated. Use
770 ``allowlist`` instead of ``whitelist``, and ``domain_allowlist`` instead of
771 ``domain_whitelist``. You may need to rename ``whitelist`` in existing
772 migrations.
773
774 * The ``default_app_config`` application configuration variable is deprecated,
775 due to the now automatic ``AppConfig`` discovery. See :ref:`whats-new-3.2`
776 for more details.
777
778 * Automatically calling ``repr()`` on a queryset in
779 ``TransactionTestCase.assertQuerysetEqual()``, when compared to string
780 values, is deprecated. If you need the previous behavior, explicitly set
781 ``transform`` to ``repr``.
782
783 * The ``django.core.cache.backends.memcached.MemcachedCache`` backend is
784 deprecated as ``python-memcached`` has some problems and seems to be
785 unmaintained. Use ``django.core.cache.backends.memcached.PyMemcacheCache``
786 or ``django.core.cache.backends.memcached.PyLibMCCache`` instead.
787
788 * The format of messages used by
789 ``django.contrib.messages.storage.cookie.CookieStorage`` is different from
790 the format generated by older versions of Django. Support for the old format
791 remains until Django 4.1.