3.1.txt 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699
  1. ============================================
  2. Django 3.1 release notes - UNDER DEVELOPMENT
  3. ============================================
  4. *Expected August 2020*
  5. Welcome to Django 3.1!
  6. These release notes cover the :ref:`new features <whats-new-3.1>`, as well as
  7. some :ref:`backwards incompatible changes <backwards-incompatible-3.1>` you'll
  8. want to be aware of when upgrading from Django 3.0 or earlier. We've
  9. :ref:`dropped some features<removed-features-3.1>` that have reached the end of
  10. their deprecation cycle, and we've :ref:`begun the deprecation process for
  11. some features <deprecated-features-3.1>`.
  12. See the :doc:`/howto/upgrade-version` guide if you're updating an existing
  13. project.
  14. Python compatibility
  15. ====================
  16. Django 3.1 supports Python 3.6, 3.7, and 3.8. We **highly recommend** and only
  17. officially support the latest release of each series.
  18. .. _whats-new-3.1:
  19. What's new in Django 3.1
  20. ========================
  21. Asynchronous views and middleware support
  22. -----------------------------------------
  23. Django now supports a fully asynchronous request path, including:
  24. * :ref:`Asynchronous views <async-views>`
  25. * :ref:`Asynchronous middleware <async-middleware>`
  26. * :ref:`Asynchronous tests and test client <async-tests>`
  27. To get started with async views, you need to declare a view using
  28. ``async def``::
  29. async def my_view(request):
  30. await asyncio.sleep(0.5)
  31. return HttpResponse('Hello, async world!')
  32. All asynchronous features are supported whether you are running under WSGI or
  33. ASGI mode. However, there will be performance penalties using async code in
  34. WSGI mode. You can read more about the specifics in :doc:`/topics/async`
  35. documentation.
  36. You are free to mix async and sync views, middleware, and tests as much as you
  37. want. Django will ensure that you always end up with the right execution
  38. context. We expect most projects will keep the majority of their views
  39. synchronous, and only have a select few running in async mode - but it is
  40. entirely your choice.
  41. Django's ORM, cache layer, and other pieces of code that do long-running
  42. network calls do not yet support async access. We expect to add support for
  43. them in upcoming releases. Async views are ideal, however, if you are doing a
  44. lot of API or HTTP calls inside your view, you can now natively do all those
  45. HTTP calls in parallel to considerably speed up your view's execution.
  46. Asynchronous support should be entirely backwards-compatible and we have tried
  47. to ensure that it has no speed regressions for your existing, synchronous code.
  48. It should have no noticeable effect on any existing Django projects.
  49. Minor features
  50. --------------
  51. :mod:`django.contrib.admin`
  52. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  53. * The new ``django.contrib.admin.EmptyFieldListFilter`` for
  54. :attr:`.ModelAdmin.list_filter` allows filtering on empty values (empty
  55. strings and nulls) in the admin changelist view.
  56. * Filters in the right sidebar of the admin changelist view now contains a link
  57. to clear all filters.
  58. :mod:`django.contrib.admindocs`
  59. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  60. * ...
  61. :mod:`django.contrib.auth`
  62. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  63. * The default iteration count for the PBKDF2 password hasher is increased from
  64. 180,000 to 216,000.
  65. * Added the :setting:`PASSWORD_RESET_TIMEOUT` setting to define the minimum
  66. number of seconds a password reset link is valid for. This is encouraged
  67. instead of deprecated ``PASSWORD_RESET_TIMEOUT_DAYS``, which will be removed
  68. in Django 4.0.
  69. * The password reset mechanism now uses the SHA-256 hashing algorithm. Support
  70. for tokens that use the old hashing algorithm remains until Django 4.0.
  71. :mod:`django.contrib.contenttypes`
  72. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  73. * The new :option:`remove_stale_contenttypes --include-stale-apps` option
  74. allows removing stale content types from previously installed apps that have
  75. been removed from :setting:`INSTALLED_APPS`.
  76. :mod:`django.contrib.gis`
  77. ~~~~~~~~~~~~~~~~~~~~~~~~~
  78. * :lookup:`relate` lookup is now supported on MariaDB.
  79. * Added the :attr:`.LinearRing.is_counterclockwise` property.
  80. * :class:`~django.contrib.gis.db.models.functions.AsGeoJSON` is now supported
  81. on Oracle.
  82. * Added the :class:`~django.contrib.gis.db.models.functions.AsWKB` and
  83. :class:`~django.contrib.gis.db.models.functions.AsWKT` functions.
  84. :mod:`django.contrib.humanize`
  85. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  86. * :tfilter:`intword` template filter now supports negative integers.
  87. :mod:`django.contrib.messages`
  88. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  89. * ...
  90. :mod:`django.contrib.postgres`
  91. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  92. * The new :class:`~django.contrib.postgres.indexes.BloomIndex` class allows
  93. creating ``bloom`` indexes in the database. The new
  94. :class:`~django.contrib.postgres.operations.BloomExtension` migration
  95. operation installs the ``bloom`` extension to add support for this index.
  96. * :meth:`~django.db.models.Model.get_FOO_display` now supports
  97. :class:`~django.contrib.postgres.fields.ArrayField` and
  98. :class:`~django.contrib.postgres.fields.RangeField`.
  99. * The new :lookup:`rangefield.lower_inc`, :lookup:`rangefield.lower_inf`,
  100. :lookup:`rangefield.upper_inc`, and :lookup:`rangefield.upper_inf` allows
  101. querying :class:`~django.contrib.postgres.fields.RangeField` by a bound type.
  102. * :lookup:`rangefield.contained_by` now supports
  103. :class:`~django.db.models.SmallAutoField`,
  104. :class:`~django.db.models.AutoField`,
  105. :class:`~django.db.models.BigAutoField`,
  106. :class:`~django.db.models.SmallIntegerField`, and
  107. :class:`~django.db.models.DecimalField`.
  108. * :class:`~django.contrib.postgres.search.SearchQuery` now supports
  109. ``'websearch'`` search type on PostgreSQL 11+.
  110. * :class:`SearchQuery.value <django.contrib.postgres.search.SearchQuery>` now
  111. supports query expressions.
  112. * The new :class:`~django.contrib.postgres.search.SearchHeadline` class allows
  113. highlighting search results.
  114. * :lookup:`search` lookup now supports query expressions.
  115. * The new ``cover_density`` parameter of
  116. :class:`~django.contrib.postgres.search.SearchRank` allows ranking by cover
  117. density.
  118. * The new ``normalization`` parameter of
  119. :class:`~django.contrib.postgres.search.SearchRank` allows rank
  120. normalization.
  121. :mod:`django.contrib.redirects`
  122. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  123. * ...
  124. :mod:`django.contrib.sessions`
  125. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  126. * The :setting:`SESSION_COOKIE_SAMESITE` setting now allows ``'None'`` (string)
  127. value to explicitly state that the cookie is sent with all same-site and
  128. cross-site requests.
  129. :mod:`django.contrib.sitemaps`
  130. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  131. * ...
  132. :mod:`django.contrib.sites`
  133. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  134. * ...
  135. :mod:`django.contrib.staticfiles`
  136. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  137. * The :setting:`STATICFILES_DIRS` setting now supports :class:`pathlib.Path`.
  138. :mod:`django.contrib.syndication`
  139. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  140. * ...
  141. Cache
  142. ~~~~~
  143. * The :func:`~django.views.decorators.cache.cache_control` decorator and
  144. :func:`~django.utils.cache.patch_cache_control` method now support multiple
  145. field names in the ``no-cache`` directive for the ``Cache-Control`` header,
  146. according to :rfc:`7234#section-5.2.2.2`.
  147. * :meth:`~django.core.caches.cache.delete` now returns ``True`` if the key was
  148. successfully deleted, ``False`` otherwise.
  149. CSRF
  150. ~~~~
  151. * The :setting:`CSRF_COOKIE_SAMESITE` setting now allows ``'None'`` (string)
  152. value to explicitly state that the cookie is sent with all same-site and
  153. cross-site requests.
  154. Email
  155. ~~~~~
  156. * The :setting:`EMAIL_FILE_PATH` setting, used by the :ref:`file email backend
  157. <topic-email-file-backend>`, now supports :class:`pathlib.Path`.
  158. Error Reporting
  159. ~~~~~~~~~~~~~~~
  160. * :class:`django.views.debug.SafeExceptionReporterFilter` now filters sensitive
  161. values from ``request.META`` in exception reports.
  162. * The new :attr:`.SafeExceptionReporterFilter.cleansed_substitute` and
  163. :attr:`.SafeExceptionReporterFilter.hidden_settings` attributes allow
  164. customization of sensitive settings and ``request.META`` filtering in
  165. exception reports.
  166. * The technical 404 debug view now respects
  167. :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` when applying settings
  168. filtering.
  169. * The new :setting:`DEFAULT_EXCEPTION_REPORTER` allows providing a
  170. :class:`django.views.debug.ExceptionReporter` subclass to customize exception
  171. report generation. See :ref:`custom-error-reports` for details.
  172. File Storage
  173. ~~~~~~~~~~~~
  174. * ``FileSystemStorage.save()`` method now supports :class:`pathlib.Path`.
  175. File Uploads
  176. ~~~~~~~~~~~~
  177. * ...
  178. Forms
  179. ~~~~~
  180. * :class:`~django.forms.ModelChoiceIterator`, used by
  181. :class:`~django.forms.ModelChoiceField` and
  182. :class:`~django.forms.ModelMultipleChoiceField`, now uses
  183. :class:`~django.forms.ModelChoiceIteratorValue` that can be used by widgets
  184. to access model instances. See :ref:`iterating-relationship-choices` for
  185. details.
  186. * :class:`django.forms.DateTimeField` now accepts dates in a subset of ISO 8601
  187. datetime formats, including optional timezone (e.g. ``2019-10-10T06:47``,
  188. ``2019-10-10T06:47:23+04:00``, or ``2019-10-10T06:47:23Z``). Additionally, it
  189. now uses ``DATE_INPUT_FORMATS`` in addition to ``DATETIME_INPUT_FORMATS``
  190. when converting a field input to a ``datetime`` value.
  191. * :attr:`.MultiWidget.widgets` now accepts a dictionary which allows
  192. customizing subwidget ``name`` attributes.
  193. Generic Views
  194. ~~~~~~~~~~~~~
  195. * ...
  196. Internationalization
  197. ~~~~~~~~~~~~~~~~~~~~
  198. * The :setting:`LANGUAGE_COOKIE_SAMESITE` setting now allows ``'None'``
  199. (string) value to explicitly state that the cookie is sent with all same-site
  200. and cross-site requests.
  201. * Added support and translations for the Algerian Arabic language.
  202. Logging
  203. ~~~~~~~
  204. * ...
  205. Management Commands
  206. ~~~~~~~~~~~~~~~~~~~
  207. * The new :option:`check --database` option allows specifying database aliases
  208. for running the ``database`` system checks. Previously these checks were
  209. enabled for all configured :setting:`DATABASES` by passing the ``database``
  210. tag to the command.
  211. * The new :option:`migrate --check` option makes the command exit with a
  212. non-zero status when unapplied migrations are detected.
  213. Migrations
  214. ~~~~~~~~~~
  215. * Migrations are now loaded also from directories without ``__init__.py``
  216. files.
  217. Models
  218. ~~~~~~
  219. * The new :class:`~django.db.models.functions.ExtractIsoWeekDay` function
  220. extracts ISO-8601 week days from :class:`~django.db.models.DateField` and
  221. :class:`~django.db.models.DateTimeField`, and the new :lookup:`iso_week_day`
  222. lookup allows querying by an ISO-8601 day of week.
  223. * :meth:`.QuerySet.explain` now supports:
  224. * ``TREE`` format on MySQL 8.0.16+,
  225. * ``analyze`` option on MySQL 8.0.18+ and MariaDB.
  226. * Added :class:`~django.db.models.PositiveBigIntegerField` which acts much like
  227. a :class:`~django.db.models.PositiveIntegerField` except that it only allows
  228. values under a certain (database-dependent) limit. Values from ``0`` to
  229. ``9223372036854775807`` are safe in all databases supported by Django.
  230. * The new :class:`~django.db.models.RESTRICT` option for
  231. :attr:`~django.db.models.ForeignKey.on_delete` argument of ``ForeignKey`` and
  232. ``OneToOneField`` emulates the behavior of the SQL constraint ``ON DELETE
  233. RESTRICT``.
  234. * :attr:`.CheckConstraint.check` now supports boolean expressions.
  235. * The :meth:`.RelatedManager.add`, :meth:`~.RelatedManager.create`, and
  236. :meth:`~.RelatedManager.set` methods now accept callables as values in the
  237. ``through_defaults`` argument.
  238. * The new ``is_dst`` parameter of the :meth:`.QuerySet.datetimes` determines
  239. the treatment of nonexistent and ambiguous datetimes.
  240. * The new :class:`~django.db.models.F` expression ``bitxor()`` method allows
  241. :ref:`bitwise XOR operation <using-f-expressions-in-filters>`.
  242. * :meth:`.QuerySet.bulk_create` now sets the primary key on objects when using
  243. MariaDB 10.5+.
  244. Pagination
  245. ~~~~~~~~~~
  246. * :class:`~django.core.paginator.Paginator` can now be iterated over to yield
  247. its pages.
  248. Requests and Responses
  249. ~~~~~~~~~~~~~~~~~~~~~~
  250. * If :setting:`ALLOWED_HOSTS` is empty and ``DEBUG=True``, subdomains of
  251. localhost are now allowed in the ``Host`` header, e.g. ``static.localhost``.
  252. * :meth:`.HttpResponse.set_cookie` and :meth:`.HttpResponse.set_signed_cookie`
  253. now allow using ``samesite='None'`` (string) to explicitly state that the
  254. cookie is sent with all same-site and cross-site requests.
  255. * The new :meth:`.HttpRequest.accepts` method returns whether the request
  256. accepts the given MIME type according to the ``Accept`` HTTP header.
  257. .. _whats-new-security-3.1:
  258. Security
  259. ~~~~~~~~
  260. * The :setting:`SECURE_REFERRER_POLICY` setting now defaults to
  261. ``'same-origin'``. With this configured,
  262. :class:`~django.middleware.security.SecurityMiddleware` sets the
  263. :ref:`referrer-policy` header to ``same-origin`` on all responses that do not
  264. already have it. This prevents the ``Referer`` header being sent to other
  265. origins. If you need the previous behavior, explicitly set
  266. :setting:`SECURE_REFERRER_POLICY` to ``None``.
  267. Serialization
  268. ~~~~~~~~~~~~~
  269. * ...
  270. Signals
  271. ~~~~~~~
  272. * ...
  273. Templates
  274. ~~~~~~~~~
  275. * The renamed :ttag:`translate` and :ttag:`blocktranslate` template tags are
  276. introduced for internationalization in template code. The older :ttag:`trans`
  277. and :ttag:`blocktrans` template tags aliases continue to work, and will be
  278. retained for the foreseeable future.
  279. * The :ttag:`include` template tag now accepts iterables of template names.
  280. Tests
  281. ~~~~~
  282. * :class:`~django.test.SimpleTestCase` now implements the ``debug()`` method to
  283. allow running a test without collecting the result and catching exceptions.
  284. This can be used to support running tests under a debugger.
  285. * The new :setting:`MIGRATE <TEST_MIGRATE>` test database setting allows
  286. disabling of migrations during a test database creation.
  287. * Django test runner now supports a :option:`test --buffer` option to discard
  288. output for passing tests.
  289. * :class:`~django.test.runner.DiscoverRunner` now skips running the system
  290. checks on databases not :ref:`referenced by tests<testing-multi-db>`.
  291. URLs
  292. ~~~~
  293. * :ref:`Path converters <registering-custom-path-converters>` can now raise
  294. ``ValueError`` in ``to_url()`` to indicate no match when reversing URLs.
  295. Utilities
  296. ~~~~~~~~~
  297. * :func:`~django.utils.encoding.filepath_to_uri` now supports
  298. :class:`pathlib.Path`.
  299. * :func:`~django.utils.dateparse.parse_duration` now supports comma separators
  300. for decimal fractions in the ISO 8601 format.
  301. * :func:`~django.utils.dateparse.parse_datetime`,
  302. :func:`~django.utils.dateparse.parse_duration`, and
  303. :func:`~django.utils.dateparse.parse_time` now support comma separators for
  304. milliseconds.
  305. Validators
  306. ~~~~~~~~~~
  307. * ...
  308. Miscellaneous
  309. ~~~~~~~~~~~~~
  310. * The SQLite backend now supports :class:`pathlib.Path` for the ``NAME``
  311. setting.
  312. * The ``settings.py`` generated by the :djadmin:`startproject` command now uses
  313. :class:`pathlib.Path` instead of :mod:`os.path` for building filesystem
  314. paths.
  315. * The :setting:`TIME_ZONE <DATABASE-TIME_ZONE>` setting is now allowed on
  316. databases that support time zones.
  317. .. _backwards-incompatible-3.1:
  318. Backwards incompatible changes in 3.1
  319. =====================================
  320. Database backend API
  321. --------------------
  322. This section describes changes that may be needed in third-party database
  323. backends.
  324. * ``DatabaseOperations.fetch_returned_insert_columns()`` now requires an
  325. additional ``returning_params`` argument.
  326. * ``connection.timezone`` property is now ``'UTC'`` by default, or the
  327. :setting:`TIME_ZONE <DATABASE-TIME_ZONE>` when :setting:`USE_TZ` is ``True``
  328. on databases that support time zones. Previously, it was ``None`` on
  329. databases that support time zones.
  330. * ``connection._nodb_connection`` property is changed to the
  331. ``connection._nodb_cursor()`` method and now returns a context manager that
  332. yields a cursor and automatically closes the cursor and connection upon
  333. exiting the ``with`` statement.
  334. Dropped support for MariaDB 10.1
  335. --------------------------------
  336. Upstream support for MariaDB 10.1 ends in October 2020. Django 3.1 supports
  337. MariaDB 10.2 and higher.
  338. ``contrib.admin`` browser support
  339. ---------------------------------
  340. The admin no longer supports the legacy Internet Explorer browser. See
  341. :ref:`the admin FAQ <admin-browser-support>` for details on supported browsers.
  342. :attr:`AbstractUser.first_name <django.contrib.auth.models.User.first_name>` ``max_length`` increased to 150
  343. ------------------------------------------------------------------------------------------------------------
  344. A migration for :attr:`django.contrib.auth.models.User.first_name` is included.
  345. If you have a custom user model inheriting from ``AbstractUser``, you'll need
  346. to generate and apply a database migration for your user model.
  347. If you want to preserve the 30 character limit for first names, use a custom
  348. form::
  349. from django import forms
  350. from django.contrib.auth.forms import UserChangeForm
  351. class MyUserChangeForm(UserChangeForm):
  352. first_name = forms.CharField(max_length=30, required=False)
  353. If you wish to keep this restriction in the admin when editing users, set
  354. ``UserAdmin.form`` to use this form::
  355. from django.contrib.auth.admin import UserAdmin
  356. from django.contrib.auth.models import User
  357. class MyUserAdmin(UserAdmin):
  358. form = MyUserChangeForm
  359. admin.site.unregister(User)
  360. admin.site.register(User, MyUserAdmin)
  361. Miscellaneous
  362. -------------
  363. * The cache keys used by :ttag:`cache` and generated by
  364. :func:`~django.core.cache.utils.make_template_fragment_key` are different
  365. from the keys generated by older versions of Django. After upgrading to
  366. Django 3.1, the first request to any previously cached template fragment will
  367. be a cache miss.
  368. * The logic behind the decision to return a redirection fallback or a 204 HTTP
  369. response from the :func:`~django.views.i18n.set_language` view is now based
  370. on the ``Accept`` HTTP header instead of the ``X-Requested-With`` HTTP header
  371. presence.
  372. * The compatibility imports of ``django.core.exceptions.EmptyResultSet`` in
  373. ``django.db.models.query``, ``django.db.models.sql``, and
  374. ``django.db.models.sql.datastructures`` are removed.
  375. * The compatibility import of ``django.core.exceptions.FieldDoesNotExist`` in
  376. ``django.db.models.fields`` is removed.
  377. * The compatibility imports of ``django.forms.utils.pretty_name()`` and
  378. ``django.forms.boundfield.BoundField`` in ``django.forms.forms`` are removed.
  379. * The compatibility imports of ``Context``, ``ContextPopException``, and
  380. ``RequestContext`` in ``django.template.base`` are removed.
  381. * The compatibility import of
  382. ``django.contrib.admin.helpers.ACTION_CHECKBOX_NAME`` in
  383. ``django.contrib.admin`` is removed.
  384. * The :setting:`STATIC_URL` and :setting:`MEDIA_URL` settings set to relative
  385. paths are now prefixed by the server-provided value of ``SCRIPT_NAME`` (or
  386. ``/`` if not set). This change should not affect settings set to valid URLs
  387. or absolute paths.
  388. * :class:`~django.middleware.http.ConditionalGetMiddleware` no longer adds the
  389. ``ETag`` header to responses with an empty
  390. :attr:`~django.http.HttpResponse.content`.
  391. * ``django.utils.decorators.classproperty()`` decorator is made public and
  392. moved to :class:`django.utils.functional.classproperty()`.
  393. * :tfilter:`floatformat` template filter now outputs (positive) ``0`` for
  394. negative numbers which round to zero.
  395. * :attr:`Meta.ordering <django.db.models.Options.ordering>` and
  396. :attr:`Meta.unique_together <django.db.models.Options.unique_together>`
  397. options on models in ``django.contrib`` modules that were formerly tuples are
  398. now lists.
  399. * The admin calendar widget now handles two-digit years according to the Open
  400. Group Specification, i.e. values between 69 and 99 are mapped to the previous
  401. century, and values between 0 and 68 are mapped to the current century.
  402. * Date-only formats are removed from the default list for
  403. :setting:`DATETIME_INPUT_FORMATS`.
  404. * The :class:`~django.forms.FileInput` widget no longer renders with the
  405. ``required`` HTML attribute when initial data exists.
  406. * The undocumented ``django.views.debug.ExceptionReporterFilter`` class is
  407. removed. As per the :ref:`custom-error-reports` documentation, classes to be
  408. used with :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` needs to inherit from
  409. :class:`django.views.debug.SafeExceptionReporterFilter`.
  410. * The cache timeout set by :func:`~django.views.decorators.cache.cache_page`
  411. decorator now takes precedence over the ``max-age`` directive from the
  412. ``Cache-Control`` header.
  413. * Providing a non-local remote field in the :attr:`.ForeignKey.to_field`
  414. argument now raises :class:`~django.core.exceptions.FieldError`.
  415. * :setting:`SECURE_REFERRER_POLICY` now defaults to ``'same-origin'``. See the
  416. *What's New* :ref:`Security section <whats-new-security-3.1>` above for more
  417. details.
  418. * :djadmin:`check` management command now runs the ``database`` system checks
  419. only for database aliases specified using :option:`check --database` option.
  420. * :djadmin:`migrate` management command now runs the ``database`` system checks
  421. only for a database to migrate.
  422. * The admin CSS classes ``row1`` and ``row2`` are removed in favor of
  423. ``:nth-child(odd)`` and ``:nth-child(even)`` pseudo-classes.
  424. * The :func:`~django.contrib.auth.hashers.make_password` now requires its
  425. argument to be a string or bytes. Other types should be explicitly cast to
  426. one of these.
  427. .. _deprecated-features-3.1:
  428. Features deprecated in 3.1
  429. ==========================
  430. Miscellaneous
  431. -------------
  432. * ``PASSWORD_RESET_TIMEOUT_DAYS`` setting is deprecated in favor of
  433. :setting:`PASSWORD_RESET_TIMEOUT`.
  434. * The undocumented usage of the :lookup:`isnull` lookup with non-boolean values
  435. as the right-hand side is deprecated, use ``True`` or ``False`` instead.
  436. * The barely documented ``django.db.models.query_utils.InvalidQuery`` exception
  437. class is deprecated in favor of
  438. :class:`~django.core.exceptions.FieldDoesNotExist` and
  439. :class:`~django.core.exceptions.FieldError`.
  440. * The ``django-admin.py`` entry point is deprecated in favor of
  441. ``django-admin``.
  442. * The ``HttpRequest.is_ajax()`` method is deprecated as it relied on a
  443. jQuery-specific way of signifying AJAX calls, while current usage tends to
  444. use the JavaScript `Fetch API
  445. <https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API>`_. Depending on
  446. your use case, you can either write your own AJAX detection method, or use
  447. the new :meth:`.HttpRequest.accepts` method if your code depends on the
  448. client ``Accept`` HTTP header.
  449. If you are writing your own AJAX detection method, ``request.is_ajax()`` can
  450. be reproduced exactly as
  451. ``request.headers.get('x-requested-with') == 'XMLHttpRequest'``.
  452. * Passing ``None`` as the first argument to
  453. ``django.utils.deprecation.MiddlewareMixin.__init__()`` is deprecated.
  454. * The encoding format of cookies values used by
  455. :class:`~django.contrib.messages.storage.cookie.CookieStorage` is different
  456. from the format generated by older versions of Django. Support for the old
  457. format remains until Django 4.0.
  458. * The encoding format of sessions is different from the format generated by
  459. older versions of Django. Support for the old format remains until Django
  460. 4.0.
  461. * The purely documentational ``providing_args`` argument for
  462. :class:`~django.dispatch.Signal` is deprecated. If you rely on this
  463. argument as documentation, you can move the text to a code comment or
  464. docstring.
  465. * Calling ``django.utils.crypto.get_random_string()`` without a ``length``
  466. argument is deprecated.
  467. * The ``list`` message for :class:`~django.forms.ModelMultipleChoiceField` is
  468. deprecated in favor of ``invalid_list``.
  469. * The passing of URL kwargs directly to the context by
  470. :class:`~django.views.generic.base.TemplateView` is deprecated. Reference
  471. them in the template with ``view.kwargs`` instead.
  472. .. _removed-features-3.1:
  473. Features removed in 3.1
  474. =======================
  475. These features have reached the end of their deprecation cycle and are removed
  476. in Django 3.1.
  477. See :ref:`deprecated-features-2.2` for details on these changes, including how
  478. to remove usage of these features.
  479. * ``django.utils.timezone.FixedOffset`` is removed.
  480. * ``django.core.paginator.QuerySetPaginator`` is removed.
  481. * A model's ``Meta.ordering`` doesn't affect ``GROUP BY`` queries.
  482. * ``django.contrib.postgres.fields.FloatRangeField`` and
  483. ``django.contrib.postgres.forms.FloatRangeField`` are removed.
  484. * The ``FILE_CHARSET`` setting is removed.
  485. * ``django.contrib.staticfiles.storage.CachedStaticFilesStorage`` is removed.
  486. * The ``RemoteUserBackend.configure_user()`` method requires ``request`` as the
  487. first positional argument.
  488. * Support for ``SimpleTestCase.allow_database_queries`` and
  489. ``TransactionTestCase.multi_db`` is removed.