path: root/docs/releases/3.1.txt

============================================
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
========================

Minor features
--------------

:mod:`django.contrib.admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~

* 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.

* Filters in the right sidebar of the admin changelist view now contains a link
  to clear all filters.

:mod:`django.contrib.admindocs`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.auth`
~~~~~~~~~~~~~~~~~~~~~~~~~~

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

* 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.

* 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.

:mod:`django.contrib.contenttypes`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.gis`
~~~~~~~~~~~~~~~~~~~~~~~~~

* :lookup:`relate` lookup is now supported on MariaDB.

* Added the :attr:`.LinearRing.is_counterclockwise` property.

* :class:`~django.contrib.gis.db.models.functions.AsGeoJSON` is now supported
  on Oracle.

* Added the :class:`~django.contrib.gis.db.models.functions.AsWKB` and
  :class:`~django.contrib.gis.db.models.functions.AsWKT` functions.

:mod:`django.contrib.messages`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.postgres`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* 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.

* :meth:`~django.db.models.Model.get_FOO_display` now supports
  :class:`~django.contrib.postgres.fields.ArrayField` and
  :class:`~django.contrib.postgres.fields.RangeField`.

* 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.

* :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`.

* :class:`~django.contrib.postgres.search.SearchQuery` now supports
  ``'websearch'`` search type on PostgreSQL 11+.

:mod:`django.contrib.redirects`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.sessions`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* 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.

:mod:`django.contrib.sitemaps`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.sites`
~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

:mod:`django.contrib.staticfiles`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* The :setting:`STATICFILES_DIRS` setting now supports :class:`pathlib.Path`.

:mod:`django.contrib.syndication`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ...

Cache
~~~~~

* 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`.

* :meth:`~django.core.caches.cache.delete` now returns ``True`` if the key was
  successfully deleted, ``False`` otherwise.

CSRF
~~~~

* 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.

Email
~~~~~

* The :setting:`EMAIL_FILE_PATH` setting, used by the :ref:`file email backend
  <topic-email-file-backend>`, now supports :class:`pathlib.Path`.

Error Reporting
~~~~~~~~~~~~~~~

* :class:`django.views.debug.SafeExceptionReporterFilter` now filters sensitive
  values from ``request.META`` in exception reports.

* The new :attr:`.SafeExceptionReporterFilter.cleansed_substitute` and
  :attr:`.SafeExceptionReporterFilter.hidden_settings` attributes allow
  customization of sensitive settings and ``request.META`` filtering in
  exception reports.

* The technical 404 debug view now respects
  :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` when applying settings
  filtering.

* 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.

File Storage
~~~~~~~~~~~~

* ``FileSystemStorage.save()`` method now supports :class:`pathlib.Path`.

File Uploads
~~~~~~~~~~~~

* ...


Forms
~~~~~

* :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.

* :class:`django.forms.DateTimeField` now accepts dates in a subset of ISO 8601
  datetime formats, including optional timezone (e.g. ``2019-10-10T06:47``,
  ``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.

Generic Views
~~~~~~~~~~~~~

* ...

Internationalization
~~~~~~~~~~~~~~~~~~~~

* 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.

* Added support and translations for the Algerian Arabic language.

Logging
~~~~~~~

* ...

Management Commands
~~~~~~~~~~~~~~~~~~~

* 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.

Migrations
~~~~~~~~~~

* Migrations are now loaded also from directories without ``__init__.py``
  files.

Models
~~~~~~

* 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.

* :meth:`.QuerySet.explain` now supports:

  * ``TREE`` format on MySQL 8.0.16+,
  * ``analyze`` option on MySQL 8.0.18+ and MariaDB.

* 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.

* 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``.

* :attr:`.CheckConstraint.check` now supports boolean expressions.

* The :meth:`.RelatedManager.add`, :meth:`~.RelatedManager.create`, and
  :meth:`~.RelatedManager.set` methods now accept callables as values in the
  ``through_defaults`` argument.

Pagination
~~~~~~~~~~

* :class:`~django.core.paginator.Paginator` can now be iterated over to yield
  its pages.

Requests and Responses
~~~~~~~~~~~~~~~~~~~~~~

* If :setting:`ALLOWED_HOSTS` is empty and ``DEBUG=True``, subdomains of
  localhost are now allowed in the ``Host`` header, e.g. ``static.localhost``.

* :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.

* The new :meth:`.HttpRequest.accepts` method returns whether the request
  accepts the given MIME type according to the ``Accept`` HTTP header.

.. _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``.

Serialization
~~~~~~~~~~~~~

* ...

Signals
~~~~~~~

* ...

Templates
~~~~~~~~~

* 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.

* The :ttag:`include` template tag now accepts iterables of template names.

Tests
~~~~~

* :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.

* The new :setting:`MIGRATE <TEST_MIGRATE>` test database setting allows
  disabling of migrations during a test database creation.

* Django test runner now supports a :option:`test --buffer` option to discard
  output for passing tests.

* :class:`~django.test.runner.DiscoverRunner` now skips running the system
  checks on databases not :ref:`referenced by tests<testing-multi-db>`.

URLs
~~~~

* :ref:`Path converters <registering-custom-path-converters>` can now raise
  ``ValueError`` in ``to_url()`` to indicate no match when reversing URLs.

Utilities
~~~~~~~~~

* :func:`~django.utils.encoding.filepath_to_uri` now supports
  :class:`pathlib.Path`.

* :func:`~django.utils.dateparse.parse_duration` now supports comma separators
  for decimal fractions in the ISO 8601 format.

* :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.

Validators
~~~~~~~~~~

* ...

Miscellaneous
~~~~~~~~~~~~~

* The SQLite backend now supports :class:`pathlib.Path` for the ``NAME``
  setting.

* The ``settings.py`` generated by the :djadmin:`startproject` command now uses
  :class:`pathlib.Path` instead of :mod:`os.path` for building filesystem
  paths.

* The :setting:`TIME_ZONE <DATABASE-TIME_ZONE>` setting is now allowed on
  databases that support time zones.

.. _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.

* ``DatabaseOperations.fetch_returned_insert_columns()`` now requires an
  additional ``returning_params`` argument.

* ``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.

* ``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.

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.

``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.

Miscellaneous
-------------

* 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.

* 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.

* 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.

* The compatibility import of
  ``django.contrib.admin.helpers.ACTION_CHECKBOX_NAME`` in
  ``django.contrib.admin`` is removed.

* 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.

* :class:`~django.middleware.http.ConditionalGetMiddleware` no longer adds the
  ``ETag`` header to responses with an empty
  :attr:`~django.http.HttpResponse.content`.

* ``django.utils.decorators.classproperty()`` decorator is moved to
  ``django.utils.functional.classproperty()``.

* :tfilter:`floatformat` template filter now outputs (positive) ``0`` for
  negative numbers which round to zero.

* :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.

* 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.

* Date-only formats are removed from the default list for
  :setting:`DATETIME_INPUT_FORMATS`.

* The :class:`~django.forms.FileInput` widget no longer renders with the
  ``required`` HTML attribute when initial data exists.

* 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`.

* 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.

* Providing a non-local remote field in the :attr:`.ForeignKey.to_field`
  argument now raises :class:`~django.core.exceptions.FieldError`.

* :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.

* :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.

.. _deprecated-features-3.1:

Features deprecated in 3.1
==========================

Miscellaneous
-------------

* ``PASSWORD_RESET_TIMEOUT_DAYS`` setting is deprecated in favor of
  :setting:`PASSWORD_RESET_TIMEOUT`.

* The undocumented usage of the :lookup:`isnull` lookup with non-boolean values
  as the right-hand side is deprecated, use ``True`` or ``False`` instead.

* 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`.

* The ``django-admin.py`` entry point is deprecated in favor of
  ``django-admin``.

* The ``HttpRequest.is_ajax()`` method is deprecated as it relied on a
  jQuery-specific way of signifying AJAX calls, while current usage tends to
  use the JavaScript `Fetch API
  <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.

  If you are writing your own AJAX detection method, ``request.is_ajax()`` can
  be reproduced exactly as
  ``request.headers.get('x-requested-with') == 'XMLHttpRequest'``.

* Passing ``None`` as the first argument to
  ``django.utils.deprecation.MiddlewareMixin.__init__()`` is deprecated.

* 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.

.. _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.

* ``django.utils.timezone.FixedOffset`` is removed.

* ``django.core.paginator.QuerySetPaginator`` is removed.

* A model's ``Meta.ordering`` doesn't affect ``GROUP BY`` queries.

* ``django.contrib.postgres.fields.FloatRangeField`` and
  ``django.contrib.postgres.forms.FloatRangeField`` are removed.

* The ``FILE_CHARSET`` setting is removed.

* ``django.contrib.staticfiles.storage.CachedStaticFilesStorage`` is removed.

* The ``RemoteUserBackend.configure_user()`` method requires ``request`` as the
  first positional argument.

* Support for ``SimpleTestCase.allow_database_queries`` and
  ``TransactionTestCase.multi_db`` is removed.