3.1.txt 31 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824
  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. JSONField for all supported database backends
  50. ---------------------------------------------
  51. Django now includes :class:`.models.JSONField` and
  52. :class:`forms.JSONField <django.forms.JSONField>` that can be used on all
  53. supported database backends. Both fields support the use of custom JSON
  54. encoders and decoders. The model field supports the introspection,
  55. :ref:`lookups, and transforms <querying-jsonfield>` that were previously
  56. PostgreSQL-only::
  57. from django.db import models
  58. class ContactInfo(models.Model):
  59. data = models.JSONField()
  60. ContactInfo.objects.create(data={
  61. 'name': 'John',
  62. 'cities': ['London', 'Cambridge'],
  63. 'pets': {'dogs': ['Rufus', 'Meg']},
  64. })
  65. ContactInfo.objects.filter(
  66. data__name='John',
  67. data__pets__has_key='dogs',
  68. data__cities__contains='London',
  69. ).delete()
  70. If your project uses ``django.contrib.postgres.fields.JSONField``, plus the
  71. related form field and transforms, you should adjust to use the new fields,
  72. and generate and apply a database migration. For now, the old fields and
  73. transforms are left as a reference to the new ones and are :ref:`deprecated as
  74. of this release <deprecated-jsonfield>`.
  75. Minor features
  76. --------------
  77. :mod:`django.contrib.admin`
  78. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79. * The new ``django.contrib.admin.EmptyFieldListFilter`` for
  80. :attr:`.ModelAdmin.list_filter` allows filtering on empty values (empty
  81. strings and nulls) in the admin changelist view.
  82. * Filters in the right sidebar of the admin changelist view now contain a link
  83. to clear all filters.
  84. * The admin now has a sidebar on larger screens for easier navigation. It is
  85. enabled by default but can be disabled by using a custom ``AdminSite`` and
  86. setting :attr:`.AdminSite.enable_nav_sidebar` to ``False``.
  87. Rendering the sidebar requires access to the current request in order to set
  88. CSS and ARIA role affordances. This requires using
  89. ``'django.template.context_processors.request'`` in the
  90. ``'context_processors'`` option of :setting:`OPTIONS <TEMPLATES-OPTIONS>`.
  91. * ``XRegExp`` is upgraded from version 2.0.0 to 3.2.0.
  92. * jQuery is upgraded from version 3.4.1 to 3.5.1.
  93. * Select2 library is upgraded from version 4.0.7 to 4.0.13.
  94. :mod:`django.contrib.auth`
  95. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  96. * The default iteration count for the PBKDF2 password hasher is increased from
  97. 180,000 to 216,000.
  98. * The new :setting:`PASSWORD_RESET_TIMEOUT` setting allows defining the number
  99. of seconds a password reset link is valid for. This is encouraged instead of
  100. the deprecated ``PASSWORD_RESET_TIMEOUT_DAYS`` setting, which will be removed
  101. in Django 4.0.
  102. * The password reset mechanism now uses the SHA-256 hashing algorithm. Support
  103. for tokens that use the old hashing algorithm remains until Django 4.0.
  104. * :meth:`.AbstractBaseUser.get_session_auth_hash` now uses the SHA-256 hashing
  105. algorithm. Support for user sessions that use the old hashing algorithm
  106. remains until Django 4.0.
  107. :mod:`django.contrib.contenttypes`
  108. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  109. * The new :option:`remove_stale_contenttypes --include-stale-apps` option
  110. allows removing stale content types from previously installed apps that have
  111. been removed from :setting:`INSTALLED_APPS`.
  112. :mod:`django.contrib.gis`
  113. ~~~~~~~~~~~~~~~~~~~~~~~~~
  114. * :lookup:`relate` lookup is now supported on MariaDB.
  115. * Added the :attr:`.LinearRing.is_counterclockwise` property.
  116. * :class:`~django.contrib.gis.db.models.functions.AsGeoJSON` is now supported
  117. on Oracle.
  118. * Added the :class:`~django.contrib.gis.db.models.functions.AsWKB` and
  119. :class:`~django.contrib.gis.db.models.functions.AsWKT` functions.
  120. * Added support for PostGIS 3 and GDAL 3.
  121. :mod:`django.contrib.humanize`
  122. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  123. * :tfilter:`intword` template filter now supports negative integers.
  124. :mod:`django.contrib.postgres`
  125. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  126. * The new :class:`~django.contrib.postgres.indexes.BloomIndex` class allows
  127. creating ``bloom`` indexes in the database. The new
  128. :class:`~django.contrib.postgres.operations.BloomExtension` migration
  129. operation installs the ``bloom`` extension to add support for this index.
  130. * :meth:`~django.db.models.Model.get_FOO_display` now supports
  131. :class:`~django.contrib.postgres.fields.ArrayField` and
  132. :class:`~django.contrib.postgres.fields.RangeField`.
  133. * The new :lookup:`rangefield.lower_inc`, :lookup:`rangefield.lower_inf`,
  134. :lookup:`rangefield.upper_inc`, and :lookup:`rangefield.upper_inf` lookups
  135. allow querying :class:`~django.contrib.postgres.fields.RangeField` by a bound
  136. type.
  137. * :lookup:`rangefield.contained_by` now supports
  138. :class:`~django.db.models.SmallAutoField`,
  139. :class:`~django.db.models.AutoField`,
  140. :class:`~django.db.models.BigAutoField`,
  141. :class:`~django.db.models.SmallIntegerField`, and
  142. :class:`~django.db.models.DecimalField`.
  143. * :class:`~django.contrib.postgres.search.SearchQuery` now supports
  144. ``'websearch'`` search type on PostgreSQL 11+.
  145. * :class:`SearchQuery.value <django.contrib.postgres.search.SearchQuery>` now
  146. supports query expressions.
  147. * The new :class:`~django.contrib.postgres.search.SearchHeadline` class allows
  148. highlighting search results.
  149. * :lookup:`search` lookup now supports query expressions.
  150. * The new ``cover_density`` parameter of
  151. :class:`~django.contrib.postgres.search.SearchRank` allows ranking by cover
  152. density.
  153. * The new ``normalization`` parameter of
  154. :class:`~django.contrib.postgres.search.SearchRank` allows rank
  155. normalization.
  156. * The new :attr:`.ExclusionConstraint.deferrable` attribute allows creating
  157. deferrable exclusion constraints.
  158. :mod:`django.contrib.sessions`
  159. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  160. * The :setting:`SESSION_COOKIE_SAMESITE` setting now allows ``'None'`` (string)
  161. value to explicitly state that the cookie is sent with all same-site and
  162. cross-site requests.
  163. :mod:`django.contrib.staticfiles`
  164. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  165. * The :setting:`STATICFILES_DIRS` setting now supports :class:`pathlib.Path`.
  166. Cache
  167. ~~~~~
  168. * The :func:`~django.views.decorators.cache.cache_control` decorator and
  169. :func:`~django.utils.cache.patch_cache_control` method now support multiple
  170. field names in the ``no-cache`` directive for the ``Cache-Control`` header,
  171. according to :rfc:`7234#section-5.2.2.2`.
  172. * :meth:`~django.core.caches.cache.delete` now returns ``True`` if the key was
  173. successfully deleted, ``False`` otherwise.
  174. CSRF
  175. ~~~~
  176. * The :setting:`CSRF_COOKIE_SAMESITE` setting now allows ``'None'`` (string)
  177. value to explicitly state that the cookie is sent with all same-site and
  178. cross-site requests.
  179. Email
  180. ~~~~~
  181. * The :setting:`EMAIL_FILE_PATH` setting, used by the :ref:`file email backend
  182. <topic-email-file-backend>`, now supports :class:`pathlib.Path`.
  183. Error Reporting
  184. ~~~~~~~~~~~~~~~
  185. * :class:`django.views.debug.SafeExceptionReporterFilter` now filters sensitive
  186. values from ``request.META`` in exception reports.
  187. * The new :attr:`.SafeExceptionReporterFilter.cleansed_substitute` and
  188. :attr:`.SafeExceptionReporterFilter.hidden_settings` attributes allow
  189. customization of sensitive settings and ``request.META`` filtering in
  190. exception reports.
  191. * The technical 404 debug view now respects
  192. :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` when applying settings
  193. filtering.
  194. * The new :setting:`DEFAULT_EXCEPTION_REPORTER` allows providing a
  195. :class:`django.views.debug.ExceptionReporter` subclass to customize exception
  196. report generation. See :ref:`custom-error-reports` for details.
  197. File Storage
  198. ~~~~~~~~~~~~
  199. * ``FileSystemStorage.save()`` method now supports :class:`pathlib.Path`.
  200. * :class:`~django.db.models.FileField` and
  201. :class:`~django.db.models.ImageField` now accept a callable for ``storage``.
  202. This allows you to modify the used storage at runtime, selecting different
  203. storages for different environments, for example.
  204. Forms
  205. ~~~~~
  206. * :class:`~django.forms.ModelChoiceIterator`, used by
  207. :class:`~django.forms.ModelChoiceField` and
  208. :class:`~django.forms.ModelMultipleChoiceField`, now uses
  209. :class:`~django.forms.ModelChoiceIteratorValue` that can be used by widgets
  210. to access model instances. See :ref:`iterating-relationship-choices` for
  211. details.
  212. * :class:`django.forms.DateTimeField` now accepts dates in a subset of ISO 8601
  213. datetime formats, including optional timezone, e.g. ``2019-10-10T06:47``,
  214. ``2019-10-10T06:47:23+04:00``, or ``2019-10-10T06:47:23Z``. The timezone will
  215. always be retained if provided, with timezone-aware datetimes being returned
  216. even when :setting:`USE_TZ` is ``False``.
  217. Additionally, ``DateTimeField`` now uses ``DATE_INPUT_FORMATS`` in addition
  218. to ``DATETIME_INPUT_FORMATS`` when converting a field input to a ``datetime``
  219. value.
  220. * :attr:`.MultiWidget.widgets` now accepts a dictionary which allows
  221. customizing subwidget ``name`` attributes.
  222. * The new :attr:`.BoundField.widget_type` property can be used to dynamically
  223. adjust form rendering based upon the widget type.
  224. Internationalization
  225. ~~~~~~~~~~~~~~~~~~~~
  226. * The :setting:`LANGUAGE_COOKIE_SAMESITE` setting now allows ``'None'``
  227. (string) value to explicitly state that the cookie is sent with all same-site
  228. and cross-site requests.
  229. * Added support and translations for the Algerian Arabic, Kyrgyz, Tajik, and
  230. Turkmen languages.
  231. Management Commands
  232. ~~~~~~~~~~~~~~~~~~~
  233. * The new :option:`check --database` option allows specifying database aliases
  234. for running the ``database`` system checks. Previously these checks were
  235. enabled for all configured :setting:`DATABASES` by passing the ``database``
  236. tag to the command.
  237. * The new :option:`migrate --check` option makes the command exit with a
  238. non-zero status when unapplied migrations are detected.
  239. * The new ``returncode`` argument for
  240. :attr:`~django.core.management.CommandError` allows customizing the exit
  241. status for management commands.
  242. * The new :option:`dbshell -- ARGUMENTS <dbshell -->` option allows passing
  243. extra arguments to the command-line client for the database.
  244. * The :djadmin:`flush` and :djadmin:`sqlflush` commands now include SQL to
  245. reset sequences on SQLite.
  246. Migrations
  247. ~~~~~~~~~~
  248. * Migrations are now loaded also from directories without ``__init__.py``
  249. files.
  250. Models
  251. ~~~~~~
  252. * The new :class:`~django.db.models.functions.ExtractIsoWeekDay` function
  253. extracts ISO-8601 week days from :class:`~django.db.models.DateField` and
  254. :class:`~django.db.models.DateTimeField`, and the new :lookup:`iso_week_day`
  255. lookup allows querying by an ISO-8601 day of week.
  256. * :meth:`.QuerySet.explain` now supports:
  257. * ``TREE`` format on MySQL 8.0.16+,
  258. * ``analyze`` option on MySQL 8.0.18+ and MariaDB.
  259. * Added :class:`~django.db.models.PositiveBigIntegerField` which acts much like
  260. a :class:`~django.db.models.PositiveIntegerField` except that it only allows
  261. values under a certain (database-dependent) limit. Values from ``0`` to
  262. ``9223372036854775807`` are safe in all databases supported by Django.
  263. * The new :class:`~django.db.models.RESTRICT` option for
  264. :attr:`~django.db.models.ForeignKey.on_delete` argument of ``ForeignKey`` and
  265. ``OneToOneField`` emulates the behavior of the SQL constraint ``ON DELETE
  266. RESTRICT``.
  267. * :attr:`.CheckConstraint.check` now supports boolean expressions.
  268. * The :meth:`.RelatedManager.add`, :meth:`~.RelatedManager.create`, and
  269. :meth:`~.RelatedManager.set` methods now accept callables as values in the
  270. ``through_defaults`` argument.
  271. * The new ``is_dst`` parameter of the :meth:`.QuerySet.datetimes` determines
  272. the treatment of nonexistent and ambiguous datetimes.
  273. * The new :class:`~django.db.models.F` expression ``bitxor()`` method allows
  274. :ref:`bitwise XOR operation <using-f-expressions-in-filters>`.
  275. * :meth:`.QuerySet.bulk_create` now sets the primary key on objects when using
  276. MariaDB 10.5+.
  277. * The ``DatabaseOperations.sql_flush()`` method now generates more efficient
  278. SQL on MySQL by using ``DELETE`` instead of ``TRUNCATE`` statements for
  279. tables which don't require resetting sequences.
  280. * SQLite functions are now marked as :py:meth:`deterministic
  281. <sqlite3.Connection.create_function>` on Python 3.8+. This allows using them
  282. in check constraints and partial indexes.
  283. * The new :attr:`.UniqueConstraint.deferrable` attribute allows creating
  284. deferrable unique constraints.
  285. Pagination
  286. ~~~~~~~~~~
  287. * :class:`~django.core.paginator.Paginator` can now be iterated over to yield
  288. its pages.
  289. Requests and Responses
  290. ~~~~~~~~~~~~~~~~~~~~~~
  291. * If :setting:`ALLOWED_HOSTS` is empty and ``DEBUG=True``, subdomains of
  292. localhost are now allowed in the ``Host`` header, e.g. ``static.localhost``.
  293. * :meth:`.HttpResponse.set_cookie` and :meth:`.HttpResponse.set_signed_cookie`
  294. now allow using ``samesite='None'`` (string) to explicitly state that the
  295. cookie is sent with all same-site and cross-site requests.
  296. * The new :meth:`.HttpRequest.accepts` method returns whether the request
  297. accepts the given MIME type according to the ``Accept`` HTTP header.
  298. .. _whats-new-security-3.1:
  299. Security
  300. ~~~~~~~~
  301. * The :setting:`SECURE_REFERRER_POLICY` setting now defaults to
  302. ``'same-origin'``. With this configured,
  303. :class:`~django.middleware.security.SecurityMiddleware` sets the
  304. :ref:`referrer-policy` header to ``same-origin`` on all responses that do not
  305. already have it. This prevents the ``Referer`` header being sent to other
  306. origins. If you need the previous behavior, explicitly set
  307. :setting:`SECURE_REFERRER_POLICY` to ``None``.
  308. * The default :class:`django.core.signing.Signer` algorithm is changed to the
  309. SHA-256. Support for signatures made with the old SHA-1 algorithm remains
  310. until Django 4.0.
  311. Also, the new ``algorithm`` parameter of the
  312. :class:`~django.core.signing.Signer` allows customizing the hashing
  313. algorithm.
  314. Templates
  315. ~~~~~~~~~
  316. * The renamed :ttag:`translate` and :ttag:`blocktranslate` template tags are
  317. introduced for internationalization in template code. The older :ttag:`trans`
  318. and :ttag:`blocktrans` template tags aliases continue to work, and will be
  319. retained for the foreseeable future.
  320. * The :ttag:`include` template tag now accepts iterables of template names.
  321. Tests
  322. ~~~~~
  323. * :class:`~django.test.SimpleTestCase` now implements the ``debug()`` method to
  324. allow running a test without collecting the result and catching exceptions.
  325. This can be used to support running tests under a debugger.
  326. * The new :setting:`MIGRATE <TEST_MIGRATE>` test database setting allows
  327. disabling of migrations during a test database creation.
  328. * Django test runner now supports a :option:`test --buffer` option to discard
  329. output for passing tests.
  330. * :class:`~django.test.runner.DiscoverRunner` now skips running the system
  331. checks on databases not :ref:`referenced by tests<testing-multi-db>`.
  332. * :class:`~django.test.TransactionTestCase` teardown is now faster on MySQL
  333. due to :djadmin:`flush` command improvements. As a side effect the latter
  334. doesn't automatically reset sequences on teardown anymore. Enable
  335. :attr:`.TransactionTestCase.reset_sequences` if your tests require this
  336. feature.
  337. URLs
  338. ~~~~
  339. * :ref:`Path converters <registering-custom-path-converters>` can now raise
  340. ``ValueError`` in ``to_url()`` to indicate no match when reversing URLs.
  341. Utilities
  342. ~~~~~~~~~
  343. * :func:`~django.utils.encoding.filepath_to_uri` now supports
  344. :class:`pathlib.Path`.
  345. * :func:`~django.utils.dateparse.parse_duration` now supports comma separators
  346. for decimal fractions in the ISO 8601 format.
  347. * :func:`~django.utils.dateparse.parse_datetime`,
  348. :func:`~django.utils.dateparse.parse_duration`, and
  349. :func:`~django.utils.dateparse.parse_time` now support comma separators for
  350. milliseconds.
  351. Miscellaneous
  352. ~~~~~~~~~~~~~
  353. * The SQLite backend now supports :class:`pathlib.Path` for the ``NAME``
  354. setting.
  355. * The ``settings.py`` generated by the :djadmin:`startproject` command now uses
  356. :class:`pathlib.Path` instead of :mod:`os.path` for building filesystem
  357. paths.
  358. * The :setting:`TIME_ZONE <DATABASE-TIME_ZONE>` setting is now allowed on
  359. databases that support time zones.
  360. .. _backwards-incompatible-3.1:
  361. Backwards incompatible changes in 3.1
  362. =====================================
  363. Database backend API
  364. --------------------
  365. This section describes changes that may be needed in third-party database
  366. backends.
  367. * ``DatabaseOperations.fetch_returned_insert_columns()`` now requires an
  368. additional ``returning_params`` argument.
  369. * ``connection.timezone`` property is now ``'UTC'`` by default, or the
  370. :setting:`TIME_ZONE <DATABASE-TIME_ZONE>` when :setting:`USE_TZ` is ``True``
  371. on databases that support time zones. Previously, it was ``None`` on
  372. databases that support time zones.
  373. * ``connection._nodb_connection`` property is changed to the
  374. ``connection._nodb_cursor()`` method and now returns a context manager that
  375. yields a cursor and automatically closes the cursor and connection upon
  376. exiting the ``with`` statement.
  377. * ``DatabaseClient.runshell()`` now requires an additional ``parameters``
  378. argument as a list of extra arguments to pass on to the command-line client.
  379. * The ``sequences`` positional argument of ``DatabaseOperations.sql_flush()``
  380. is replaced by the boolean keyword-only argument ``reset_sequences``. If
  381. ``True``, the sequences of the truncated tables will be reset.
  382. * The ``allow_cascade`` argument of ``DatabaseOperations.sql_flush()`` is now a
  383. keyword-only argument.
  384. * The ``using`` positional argument of
  385. ``DatabaseOperations.execute_sql_flush()`` is removed. The method now uses
  386. the database of the called instance.
  387. * Third-party database backends must implement support for ``JSONField`` or set
  388. ``DatabaseFeatures.supports_json_field`` to ``False``. If storing primitives
  389. is not supported, set ``DatabaseFeatures.supports_primitives_in_json_field``
  390. to ``False``. If there is a true datatype for JSON, set
  391. ``DatabaseFeatures.has_native_json_field`` to ``True``.
  392. * Third party database backends must implement introspection for ``JSONField``
  393. or set ``can_introspect_json_field`` to ``False``.
  394. Dropped support for MariaDB 10.1
  395. --------------------------------
  396. Upstream support for MariaDB 10.1 ends in October 2020. Django 3.1 supports
  397. MariaDB 10.2 and higher.
  398. ``contrib.admin`` browser support
  399. ---------------------------------
  400. The admin no longer supports the legacy Internet Explorer browser. See
  401. :ref:`the admin FAQ <admin-browser-support>` for details on supported browsers.
  402. :attr:`AbstractUser.first_name <django.contrib.auth.models.User.first_name>` ``max_length`` increased to 150
  403. ------------------------------------------------------------------------------------------------------------
  404. A migration for :attr:`django.contrib.auth.models.User.first_name` is included.
  405. If you have a custom user model inheriting from ``AbstractUser``, you'll need
  406. to generate and apply a database migration for your user model.
  407. If you want to preserve the 30 character limit for first names, use a custom
  408. form::
  409. from django import forms
  410. from django.contrib.auth.forms import UserChangeForm
  411. class MyUserChangeForm(UserChangeForm):
  412. first_name = forms.CharField(max_length=30, required=False)
  413. If you wish to keep this restriction in the admin when editing users, set
  414. ``UserAdmin.form`` to use this form::
  415. from django.contrib.auth.admin import UserAdmin
  416. from django.contrib.auth.models import User
  417. class MyUserAdmin(UserAdmin):
  418. form = MyUserChangeForm
  419. admin.site.unregister(User)
  420. admin.site.register(User, MyUserAdmin)
  421. Miscellaneous
  422. -------------
  423. * The cache keys used by :ttag:`cache` and generated by
  424. :func:`~django.core.cache.utils.make_template_fragment_key` are different
  425. from the keys generated by older versions of Django. After upgrading to
  426. Django 3.1, the first request to any previously cached template fragment will
  427. be a cache miss.
  428. * The logic behind the decision to return a redirection fallback or a 204 HTTP
  429. response from the :func:`~django.views.i18n.set_language` view is now based
  430. on the ``Accept`` HTTP header instead of the ``X-Requested-With`` HTTP header
  431. presence.
  432. * The compatibility imports of ``django.core.exceptions.EmptyResultSet`` in
  433. ``django.db.models.query``, ``django.db.models.sql``, and
  434. ``django.db.models.sql.datastructures`` are removed.
  435. * The compatibility import of ``django.core.exceptions.FieldDoesNotExist`` in
  436. ``django.db.models.fields`` is removed.
  437. * The compatibility imports of ``django.forms.utils.pretty_name()`` and
  438. ``django.forms.boundfield.BoundField`` in ``django.forms.forms`` are removed.
  439. * The compatibility imports of ``Context``, ``ContextPopException``, and
  440. ``RequestContext`` in ``django.template.base`` are removed.
  441. * The compatibility import of
  442. ``django.contrib.admin.helpers.ACTION_CHECKBOX_NAME`` in
  443. ``django.contrib.admin`` is removed.
  444. * The :setting:`STATIC_URL` and :setting:`MEDIA_URL` settings set to relative
  445. paths are now prefixed by the server-provided value of ``SCRIPT_NAME`` (or
  446. ``/`` if not set). This change should not affect settings set to valid URLs
  447. or absolute paths.
  448. * :class:`~django.middleware.http.ConditionalGetMiddleware` no longer adds the
  449. ``ETag`` header to responses with an empty
  450. :attr:`~django.http.HttpResponse.content`.
  451. * ``django.utils.decorators.classproperty()`` decorator is made public and
  452. moved to :class:`django.utils.functional.classproperty()`.
  453. * :tfilter:`floatformat` template filter now outputs (positive) ``0`` for
  454. negative numbers which round to zero.
  455. * :attr:`Meta.ordering <django.db.models.Options.ordering>` and
  456. :attr:`Meta.unique_together <django.db.models.Options.unique_together>`
  457. options on models in ``django.contrib`` modules that were formerly tuples are
  458. now lists.
  459. * The admin calendar widget now handles two-digit years according to the Open
  460. Group Specification, i.e. values between 69 and 99 are mapped to the previous
  461. century, and values between 0 and 68 are mapped to the current century.
  462. * Date-only formats are removed from the default list for
  463. :setting:`DATETIME_INPUT_FORMATS`.
  464. * The :class:`~django.forms.FileInput` widget no longer renders with the
  465. ``required`` HTML attribute when initial data exists.
  466. * The undocumented ``django.views.debug.ExceptionReporterFilter`` class is
  467. removed. As per the :ref:`custom-error-reports` documentation, classes to be
  468. used with :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` need to inherit from
  469. :class:`django.views.debug.SafeExceptionReporterFilter`.
  470. * The cache timeout set by :func:`~django.views.decorators.cache.cache_page`
  471. decorator now takes precedence over the ``max-age`` directive from the
  472. ``Cache-Control`` header.
  473. * Providing a non-local remote field in the :attr:`.ForeignKey.to_field`
  474. argument now raises :class:`~django.core.exceptions.FieldError`.
  475. * :setting:`SECURE_REFERRER_POLICY` now defaults to ``'same-origin'``. See the
  476. *What's New* :ref:`Security section <whats-new-security-3.1>` above for more
  477. details.
  478. * :djadmin:`check` management command now runs the ``database`` system checks
  479. only for database aliases specified using :option:`check --database` option.
  480. * :djadmin:`migrate` management command now runs the ``database`` system checks
  481. only for a database to migrate.
  482. * The admin CSS classes ``row1`` and ``row2`` are removed in favor of
  483. ``:nth-child(odd)`` and ``:nth-child(even)`` pseudo-classes.
  484. * The :func:`~django.contrib.auth.hashers.make_password` function now requires
  485. its argument to be a string or bytes. Other types should be explicitly cast
  486. to one of these.
  487. * The undocumented ``version`` parameter to the
  488. :class:`~django.contrib.gis.db.models.functions.AsKML` function is removed.
  489. * :ref:`JSON and YAML serializers <serialization-formats>`, used by
  490. :djadmin:`dumpdata`, now dump all data with Unicode by default. If you need
  491. the previous behavior, pass ``ensure_ascii=True`` to JSON serializer, or
  492. ``allow_unicode=False`` to YAML serializer.
  493. * The auto-reloader no longer monitors changes in built-in Django translation
  494. files.
  495. * The minimum supported version of ``mysqlclient`` is increased from 1.3.13 to
  496. 1.4.0.
  497. * The undocumented ``django.contrib.postgres.forms.InvalidJSONInput`` and
  498. ``django.contrib.postgres.forms.JSONString`` are moved to
  499. ``django.forms.fields``.
  500. * The undocumented ``django.contrib.postgres.fields.jsonb.JsonAdapter`` class
  501. is removed.
  502. * The :ttag:`{% localize off %} <localize>` tag and :tfilter:`unlocalize`
  503. filter no longer respect :setting:`DECIMAL_SEPARATOR` setting.
  504. .. _deprecated-features-3.1:
  505. Features deprecated in 3.1
  506. ==========================
  507. .. _deprecated-jsonfield:
  508. PostgreSQL ``JSONField``
  509. ------------------------
  510. ``django.contrib.postgres.fields.JSONField`` and
  511. ``django.contrib.postgres.forms.JSONField`` are deprecated in favor of
  512. :class:`.models.JSONField` and
  513. :class:`forms.JSONField <django.forms.JSONField>`.
  514. The undocumented ``django.contrib.postgres.fields.jsonb.KeyTransform`` and
  515. ``django.contrib.postgres.fields.jsonb.KeyTextTransform`` are also deprecated
  516. in favor of the transforms in ``django.db.models.fields.json``.
  517. The new ``JSONField``\s, ``KeyTransform``, and ``KeyTextTransform`` can be used
  518. on all supported database backends.
  519. Miscellaneous
  520. -------------
  521. * ``PASSWORD_RESET_TIMEOUT_DAYS`` setting is deprecated in favor of
  522. :setting:`PASSWORD_RESET_TIMEOUT`.
  523. * The undocumented usage of the :lookup:`isnull` lookup with non-boolean values
  524. as the right-hand side is deprecated, use ``True`` or ``False`` instead.
  525. * The barely documented ``django.db.models.query_utils.InvalidQuery`` exception
  526. class is deprecated in favor of
  527. :class:`~django.core.exceptions.FieldDoesNotExist` and
  528. :class:`~django.core.exceptions.FieldError`.
  529. * The ``django-admin.py`` entry point is deprecated in favor of
  530. ``django-admin``.
  531. * The ``HttpRequest.is_ajax()`` method is deprecated as it relied on a
  532. jQuery-specific way of signifying AJAX calls, while current usage tends to
  533. use the JavaScript `Fetch API
  534. <https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API>`_. Depending on
  535. your use case, you can either write your own AJAX detection method, or use
  536. the new :meth:`.HttpRequest.accepts` method if your code depends on the
  537. client ``Accept`` HTTP header.
  538. If you are writing your own AJAX detection method, ``request.is_ajax()`` can
  539. be reproduced exactly as
  540. ``request.headers.get('x-requested-with') == 'XMLHttpRequest'``.
  541. * Passing ``None`` as the first argument to
  542. ``django.utils.deprecation.MiddlewareMixin.__init__()`` is deprecated.
  543. * The encoding format of cookies values used by
  544. :class:`~django.contrib.messages.storage.cookie.CookieStorage` is different
  545. from the format generated by older versions of Django. Support for the old
  546. format remains until Django 4.0.
  547. * The encoding format of sessions is different from the format generated by
  548. older versions of Django. Support for the old format remains until Django
  549. 4.0.
  550. * The purely documentational ``providing_args`` argument for
  551. :class:`~django.dispatch.Signal` is deprecated. If you rely on this
  552. argument as documentation, you can move the text to a code comment or
  553. docstring.
  554. * Calling ``django.utils.crypto.get_random_string()`` without a ``length``
  555. argument is deprecated.
  556. * The ``list`` message for :class:`~django.forms.ModelMultipleChoiceField` is
  557. deprecated in favor of ``invalid_list``.
  558. * The passing of URL kwargs directly to the context by
  559. :class:`~django.views.generic.base.TemplateView` is deprecated. Reference
  560. them in the template with ``view.kwargs`` instead.
  561. * Passing raw column aliases to :meth:`.QuerySet.order_by` is deprecated. The
  562. same result can be achieved by passing aliases in a
  563. :class:`~django.db.models.expressions.RawSQL` instead beforehand.
  564. * The ``NullBooleanField`` model field is deprecated in favor of
  565. ``BooleanField(null=True)``.
  566. * ``django.conf.urls.url()`` alias of :func:`django.urls.re_path` is
  567. deprecated.
  568. * The ``{% ifequal %}`` and ``{% ifnotequal %}`` template tags are deprecated
  569. in favor of :ttag:`{% if %}<if>`. ``{% if %}`` covers all use cases, but if
  570. you need to continue using these tags, they can be extracted from Django to a
  571. module and included as a built-in tag in the :class:`'builtins'
  572. <django.template.backends.django.DjangoTemplates>` option in
  573. :setting:`OPTIONS <TEMPLATES-OPTIONS>`.
  574. .. _removed-features-3.1:
  575. Features removed in 3.1
  576. =======================
  577. These features have reached the end of their deprecation cycle and are removed
  578. in Django 3.1.
  579. See :ref:`deprecated-features-2.2` for details on these changes, including how
  580. to remove usage of these features.
  581. * ``django.utils.timezone.FixedOffset`` is removed.
  582. * ``django.core.paginator.QuerySetPaginator`` is removed.
  583. * A model's ``Meta.ordering`` doesn't affect ``GROUP BY`` queries.
  584. * ``django.contrib.postgres.fields.FloatRangeField`` and
  585. ``django.contrib.postgres.forms.FloatRangeField`` are removed.
  586. * The ``FILE_CHARSET`` setting is removed.
  587. * ``django.contrib.staticfiles.storage.CachedStaticFilesStorage`` is removed.
  588. * The ``RemoteUserBackend.configure_user()`` method requires ``request`` as the
  589. first positional argument.
  590. * Support for ``SimpleTestCase.allow_database_queries`` and
  591. ``TransactionTestCase.multi_db`` is removed.