1
0
mirror of https://github.com/django/django.git synced 2024-12-23 09:36:06 +00:00
django/docs/releases/3.2.txt
Tom Carrick e387f191f7 Fixed #31777 -- Added support for database collations to Char/TextFields.
Thanks Simon Charette and Mariusz Felisiak for reviews.
2020-09-21 18:24:56 +02:00

558 lines
19 KiB
Plaintext

============================================
Django 3.2 release notes - UNDER DEVELOPMENT
============================================
*Expected April 2021*
Welcome to Django 3.2!
These release notes cover the :ref:`new features <whats-new-3.2>`, as well as
some :ref:`backwards incompatible changes <backwards-incompatible-3.2>` you'll
want to be aware of when upgrading from Django 3.1 or earlier. We've
:ref:`begun the deprecation process for some features
<deprecated-features-3.2>`.
See the :doc:`/howto/upgrade-version` guide if you're updating an existing
project.
Django 3.2 is designated as a :term:`long-term support release
<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 compatibility
====================
Django 3.2 supports Python 3.6, 3.7, and 3.8. We **highly recommend** and only
officially support the latest release of each series.
.. _whats-new-3.2:
What's new in Django 3.2
========================
Automatic :class:`~django.apps.AppConfig` discovery
---------------------------------------------------
Most pluggable applications define an :class:`~django.apps.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
:class:`~django.apps.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 :setting:`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 :ref:`configuring-applications-ref` for full details.
``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 :doc:`documentation on caching in
Django </topics/cache>`.
.. _pymemcache: https://pypi.org/project/pymemcache/
Minor features
--------------
:mod:`django.contrib.admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :attr:`.ModelAdmin.search_fields` now allows searching against quoted phrases
with spaces.
:mod:`django.contrib.admindocs`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ...
:mod:`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.
:mod:`django.contrib.contenttypes`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The new ``absolute_max`` argument for
:func:`~django.contrib.contenttypes.forms.generic_inlineformset_factory`
allows customizing the maximum number of forms that can be instantiated when
supplying ``POST`` data. See :ref:`formsets-absolute-max` for more details.
* The new ``can_delete_extra`` argument for
:func:`~django.contrib.contenttypes.forms.generic_inlineformset_factory`
allows removal of the option to delete extra forms. See
:attr:`~.BaseFormSet.can_delete_extra` for more information.
:mod:`django.contrib.gis`
~~~~~~~~~~~~~~~~~~~~~~~~~
* The :meth:`.GDALRaster.transform` method now supports
:class:`~django.contrib.gis.gdal.SpatialReference`.
:mod:`django.contrib.messages`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ...
:mod:`django.contrib.postgres`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The new :attr:`.ExclusionConstraint.include` attribute allows creating
covering exclusion constraints on PostgreSQL 12+.
* The new :attr:`.ExclusionConstraint.opclasses` attribute allows setting
PostgreSQL operator classes.
* The new :attr:`.JSONBAgg.ordering` attribute determines the ordering of the
aggregated elements.
* The :class:`~django.contrib.postgres.operations.CreateExtension` operation
now checks that the extension already exists in the database and skips the
migration if so.
:mod:`django.contrib.redirects`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ...
:mod:`django.contrib.sessions`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ...
:mod:`django.contrib.sitemaps`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The new :class:`~django.contrib.sitemaps.Sitemap` attributes
:attr:`~django.contrib.sitemaps.Sitemap.alternates`,
:attr:`~django.contrib.sitemaps.Sitemap.languages` and
:attr:`~django.contrib.sitemaps.Sitemap.x_default` allow
generating sitemap *alternates* to localized versions of your pages.
:mod:`django.contrib.sites`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ...
:mod:`django.contrib.staticfiles`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ...
:mod:`django.contrib.syndication`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The new ``item_comments`` hook allows specifying a comments URL per feed
item.
Cache
~~~~~
* ...
CSRF
~~~~
* ...
Email
~~~~~
* ...
Error Reporting
~~~~~~~~~~~~~~~
* ...
File Storage
~~~~~~~~~~~~
* ...
File Uploads
~~~~~~~~~~~~
* ...
Forms
~~~~~
* The new ``absolute_max`` argument for :func:`.formset_factory`,
:func:`.inlineformset_factory`, and :func:`.modelformset_factory` allows
customizing the maximum number of forms that can be instantiated when
supplying ``POST`` data. See :ref:`formsets-absolute-max` for more details.
* The new ``can_delete_extra`` argument for :func:`.formset_factory`,
:func:`.inlineformset_factory`, and :func:`.modelformset_factory` allows
removal of the option to delete extra forms. See
:attr:`~.BaseFormSet.can_delete_extra` for more information.
Generic Views
~~~~~~~~~~~~~
* The ``week_format`` attributes of
:class:`~django.views.generic.dates.WeekMixin` and
:class:`~django.views.generic.dates.WeekArchiveView` now support the
``'%V'`` ISO 8601 week format.
Internationalization
~~~~~~~~~~~~~~~~~~~~
* ...
Logging
~~~~~~~
* ...
Management Commands
~~~~~~~~~~~~~~~~~~~
* :djadmin:`loaddata` now supports fixtures stored in XZ archives (``.xz``) and
LZMA archives (``.lzma``).
* :djadmin:`makemigrations` can now be called without an active database
connection. In that case, check for a consistent migration history is
skipped.
* :attr:`.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.
Migrations
~~~~~~~~~~
* 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
:mod:`pathlib`, and :class:`os.PathLike` instances.
Models
~~~~~~
* The new ``no_key`` parameter for :meth:`.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.
* :class:`When() <django.db.models.expressions.When>` expression now allows
using the ``condition`` argument with ``lookups``.
* The new :attr:`.Index.include` and :attr:`.UniqueConstraint.include`
attributes allow creating covering indexes and covering unique constraints on
PostgreSQL 11+.
* The new :attr:`.UniqueConstraint.opclasses` attribute allows setting
PostgreSQL operator classes.
* The :meth:`.QuerySet.update` method now respects the ``order_by()`` clause on
MySQL and MariaDB.
* :class:`FilteredRelation() <django.db.models.FilteredRelation>` now supports
nested relations.
* The ``of`` argument of :meth:`.QuerySet.select_for_update()` is now allowed
on MySQL 8.0.1+.
* :class:`Value() <django.db.models.Value>` expression now
automatically resolves its ``output_field`` to the appropriate
:class:`Field <django.db.models.Field>` subclass based on the type of
it's provided ``value`` for :py:class:`bool`, :py:class:`bytes`,
:py:class:`float`, :py:class:`int`, :py:class:`str`,
:py:class:`datetime.date`, :py:class:`datetime.datetime`,
:py:class:`datetime.time`, :py:class:`datetime.timedelta`,
:py:class:`decimal.Decimal`, and :py:class:`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 :meth:`.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 :class:`~django.db.models.functions.Collate` function allows
filtering and ordering by specified database collations.
* The ``field_name`` argument of :meth:`.QuerySet.in_bulk()` now accepts
distinct fields if there's only one field specified in
:meth:`.QuerySet.distinct`.
* The new ``tzinfo`` parameter of the
:class:`~django.db.models.functions.TruncDate` and
:class:`~django.db.models.functions.TruncTime` database functions allows
truncating datetimes in a specific timezone.
* The new ``db_collation`` argument for
:attr:`CharField <django.db.models.CharField.db_collation>` and
:attr:`TextField <django.db.models.TextField.db_collation>` allows setting a
database collation for the field.
Pagination
~~~~~~~~~~
* The new :meth:`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.
Requests and Responses
~~~~~~~~~~~~~~~~~~~~~~
* Response headers are now stored in :attr:`.HttpResponse.headers`. This can be
used instead of the original dict-like interface of ``HttpResponse`` objects.
Both interfaces will continue to be supported. See
:ref:`setting-header-fields` for details.
Security
~~~~~~~~
* The :setting:`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
:func:`~django.conf.settings.configure` without providing a valid
``SECRET_KEY``, and then going on to access ``settings.SECRET_KEY`` will now
raise an :exc:`~django.core.exceptions.ImproperlyConfigured` exception.
Serialization
~~~~~~~~~~~~~
* The new :ref:`JSONL <serialization-formats-jsonl>` serializer allows using
the JSON Lines format with :djadmin:`dumpdata` and :djadmin:`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.
Signals
~~~~~~~
* ...
Templates
~~~~~~~~~
* ...
Tests
~~~~~
* Objects assigned to class attributes in :meth:`.TestCase.setUpTestData` are
now isolated for each test method. Such objects are now required to support
creating deep copies with :py:func:`copy.deepcopy`. Assigning objects which
don't support ``deepcopy()`` is deprecated and will be removed in Django 4.1.
* :class:`~django.test.runner.DiscoverRunner` now enables
:py:mod:`faulthandler` by default. This can be disabled by using the
:option:`test --no-faulthandler` option.
* :class:`~django.test.runner.DiscoverRunner` and the
:djadmin:`test` management command can now track timings, including database
setup and total run time. This can be enabled by using the :option:`test
--timing` option.
* :class:`~django.test.Client` now preserves the request query string when
following 307 and 308 redirects.
* The new :meth:`.TestCase.captureOnCommitCallbacks` method captures callback
functions passed to :func:`transaction.on_commit()
<django.db.transaction.on_commit>` in a list. This allows you to test such
callbacks without using the slower :class:`.TransactionTestCase`.
URLs
~~~~
* ...
Utilities
~~~~~~~~~
* 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.
Validators
~~~~~~~~~~
* Built-in validators now include the provided value in the ``params`` argument
of a raised :exc:`~django.core.exceptions.ValidationError`. This allows
custom error messages to use the ``%(value)s`` placeholder.
* The :class:`.ValidationError` equality operator now ignores ``messages`` and
``params`` ordering.
.. _backwards-incompatible-3.2:
Backwards incompatible changes in 3.2
=====================================
Database backend API
--------------------
This section describes changes that may be needed in third-party database
backends.
* 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 (:attr:`.Index.include`) and covering
unique constraints (:attr:`.UniqueConstraint.include`), set
``DatabaseFeatures.supports_covering_indexes`` to ``True``.
* Third-party database backends must implement support for column database
collations on ``CharField``\s and ``TextField``\s 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``.
:mod:`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``.
:mod:`django.contrib.gis`
-------------------------
* Support for PostGIS 2.2 is removed.
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.
Miscellaneous
-------------
* The undocumented ``SpatiaLiteOperations.proj4_version()`` method is renamed
to ``proj_version()``.
* 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. :ref:`jquery.min.js <contrib-admin-jquery>`) are still included.
* :attr:`.ModelAdmin.prepopulated_fields` no longer strips English stop words,
such as ``'a'`` or ``'an'``.
* :func:`~django.utils.text.slugify` now removes leading and trailing dashes
and underscores.
* The :tfilter:`intcomma` and :tfilter:`intword` template filters no longer
depend on the :setting:`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
:attr:`~django.db.models.Model._base_manager` rather than
:attr:`~django.db.models.Model._default_manager` to check that related
instances exist.
* When an application defines an :class:`~django.apps.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 :class:`~django.apps.AppConfig` subclass if you need to prevent this
behavior. See :ref:`whats-new-3.2` for more details.
* Instantiating an abstract model now raises ``TypeError``.
* Keyword arguments to :func:`~django.test.utils.setup_databases` are now
keyword-only.
* The undocumented ``django.utils.http.limited_parse_qsl()`` function is
removed. Please use :func:`urllib.parse.parse_qsl` instead.
* ``django.test.utils.TestContextDecorator`` now uses
:py:meth:`~unittest.TestCase.addCleanup` so that cleanups registered in the
:py:meth:`~unittest.TestCase.setUp` method are called before
``TestContextDecorator.disable()``.
* ``SessionMiddleware`` now raises a
:exc:`~django.contrib.sessions.exceptions.SessionInterrupted` exception
instead of :exc:`~django.core.exceptions.SuspiciousOperation` when a session
is destroyed in a concurrent request.
* The :class:`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
:exc:`BlockingIOError`.
.. _deprecated-features-3.2:
Features deprecated in 3.2
==========================
Miscellaneous
-------------
* Assigning objects which don't support creating deep copies with
:py:func:`copy.deepcopy` to class attributes in
:meth:`.TestCase.setUpTestData` is deprecated.
* Using a boolean value in :attr:`.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
:class:`~django.core.validators.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 :ref:`whats-new-3.2`
for more details.