| 1 |
======================== |
| 2 |
Django 3.1 release notes |
| 3 |
======================== |
| 4 |
|
| 5 |
*August 4, 2020* |
| 6 |
|
| 7 |
Welcome to Django 3.1! |
| 8 |
|
| 9 |
These release notes cover the :ref:`new features <whats-new-3.1>`, as well as |
| 10 |
some :ref:`backwards incompatible changes <backwards-incompatible-3.1>` you'll |
| 11 |
want to be aware of when upgrading from Django 3.0 or earlier. We've |
| 12 |
:ref:`dropped some features<removed-features-3.1>` that have reached the end of |
| 13 |
their deprecation cycle, and we've :ref:`begun the deprecation process for |
| 14 |
some features <deprecated-features-3.1>`. |
| 15 |
|
| 16 |
See the :doc:`/howto/upgrade-version` guide if you're updating an existing |
| 17 |
project. |
| 18 |
|
| 19 |
Python compatibility |
| 20 |
==================== |
| 21 |
|
| 22 |
Django 3.1 supports Python 3.6, 3.7, 3.8, and 3.9 (as of 3.1.3). We **highly |
| 23 |
recommend** and only officially support the latest release of each series. |
| 24 |
|
| 25 |
.. _whats-new-3.1: |
| 26 |
|
| 27 |
What's new in Django 3.1 |
| 28 |
======================== |
| 29 |
|
| 30 |
Asynchronous views and middleware support |
| 31 |
----------------------------------------- |
| 32 |
|
| 33 |
Django now supports a fully asynchronous request path, including: |
| 34 |
|
| 35 |
* :ref:`Asynchronous views <async-views>` |
| 36 |
* :ref:`Asynchronous middleware <async-middleware>` |
| 37 |
* :ref:`Asynchronous tests and test client <async-tests>` |
| 38 |
|
| 39 |
To get started with async views, you need to declare a view using |
| 40 |
``async def``:: |
| 41 |
|
| 42 |
async def my_view(request): |
| 43 |
await asyncio.sleep(0.5) |
| 44 |
return HttpResponse("Hello, async world!") |
| 45 |
|
| 46 |
All asynchronous features are supported whether you are running under WSGI or |
| 47 |
ASGI mode. However, there will be performance penalties using async code in |
| 48 |
WSGI mode. You can read more about the specifics in :doc:`/topics/async` |
| 49 |
documentation. |
| 50 |
|
| 51 |
You are free to mix async and sync views, middleware, and tests as much as you |
| 52 |
want. Django will ensure that you always end up with the right execution |
| 53 |
context. We expect most projects will keep the majority of their views |
| 54 |
synchronous, and only have a select few running in async mode - but it is |
| 55 |
entirely your choice. |
| 56 |
|
| 57 |
Django's ORM, cache layer, and other pieces of code that do long-running |
| 58 |
network calls do not yet support async access. We expect to add support for |
| 59 |
them in upcoming releases. Async views are ideal, however, if you are doing a |
| 60 |
lot of API or HTTP calls inside your view, you can now natively do all those |
| 61 |
HTTP calls in parallel to considerably speed up your view's execution. |
| 62 |
|
| 63 |
Asynchronous support should be entirely backwards-compatible and we have tried |
| 64 |
to ensure that it has no speed regressions for your existing, synchronous code. |
| 65 |
It should have no noticeable effect on any existing Django projects. |
| 66 |
|
| 67 |
JSONField for all supported database backends |
| 68 |
--------------------------------------------- |
| 69 |
|
| 70 |
Django now includes :class:`.models.JSONField` and |
| 71 |
:class:`forms.JSONField <django.forms.JSONField>` that can be used on all |
| 72 |
supported database backends. Both fields support the use of custom JSON |
| 73 |
encoders and decoders. The model field supports the introspection, |
| 74 |
:ref:`lookups, and transforms <querying-jsonfield>` that were previously |
| 75 |
PostgreSQL-only:: |
| 76 |
|
| 77 |
from django.db import models |
| 78 |
|
| 79 |
|
| 80 |
class ContactInfo(models.Model): |
| 81 |
data = models.JSONField() |
| 82 |
|
| 83 |
|
| 84 |
ContactInfo.objects.create( |
| 85 |
data={ |
| 86 |
"name": "John", |
| 87 |
"cities": ["London", "Cambridge"], |
| 88 |
"pets": {"dogs": ["Rufus", "Meg"]}, |
| 89 |
} |
| 90 |
) |
| 91 |
ContactInfo.objects.filter( |
| 92 |
data__name="John", |
| 93 |
data__pets__has_key="dogs", |
| 94 |
data__cities__contains="London", |
| 95 |
).delete() |
| 96 |
|
| 97 |
If your project uses ``django.contrib.postgres.fields.JSONField``, plus the |
| 98 |
related form field and transforms, you should adjust to use the new fields, |
| 99 |
and generate and apply a database migration. For now, the old fields and |
| 100 |
transforms are left as a reference to the new ones and are :ref:`deprecated as |
| 101 |
of this release <deprecated-jsonfield>`. |
| 102 |
|
| 103 |
.. _default-hashing-algorithm-usage: |
| 104 |
|
| 105 |
``DEFAULT_HASHING_ALGORITHM`` settings |
| 106 |
-------------------------------------- |
| 107 |
|
| 108 |
The new ``DEFAULT_HASHING_ALGORITHM`` transitional setting allows specifying |
| 109 |
the default hashing algorithm to use for encoding cookies, password reset |
| 110 |
tokens in the admin site, user sessions, and signatures created by |
| 111 |
:class:`django.core.signing.Signer` and :meth:`django.core.signing.dumps`. |
| 112 |
|
| 113 |
Support for SHA-256 was added in Django 3.1. If you are upgrading multiple |
| 114 |
instances of the same project to Django 3.1, you should set |
| 115 |
``DEFAULT_HASHING_ALGORITHM`` to ``'sha1'`` during the transition, in order to |
| 116 |
allow compatibility with the older versions of Django. Note that this requires |
| 117 |
Django 3.1.1+. Once the transition to 3.1 is complete you can stop overriding |
| 118 |
``DEFAULT_HASHING_ALGORITHM``. |
| 119 |
|
| 120 |
This setting is deprecated as of this release, because support for tokens, |
| 121 |
cookies, sessions, and signatures that use SHA-1 algorithm will be removed in |
| 122 |
Django 4.0. |
| 123 |
|
| 124 |
Minor features |
| 125 |
-------------- |
| 126 |
|
| 127 |
:mod:`django.contrib.admin` |
| 128 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 129 |
|
| 130 |
* The new ``django.contrib.admin.EmptyFieldListFilter`` for |
| 131 |
:attr:`.ModelAdmin.list_filter` allows filtering on empty values (empty |
| 132 |
strings and nulls) in the admin changelist view. |
| 133 |
|
| 134 |
* Filters in the right sidebar of the admin changelist view now contain a link |
| 135 |
to clear all filters. |
| 136 |
|
| 137 |
* The admin now has a sidebar on larger screens for easier navigation. It is |
| 138 |
enabled by default but can be disabled by using a custom ``AdminSite`` and |
| 139 |
setting :attr:`.AdminSite.enable_nav_sidebar` to ``False``. |
| 140 |
|
| 141 |
Rendering the sidebar requires access to the current request in order to set |
| 142 |
CSS and ARIA role affordances. This requires using |
| 143 |
``'django.template.context_processors.request'`` in the |
| 144 |
``'context_processors'`` option of :setting:`OPTIONS <TEMPLATES-OPTIONS>`. |
| 145 |
|
| 146 |
* Initially empty ``extra`` inlines can now be removed, in the same way as |
| 147 |
dynamically created ones. |
| 148 |
|
| 149 |
* ``XRegExp`` is upgraded from version 2.0.0 to 3.2.0. |
| 150 |
|
| 151 |
* jQuery is upgraded from version 3.4.1 to 3.5.1. |
| 152 |
|
| 153 |
* Select2 library is upgraded from version 4.0.7 to 4.0.13. |
| 154 |
|
| 155 |
:mod:`django.contrib.auth` |
| 156 |
~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 157 |
|
| 158 |
* The default iteration count for the PBKDF2 password hasher is increased from |
| 159 |
180,000 to 216,000. |
| 160 |
|
| 161 |
* The new :setting:`PASSWORD_RESET_TIMEOUT` setting allows defining the number |
| 162 |
of seconds a password reset link is valid for. This is encouraged instead of |
| 163 |
the deprecated ``PASSWORD_RESET_TIMEOUT_DAYS`` setting, which will be removed |
| 164 |
in Django 4.0. |
| 165 |
|
| 166 |
* The password reset mechanism now uses the SHA-256 hashing algorithm. Support |
| 167 |
for tokens that use the old hashing algorithm remains until Django 4.0. |
| 168 |
|
| 169 |
* :meth:`.AbstractBaseUser.get_session_auth_hash` now uses the SHA-256 hashing |
| 170 |
algorithm. Support for user sessions that use the old hashing algorithm |
| 171 |
remains until Django 4.0. |
| 172 |
|
| 173 |
:mod:`django.contrib.contenttypes` |
| 174 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 175 |
|
| 176 |
* The new :option:`remove_stale_contenttypes --include-stale-apps` option |
| 177 |
allows removing stale content types from previously installed apps that have |
| 178 |
been removed from :setting:`INSTALLED_APPS`. |
| 179 |
|
| 180 |
:mod:`django.contrib.gis` |
| 181 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 182 |
|
| 183 |
* :lookup:`relate` lookup is now supported on MariaDB. |
| 184 |
|
| 185 |
* Added the :attr:`.LinearRing.is_counterclockwise` property. |
| 186 |
|
| 187 |
* :class:`~django.contrib.gis.db.models.functions.AsGeoJSON` is now supported |
| 188 |
on Oracle. |
| 189 |
|
| 190 |
* Added the :class:`~django.contrib.gis.db.models.functions.AsWKB` and |
| 191 |
:class:`~django.contrib.gis.db.models.functions.AsWKT` functions. |
| 192 |
|
| 193 |
* Added support for PostGIS 3 and GDAL 3. |
| 194 |
|
| 195 |
:mod:`django.contrib.humanize` |
| 196 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 197 |
|
| 198 |
* :tfilter:`intword` template filter now supports negative integers. |
| 199 |
|
| 200 |
:mod:`django.contrib.postgres` |
| 201 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 202 |
|
| 203 |
* The new :class:`~django.contrib.postgres.indexes.BloomIndex` class allows |
| 204 |
creating ``bloom`` indexes in the database. The new |
| 205 |
:class:`~django.contrib.postgres.operations.BloomExtension` migration |
| 206 |
operation installs the ``bloom`` extension to add support for this index. |
| 207 |
|
| 208 |
* :meth:`~django.db.models.Model.get_FOO_display` now supports |
| 209 |
:class:`~django.contrib.postgres.fields.ArrayField` and |
| 210 |
:class:`~django.contrib.postgres.fields.RangeField`. |
| 211 |
|
| 212 |
* The new :lookup:`rangefield.lower_inc`, :lookup:`rangefield.lower_inf`, |
| 213 |
:lookup:`rangefield.upper_inc`, and :lookup:`rangefield.upper_inf` lookups |
| 214 |
allow querying :class:`~django.contrib.postgres.fields.RangeField` by a bound |
| 215 |
type. |
| 216 |
|
| 217 |
* :lookup:`rangefield.contained_by` now supports |
| 218 |
:class:`~django.db.models.SmallAutoField`, |
| 219 |
:class:`~django.db.models.AutoField`, |
| 220 |
:class:`~django.db.models.BigAutoField`, |
| 221 |
:class:`~django.db.models.SmallIntegerField`, and |
| 222 |
:class:`~django.db.models.DecimalField`. |
| 223 |
|
| 224 |
* :class:`~django.contrib.postgres.search.SearchQuery` now supports |
| 225 |
``'websearch'`` search type on PostgreSQL 11+. |
| 226 |
|
| 227 |
* :class:`SearchQuery.value <django.contrib.postgres.search.SearchQuery>` now |
| 228 |
supports query expressions. |
| 229 |
|
| 230 |
* The new :class:`~django.contrib.postgres.search.SearchHeadline` class allows |
| 231 |
highlighting search results. |
| 232 |
|
| 233 |
* :lookup:`search` lookup now supports query expressions. |
| 234 |
|
| 235 |
* The new ``cover_density`` parameter of |
| 236 |
:class:`~django.contrib.postgres.search.SearchRank` allows ranking by cover |
| 237 |
density. |
| 238 |
|
| 239 |
* The new ``normalization`` parameter of |
| 240 |
:class:`~django.contrib.postgres.search.SearchRank` allows rank |
| 241 |
normalization. |
| 242 |
|
| 243 |
* The new :attr:`.ExclusionConstraint.deferrable` attribute allows creating |
| 244 |
deferrable exclusion constraints. |
| 245 |
|
| 246 |
:mod:`django.contrib.sessions` |
| 247 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 248 |
|
| 249 |
* The :setting:`SESSION_COOKIE_SAMESITE` setting now allows ``'None'`` (string) |
| 250 |
value to explicitly state that the cookie is sent with all same-site and |
| 251 |
cross-site requests. |
| 252 |
|
| 253 |
:mod:`django.contrib.staticfiles` |
| 254 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 255 |
|
| 256 |
* The :setting:`STATICFILES_DIRS` setting now supports :class:`pathlib.Path`. |
| 257 |
|
| 258 |
Cache |
| 259 |
~~~~~ |
| 260 |
|
| 261 |
* The :func:`~django.views.decorators.cache.cache_control` decorator and |
| 262 |
:func:`~django.utils.cache.patch_cache_control` method now support multiple |
| 263 |
field names in the ``no-cache`` directive for the ``Cache-Control`` header, |
| 264 |
according to :rfc:`7234#section-5.2.2.2`. |
| 265 |
|
| 266 |
* :meth:`~django.core.cache.cache.delete` now returns ``True`` if the key was |
| 267 |
successfully deleted, ``False`` otherwise. |
| 268 |
|
| 269 |
CSRF |
| 270 |
~~~~ |
| 271 |
|
| 272 |
* The :setting:`CSRF_COOKIE_SAMESITE` setting now allows ``'None'`` (string) |
| 273 |
value to explicitly state that the cookie is sent with all same-site and |
| 274 |
cross-site requests. |
| 275 |
|
| 276 |
Email |
| 277 |
~~~~~ |
| 278 |
|
| 279 |
* The :setting:`EMAIL_FILE_PATH` setting, used by the :ref:`file email backend |
| 280 |
<topic-email-file-backend>`, now supports :class:`pathlib.Path`. |
| 281 |
|
| 282 |
Error Reporting |
| 283 |
~~~~~~~~~~~~~~~ |
| 284 |
|
| 285 |
* :class:`django.views.debug.SafeExceptionReporterFilter` now filters sensitive |
| 286 |
values from ``request.META`` in exception reports. |
| 287 |
|
| 288 |
* The new :attr:`.SafeExceptionReporterFilter.cleansed_substitute` and |
| 289 |
:attr:`.SafeExceptionReporterFilter.hidden_settings` attributes allow |
| 290 |
customization of sensitive settings and ``request.META`` filtering in |
| 291 |
exception reports. |
| 292 |
|
| 293 |
* The technical 404 debug view now respects |
| 294 |
:setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` when applying settings |
| 295 |
filtering. |
| 296 |
|
| 297 |
* The new :setting:`DEFAULT_EXCEPTION_REPORTER` allows providing a |
| 298 |
:class:`django.views.debug.ExceptionReporter` subclass to customize exception |
| 299 |
report generation. See :ref:`custom-error-reports` for details. |
| 300 |
|
| 301 |
File Storage |
| 302 |
~~~~~~~~~~~~ |
| 303 |
|
| 304 |
* ``FileSystemStorage.save()`` method now supports :class:`pathlib.Path`. |
| 305 |
|
| 306 |
* :class:`~django.db.models.FileField` and |
| 307 |
:class:`~django.db.models.ImageField` now accept a callable for ``storage``. |
| 308 |
This allows you to modify the used storage at runtime, selecting different |
| 309 |
storages for different environments, for example. |
| 310 |
|
| 311 |
Forms |
| 312 |
~~~~~ |
| 313 |
|
| 314 |
* :class:`~django.forms.ModelChoiceIterator`, used by |
| 315 |
:class:`~django.forms.ModelChoiceField` and |
| 316 |
:class:`~django.forms.ModelMultipleChoiceField`, now uses |
| 317 |
:class:`~django.forms.ModelChoiceIteratorValue` that can be used by widgets |
| 318 |
to access model instances. See :ref:`iterating-relationship-choices` for |
| 319 |
details. |
| 320 |
|
| 321 |
* :class:`django.forms.DateTimeField` now accepts dates in a subset of ISO 8601 |
| 322 |
datetime formats, including optional timezone, e.g. ``2019-10-10T06:47``, |
| 323 |
``2019-10-10T06:47:23+04:00``, or ``2019-10-10T06:47:23Z``. The timezone will |
| 324 |
always be retained if provided, with timezone-aware datetimes being returned |
| 325 |
even when :setting:`USE_TZ` is ``False``. |
| 326 |
|
| 327 |
Additionally, ``DateTimeField`` now uses ``DATE_INPUT_FORMATS`` in addition |
| 328 |
to ``DATETIME_INPUT_FORMATS`` when converting a field input to a ``datetime`` |
| 329 |
value. |
| 330 |
|
| 331 |
* :attr:`.MultiWidget.widgets` now accepts a dictionary which allows |
| 332 |
customizing subwidget ``name`` attributes. |
| 333 |
|
| 334 |
* The new :attr:`.BoundField.widget_type` property can be used to dynamically |
| 335 |
adjust form rendering based upon the widget type. |
| 336 |
|
| 337 |
Internationalization |
| 338 |
~~~~~~~~~~~~~~~~~~~~ |
| 339 |
|
| 340 |
* The :setting:`LANGUAGE_COOKIE_SAMESITE` setting now allows ``'None'`` |
| 341 |
(string) value to explicitly state that the cookie is sent with all same-site |
| 342 |
and cross-site requests. |
| 343 |
|
| 344 |
* Added support and translations for the Algerian Arabic, Igbo, Kyrgyz, Tajik, |
| 345 |
and Turkmen languages. |
| 346 |
|
| 347 |
Management Commands |
| 348 |
~~~~~~~~~~~~~~~~~~~ |
| 349 |
|
| 350 |
* The new :option:`check --database` option allows specifying database aliases |
| 351 |
for running the ``database`` system checks. Previously these checks were |
| 352 |
enabled for all configured :setting:`DATABASES` by passing the ``database`` |
| 353 |
tag to the command. |
| 354 |
|
| 355 |
* The new :option:`migrate --check` option makes the command exit with a |
| 356 |
non-zero status when unapplied migrations are detected. |
| 357 |
|
| 358 |
* The new ``returncode`` argument for |
| 359 |
:attr:`~django.core.management.CommandError` allows customizing the exit |
| 360 |
status for management commands. |
| 361 |
|
| 362 |
* The new :option:`dbshell -- ARGUMENTS <dbshell -->` option allows passing |
| 363 |
extra arguments to the command-line client for the database. |
| 364 |
|
| 365 |
* The :djadmin:`flush` and :djadmin:`sqlflush` commands now include SQL to |
| 366 |
reset sequences on SQLite. |
| 367 |
|
| 368 |
Models |
| 369 |
~~~~~~ |
| 370 |
|
| 371 |
* The new :class:`~django.db.models.functions.ExtractIsoWeekDay` function |
| 372 |
extracts ISO-8601 week days from :class:`~django.db.models.DateField` and |
| 373 |
:class:`~django.db.models.DateTimeField`, and the new :lookup:`iso_week_day` |
| 374 |
lookup allows querying by an ISO-8601 day of week. |
| 375 |
|
| 376 |
* :meth:`.QuerySet.explain` now supports: |
| 377 |
|
| 378 |
* ``TREE`` format on MySQL 8.0.16+, |
| 379 |
* ``analyze`` option on MySQL 8.0.18+ and MariaDB. |
| 380 |
|
| 381 |
* Added :class:`~django.db.models.PositiveBigIntegerField` which acts much like |
| 382 |
a :class:`~django.db.models.PositiveIntegerField` except that it only allows |
| 383 |
values under a certain (database-dependent) limit. Values from ``0`` to |
| 384 |
``9223372036854775807`` are safe in all databases supported by Django. |
| 385 |
|
| 386 |
* The new :class:`~django.db.models.RESTRICT` option for |
| 387 |
:attr:`~django.db.models.ForeignKey.on_delete` argument of ``ForeignKey`` and |
| 388 |
``OneToOneField`` emulates the behavior of the SQL constraint ``ON DELETE |
| 389 |
RESTRICT``. |
| 390 |
|
| 391 |
* ``CheckConstraint.check`` now supports boolean expressions. |
| 392 |
|
| 393 |
* The :meth:`.RelatedManager.add`, :meth:`~.RelatedManager.create`, and |
| 394 |
:meth:`~.RelatedManager.set` methods now accept callables as values in the |
| 395 |
``through_defaults`` argument. |
| 396 |
|
| 397 |
* The new ``is_dst`` parameter of the :meth:`.QuerySet.datetimes` determines |
| 398 |
the treatment of nonexistent and ambiguous datetimes. |
| 399 |
|
| 400 |
* The new :class:`~django.db.models.F` expression ``bitxor()`` method allows |
| 401 |
:ref:`bitwise XOR operation <using-f-expressions-in-filters>`. |
| 402 |
|
| 403 |
* :meth:`.QuerySet.bulk_create` now sets the primary key on objects when using |
| 404 |
MariaDB 10.5+. |
| 405 |
|
| 406 |
* The ``DatabaseOperations.sql_flush()`` method now generates more efficient |
| 407 |
SQL on MySQL by using ``DELETE`` instead of ``TRUNCATE`` statements for |
| 408 |
tables which don't require resetting sequences. |
| 409 |
|
| 410 |
* SQLite functions are now marked as :py:meth:`deterministic |
| 411 |
<sqlite3.Connection.create_function>` on Python 3.8+. This allows using them |
| 412 |
in check constraints and partial indexes. |
| 413 |
|
| 414 |
* The new :attr:`.UniqueConstraint.deferrable` attribute allows creating |
| 415 |
deferrable unique constraints. |
| 416 |
|
| 417 |
Pagination |
| 418 |
~~~~~~~~~~ |
| 419 |
|
| 420 |
* :class:`~django.core.paginator.Paginator` can now be iterated over to yield |
| 421 |
its pages. |
| 422 |
|
| 423 |
Requests and Responses |
| 424 |
~~~~~~~~~~~~~~~~~~~~~~ |
| 425 |
|
| 426 |
* If :setting:`ALLOWED_HOSTS` is empty and ``DEBUG=True``, subdomains of |
| 427 |
localhost are now allowed in the ``Host`` header, e.g. ``static.localhost``. |
| 428 |
|
| 429 |
* :meth:`.HttpResponse.set_cookie` and :meth:`.HttpResponse.set_signed_cookie` |
| 430 |
now allow using ``samesite='None'`` (string) to explicitly state that the |
| 431 |
cookie is sent with all same-site and cross-site requests. |
| 432 |
|
| 433 |
* The new :meth:`.HttpRequest.accepts` method returns whether the request |
| 434 |
accepts the given MIME type according to the ``Accept`` HTTP header. |
| 435 |
|
| 436 |
.. _whats-new-security-3.1: |
| 437 |
|
| 438 |
Security |
| 439 |
~~~~~~~~ |
| 440 |
|
| 441 |
* The :setting:`SECURE_REFERRER_POLICY` setting now defaults to |
| 442 |
``'same-origin'``. With this configured, |
| 443 |
:class:`~django.middleware.security.SecurityMiddleware` sets the |
| 444 |
:ref:`referrer-policy` header to ``same-origin`` on all responses that do not |
| 445 |
already have it. This prevents the ``Referer`` header being sent to other |
| 446 |
origins. If you need the previous behavior, explicitly set |
| 447 |
:setting:`SECURE_REFERRER_POLICY` to ``None``. |
| 448 |
|
| 449 |
* The default algorithm of :class:`django.core.signing.Signer`, |
| 450 |
:meth:`django.core.signing.loads`, and :meth:`django.core.signing.dumps` is |
| 451 |
changed to the SHA-256. Support for signatures made with the old SHA-1 |
| 452 |
algorithm remains until Django 4.0. |
| 453 |
|
| 454 |
Also, the new ``algorithm`` parameter of the |
| 455 |
:class:`~django.core.signing.Signer` allows customizing the hashing |
| 456 |
algorithm. |
| 457 |
|
| 458 |
Templates |
| 459 |
~~~~~~~~~ |
| 460 |
|
| 461 |
* The renamed :ttag:`translate` and :ttag:`blocktranslate` template tags are |
| 462 |
introduced for internationalization in template code. The older :ttag:`trans` |
| 463 |
and :ttag:`blocktrans` template tags aliases continue to work, and will be |
| 464 |
retained for the foreseeable future. |
| 465 |
|
| 466 |
* The :ttag:`include` template tag now accepts iterables of template names. |
| 467 |
|
| 468 |
Tests |
| 469 |
~~~~~ |
| 470 |
|
| 471 |
* :class:`~django.test.SimpleTestCase` now implements the ``debug()`` method to |
| 472 |
allow running a test without collecting the result and catching exceptions. |
| 473 |
This can be used to support running tests under a debugger. |
| 474 |
|
| 475 |
* The new :setting:`MIGRATE <TEST_MIGRATE>` test database setting allows |
| 476 |
disabling of migrations during a test database creation. |
| 477 |
|
| 478 |
* :class:`~django.test.runner.DiscoverRunner` can now discard output for |
| 479 |
passing tests using the :option:`test --buffer` option. |
| 480 |
|
| 481 |
* :class:`~django.test.runner.DiscoverRunner` now skips running the system |
| 482 |
checks on databases not :ref:`referenced by tests<testing-multi-db>`. |
| 483 |
|
| 484 |
* :class:`~django.test.TransactionTestCase` teardown is now faster on MySQL |
| 485 |
due to :djadmin:`flush` command improvements. As a side effect the latter |
| 486 |
doesn't automatically reset sequences on teardown anymore. Enable |
| 487 |
:attr:`.TransactionTestCase.reset_sequences` if your tests require this |
| 488 |
feature. |
| 489 |
|
| 490 |
URLs |
| 491 |
~~~~ |
| 492 |
|
| 493 |
* :ref:`Path converters <registering-custom-path-converters>` can now raise |
| 494 |
``ValueError`` in ``to_url()`` to indicate no match when reversing URLs. |
| 495 |
|
| 496 |
Utilities |
| 497 |
~~~~~~~~~ |
| 498 |
|
| 499 |
* :func:`~django.utils.encoding.filepath_to_uri` now supports |
| 500 |
:class:`pathlib.Path`. |
| 501 |
|
| 502 |
* :func:`~django.utils.dateparse.parse_duration` now supports comma separators |
| 503 |
for decimal fractions in the ISO 8601 format. |
| 504 |
|
| 505 |
* :func:`~django.utils.dateparse.parse_datetime`, |
| 506 |
:func:`~django.utils.dateparse.parse_duration`, and |
| 507 |
:func:`~django.utils.dateparse.parse_time` now support comma separators for |
| 508 |
milliseconds. |
| 509 |
|
| 510 |
Miscellaneous |
| 511 |
~~~~~~~~~~~~~ |
| 512 |
|
| 513 |
* The SQLite backend now supports :class:`pathlib.Path` for the ``NAME`` |
| 514 |
setting. |
| 515 |
|
| 516 |
* The ``settings.py`` generated by the :djadmin:`startproject` command now uses |
| 517 |
:class:`pathlib.Path` instead of :mod:`os.path` for building filesystem |
| 518 |
paths. |
| 519 |
|
| 520 |
* The :setting:`TIME_ZONE <DATABASE-TIME_ZONE>` setting is now allowed on |
| 521 |
databases that support time zones. |
| 522 |
|
| 523 |
.. _backwards-incompatible-3.1: |
| 524 |
|
| 525 |
Backwards incompatible changes in 3.1 |
| 526 |
===================================== |
| 527 |
|
| 528 |
Database backend API |
| 529 |
-------------------- |
| 530 |
|
| 531 |
This section describes changes that may be needed in third-party database |
| 532 |
backends. |
| 533 |
|
| 534 |
* ``DatabaseOperations.fetch_returned_insert_columns()`` now requires an |
| 535 |
additional ``returning_params`` argument. |
| 536 |
|
| 537 |
* ``connection.timezone`` property is now ``'UTC'`` by default, or the |
| 538 |
:setting:`TIME_ZONE <DATABASE-TIME_ZONE>` when :setting:`USE_TZ` is ``True`` |
| 539 |
on databases that support time zones. Previously, it was ``None`` on |
| 540 |
databases that support time zones. |
| 541 |
|
| 542 |
* ``connection._nodb_connection`` property is changed to the |
| 543 |
``connection._nodb_cursor()`` method and now returns a context manager that |
| 544 |
yields a cursor and automatically closes the cursor and connection upon |
| 545 |
exiting the ``with`` statement. |
| 546 |
|
| 547 |
* ``DatabaseClient.runshell()`` now requires an additional ``parameters`` |
| 548 |
argument as a list of extra arguments to pass on to the command-line client. |
| 549 |
|
| 550 |
* The ``sequences`` positional argument of ``DatabaseOperations.sql_flush()`` |
| 551 |
is replaced by the boolean keyword-only argument ``reset_sequences``. If |
| 552 |
``True``, the sequences of the truncated tables will be reset. |
| 553 |
|
| 554 |
* The ``allow_cascade`` argument of ``DatabaseOperations.sql_flush()`` is now a |
| 555 |
keyword-only argument. |
| 556 |
|
| 557 |
* The ``using`` positional argument of |
| 558 |
``DatabaseOperations.execute_sql_flush()`` is removed. The method now uses |
| 559 |
the database of the called instance. |
| 560 |
|
| 561 |
* Third-party database backends must implement support for ``JSONField`` or set |
| 562 |
``DatabaseFeatures.supports_json_field`` to ``False``. If storing primitives |
| 563 |
is not supported, set ``DatabaseFeatures.supports_primitives_in_json_field`` |
| 564 |
to ``False``. If there is a true datatype for JSON, set |
| 565 |
``DatabaseFeatures.has_native_json_field`` to ``True``. If |
| 566 |
:lookup:`jsonfield.contains` and :lookup:`jsonfield.contained_by` are not |
| 567 |
supported, set ``DatabaseFeatures.supports_json_field_contains`` to |
| 568 |
``False``. |
| 569 |
|
| 570 |
* Third party database backends must implement introspection for ``JSONField`` |
| 571 |
or set ``can_introspect_json_field`` to ``False``. |
| 572 |
|
| 573 |
Dropped support for MariaDB 10.1 |
| 574 |
-------------------------------- |
| 575 |
|
| 576 |
Upstream support for MariaDB 10.1 ends in October 2020. Django 3.1 supports |
| 577 |
MariaDB 10.2 and higher. |
| 578 |
|
| 579 |
``contrib.admin`` browser support |
| 580 |
--------------------------------- |
| 581 |
|
| 582 |
The admin no longer supports the legacy Internet Explorer browser. See |
| 583 |
:ref:`the admin FAQ <admin-browser-support>` for details on supported browsers. |
| 584 |
|
| 585 |
:attr:`AbstractUser.first_name <django.contrib.auth.models.User.first_name>` ``max_length`` increased to 150 |
| 586 |
------------------------------------------------------------------------------------------------------------ |
| 587 |
|
| 588 |
A migration for :attr:`django.contrib.auth.models.User.first_name` is included. |
| 589 |
If you have a custom user model inheriting from ``AbstractUser``, you'll need |
| 590 |
to generate and apply a database migration for your user model. |
| 591 |
|
| 592 |
If you want to preserve the 30 character limit for first names, use a custom |
| 593 |
form:: |
| 594 |
|
| 595 |
from django import forms |
| 596 |
from django.contrib.auth.forms import UserChangeForm |
| 597 |
|
| 598 |
|
| 599 |
class MyUserChangeForm(UserChangeForm): |
| 600 |
first_name = forms.CharField(max_length=30, required=False) |
| 601 |
|
| 602 |
If you wish to keep this restriction in the admin when editing users, set |
| 603 |
``UserAdmin.form`` to use this form:: |
| 604 |
|
| 605 |
from django.contrib.auth.admin import UserAdmin |
| 606 |
from django.contrib.auth.models import User |
| 607 |
|
| 608 |
|
| 609 |
class MyUserAdmin(UserAdmin): |
| 610 |
form = MyUserChangeForm |
| 611 |
|
| 612 |
|
| 613 |
admin.site.unregister(User) |
| 614 |
admin.site.register(User, MyUserAdmin) |
| 615 |
|
| 616 |
Miscellaneous |
| 617 |
------------- |
| 618 |
|
| 619 |
* The cache keys used by :ttag:`cache` and generated by |
| 620 |
:func:`~django.core.cache.utils.make_template_fragment_key` are different |
| 621 |
from the keys generated by older versions of Django. After upgrading to |
| 622 |
Django 3.1, the first request to any previously cached template fragment will |
| 623 |
be a cache miss. |
| 624 |
|
| 625 |
* The logic behind the decision to return a redirection fallback or a 204 HTTP |
| 626 |
response from the :func:`~django.views.i18n.set_language` view is now based |
| 627 |
on the ``Accept`` HTTP header instead of the ``X-Requested-With`` HTTP header |
| 628 |
presence. |
| 629 |
|
| 630 |
* The compatibility imports of ``django.core.exceptions.EmptyResultSet`` in |
| 631 |
``django.db.models.query``, ``django.db.models.sql``, and |
| 632 |
``django.db.models.sql.datastructures`` are removed. |
| 633 |
|
| 634 |
* The compatibility import of ``django.core.exceptions.FieldDoesNotExist`` in |
| 635 |
``django.db.models.fields`` is removed. |
| 636 |
|
| 637 |
* The compatibility imports of ``django.forms.utils.pretty_name()`` and |
| 638 |
``django.forms.boundfield.BoundField`` in ``django.forms.forms`` are removed. |
| 639 |
|
| 640 |
* The compatibility imports of ``Context``, ``ContextPopException``, and |
| 641 |
``RequestContext`` in ``django.template.base`` are removed. |
| 642 |
|
| 643 |
* The compatibility import of |
| 644 |
``django.contrib.admin.helpers.ACTION_CHECKBOX_NAME`` in |
| 645 |
``django.contrib.admin`` is removed. |
| 646 |
|
| 647 |
* The :setting:`STATIC_URL` and :setting:`MEDIA_URL` settings set to relative |
| 648 |
paths are now prefixed by the server-provided value of ``SCRIPT_NAME`` (or |
| 649 |
``/`` if not set). This change should not affect settings set to valid URLs |
| 650 |
or absolute paths. |
| 651 |
|
| 652 |
* :class:`~django.middleware.http.ConditionalGetMiddleware` no longer adds the |
| 653 |
``ETag`` header to responses with an empty |
| 654 |
:attr:`~django.http.HttpResponse.content`. |
| 655 |
|
| 656 |
* ``django.utils.decorators.classproperty()`` decorator is made public and |
| 657 |
moved to :class:`django.utils.functional.classproperty()`. |
| 658 |
|
| 659 |
* :tfilter:`floatformat` template filter now outputs (positive) ``0`` for |
| 660 |
negative numbers which round to zero. |
| 661 |
|
| 662 |
* :attr:`Meta.ordering <django.db.models.Options.ordering>` and |
| 663 |
:attr:`Meta.unique_together <django.db.models.Options.unique_together>` |
| 664 |
options on models in ``django.contrib`` modules that were formerly tuples are |
| 665 |
now lists. |
| 666 |
|
| 667 |
* The admin calendar widget now handles two-digit years according to the Open |
| 668 |
Group Specification, i.e. values between 69 and 99 are mapped to the previous |
| 669 |
century, and values between 0 and 68 are mapped to the current century. |
| 670 |
|
| 671 |
* Date-only formats are removed from the default list for |
| 672 |
:setting:`DATETIME_INPUT_FORMATS`. |
| 673 |
|
| 674 |
* The :class:`~django.forms.FileInput` widget no longer renders with the |
| 675 |
``required`` HTML attribute when initial data exists. |
| 676 |
|
| 677 |
* The undocumented ``django.views.debug.ExceptionReporterFilter`` class is |
| 678 |
removed. As per the :ref:`custom-error-reports` documentation, classes to be |
| 679 |
used with :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` need to inherit from |
| 680 |
:class:`django.views.debug.SafeExceptionReporterFilter`. |
| 681 |
|
| 682 |
* The cache timeout set by :func:`~django.views.decorators.cache.cache_page` |
| 683 |
decorator now takes precedence over the ``max-age`` directive from the |
| 684 |
``Cache-Control`` header. |
| 685 |
|
| 686 |
* Providing a non-local remote field in the :attr:`.ForeignKey.to_field` |
| 687 |
argument now raises :class:`~django.core.exceptions.FieldError`. |
| 688 |
|
| 689 |
* :setting:`SECURE_REFERRER_POLICY` now defaults to ``'same-origin'``. See the |
| 690 |
*What's New* :ref:`Security section <whats-new-security-3.1>` above for more |
| 691 |
details. |
| 692 |
|
| 693 |
* :djadmin:`check` management command now runs the ``database`` system checks |
| 694 |
only for database aliases specified using :option:`check --database` option. |
| 695 |
|
| 696 |
* :djadmin:`migrate` management command now runs the ``database`` system checks |
| 697 |
only for a database to migrate. |
| 698 |
|
| 699 |
* The admin CSS classes ``row1`` and ``row2`` are removed in favor of |
| 700 |
``:nth-child(odd)`` and ``:nth-child(even)`` pseudo-classes. |
| 701 |
|
| 702 |
* The :func:`~django.contrib.auth.hashers.make_password` function now requires |
| 703 |
its argument to be a string or bytes. Other types should be explicitly cast |
| 704 |
to one of these. |
| 705 |
|
| 706 |
* The undocumented ``version`` parameter to the |
| 707 |
:class:`~django.contrib.gis.db.models.functions.AsKML` function is removed. |
| 708 |
|
| 709 |
* :ref:`JSON and YAML serializers <serialization-formats>`, used by |
| 710 |
:djadmin:`dumpdata`, now dump all data with Unicode by default. If you need |
| 711 |
the previous behavior, pass ``ensure_ascii=True`` to JSON serializer, or |
| 712 |
``allow_unicode=False`` to YAML serializer. |
| 713 |
|
| 714 |
* The auto-reloader no longer monitors changes in built-in Django translation |
| 715 |
files. |
| 716 |
|
| 717 |
* The minimum supported version of ``mysqlclient`` is increased from 1.3.13 to |
| 718 |
1.4.0. |
| 719 |
|
| 720 |
* The undocumented ``django.contrib.postgres.forms.InvalidJSONInput`` and |
| 721 |
``django.contrib.postgres.forms.JSONString`` are moved to |
| 722 |
``django.forms.fields``. |
| 723 |
|
| 724 |
* The undocumented ``django.contrib.postgres.fields.jsonb.JsonAdapter`` class |
| 725 |
is removed. |
| 726 |
|
| 727 |
* The :ttag:`{% localize off %} <localize>` tag and :tfilter:`unlocalize` |
| 728 |
filter no longer respect :setting:`DECIMAL_SEPARATOR` setting. |
| 729 |
|
| 730 |
* The minimum supported version of ``asgiref`` is increased from 3.2 to |
| 731 |
3.2.10. |
| 732 |
|
| 733 |
* The :doc:`Media </topics/forms/media>` class now renders ``<script>`` tags |
| 734 |
without the ``type`` attribute to follow `WHATWG recommendations |
| 735 |
<https://html.spec.whatwg.org/multipage/scripting.html#the-script-element>`_. |
| 736 |
|
| 737 |
* :class:`~django.forms.ModelChoiceIterator`, used by |
| 738 |
:class:`~django.forms.ModelChoiceField` and |
| 739 |
:class:`~django.forms.ModelMultipleChoiceField`, now yields 2-tuple choices |
| 740 |
containing :class:`~django.forms.ModelChoiceIteratorValue` instances as the |
| 741 |
first ``value`` element in each choice. In most cases this proxies |
| 742 |
transparently, but if you need the ``field`` value itself, use the |
| 743 |
:attr:`.ModelChoiceIteratorValue.value` attribute instead. |
| 744 |
|
| 745 |
.. _deprecated-features-3.1: |
| 746 |
|
| 747 |
Features deprecated in 3.1 |
| 748 |
========================== |
| 749 |
|
| 750 |
.. _deprecated-jsonfield: |
| 751 |
|
| 752 |
PostgreSQL ``JSONField`` |
| 753 |
------------------------ |
| 754 |
|
| 755 |
``django.contrib.postgres.fields.JSONField`` and |
| 756 |
``django.contrib.postgres.forms.JSONField`` are deprecated in favor of |
| 757 |
:class:`.models.JSONField` and |
| 758 |
:class:`forms.JSONField <django.forms.JSONField>`. |
| 759 |
|
| 760 |
The undocumented ``django.contrib.postgres.fields.jsonb.KeyTransform`` and |
| 761 |
``django.contrib.postgres.fields.jsonb.KeyTextTransform`` are also deprecated |
| 762 |
in favor of the transforms in ``django.db.models.fields.json``. |
| 763 |
|
| 764 |
The new ``JSONField``\s, ``KeyTransform``, and ``KeyTextTransform`` can be used |
| 765 |
on all supported database backends. |
| 766 |
|
| 767 |
Miscellaneous |
| 768 |
------------- |
| 769 |
|
| 770 |
* ``PASSWORD_RESET_TIMEOUT_DAYS`` setting is deprecated in favor of |
| 771 |
:setting:`PASSWORD_RESET_TIMEOUT`. |
| 772 |
|
| 773 |
* The undocumented usage of the :lookup:`isnull` lookup with non-boolean values |
| 774 |
as the right-hand side is deprecated, use ``True`` or ``False`` instead. |
| 775 |
|
| 776 |
* The barely documented ``django.db.models.query_utils.InvalidQuery`` exception |
| 777 |
class is deprecated in favor of |
| 778 |
:class:`~django.core.exceptions.FieldDoesNotExist` and |
| 779 |
:class:`~django.core.exceptions.FieldError`. |
| 780 |
|
| 781 |
* The ``django-admin.py`` entry point is deprecated in favor of |
| 782 |
``django-admin``. |
| 783 |
|
| 784 |
* The ``HttpRequest.is_ajax()`` method is deprecated as it relied on a |
| 785 |
jQuery-specific way of signifying AJAX calls, while current usage tends to |
| 786 |
use the JavaScript `Fetch API |
| 787 |
<https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API>`_. Depending on |
| 788 |
your use case, you can either write your own AJAX detection method, or use |
| 789 |
the new :meth:`.HttpRequest.accepts` method if your code depends on the |
| 790 |
client ``Accept`` HTTP header. |
| 791 |
|
| 792 |
If you are writing your own AJAX detection method, ``request.is_ajax()`` can |
| 793 |
be reproduced exactly as |
| 794 |
``request.headers.get('x-requested-with') == 'XMLHttpRequest'``. |
| 795 |
|
| 796 |
* Passing ``None`` as the first argument to |
| 797 |
``django.utils.deprecation.MiddlewareMixin.__init__()`` is deprecated. |
| 798 |
|
| 799 |
* The encoding format of cookies values used by |
| 800 |
:class:`~django.contrib.messages.storage.cookie.CookieStorage` is different |
| 801 |
from the format generated by older versions of Django. Support for the old |
| 802 |
format remains until Django 4.0. |
| 803 |
|
| 804 |
* The encoding format of sessions is different from the format generated by |
| 805 |
older versions of Django. Support for the old format remains until Django |
| 806 |
4.0. |
| 807 |
|
| 808 |
* The purely documentational ``providing_args`` argument for |
| 809 |
:class:`~django.dispatch.Signal` is deprecated. If you rely on this |
| 810 |
argument as documentation, you can move the text to a code comment or |
| 811 |
docstring. |
| 812 |
|
| 813 |
* Calling ``django.utils.crypto.get_random_string()`` without a ``length`` |
| 814 |
argument is deprecated. |
| 815 |
|
| 816 |
* The ``list`` message for :class:`~django.forms.ModelMultipleChoiceField` is |
| 817 |
deprecated in favor of ``invalid_list``. |
| 818 |
|
| 819 |
* Passing raw column aliases to :meth:`.QuerySet.order_by` is deprecated. The |
| 820 |
same result can be achieved by passing aliases in a |
| 821 |
:class:`~django.db.models.expressions.RawSQL` instead beforehand. |
| 822 |
|
| 823 |
* The ``NullBooleanField`` model field is deprecated in favor of |
| 824 |
``BooleanField(null=True, blank=True)``. |
| 825 |
|
| 826 |
* ``django.conf.urls.url()`` alias of :func:`django.urls.re_path` is |
| 827 |
deprecated. |
| 828 |
|
| 829 |
* The ``{% ifequal %}`` and ``{% ifnotequal %}`` template tags are deprecated |
| 830 |
in favor of :ttag:`{% if %}<if>`. ``{% if %}`` covers all use cases, but if |
| 831 |
you need to continue using these tags, they can be extracted from Django to a |
| 832 |
module and included as a built-in tag in the :class:`'builtins' |
| 833 |
<django.template.backends.django.DjangoTemplates>` option in |
| 834 |
:setting:`OPTIONS <TEMPLATES-OPTIONS>`. |
| 835 |
|
| 836 |
* ``DEFAULT_HASHING_ALGORITHM`` transitional setting is deprecated. |
| 837 |
|
| 838 |
.. _removed-features-3.1: |
| 839 |
|
| 840 |
Features removed in 3.1 |
| 841 |
======================= |
| 842 |
|
| 843 |
These features have reached the end of their deprecation cycle and are removed |
| 844 |
in Django 3.1. |
| 845 |
|
| 846 |
See :ref:`deprecated-features-2.2` for details on these changes, including how |
| 847 |
to remove usage of these features. |
| 848 |
|
| 849 |
* ``django.utils.timezone.FixedOffset`` is removed. |
| 850 |
|
| 851 |
* ``django.core.paginator.QuerySetPaginator`` is removed. |
| 852 |
|
| 853 |
* A model's ``Meta.ordering`` doesn't affect ``GROUP BY`` queries. |
| 854 |
|
| 855 |
* ``django.contrib.postgres.fields.FloatRangeField`` and |
| 856 |
``django.contrib.postgres.forms.FloatRangeField`` are removed. |
| 857 |
|
| 858 |
* The ``FILE_CHARSET`` setting is removed. |
| 859 |
|
| 860 |
* ``django.contrib.staticfiles.storage.CachedStaticFilesStorage`` is removed. |
| 861 |
|
| 862 |
* The ``RemoteUserBackend.configure_user()`` method requires ``request`` as the |
| 863 |
first positional argument. |
| 864 |
|
| 865 |
* Support for ``SimpleTestCase.allow_database_queries`` and |
| 866 |
``TransactionTestCase.multi_db`` is removed. |