1
0
mirror of https://github.com/django/django.git synced 2024-12-23 09:36:06 +00:00
django/docs/releases/3.1.txt

463 lines
14 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`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* 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.
: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.
* :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`.
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
~~~~~~~~~~~~~~~~~~~
* ...
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.
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.
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.
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.
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.
* 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.
.. _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``.
.. _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.