2.2.txt 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536
  1. ============================================
  2. Django 2.2 release notes - UNDER DEVELOPMENT
  3. ============================================
  4. *Expected April 2019*
  5. Welcome to Django 2.2!
  6. These release notes cover the :ref:`new features <whats-new-2.2>`, as well as
  7. some :ref:`backwards incompatible changes <backwards-incompatible-2.2>` you'll
  8. want to be aware of when upgrading from Django 2.1 or earlier. We've
  9. :ref:`begun the deprecation process for some features
  10. <deprecated-features-2.2>`.
  11. See the :doc:`/howto/upgrade-version` guide if you're updating an existing
  12. project.
  13. Django 2.2 is designated as a :term:`long-term support release`. It will
  14. receive security updates for at least three years after its release. Support
  15. for the previous LTS, Django 1.11, will end in April 2020.
  16. Python compatibility
  17. ====================
  18. Django 2.2 supports Python 3.5, 3.6, and 3.7. We **highly recommend** and only
  19. officially support the latest release of each series.
  20. .. _whats-new-2.2:
  21. What's new in Django 2.2
  22. ========================
  23. Constraints
  24. -----------
  25. The new :class:`~django.db.models.CheckConstraint` and
  26. :class:`~django.db.models.UniqueConstraint` classes enable adding custom
  27. database constraints. Constraints are added to models using the
  28. :attr:`Meta.constraints <django.db.models.Options.constraints>` option.
  29. Minor features
  30. --------------
  31. :mod:`django.contrib.admin`
  32. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  33. * Added a CSS class to the column headers of
  34. :class:`~django.contrib.admin.TabularInline`.
  35. :mod:`django.contrib.admindocs`
  36. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  37. * ...
  38. :mod:`django.contrib.auth`
  39. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  40. * The ``HttpRequest`` is now passed as the first positional argument to
  41. :meth:`.RemoteUserBackend.configure_user`, if it accepts it.
  42. :mod:`django.contrib.contenttypes`
  43. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  44. * ...
  45. :mod:`django.contrib.gis`
  46. ~~~~~~~~~~~~~~~~~~~~~~~~~
  47. * Added Oracle support for the
  48. :class:`~django.contrib.gis.db.models.functions.Envelope` function.
  49. * Added SpatiaLite support for the :lookup:`coveredby` and :lookup:`covers`
  50. lookups.
  51. :mod:`django.contrib.messages`
  52. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  53. * ...
  54. :mod:`django.contrib.postgres`
  55. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  56. * The new ``ordering`` argument for
  57. :class:`~django.contrib.postgres.aggregates.ArrayAgg` and
  58. :class:`~django.contrib.postgres.aggregates.StringAgg` determines the
  59. ordering of the aggregated elements.
  60. * The new :class:`~django.contrib.postgres.indexes.BTreeIndex`,
  61. :class:`~django.contrib.postgres.indexes.HashIndex` and
  62. :class:`~django.contrib.postgres.indexes.SpGistIndex` classes allow
  63. creating ``B-Tree``, ``hash``, and ``SP-GiST`` indexes in the database.
  64. * :class:`~django.contrib.postgres.indexes.BrinIndex` now has the
  65. ``autosummarize`` parameter.
  66. * The new ``search_type`` parameter of
  67. :class:`~django.contrib.postgres.search.SearchQuery` allows searching for
  68. a phrase or raw expression.
  69. :mod:`django.contrib.redirects`
  70. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  71. * ...
  72. :mod:`django.contrib.sessions`
  73. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  74. * ...
  75. :mod:`django.contrib.sitemaps`
  76. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  77. * ...
  78. :mod:`django.contrib.sites`
  79. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  80. * ...
  81. :mod:`django.contrib.staticfiles`
  82. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  83. * Added path matching to the :option:`collectstatic --ignore` option so that
  84. patterns like ``/vendor/*.js`` can be used.
  85. :mod:`django.contrib.syndication`
  86. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  87. * ...
  88. Cache
  89. ~~~~~
  90. * ...
  91. CSRF
  92. ~~~~
  93. * ...
  94. Database backends
  95. ~~~~~~~~~~~~~~~~~
  96. * Added result streaming for :meth:`.QuerySet.iterator` on SQLite.
  97. Email
  98. ~~~~~
  99. * ...
  100. File Storage
  101. ~~~~~~~~~~~~
  102. * ...
  103. File Uploads
  104. ~~~~~~~~~~~~
  105. * ...
  106. Forms
  107. ~~~~~
  108. * ...
  109. Generic Views
  110. ~~~~~~~~~~~~~
  111. * The new :meth:`View.setup <django.views.generic.base.View.setup>` hook
  112. initializes view attributes before calling
  113. :meth:`~django.views.generic.base.View.dispatch`. It allows mixins to setup
  114. instance attributes for reuse in child classes.
  115. Internationalization
  116. ~~~~~~~~~~~~~~~~~~~~
  117. * Added support and translations for the Armenian language.
  118. Management Commands
  119. ~~~~~~~~~~~~~~~~~~~
  120. * The new :option:`--force-color` option forces colorization of the command
  121. output.
  122. * :djadmin:`inspectdb` now creates models for foreign tables on PostgreSQL.
  123. * :option:`inspectdb --include-views` now creates models for materialized views
  124. on Oracle and PostgreSQL.
  125. * The new :option:`inspectdb --include-partitions` option allows creating
  126. models for partition tables on PostgreSQL. In older versions, models are
  127. created child tables instead the parent.
  128. * :djadmin:`inspectdb` now introspects :class:`~django.db.models.DurationField`
  129. for Oracle and PostgreSQL, and :class:`~django.db.models.AutoField` for
  130. SQLite.
  131. * On Oracle, :djadmin:`dbshell` is wrapped with ``rlwrap``, if available.
  132. ``rlwrap`` provides a command history and editing of keyboard input.
  133. * The new :option:`makemigrations --no-header` option avoids writing header
  134. comments in generated migration file(s). This option is also available for
  135. :djadmin:`squashmigrations`.
  136. Migrations
  137. ~~~~~~~~~~
  138. * The new :option:`migrate --plan` option prints the list of migration
  139. operations that will be performed.
  140. * ``NoneType`` can now be serialized in migrations.
  141. * You can now :ref:`register custom serializers <custom-migration-serializers>`
  142. for migrations.
  143. Models
  144. ~~~~~~
  145. * Added support for PostgreSQL operator classes (:attr:`.Index.opclasses`).
  146. * Added support for partial indexes (:attr:`.Index.condition`).
  147. * Added many :ref:`math database functions <math-functions>`.
  148. * The new :class:`~django.db.models.functions.NullIf` database function
  149. returns ``None`` if the two expressions are equal.
  150. * Setting the new ``ignore_conflicts`` parameter of
  151. :meth:`.QuerySet.bulk_create` to ``True`` tells the database to ignore
  152. failure to insert rows that fail uniqueness constraints or other checks.
  153. * The new :class:`~django.db.models.functions.ExtractIsoYear` function extracts
  154. ISO-8601 week-numbering years from :class:`~django.db.models.DateField` and
  155. :class:`~django.db.models.DateTimeField`, and the new :lookup:`iso_year`
  156. lookup allows querying by an ISO-8601 week-numbering year.
  157. * The new :meth:`.QuerySet.bulk_update` method allows efficiently updating
  158. specific fields on multiple model instances.
  159. * Django no longer always starts a transaction when a single query is being
  160. performed, such as ``Model.save()``, ``QuerySet.update()``, and
  161. ``Model.delete()``. This improves the performance of autocommit by reducing
  162. the number of database round trips.
  163. * Added SQLite support for the :class:`~django.db.models.StdDev` and
  164. :class:`~django.db.models.Variance` functions.
  165. * The handling of ``DISTINCT`` aggregation is added to the
  166. :class:`~django.db.models.Aggregate` class. Adding :attr:`allow_distinct =
  167. True <django.db.models.Aggregate.allow_distinct>` as a class attribute on
  168. ``Aggregate`` subclasses allows a ``distinct`` keyword argument to be
  169. specified on initialization to ensure that the aggregate function is only
  170. called for each distinct value of ``expressions``.
  171. Requests and Responses
  172. ~~~~~~~~~~~~~~~~~~~~~~
  173. * ...
  174. Serialization
  175. ~~~~~~~~~~~~~
  176. * You can now deserialize data using natural keys containing :ref:`forward
  177. references <natural-keys-and-forward-references>` by passing
  178. ``handle_forward_references=True`` to ``serializers.deserialize()``.
  179. Additionally, :djadmin:`loaddata` handles forward references automatically.
  180. Signals
  181. ~~~~~~~
  182. * ...
  183. Templates
  184. ~~~~~~~~~
  185. * ...
  186. Tests
  187. ~~~~~
  188. * The new :meth:`.SimpleTestCase.assertURLEqual` assertion checks for a given
  189. URL, ignoring the ordering of the query string.
  190. :meth:`~.SimpleTestCase.assertRedirects` uses the new assertion.
  191. * The test :class:`~.django.test.Client` now supports automatic JSON
  192. serialization of list and tuple ``data`` when
  193. ``content_type='application/json'``.
  194. * The new :setting:`ORACLE_MANAGED_FILES <TEST_ORACLE_MANAGED_FILES>` test
  195. database setting allows using Oracle Managed Files (OMF) tablespaces.
  196. * Deferrable database constraints are now checked at the end of each
  197. :class:`~django.test.TestCase` test on SQLite 3.20+, just like on other
  198. backends that support deferrable constraints. These checks aren't implemented
  199. for older versions of SQLite because they would require expensive table
  200. introspection there.
  201. * :class:`~django.test.runner.DiscoverRunner` now skips the setup of databases
  202. not :ref:`referenced by tests<testing-multi-db>`.
  203. URLs
  204. ~~~~
  205. * The new :attr:`.ResolverMatch.route` attribute stores the route of the
  206. matching URL pattern.
  207. Validators
  208. ~~~~~~~~~~
  209. * :class:`.MaxValueValidator`, :class:`.MinValueValidator`,
  210. :class:`.MinLengthValidator`, and :class:`.MaxLengthValidator` now accept
  211. a callable ``limit_value``.
  212. .. _backwards-incompatible-2.2:
  213. Backwards incompatible changes in 2.2
  214. =====================================
  215. Database backend API
  216. --------------------
  217. This section describes changes that may be needed in third-party database
  218. backends.
  219. * Third-party database backends must implement support for table check
  220. constraints or set ``DatabaseFeatures.supports_table_check_constraints`` to
  221. ``False``.
  222. * Third party database backends must implement support for ignoring
  223. constraints or uniqueness errors while inserting or set
  224. ``DatabaseFeatures.supports_ignore_conflicts`` to ``False``.
  225. * Third party database backends must implement introspection for
  226. ``DurationField`` or set ``DatabaseFeatures.can_introspect_duration_field``
  227. to ``False``.
  228. * ``DatabaseFeatures.uses_savepoints`` now defaults to ``True``.
  229. * Third party database backends must implement support for partial indexes or
  230. set ``DatabaseFeatures.supports_partial_indexes`` to ``False``.
  231. * ``DatabaseIntrospection.table_name_converter()`` and
  232. ``column_name_converter()`` are removed. Third party database backends may
  233. need to instead implement ``DatabaseIntrospection.identifier_converter()``.
  234. In that case, the constraint names that
  235. ``DatabaseIntrospection.get_constraints()`` returns must be normalized by
  236. ``identifier_converter()``.
  237. * SQL generation for indexes is moved from :class:`~django.db.models.Index` to
  238. ``SchemaEditor`` and these ``SchemaEditor`` methods are added:
  239. * ``_create_primary_key_sql()`` and ``_delete_primary_key_sql()``
  240. * ``_delete_index_sql()`` (to pair with ``_create_index_sql()``)
  241. * ``_delete_unique_sql`` (to pair with ``_create_unique_sql()``)
  242. * ``_delete_fk_sql()`` (to pair with ``_create_fk_sql()``)
  243. * ``_create_check_sql()`` and ``_delete_check_sql()``
  244. Admin actions are no longer collected from base ``ModelAdmin`` classes
  245. ----------------------------------------------------------------------
  246. For example, in older versions of Django::
  247. from django.contrib import admin
  248. class BaseAdmin(admin.ModelAdmin):
  249. actions = ['a']
  250. class SubAdmin(BaseAdmin):
  251. actions = ['b']
  252. ``SubAdmin`` will have actions ``'a'`` and ``'b'``.
  253. Now ``actions`` follows standard Python inheritance. To get the same result as
  254. before::
  255. class SubAdmin(BaseAdmin):
  256. actions = BaseAdmin.actions + ['b']
  257. :mod:`django.contrib.gis`
  258. -------------------------
  259. * Support for GDAL 1.9 and 1.10 is dropped.
  260. ``TransactionTestCase`` serialized data loading
  261. -----------------------------------------------
  262. Initial data migrations are now loaded in
  263. :class:`~django.test.TransactionTestCase` at the end of the test, after the
  264. database flush. In older versions, this data was loaded at the beginning of the
  265. test, but this prevents the :option:`test --keepdb` option from working
  266. properly (the database was empty at the end of the whole test suite). This
  267. change shouldn't have an impact on your tests unless you've customized
  268. :class:`~django.test.TransactionTestCase`'s internals.
  269. ``sqlparse`` is required dependency
  270. -----------------------------------
  271. To simplify a few parts of Django's database handling, `sqlparse
  272. <https://pypi.org/project/sqlparse/>`_ is now a required dependency. It's
  273. automatically installed along with Django.
  274. ``cached_property`` aliases
  275. ---------------------------
  276. In usage like::
  277. from django.utils.functional import cached_property
  278. class A:
  279. @cached_property
  280. def base(self):
  281. return ...
  282. alias = base
  283. ``alias`` is not cached. Such usage now raises ``TypeError: Cannot assign the
  284. same cached_property to two different names ('base' and 'alias').`` on Python
  285. 3.6 and later.
  286. Use this instead::
  287. import operator
  288. class A:
  289. ...
  290. alias = property(operator.attrgetter('base'))
  291. Miscellaneous
  292. -------------
  293. * To improve readability, the ``UUIDField`` form field now displays values with
  294. dashes, e.g. ``550e8400-e29b-41d4-a716-446655440000`` instead of
  295. ``550e8400e29b41d4a716446655440000``.
  296. * On SQLite, ``PositiveIntegerField`` and ``PositiveSmallIntegerField`` now
  297. include a check constraint to prevent negative values in the database. If you
  298. have existing invalid data and run a migration that recreates a table, you'll
  299. see ``CHECK constraint failed``.
  300. * For consistency with WSGI servers, the test client now sets the
  301. ``Content-Length`` header to a string rather than an integer.
  302. * The return value of :func:`django.utils.text.slugify` is no longer marked as
  303. HTML safe.
  304. * The default truncation character used by the :tfilter:`urlizetrunc`,
  305. :tfilter:`truncatechars`, :tfilter:`truncatechars_html`,
  306. :tfilter:`truncatewords`, and :tfilter:`truncatewords_html` template filters
  307. is now the real ellipsis character (``…``) instead of 3 dots. You may have to
  308. adapt some test output comparisons.
  309. * Support for bytestring paths in the template filesystem loader is removed.
  310. * :func:`django.utils.http.urlsafe_base64_encode` now returns a string instead
  311. of a bytestring, and :func:`django.utils.http.urlsafe_base64_decode` may no
  312. longer be passed a bytestring.
  313. * Support for ``cx_Oracle`` < 6.0 is removed.
  314. * The minimum supported version of ``mysqlclient`` is increased from 1.3.7 to
  315. 1.3.13.
  316. * The minimum supported version of SQLite is increased from 3.7.15 to 3.8.3.
  317. * In an attempt to provide more semantic query data, ``NullBooleanSelect`` now
  318. renders ``<option>`` values of ``unknown``, ``true``, and ``false`` instead
  319. of ``1``, ``2``, and ``3``. For backwards compatibility, the old values are
  320. still accepted as data.
  321. * :attr:`Group.name <django.contrib.auth.models.Group.name>` ``max_length``
  322. is increased from 80 to 150 characters.
  323. * Tests that violate deferrable database constraints now error when run on
  324. SQLite 3.20+, just like on other backends that support such constraints.
  325. * To catch usage mistakes, the test :class:`~django.test.Client` and
  326. :func:`django.utils.http.urlencode` now raise ``TypeError`` if ``None`` is
  327. passed as a value to encode because ``None`` can't be encoded in GET and POST
  328. data. Either pass an empty string or omit the value.
  329. * The :djadmin:`ping_google` management command now defaults to ``https``
  330. instead of ``http`` for the sitemap's URL. If your site uses http, use the
  331. new :option:`ping_google --sitemap-uses-http` option. If you use the
  332. :func:`~django.contrib.sitemaps.ping_google` function, set the new
  333. ``sitemap_uses_https`` argument to ``False``.
  334. .. _deprecated-features-2.2:
  335. Features deprecated in 2.2
  336. ==========================
  337. Model ``Meta.ordering`` will no longer affect ``GROUP BY`` queries
  338. ------------------------------------------------------------------
  339. A model's ``Meta.ordering`` affecting ``GROUP BY`` queries (such as
  340. ``.annotate().values()``) is a common source of confusion. Such queries now
  341. issue a deprecation warning with the advice to add an ``order_by()`` to retain
  342. the current query. ``Meta.ordering`` will be ignored in such queries starting
  343. in Django 3.1.
  344. Miscellaneous
  345. -------------
  346. * ``django.utils.timezone.FixedOffset`` is deprecated in favor of
  347. :class:`datetime.timezone`.
  348. * The undocumented ``QuerySetPaginator`` alias of
  349. ``django.core.paginator.Paginator`` is deprecated.
  350. * The ``FloatRangeField`` model and form fields in ``django.contrib.postgres``
  351. are deprecated in favor of a new name, ``DecimalRangeField``, to match the
  352. underlying ``numrange`` data type used in the database.
  353. * The ``FILE_CHARSET`` setting is deprecated. Starting with Django 3.1, files
  354. read from disk must be UTF-8 encoded.
  355. * ``django.contrib.staticfiles.storage.CachedStaticFilesStorage`` is
  356. deprecated due to the intractable problems that is has. Use
  357. :class:`.ManifestStaticFilesStorage` or a third-party cloud storage instead.
  358. * :meth:`.RemoteUserBackend.configure_user` is now passed ``request`` as the
  359. first positional argument, if it accepts it. Support for overrides that don't
  360. accept it will be removed in Django 3.1.
  361. * The :attr:`.SimpleTestCase.allow_database_queries`,
  362. :attr:`.TransactionTestCase.multi_db`, and :attr:`.TestCase.multi_db`
  363. attributes are deprecated in favor of :attr:`.SimpleTestCase.databases`,
  364. :attr:`.TransactionTestCase.databases`, and :attr:`.TestCase.databases`.
  365. These new attributes allow databases dependencies to be declared in order to
  366. prevent unexpected queries against non-default databases to leak state
  367. between tests. The previous behavior of ``allow_database_queries=True`` and
  368. ``multi_db=True`` can be achieved by setting ``databases='__all__'``.