2019-09-05 20:46:01 +08:00
|
|
|
============================================
|
|
|
|
Django 3.1 release notes - UNDER DEVELOPMENT
|
|
|
|
============================================
|
|
|
|
|
|
|
|
*Expected August 2020*
|
|
|
|
|
|
|
|
Welcome to Django 3.1!
|
|
|
|
|
|
|
|
These release notes cover the :ref:`new features <whats-new-3.1>`, as well as
|
|
|
|
some :ref:`backwards incompatible changes <backwards-incompatible-3.1>` you'll
|
|
|
|
want to be aware of when upgrading from Django 3.0 or earlier. We've
|
|
|
|
:ref:`dropped some features<removed-features-3.1>` that have reached the end of
|
|
|
|
their deprecation cycle, and we've :ref:`begun the deprecation process for
|
|
|
|
some features <deprecated-features-3.1>`.
|
|
|
|
|
|
|
|
See the :doc:`/howto/upgrade-version` guide if you're updating an existing
|
|
|
|
project.
|
|
|
|
|
|
|
|
Python compatibility
|
|
|
|
====================
|
|
|
|
|
|
|
|
Django 3.1 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.1:
|
|
|
|
|
|
|
|
What's new in Django 3.1
|
|
|
|
========================
|
|
|
|
|
2020-02-13 06:15:00 +08:00
|
|
|
Asynchronous views and middleware support
|
|
|
|
-----------------------------------------
|
|
|
|
|
|
|
|
Django now supports a fully asynchronous request path, including:
|
|
|
|
|
|
|
|
* :ref:`Asynchronous views <async-views>`
|
|
|
|
* :ref:`Asynchronous middleware <async-middleware>`
|
|
|
|
* :ref:`Asynchronous tests and test client <async-tests>`
|
|
|
|
|
|
|
|
To get started with async views, you need to declare a view using
|
|
|
|
``async def``::
|
|
|
|
|
|
|
|
async def my_view(request):
|
|
|
|
await asyncio.sleep(0.5)
|
|
|
|
return HttpResponse('Hello, async world!')
|
|
|
|
|
|
|
|
All asynchronous features are supported whether you are running under WSGI or
|
|
|
|
ASGI mode. However, there will be performance penalties using async code in
|
|
|
|
WSGI mode. You can read more about the specifics in :doc:`/topics/async`
|
|
|
|
documentation.
|
|
|
|
|
|
|
|
You are free to mix async and sync views, middleware, and tests as much as you
|
|
|
|
want. Django will ensure that you always end up with the right execution
|
|
|
|
context. We expect most projects will keep the majority of their views
|
|
|
|
synchronous, and only have a select few running in async mode - but it is
|
|
|
|
entirely your choice.
|
|
|
|
|
|
|
|
Django's ORM, cache layer, and other pieces of code that do long-running
|
|
|
|
network calls do not yet support async access. We expect to add support for
|
|
|
|
them in upcoming releases. Async views are ideal, however, if you are doing a
|
|
|
|
lot of API or HTTP calls inside your view, you can now natively do all those
|
|
|
|
HTTP calls in parallel to considerably speed up your view's execution.
|
|
|
|
|
|
|
|
Asynchronous support should be entirely backwards-compatible and we have tried
|
|
|
|
to ensure that it has no speed regressions for your existing, synchronous code.
|
|
|
|
It should have no noticeable effect on any existing Django projects.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
Minor features
|
|
|
|
--------------
|
|
|
|
|
|
|
|
:mod:`django.contrib.admin`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2018-01-06 06:53:51 +08:00
|
|
|
* The new ``django.contrib.admin.EmptyFieldListFilter`` for
|
|
|
|
:attr:`.ModelAdmin.list_filter` allows filtering on empty values (empty
|
|
|
|
strings and nulls) in the admin changelist view.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2020-01-21 22:14:11 +08:00
|
|
|
* Filters in the right sidebar of the admin changelist view now contains a link
|
|
|
|
to clear all filters.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
:mod:`django.contrib.admindocs`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
* ...
|
|
|
|
|
|
|
|
:mod:`django.contrib.auth`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2019-09-12 17:46:37 +08:00
|
|
|
* The default iteration count for the PBKDF2 password hasher is increased from
|
|
|
|
180,000 to 216,000.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2019-08-23 23:14:07 +08:00
|
|
|
* Added the :setting:`PASSWORD_RESET_TIMEOUT` setting to define the minimum
|
|
|
|
number of seconds a password reset link is valid for. This is encouraged
|
|
|
|
instead of deprecated ``PASSWORD_RESET_TIMEOUT_DAYS``, which will be removed
|
|
|
|
in Django 4.0.
|
|
|
|
|
2020-01-17 17:09:55 +08:00
|
|
|
* The password reset mechanism now uses the SHA-256 hashing algorithm. Support
|
|
|
|
for tokens that use the old hashing algorithm remains until Django 4.0.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
:mod:`django.contrib.contenttypes`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2020-03-12 03:14:50 +08:00
|
|
|
* The new :option:`remove_stale_contenttypes --include-stale-apps` option
|
|
|
|
allows removing stale content types from previously installed apps that have
|
|
|
|
been removed from :setting:`INSTALLED_APPS`.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
|
|
|
:mod:`django.contrib.gis`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2019-10-17 20:02:37 +08:00
|
|
|
* :lookup:`relate` lookup is now supported on MariaDB.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2019-10-17 16:17:42 +08:00
|
|
|
* Added the :attr:`.LinearRing.is_counterclockwise` property.
|
|
|
|
|
2019-11-16 23:22:01 +08:00
|
|
|
* :class:`~django.contrib.gis.db.models.functions.AsGeoJSON` is now supported
|
|
|
|
on Oracle.
|
|
|
|
|
2019-11-16 02:37:43 +08:00
|
|
|
* Added the :class:`~django.contrib.gis.db.models.functions.AsWKB` and
|
|
|
|
:class:`~django.contrib.gis.db.models.functions.AsWKT` functions.
|
|
|
|
|
2020-03-15 00:32:19 +08:00
|
|
|
:mod:`django.contrib.humanize`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
* :tfilter:`intword` template filter now supports negative integers.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
:mod:`django.contrib.messages`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
* ...
|
|
|
|
|
|
|
|
:mod:`django.contrib.postgres`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2019-10-18 17:08:50 +08:00
|
|
|
* The new :class:`~django.contrib.postgres.indexes.BloomIndex` class allows
|
|
|
|
creating ``bloom`` indexes in the database. The new
|
|
|
|
:class:`~django.contrib.postgres.operations.BloomExtension` migration
|
|
|
|
operation installs the ``bloom`` extension to add support for this index.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2019-11-07 22:35:33 +08:00
|
|
|
* :meth:`~django.db.models.Model.get_FOO_display` now supports
|
|
|
|
:class:`~django.contrib.postgres.fields.ArrayField` and
|
|
|
|
:class:`~django.contrib.postgres.fields.RangeField`.
|
|
|
|
|
2019-11-06 18:22:15 +08:00
|
|
|
* The new :lookup:`rangefield.lower_inc`, :lookup:`rangefield.lower_inf`,
|
|
|
|
:lookup:`rangefield.upper_inc`, and :lookup:`rangefield.upper_inf` allows
|
|
|
|
querying :class:`~django.contrib.postgres.fields.RangeField` by a bound type.
|
|
|
|
|
2019-12-05 16:54:27 +08:00
|
|
|
* :lookup:`rangefield.contained_by` now supports
|
|
|
|
:class:`~django.db.models.SmallAutoField`,
|
|
|
|
:class:`~django.db.models.AutoField`,
|
|
|
|
:class:`~django.db.models.BigAutoField`,
|
|
|
|
:class:`~django.db.models.SmallIntegerField`, and
|
|
|
|
:class:`~django.db.models.DecimalField`.
|
|
|
|
|
2019-12-14 04:10:33 +08:00
|
|
|
* :class:`~django.contrib.postgres.search.SearchQuery` now supports
|
|
|
|
``'websearch'`` search type on PostgreSQL 11+.
|
|
|
|
|
2020-03-04 20:33:12 +08:00
|
|
|
* :class:`SearchQuery.value <django.contrib.postgres.search.SearchQuery>` now
|
|
|
|
supports query expressions.
|
|
|
|
|
2019-11-19 21:59:06 +08:00
|
|
|
* The new :class:`~django.contrib.postgres.search.SearchHeadline` class allows
|
|
|
|
highlighting search results.
|
|
|
|
|
2020-03-04 20:33:12 +08:00
|
|
|
* :lookup:`search` lookup now supports query expressions.
|
|
|
|
|
2020-03-21 05:01:26 +08:00
|
|
|
* The new ``cover_density`` parameter of
|
|
|
|
:class:`~django.contrib.postgres.search.SearchRank` allows ranking by cover
|
|
|
|
density.
|
|
|
|
|
|
|
|
* The new ``normalization`` parameter of
|
|
|
|
:class:`~django.contrib.postgres.search.SearchRank` allows rank
|
|
|
|
normalization.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
:mod:`django.contrib.redirects`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
* ...
|
|
|
|
|
|
|
|
:mod:`django.contrib.sessions`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2019-10-09 19:42:55 +08:00
|
|
|
* The :setting:`SESSION_COOKIE_SAMESITE` setting now allows ``'None'`` (string)
|
|
|
|
value to explicitly state that the cookie is sent with all same-site and
|
|
|
|
cross-site requests.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
|
|
|
:mod:`django.contrib.sitemaps`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
* ...
|
|
|
|
|
|
|
|
:mod:`django.contrib.sites`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
* ...
|
|
|
|
|
|
|
|
:mod:`django.contrib.staticfiles`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2019-11-07 17:26:22 +08:00
|
|
|
* The :setting:`STATICFILES_DIRS` setting now supports :class:`pathlib.Path`.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
|
|
|
:mod:`django.contrib.syndication`
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
* ...
|
|
|
|
|
|
|
|
Cache
|
|
|
|
~~~~~
|
|
|
|
|
2019-09-27 04:58:14 +08:00
|
|
|
* The :func:`~django.views.decorators.cache.cache_control` decorator and
|
|
|
|
:func:`~django.utils.cache.patch_cache_control` method now support multiple
|
|
|
|
field names in the ``no-cache`` directive for the ``Cache-Control`` header,
|
|
|
|
according to :rfc:`7234#section-5.2.2.2`.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2019-10-08 17:02:40 +08:00
|
|
|
* :meth:`~django.core.caches.cache.delete` now returns ``True`` if the key was
|
|
|
|
successfully deleted, ``False`` otherwise.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
CSRF
|
|
|
|
~~~~
|
|
|
|
|
2019-10-09 19:42:55 +08:00
|
|
|
* The :setting:`CSRF_COOKIE_SAMESITE` setting now allows ``'None'`` (string)
|
|
|
|
value to explicitly state that the cookie is sent with all same-site and
|
|
|
|
cross-site requests.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
|
|
|
Email
|
|
|
|
~~~~~
|
|
|
|
|
2019-11-06 16:33:07 +08:00
|
|
|
* The :setting:`EMAIL_FILE_PATH` setting, used by the :ref:`file email backend
|
|
|
|
<topic-email-file-backend>`, now supports :class:`pathlib.Path`.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2020-01-09 17:00:07 +08:00
|
|
|
Error Reporting
|
|
|
|
~~~~~~~~~~~~~~~
|
|
|
|
|
2020-01-09 18:37:19 +08:00
|
|
|
* :class:`django.views.debug.SafeExceptionReporterFilter` now filters sensitive
|
|
|
|
values from ``request.META`` in exception reports.
|
|
|
|
|
2020-01-09 17:00:07 +08:00
|
|
|
* The new :attr:`.SafeExceptionReporterFilter.cleansed_substitute` and
|
|
|
|
:attr:`.SafeExceptionReporterFilter.hidden_settings` attributes allow
|
2020-01-09 18:37:19 +08:00
|
|
|
customization of sensitive settings and ``request.META`` filtering in
|
|
|
|
exception reports.
|
2020-01-09 17:00:07 +08:00
|
|
|
|
|
|
|
* The technical 404 debug view now respects
|
|
|
|
:setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` when applying settings
|
|
|
|
filtering.
|
|
|
|
|
2019-09-08 01:08:12 +08:00
|
|
|
* The new :setting:`DEFAULT_EXCEPTION_REPORTER` allows providing a
|
|
|
|
:class:`django.views.debug.ExceptionReporter` subclass to customize exception
|
|
|
|
report generation. See :ref:`custom-error-reports` for details.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
File Storage
|
|
|
|
~~~~~~~~~~~~
|
|
|
|
|
2019-10-22 00:03:48 +08:00
|
|
|
* ``FileSystemStorage.save()`` method now supports :class:`pathlib.Path`.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
|
|
|
File Uploads
|
|
|
|
~~~~~~~~~~~~
|
|
|
|
|
|
|
|
* ...
|
|
|
|
|
|
|
|
|
|
|
|
Forms
|
|
|
|
~~~~~
|
|
|
|
|
2019-11-18 07:41:23 +08:00
|
|
|
* :class:`~django.forms.ModelChoiceIterator`, used by
|
|
|
|
:class:`~django.forms.ModelChoiceField` and
|
|
|
|
:class:`~django.forms.ModelMultipleChoiceField`, now uses
|
|
|
|
:class:`~django.forms.ModelChoiceIteratorValue` that can be used by widgets
|
|
|
|
to access model instances. See :ref:`iterating-relationship-choices` for
|
|
|
|
details.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2019-10-09 18:08:50 +08:00
|
|
|
* :class:`django.forms.DateTimeField` now accepts dates in a subset of ISO 8601
|
|
|
|
datetime formats, including optional timezone (e.g. ``2019-10-10T06:47``,
|
2020-01-04 18:44:11 +08:00
|
|
|
``2019-10-10T06:47:23+04:00``, or ``2019-10-10T06:47:23Z``). Additionally, it
|
|
|
|
now uses ``DATE_INPUT_FORMATS`` in addition to ``DATETIME_INPUT_FORMATS``
|
|
|
|
when converting a field input to a ``datetime`` value.
|
2019-10-09 18:08:50 +08:00
|
|
|
|
2020-02-14 06:12:46 +08:00
|
|
|
* :attr:`.MultiWidget.widgets` now accepts a dictionary which allows
|
|
|
|
customizing subwidget ``name`` attributes.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
Generic Views
|
|
|
|
~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
* ...
|
|
|
|
|
|
|
|
Internationalization
|
|
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2019-10-09 19:42:55 +08:00
|
|
|
* The :setting:`LANGUAGE_COOKIE_SAMESITE` setting now allows ``'None'``
|
|
|
|
(string) value to explicitly state that the cookie is sent with all same-site
|
|
|
|
and cross-site requests.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2019-12-13 16:20:27 +08:00
|
|
|
* Added support and translations for the Algerian Arabic language.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
Logging
|
|
|
|
~~~~~~~
|
|
|
|
|
|
|
|
* ...
|
|
|
|
|
|
|
|
Management Commands
|
|
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2020-02-07 15:46:13 +08:00
|
|
|
* The new :option:`check --database` option allows specifying database aliases
|
|
|
|
for running the ``database`` system checks. Previously these checks were
|
|
|
|
enabled for all configured :setting:`DATABASES` by passing the ``database``
|
|
|
|
tag to the command.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2020-03-26 17:08:58 +08:00
|
|
|
* The new :option:`migrate --check` option makes the command exit with a
|
|
|
|
non-zero status when unapplied migrations are detected.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
Migrations
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
2019-03-29 04:47:05 +08:00
|
|
|
* Migrations are now loaded also from directories without ``__init__.py``
|
|
|
|
files.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
|
|
|
Models
|
|
|
|
~~~~~~
|
|
|
|
|
2019-10-01 06:12:19 +08:00
|
|
|
* The new :class:`~django.db.models.functions.ExtractIsoWeekDay` function
|
|
|
|
extracts ISO-8601 week days from :class:`~django.db.models.DateField` and
|
|
|
|
:class:`~django.db.models.DateTimeField`, and the new :lookup:`iso_week_day`
|
|
|
|
lookup allows querying by an ISO-8601 day of week.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2019-10-22 00:34:19 +08:00
|
|
|
* :meth:`.QuerySet.explain` now supports:
|
|
|
|
|
|
|
|
* ``TREE`` format on MySQL 8.0.16+,
|
|
|
|
* ``analyze`` option on MySQL 8.0.18+ and MariaDB.
|
2019-10-22 00:32:56 +08:00
|
|
|
|
2019-10-16 20:32:12 +08:00
|
|
|
* Added :class:`~django.db.models.PositiveBigIntegerField` which acts much like
|
|
|
|
a :class:`~django.db.models.PositiveIntegerField` except that it only allows
|
|
|
|
values under a certain (database-dependent) limit. Values from ``0`` to
|
|
|
|
``9223372036854775807`` are safe in all databases supported by Django.
|
|
|
|
|
2016-10-10 15:23:35 +08:00
|
|
|
* The new :class:`~django.db.models.RESTRICT` option for
|
|
|
|
:attr:`~django.db.models.ForeignKey.on_delete` argument of ``ForeignKey`` and
|
|
|
|
``OneToOneField`` emulates the behavior of the SQL constraint ``ON DELETE
|
|
|
|
RESTRICT``.
|
|
|
|
|
2019-11-15 13:08:36 +08:00
|
|
|
* :attr:`.CheckConstraint.check` now supports boolean expressions.
|
|
|
|
|
2019-11-30 00:54:03 +08:00
|
|
|
* The :meth:`.RelatedManager.add`, :meth:`~.RelatedManager.create`, and
|
|
|
|
:meth:`~.RelatedManager.set` methods now accept callables as values in the
|
|
|
|
``through_defaults`` argument.
|
|
|
|
|
2020-02-19 01:12:51 +08:00
|
|
|
* The new ``is_dst`` parameter of the :meth:`.QuerySet.datetimes` determines
|
|
|
|
the treatment of nonexistent and ambiguous datetimes.
|
|
|
|
|
2020-03-21 06:08:32 +08:00
|
|
|
* The new :class:`~django.db.models.F` expression ``bitxor()`` method allows
|
|
|
|
:ref:`bitwise XOR operation <using-f-expressions-in-filters>`.
|
|
|
|
|
2020-03-25 16:58:21 +08:00
|
|
|
* :meth:`.QuerySet.bulk_create` now sets the primary key on objects when using
|
|
|
|
MariaDB 10.5+.
|
|
|
|
|
2019-09-21 05:04:34 +08:00
|
|
|
Pagination
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
2019-10-03 16:14:06 +08:00
|
|
|
* :class:`~django.core.paginator.Paginator` can now be iterated over to yield
|
|
|
|
its pages.
|
2019-09-21 05:04:34 +08:00
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
Requests and Responses
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2019-11-24 10:17:31 +08:00
|
|
|
* If :setting:`ALLOWED_HOSTS` is empty and ``DEBUG=True``, subdomains of
|
|
|
|
localhost are now allowed in the ``Host`` header, e.g. ``static.localhost``.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2019-10-09 19:42:55 +08:00
|
|
|
* :meth:`.HttpResponse.set_cookie` and :meth:`.HttpResponse.set_signed_cookie`
|
|
|
|
now allow using ``samesite='None'`` (string) to explicitly state that the
|
|
|
|
cookie is sent with all same-site and cross-site requests.
|
|
|
|
|
2019-11-17 20:24:10 +08:00
|
|
|
* The new :meth:`.HttpRequest.accepts` method returns whether the request
|
|
|
|
accepts the given MIME type according to the ``Accept`` HTTP header.
|
|
|
|
|
2020-02-05 18:02:35 +08:00
|
|
|
.. _whats-new-security-3.1:
|
|
|
|
|
|
|
|
Security
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
* The :setting:`SECURE_REFERRER_POLICY` setting now defaults to
|
|
|
|
``'same-origin'``. With this configured,
|
|
|
|
:class:`~django.middleware.security.SecurityMiddleware` sets the
|
|
|
|
:ref:`referrer-policy` header to ``same-origin`` on all responses that do not
|
|
|
|
already have it. This prevents the ``Referer`` header being sent to other
|
|
|
|
origins. If you need the previous behavior, explicitly set
|
|
|
|
:setting:`SECURE_REFERRER_POLICY` to ``None``.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
Serialization
|
|
|
|
~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
* ...
|
|
|
|
|
|
|
|
Signals
|
|
|
|
~~~~~~~
|
|
|
|
|
|
|
|
* ...
|
|
|
|
|
|
|
|
Templates
|
|
|
|
~~~~~~~~~
|
|
|
|
|
2019-06-22 00:41:01 +08:00
|
|
|
* The renamed :ttag:`translate` and :ttag:`blocktranslate` template tags are
|
|
|
|
introduced for internationalization in template code. The older :ttag:`trans`
|
|
|
|
and :ttag:`blocktrans` template tags aliases continue to work, and will be
|
|
|
|
retained for the foreseeable future.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2020-02-03 00:48:07 +08:00
|
|
|
* The :ttag:`include` template tag now accepts iterables of template names.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
Tests
|
|
|
|
~~~~~
|
|
|
|
|
2016-10-27 05:10:17 +08:00
|
|
|
* :class:`~django.test.SimpleTestCase` now implements the ``debug()`` method to
|
|
|
|
allow running a test without collecting the result and catching exceptions.
|
|
|
|
This can be used to support running tests under a debugger.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2019-11-13 11:49:09 +08:00
|
|
|
* The new :setting:`MIGRATE <TEST_MIGRATE>` test database setting allows
|
|
|
|
disabling of migrations during a test database creation.
|
|
|
|
|
2019-12-01 05:10:16 +08:00
|
|
|
* Django test runner now supports a :option:`test --buffer` option to discard
|
|
|
|
output for passing tests.
|
|
|
|
|
2020-02-07 17:37:25 +08:00
|
|
|
* :class:`~django.test.runner.DiscoverRunner` now skips running the system
|
|
|
|
checks on databases not :ref:`referenced by tests<testing-multi-db>`.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
URLs
|
|
|
|
~~~~
|
|
|
|
|
2019-12-22 02:22:18 +08:00
|
|
|
* :ref:`Path converters <registering-custom-path-converters>` can now raise
|
|
|
|
``ValueError`` in ``to_url()`` to indicate no match when reversing URLs.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2019-10-30 04:15:18 +08:00
|
|
|
Utilities
|
|
|
|
~~~~~~~~~
|
|
|
|
|
|
|
|
* :func:`~django.utils.encoding.filepath_to_uri` now supports
|
|
|
|
:class:`pathlib.Path`.
|
|
|
|
|
2019-11-27 15:14:00 +08:00
|
|
|
* :func:`~django.utils.dateparse.parse_duration` now supports comma separators
|
|
|
|
for decimal fractions in the ISO 8601 format.
|
|
|
|
|
2019-09-26 04:17:22 +08:00
|
|
|
* :func:`~django.utils.dateparse.parse_datetime`,
|
|
|
|
:func:`~django.utils.dateparse.parse_duration`, and
|
|
|
|
:func:`~django.utils.dateparse.parse_time` now support comma separators for
|
|
|
|
milliseconds.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
Validators
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
|
|
|
* ...
|
|
|
|
|
2019-11-07 17:26:22 +08:00
|
|
|
Miscellaneous
|
|
|
|
~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
* The SQLite backend now supports :class:`pathlib.Path` for the ``NAME``
|
|
|
|
setting.
|
|
|
|
|
2019-11-07 18:11:27 +08:00
|
|
|
* The ``settings.py`` generated by the :djadmin:`startproject` command now uses
|
|
|
|
:class:`pathlib.Path` instead of :mod:`os.path` for building filesystem
|
|
|
|
paths.
|
|
|
|
|
2019-07-20 21:38:43 +08:00
|
|
|
* The :setting:`TIME_ZONE <DATABASE-TIME_ZONE>` setting is now allowed on
|
|
|
|
databases that support time zones.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
.. _backwards-incompatible-3.1:
|
|
|
|
|
|
|
|
Backwards incompatible changes in 3.1
|
|
|
|
=====================================
|
|
|
|
|
|
|
|
Database backend API
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
This section describes changes that may be needed in third-party database
|
|
|
|
backends.
|
|
|
|
|
2019-09-15 05:50:14 +08:00
|
|
|
* ``DatabaseOperations.fetch_returned_insert_columns()`` now requires an
|
|
|
|
additional ``returning_params`` argument.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2019-07-21 00:31:47 +08:00
|
|
|
* ``connection.timezone`` property is now ``'UTC'`` by default, or the
|
|
|
|
:setting:`TIME_ZONE <DATABASE-TIME_ZONE>` when :setting:`USE_TZ` is ``True``
|
|
|
|
on databases that support time zones. Previously, it was ``None`` on
|
|
|
|
databases that support time zones.
|
|
|
|
|
2020-02-04 11:07:00 +08:00
|
|
|
* ``connection._nodb_connection`` property is changed to the
|
|
|
|
``connection._nodb_cursor()`` method and now returns a context manager that
|
|
|
|
yields a cursor and automatically closes the cursor and connection upon
|
|
|
|
exiting the ``with`` statement.
|
|
|
|
|
2019-10-16 18:58:05 +08:00
|
|
|
Dropped support for MariaDB 10.1
|
|
|
|
--------------------------------
|
|
|
|
|
|
|
|
Upstream support for MariaDB 10.1 ends in October 2020. Django 3.1 supports
|
|
|
|
MariaDB 10.2 and higher.
|
|
|
|
|
2020-02-28 19:39:14 +08:00
|
|
|
``contrib.admin`` browser support
|
|
|
|
---------------------------------
|
|
|
|
|
|
|
|
The admin no longer supports the legacy Internet Explorer browser. See
|
|
|
|
:ref:`the admin FAQ <admin-browser-support>` for details on supported browsers.
|
|
|
|
|
2020-03-17 20:12:32 +08:00
|
|
|
:attr:`AbstractUser.first_name <django.contrib.auth.models.User.first_name>` ``max_length`` increased to 150
|
|
|
|
------------------------------------------------------------------------------------------------------------
|
|
|
|
|
|
|
|
A migration for :attr:`django.contrib.auth.models.User.first_name` is included.
|
|
|
|
If you have a custom user model inheriting from ``AbstractUser``, you'll need
|
|
|
|
to generate and apply a database migration for your user model.
|
|
|
|
|
|
|
|
If you want to preserve the 30 character limit for first names, use a custom
|
|
|
|
form::
|
|
|
|
|
|
|
|
from django import forms
|
|
|
|
from django.contrib.auth.forms import UserChangeForm
|
|
|
|
|
|
|
|
class MyUserChangeForm(UserChangeForm):
|
|
|
|
first_name = forms.CharField(max_length=30, required=False)
|
|
|
|
|
|
|
|
If you wish to keep this restriction in the admin when editing users, set
|
|
|
|
``UserAdmin.form`` to use this form::
|
|
|
|
|
|
|
|
from django.contrib.auth.admin import UserAdmin
|
|
|
|
from django.contrib.auth.models import User
|
|
|
|
|
|
|
|
class MyUserAdmin(UserAdmin):
|
|
|
|
form = MyUserChangeForm
|
|
|
|
|
|
|
|
admin.site.unregister(User)
|
|
|
|
admin.site.register(User, MyUserAdmin)
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
Miscellaneous
|
|
|
|
-------------
|
|
|
|
|
2019-09-12 05:12:35 +08:00
|
|
|
* The cache keys used by :ttag:`cache` and generated by
|
|
|
|
:func:`~django.core.cache.utils.make_template_fragment_key` are different
|
|
|
|
from the keys generated by older versions of Django. After upgrading to
|
|
|
|
Django 3.1, the first request to any previously cached template fragment will
|
|
|
|
be a cache miss.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2019-12-15 22:30:35 +08:00
|
|
|
* The logic behind the decision to return a redirection fallback or a 204 HTTP
|
|
|
|
response from the :func:`~django.views.i18n.set_language` view is now based
|
|
|
|
on the ``Accept`` HTTP header instead of the ``X-Requested-With`` HTTP header
|
|
|
|
presence.
|
|
|
|
|
2019-07-18 14:13:01 +08:00
|
|
|
* The compatibility imports of ``django.core.exceptions.EmptyResultSet`` in
|
|
|
|
``django.db.models.query``, ``django.db.models.sql``, and
|
|
|
|
``django.db.models.sql.datastructures`` are removed.
|
|
|
|
|
|
|
|
* The compatibility import of ``django.core.exceptions.FieldDoesNotExist`` in
|
|
|
|
``django.db.models.fields`` is removed.
|
|
|
|
|
|
|
|
* The compatibility imports of ``django.forms.utils.pretty_name()`` and
|
|
|
|
``django.forms.boundfield.BoundField`` in ``django.forms.forms`` are removed.
|
|
|
|
|
|
|
|
* The compatibility imports of ``Context``, ``ContextPopException``, and
|
|
|
|
``RequestContext`` in ``django.template.base`` are removed.
|
|
|
|
|
2019-11-06 19:41:07 +08:00
|
|
|
* The compatibility import of
|
|
|
|
``django.contrib.admin.helpers.ACTION_CHECKBOX_NAME`` in
|
|
|
|
``django.contrib.admin`` is removed.
|
|
|
|
|
2018-12-06 08:15:33 +08:00
|
|
|
* The :setting:`STATIC_URL` and :setting:`MEDIA_URL` settings set to relative
|
|
|
|
paths are now prefixed by the server-provided value of ``SCRIPT_NAME`` (or
|
|
|
|
``/`` if not set). This change should not affect settings set to valid URLs
|
|
|
|
or absolute paths.
|
|
|
|
|
2019-10-09 17:20:17 +08:00
|
|
|
* :class:`~django.middleware.http.ConditionalGetMiddleware` no longer adds the
|
|
|
|
``ETag`` header to responses with an empty
|
|
|
|
:attr:`~django.http.HttpResponse.content`.
|
|
|
|
|
2020-03-28 21:22:54 +08:00
|
|
|
* ``django.utils.decorators.classproperty()`` decorator is made public and
|
|
|
|
moved to :class:`django.utils.functional.classproperty()`.
|
2019-10-19 03:00:34 +08:00
|
|
|
|
2019-10-31 10:05:26 +08:00
|
|
|
* :tfilter:`floatformat` template filter now outputs (positive) ``0`` for
|
|
|
|
negative numbers which round to zero.
|
|
|
|
|
2019-04-24 18:44:13 +08:00
|
|
|
* :attr:`Meta.ordering <django.db.models.Options.ordering>` and
|
|
|
|
:attr:`Meta.unique_together <django.db.models.Options.unique_together>`
|
|
|
|
options on models in ``django.contrib`` modules that were formerly tuples are
|
|
|
|
now lists.
|
|
|
|
|
2019-10-12 00:33:29 +08:00
|
|
|
* The admin calendar widget now handles two-digit years according to the Open
|
|
|
|
Group Specification, i.e. values between 69 and 99 are mapped to the previous
|
|
|
|
century, and values between 0 and 68 are mapped to the current century.
|
|
|
|
|
2020-01-04 18:44:11 +08:00
|
|
|
* Date-only formats are removed from the default list for
|
|
|
|
:setting:`DATETIME_INPUT_FORMATS`.
|
|
|
|
|
2020-01-05 15:51:33 +08:00
|
|
|
* The :class:`~django.forms.FileInput` widget no longer renders with the
|
|
|
|
``required`` HTML attribute when initial data exists.
|
|
|
|
|
2020-01-09 22:54:05 +08:00
|
|
|
* The undocumented ``django.views.debug.ExceptionReporterFilter`` class is
|
|
|
|
removed. As per the :ref:`custom-error-reports` documentation, classes to be
|
|
|
|
used with :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` needs to inherit from
|
|
|
|
:class:`django.views.debug.SafeExceptionReporterFilter`.
|
|
|
|
|
2019-09-27 02:41:38 +08:00
|
|
|
* The cache timeout set by :func:`~django.views.decorators.cache.cache_page`
|
|
|
|
decorator now takes precedence over the ``max-age`` directive from the
|
|
|
|
``Cache-Control`` header.
|
|
|
|
|
2020-01-29 21:29:09 +08:00
|
|
|
* Providing a non-local remote field in the :attr:`.ForeignKey.to_field`
|
|
|
|
argument now raises :class:`~django.core.exceptions.FieldError`.
|
|
|
|
|
2020-02-05 18:02:35 +08:00
|
|
|
* :setting:`SECURE_REFERRER_POLICY` now defaults to ``'same-origin'``. See the
|
|
|
|
*What's New* :ref:`Security section <whats-new-security-3.1>` above for more
|
|
|
|
details.
|
|
|
|
|
2020-02-07 15:46:13 +08:00
|
|
|
* :djadmin:`check` management command now runs the ``database`` system checks
|
|
|
|
only for database aliases specified using :option:`check --database` option.
|
|
|
|
|
|
|
|
* :djadmin:`migrate` management command now runs the ``database`` system checks
|
|
|
|
only for a database to migrate.
|
|
|
|
|
2020-03-08 01:35:59 +08:00
|
|
|
* The admin CSS classes ``row1`` and ``row2`` are removed in favor of
|
|
|
|
``:nth-child(odd)`` and ``:nth-child(even)`` pseudo-classes.
|
|
|
|
|
2020-03-26 20:23:32 +08:00
|
|
|
* The :func:`~django.contrib.auth.hashers.make_password` now requires its
|
|
|
|
argument to be a string or bytes. Other types should be explicitly cast to
|
|
|
|
one of these.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
.. _deprecated-features-3.1:
|
|
|
|
|
|
|
|
Features deprecated in 3.1
|
|
|
|
==========================
|
|
|
|
|
|
|
|
Miscellaneous
|
|
|
|
-------------
|
|
|
|
|
2019-08-23 23:14:07 +08:00
|
|
|
* ``PASSWORD_RESET_TIMEOUT_DAYS`` setting is deprecated in favor of
|
|
|
|
:setting:`PASSWORD_RESET_TIMEOUT`.
|
2019-09-05 20:46:01 +08:00
|
|
|
|
2019-10-12 02:10:31 +08:00
|
|
|
* The undocumented usage of the :lookup:`isnull` lookup with non-boolean values
|
|
|
|
as the right-hand side is deprecated, use ``True`` or ``False`` instead.
|
|
|
|
|
2019-11-16 05:20:07 +08:00
|
|
|
* The barely documented ``django.db.models.query_utils.InvalidQuery`` exception
|
|
|
|
class is deprecated in favor of
|
|
|
|
:class:`~django.core.exceptions.FieldDoesNotExist` and
|
|
|
|
:class:`~django.core.exceptions.FieldError`.
|
|
|
|
|
2019-11-02 12:08:23 +08:00
|
|
|
* The ``django-admin.py`` entry point is deprecated in favor of
|
|
|
|
``django-admin``.
|
|
|
|
|
2020-01-24 01:01:41 +08:00
|
|
|
* The ``HttpRequest.is_ajax()`` method is deprecated as it relied on a
|
2020-02-04 19:03:13 +08:00
|
|
|
jQuery-specific way of signifying AJAX calls, while current usage tends to
|
|
|
|
use the JavaScript `Fetch API
|
2020-01-27 21:21:52 +08:00
|
|
|
<https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API>`_. Depending on
|
|
|
|
your use case, you can either write your own AJAX detection method, or use
|
|
|
|
the new :meth:`.HttpRequest.accepts` method if your code depends on the
|
|
|
|
client ``Accept`` HTTP header.
|
2020-01-24 01:01:41 +08:00
|
|
|
|
2020-02-03 20:43:11 +08:00
|
|
|
If you are writing your own AJAX detection method, ``request.is_ajax()`` can
|
|
|
|
be reproduced exactly as
|
|
|
|
``request.headers.get('x-requested-with') == 'XMLHttpRequest'``.
|
|
|
|
|
2019-09-27 01:06:35 +08:00
|
|
|
* Passing ``None`` as the first argument to
|
|
|
|
``django.utils.deprecation.MiddlewareMixin.__init__()`` is deprecated.
|
|
|
|
|
2020-01-31 06:11:09 +08:00
|
|
|
* The encoding format of cookies values used by
|
|
|
|
:class:`~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.0.
|
|
|
|
|
2020-02-15 19:20:37 +08:00
|
|
|
* The encoding format of sessions is different from the format generated by
|
|
|
|
older versions of Django. Support for the old format remains until Django
|
|
|
|
4.0.
|
|
|
|
|
2020-03-02 01:22:03 +08:00
|
|
|
* The purely documentational ``providing_args`` argument for
|
|
|
|
:class:`~django.dispatch.Signal` is deprecated. If you rely on this
|
2020-03-10 19:01:32 +08:00
|
|
|
argument as documentation, you can move the text to a code comment or
|
2020-03-02 01:22:03 +08:00
|
|
|
docstring.
|
2020-03-10 19:01:32 +08:00
|
|
|
|
2020-03-11 16:47:43 +08:00
|
|
|
* Calling ``django.utils.crypto.get_random_string()`` without a ``length``
|
|
|
|
argument is deprecated.
|
|
|
|
|
2020-03-06 05:53:16 +08:00
|
|
|
* The ``list`` message for :class:`~django.forms.ModelMultipleChoiceField` is
|
|
|
|
deprecated in favor of ``invalid_list``.
|
|
|
|
|
2019-08-15 13:48:33 +08:00
|
|
|
* The passing of URL kwargs directly to the context by
|
|
|
|
:class:`~django.views.generic.base.TemplateView` is deprecated. Reference
|
|
|
|
them in the template with ``view.kwargs`` instead.
|
|
|
|
|
2019-09-05 20:46:01 +08:00
|
|
|
.. _removed-features-3.1:
|
|
|
|
|
|
|
|
Features removed in 3.1
|
|
|
|
=======================
|
|
|
|
|
|
|
|
These features have reached the end of their deprecation cycle and are removed
|
|
|
|
in Django 3.1.
|
|
|
|
|
|
|
|
See :ref:`deprecated-features-2.2` for details on these changes, including how
|
|
|
|
to remove usage of these features.
|
|
|
|
|
2019-09-06 13:59:06 +08:00
|
|
|
* ``django.utils.timezone.FixedOffset`` is removed.
|
|
|
|
|
2019-09-06 14:07:20 +08:00
|
|
|
* ``django.core.paginator.QuerySetPaginator`` is removed.
|
|
|
|
|
2019-09-08 01:28:19 +08:00
|
|
|
* A model's ``Meta.ordering`` doesn't affect ``GROUP BY`` queries.
|
|
|
|
|
2019-09-05 22:10:21 +08:00
|
|
|
* ``django.contrib.postgres.fields.FloatRangeField`` and
|
|
|
|
``django.contrib.postgres.forms.FloatRangeField`` are removed.
|
2019-09-05 22:25:30 +08:00
|
|
|
|
|
|
|
* The ``FILE_CHARSET`` setting is removed.
|
2019-09-06 19:40:59 +08:00
|
|
|
|
|
|
|
* ``django.contrib.staticfiles.storage.CachedStaticFilesStorage`` is removed.
|
2019-09-07 17:57:46 +08:00
|
|
|
|
2019-09-07 21:58:49 +08:00
|
|
|
* The ``RemoteUserBackend.configure_user()`` method requires ``request`` as the
|
|
|
|
first positional argument.
|
|
|
|
|
2019-09-07 17:57:46 +08:00
|
|
|
* Support for ``SimpleTestCase.allow_database_queries`` and
|
|
|
|
``TransactionTestCase.multi_db`` is removed.
|