============================================ Django 3.1 release notes - UNDER DEVELOPMENT ============================================ *Expected August 2020* Welcome to Django 3.1! These release notes cover the :ref:`new features `, as well as some :ref:`backwards incompatible changes ` you'll want to be aware of when upgrading from Django 3.0 or earlier. We've :ref:`dropped some features` that have reached the end of their deprecation cycle, and we've :ref:`begun the deprecation process for some features `. 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+. * The new :class:`~django.contrib.postgres.search.SearchHeadline` class allows highlighting search results. :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 `, 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 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`. URLs ~~~~ * :ref:`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 ` 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 ` 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 ` 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 ` and :attr:`Meta.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 ` 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. * The admin CSS classes ``row1`` and ``row2`` are removed in favor of ``:nth-child(odd)`` and ``:nth-child(even)`` pseudo-classes. .. _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 `_. 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. * 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. * The purely documentational ``providing_args`` argument for :class:`~django.dispatch.Signal` is deprecated. If you rely on this argument as documentation, you can move the text to a code comment or docstring. * Calling ``django.utils.crypto.get_random_string()`` without a ``length`` argument is deprecated. * The ``list`` message for :class:`~django.forms.ModelMultipleChoiceField` is deprecated in favor of ``invalid_list``. .. _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.