mirror of
https://github.com/django/django.git
synced 2024-12-26 02:56:25 +00:00
396 lines
10 KiB
Plaintext
396 lines
10 KiB
Plaintext
============================================
|
|
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`
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
* ...
|
|
|
|
: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.
|
|
|
|
: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.
|
|
|
|
:mod:`django.contrib.redirects`
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
* ...
|
|
|
|
:mod:`django.contrib.sessions`
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
* ...
|
|
|
|
: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
|
|
~~~~
|
|
|
|
* ...
|
|
|
|
Email
|
|
~~~~~
|
|
|
|
* The :setting:`EMAIL_FILE_PATH` setting, used by the :ref:`file email backend
|
|
<topic-email-file-backend>`, now supports :class:`pathlib.Path`.
|
|
|
|
File Storage
|
|
~~~~~~~~~~~~
|
|
|
|
* ``FileSystemStorage.save()`` method now supports :class:`pathlib.Path`.
|
|
|
|
File Uploads
|
|
~~~~~~~~~~~~
|
|
|
|
* ...
|
|
|
|
|
|
Forms
|
|
~~~~~
|
|
|
|
* ...
|
|
|
|
Generic Views
|
|
~~~~~~~~~~~~~
|
|
|
|
* ...
|
|
|
|
Internationalization
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
* ...
|
|
|
|
Logging
|
|
~~~~~~~
|
|
|
|
* ...
|
|
|
|
Management Commands
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
* ...
|
|
|
|
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.
|
|
|
|
Pagination
|
|
~~~~~~~~~~
|
|
|
|
* :class:`~django.core.paginator.Paginator` can now be iterated over to yield
|
|
its pages.
|
|
|
|
Requests and Responses
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
* ...
|
|
|
|
Serialization
|
|
~~~~~~~~~~~~~
|
|
|
|
* ...
|
|
|
|
Signals
|
|
~~~~~~~
|
|
|
|
* ...
|
|
|
|
Templates
|
|
~~~~~~~~~
|
|
|
|
* ...
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
.. _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.
|
|
|
|
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.
|
|
|
|
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 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.
|
|
|
|
.. _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`.
|
|
|
|
.. _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.
|