| 1 |
======================== |
| 2 |
Django 4.2 release notes |
| 3 |
======================== |
| 4 |
|
| 5 |
*April 3, 2023* |
| 6 |
|
| 7 |
Welcome to Django 4.2! |
| 8 |
|
| 9 |
These release notes cover the :ref:`new features <whats-new-4.2>`, as well as |
| 10 |
some :ref:`backwards incompatible changes <backwards-incompatible-4.2>` you'll |
| 11 |
want to be aware of when upgrading from Django 4.1 or earlier. We've |
| 12 |
:ref:`begun the deprecation process for some features |
| 13 |
<deprecated-features-4.2>`. |
| 14 |
|
| 15 |
See the :doc:`/howto/upgrade-version` guide if you're updating an existing |
| 16 |
project. |
| 17 |
|
| 18 |
Django 4.2 is designated as a :term:`long-term support release |
| 19 |
<Long-term support release>`. It will receive security updates for at least |
| 20 |
three years after its release. Support for the previous LTS, Django 3.2, will |
| 21 |
end in April 2024. |
| 22 |
|
| 23 |
Python compatibility |
| 24 |
==================== |
| 25 |
|
| 26 |
Django 4.2 supports Python 3.8, 3.9, 3.10, 3.11, and 3.12 (as of 4.2.8). We |
| 27 |
**highly recommend** and only officially support the latest release of each |
| 28 |
series. |
| 29 |
|
| 30 |
.. _whats-new-4.2: |
| 31 |
|
| 32 |
What's new in Django 4.2 |
| 33 |
======================== |
| 34 |
|
| 35 |
Psycopg 3 support |
| 36 |
----------------- |
| 37 |
|
| 38 |
Django now supports `psycopg`_ version 3.1.8 or higher. To update your code, |
| 39 |
install the :pypi:`psycopg library <psycopg>`, you don't need to change the |
| 40 |
:setting:`ENGINE <DATABASE-ENGINE>` as ``django.db.backends.postgresql`` |
| 41 |
supports both libraries. |
| 42 |
|
| 43 |
Support for ``psycopg2`` is likely to be deprecated and removed at some point |
| 44 |
in the future. |
| 45 |
|
| 46 |
Be aware that ``psycopg`` 3 introduces some breaking changes over ``psycopg2``. |
| 47 |
As a consequence, you may need to make some changes to account for |
| 48 |
`differences from psycopg2`_. |
| 49 |
|
| 50 |
.. _psycopg: https://www.psycopg.org/psycopg3/ |
| 51 |
.. _differences from psycopg2: https://www.psycopg.org/psycopg3/docs/basic/from_pg2.html |
| 52 |
|
| 53 |
Comments on columns and tables |
| 54 |
------------------------------ |
| 55 |
|
| 56 |
The new :attr:`Field.db_comment <django.db.models.Field.db_comment>` and |
| 57 |
:attr:`Meta.db_table_comment <django.db.models.Options.db_table_comment>` |
| 58 |
options allow creating comments on columns and tables, respectively. For |
| 59 |
example:: |
| 60 |
|
| 61 |
from django.db import models |
| 62 |
|
| 63 |
|
| 64 |
class Question(models.Model): |
| 65 |
text = models.TextField(db_comment="Poll question") |
| 66 |
pub_date = models.DateTimeField( |
| 67 |
db_comment="Date and time when the question was published", |
| 68 |
) |
| 69 |
|
| 70 |
class Meta: |
| 71 |
db_table_comment = "Poll questions" |
| 72 |
|
| 73 |
|
| 74 |
class Answer(models.Model): |
| 75 |
question = models.ForeignKey( |
| 76 |
Question, |
| 77 |
on_delete=models.CASCADE, |
| 78 |
db_comment="Reference to a question", |
| 79 |
) |
| 80 |
answer = models.TextField(db_comment="Question answer") |
| 81 |
|
| 82 |
class Meta: |
| 83 |
db_table_comment = "Question answers" |
| 84 |
|
| 85 |
Also, the new :class:`~django.db.migrations.operations.AlterModelTableComment` |
| 86 |
operation allows changing table comments defined in the |
| 87 |
:attr:`Meta.db_table_comment <django.db.models.Options.db_table_comment>`. |
| 88 |
|
| 89 |
Mitigation for the BREACH attack |
| 90 |
-------------------------------- |
| 91 |
|
| 92 |
:class:`~django.middleware.gzip.GZipMiddleware` now includes a mitigation for |
| 93 |
the BREACH attack. It will add up to 100 random bytes to gzip responses to make |
| 94 |
BREACH attacks harder. Read more about the mitigation technique in the `Heal |
| 95 |
The Breach (HTB) paper`_. |
| 96 |
|
| 97 |
.. _Heal The Breach (HTB) paper: https://ieeexplore.ieee.org/document/9754554 |
| 98 |
|
| 99 |
In-memory file storage |
| 100 |
---------------------- |
| 101 |
|
| 102 |
The new :class:`django.core.files.storage.InMemoryStorage` class provides a |
| 103 |
non-persistent storage useful for speeding up tests by avoiding disk access. |
| 104 |
|
| 105 |
Custom file storages |
| 106 |
-------------------- |
| 107 |
|
| 108 |
The new :setting:`STORAGES` setting allows configuring multiple custom file |
| 109 |
storage backends. It also controls storage engines for managing |
| 110 |
:doc:`files </topics/files>` (the ``"default"`` key) and :doc:`static files |
| 111 |
</ref/contrib/staticfiles>` (the ``"staticfiles"`` key). |
| 112 |
|
| 113 |
The old ``DEFAULT_FILE_STORAGE`` and ``STATICFILES_STORAGE`` settings are |
| 114 |
deprecated as of this release. |
| 115 |
|
| 116 |
Minor features |
| 117 |
-------------- |
| 118 |
|
| 119 |
:mod:`django.contrib.admin` |
| 120 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 121 |
|
| 122 |
* The light or dark color theme of the admin can now be toggled in the UI, as |
| 123 |
well as being set to follow the system setting. |
| 124 |
|
| 125 |
* The admin's font stack now prefers system UI fonts and no longer requires |
| 126 |
downloading fonts. Additionally, CSS variables are available to more easily |
| 127 |
override the default font families. |
| 128 |
|
| 129 |
* The :source:`admin/delete_confirmation.html |
| 130 |
<django/contrib/admin/templates/admin/delete_confirmation.html>` template now |
| 131 |
has some additional blocks and scripting hooks to ease customization. |
| 132 |
|
| 133 |
* The chosen options of |
| 134 |
:attr:`~django.contrib.admin.ModelAdmin.filter_horizontal` and |
| 135 |
:attr:`~django.contrib.admin.ModelAdmin.filter_vertical` widgets are now |
| 136 |
filterable. |
| 137 |
|
| 138 |
* The ``admin/base.html`` template now has a new block ``nav-breadcrumbs`` |
| 139 |
which contains the navigation landmark and the ``breadcrumbs`` block. |
| 140 |
|
| 141 |
* :attr:`.ModelAdmin.list_editable` now uses atomic transactions when making |
| 142 |
edits. |
| 143 |
|
| 144 |
* jQuery is upgraded from version 3.6.0 to 3.6.4. |
| 145 |
|
| 146 |
:mod:`django.contrib.auth` |
| 147 |
~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 148 |
|
| 149 |
* The default iteration count for the PBKDF2 password hasher is increased from |
| 150 |
390,000 to 600,000. |
| 151 |
|
| 152 |
* :class:`~django.contrib.auth.forms.UserCreationForm` now saves many-to-many |
| 153 |
form fields for a custom user model. |
| 154 |
|
| 155 |
* The new :class:`~django.contrib.auth.forms.BaseUserCreationForm` is now the |
| 156 |
recommended base class for customizing the user creation form. |
| 157 |
|
| 158 |
:mod:`django.contrib.gis` |
| 159 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 160 |
|
| 161 |
* The :doc:`GeoJSON serializer </ref/contrib/gis/serializers>` now outputs the |
| 162 |
``id`` key for serialized features, which defaults to the primary key of |
| 163 |
objects. |
| 164 |
|
| 165 |
* The :class:`~django.contrib.gis.gdal.GDALRaster` class now supports |
| 166 |
:class:`pathlib.Path`. |
| 167 |
|
| 168 |
* The :class:`~django.contrib.gis.geoip2.GeoIP2` class now supports ``.mmdb`` |
| 169 |
files downloaded from DB-IP. |
| 170 |
|
| 171 |
* The OpenLayers template widget no longer includes inline CSS (which also |
| 172 |
removes the former ``map_css`` block) to better comply with a strict Content |
| 173 |
Security Policy. |
| 174 |
|
| 175 |
* :class:`~django.contrib.gis.forms.widgets.OpenLayersWidget` is now based on |
| 176 |
OpenLayers 7.2.2 (previously 4.6.5). |
| 177 |
|
| 178 |
* The new :lookup:`isempty` lookup and |
| 179 |
:class:`IsEmpty() <django.contrib.gis.db.models.functions.IsEmpty>` |
| 180 |
expression allow filtering empty geometries on PostGIS. |
| 181 |
|
| 182 |
* The new :class:`FromWKB() <django.contrib.gis.db.models.functions.FromWKB>` |
| 183 |
and :class:`FromWKT() <django.contrib.gis.db.models.functions.FromWKT>` |
| 184 |
functions allow creating geometries from Well-known binary (WKB) and |
| 185 |
Well-known text (WKT) representations. |
| 186 |
|
| 187 |
:mod:`django.contrib.postgres` |
| 188 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 189 |
|
| 190 |
* The new :lookup:`trigram_strict_word_similar` lookup, and the |
| 191 |
:class:`TrigramStrictWordSimilarity() |
| 192 |
<django.contrib.postgres.search.TrigramStrictWordSimilarity>` and |
| 193 |
:class:`TrigramStrictWordDistance() |
| 194 |
<django.contrib.postgres.search.TrigramStrictWordDistance>` expressions allow |
| 195 |
using trigram strict word similarity. |
| 196 |
|
| 197 |
* The :lookup:`arrayfield.overlap` lookup now supports ``QuerySet.values()`` |
| 198 |
and ``values_list()`` as a right-hand side. |
| 199 |
|
| 200 |
:mod:`django.contrib.sitemaps` |
| 201 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 202 |
|
| 203 |
* The new :meth:`.Sitemap.get_languages_for_item` method allows customizing the |
| 204 |
list of languages for which the item is displayed. |
| 205 |
|
| 206 |
:mod:`django.contrib.staticfiles` |
| 207 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 208 |
|
| 209 |
* :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` now |
| 210 |
has experimental support for replacing paths to JavaScript modules in |
| 211 |
``import`` and ``export`` statements with their hashed counterparts. If you |
| 212 |
want to try it, subclass ``ManifestStaticFilesStorage`` and set the |
| 213 |
``support_js_module_import_aggregation`` attribute to ``True``. |
| 214 |
|
| 215 |
* The new :attr:`.ManifestStaticFilesStorage.manifest_hash` attribute provides |
| 216 |
a hash over all files in the manifest and changes whenever one of the files |
| 217 |
changes. |
| 218 |
|
| 219 |
Database backends |
| 220 |
~~~~~~~~~~~~~~~~~ |
| 221 |
|
| 222 |
* The new ``"assume_role"`` option is now supported in :setting:`OPTIONS` on |
| 223 |
PostgreSQL to allow specifying the :ref:`session role <database-role>`. |
| 224 |
|
| 225 |
* The new ``"server_side_binding"`` option is now supported in |
| 226 |
:setting:`OPTIONS` on PostgreSQL with ``psycopg`` 3.1.8+ to allow using |
| 227 |
:ref:`server-side binding cursors <database-server-side-parameters-binding>`. |
| 228 |
|
| 229 |
Error Reporting |
| 230 |
~~~~~~~~~~~~~~~ |
| 231 |
|
| 232 |
* The debug page now shows :pep:`exception notes <678>` and |
| 233 |
:pep:`fine-grained error locations <657>` on Python 3.11+. |
| 234 |
|
| 235 |
* Session cookies are now treated as credentials and therefore hidden and |
| 236 |
replaced with stars (``**********``) in error reports. |
| 237 |
|
| 238 |
Forms |
| 239 |
~~~~~ |
| 240 |
|
| 241 |
* :class:`~django.forms.ModelForm` now accepts the new ``Meta`` option |
| 242 |
``formfield_callback`` to customize form fields. |
| 243 |
|
| 244 |
* :func:`~django.forms.models.modelform_factory` now respects the |
| 245 |
``formfield_callback`` attribute of the ``form``’s ``Meta``. |
| 246 |
|
| 247 |
Internationalization |
| 248 |
~~~~~~~~~~~~~~~~~~~~ |
| 249 |
|
| 250 |
* Added support and translations for the Central Kurdish (Sorani) language. |
| 251 |
|
| 252 |
Logging |
| 253 |
~~~~~~~ |
| 254 |
|
| 255 |
* The :ref:`django-db-logger` logger now logs transaction management queries |
| 256 |
(``BEGIN``, ``COMMIT``, and ``ROLLBACK``) at the ``DEBUG`` level. |
| 257 |
|
| 258 |
Management Commands |
| 259 |
~~~~~~~~~~~~~~~~~~~ |
| 260 |
|
| 261 |
* :djadmin:`makemessages` command now supports locales with private sub-tags |
| 262 |
such as ``nl_NL-x-informal``. |
| 263 |
|
| 264 |
* The new :option:`makemigrations --update` option merges model changes into |
| 265 |
the latest migration and optimizes the resulting operations. |
| 266 |
|
| 267 |
Migrations |
| 268 |
~~~~~~~~~~ |
| 269 |
|
| 270 |
* Migrations now support serialization of ``enum.Flag`` objects. |
| 271 |
|
| 272 |
Models |
| 273 |
~~~~~~ |
| 274 |
|
| 275 |
* ``QuerySet`` now extensively supports filtering against |
| 276 |
:ref:`window-functions` with the exception of disjunctive filter lookups |
| 277 |
against window functions when performing aggregation. |
| 278 |
|
| 279 |
* :meth:`~.QuerySet.prefetch_related` now supports |
| 280 |
:class:`~django.db.models.Prefetch` objects with sliced querysets. |
| 281 |
|
| 282 |
* :ref:`Registering lookups <lookup-registration-api>` on |
| 283 |
:class:`~django.db.models.Field` instances is now supported. |
| 284 |
|
| 285 |
* The new ``robust`` argument for :func:`~django.db.transaction.on_commit` |
| 286 |
allows performing actions that can fail after a database transaction is |
| 287 |
successfully committed. |
| 288 |
|
| 289 |
* The new :class:`KT() <django.db.models.fields.json.KT>` expression represents |
| 290 |
the text value of a key, index, or path transform of |
| 291 |
:class:`~django.db.models.JSONField`. |
| 292 |
|
| 293 |
* :class:`~django.db.models.functions.Now` now supports microsecond precision |
| 294 |
on MySQL and millisecond precision on SQLite. |
| 295 |
|
| 296 |
* :class:`F() <django.db.models.F>` expressions that output ``BooleanField`` |
| 297 |
can now be negated using ``~F()`` (inversion operator). |
| 298 |
|
| 299 |
* ``Model`` now provides asynchronous versions of some methods that use the |
| 300 |
database, using an ``a`` prefix: :meth:`~.Model.adelete`, |
| 301 |
:meth:`~.Model.arefresh_from_db`, and :meth:`~.Model.asave`. |
| 302 |
|
| 303 |
* Related managers now provide asynchronous versions of methods that change a |
| 304 |
set of related objects, using an ``a`` prefix: :meth:`~.RelatedManager.aadd`, |
| 305 |
:meth:`~.RelatedManager.aclear`, :meth:`~.RelatedManager.aremove`, and |
| 306 |
:meth:`~.RelatedManager.aset`. |
| 307 |
|
| 308 |
* :attr:`CharField.max_length <django.db.models.CharField.max_length>` is no |
| 309 |
longer required to be set on PostgreSQL, which supports unlimited ``VARCHAR`` |
| 310 |
columns. |
| 311 |
|
| 312 |
Requests and Responses |
| 313 |
~~~~~~~~~~~~~~~~~~~~~~ |
| 314 |
|
| 315 |
* :class:`~django.http.StreamingHttpResponse` now supports async iterators |
| 316 |
when Django is served via ASGI. |
| 317 |
|
| 318 |
Tests |
| 319 |
~~~~~ |
| 320 |
|
| 321 |
* The :option:`test --debug-sql` option now formats SQL queries with |
| 322 |
``sqlparse``. |
| 323 |
|
| 324 |
* The :class:`~django.test.RequestFactory`, |
| 325 |
:class:`~django.test.AsyncRequestFactory`, :class:`~django.test.Client`, and |
| 326 |
:class:`~django.test.AsyncClient` classes now support the ``headers`` |
| 327 |
parameter, which accepts a dictionary of header names and values. This allows |
| 328 |
a more natural syntax for declaring headers. |
| 329 |
|
| 330 |
.. code-block:: python |
| 331 |
|
| 332 |
# Before: |
| 333 |
self.client.get("/home/", HTTP_ACCEPT_LANGUAGE="fr") |
| 334 |
await self.async_client.get("/home/", ACCEPT_LANGUAGE="fr") |
| 335 |
|
| 336 |
# After: |
| 337 |
self.client.get("/home/", headers={"accept-language": "fr"}) |
| 338 |
await self.async_client.get("/home/", headers={"accept-language": "fr"}) |
| 339 |
|
| 340 |
Utilities |
| 341 |
~~~~~~~~~ |
| 342 |
|
| 343 |
* The new ``encoder`` parameter for :meth:`django.utils.html.json_script` |
| 344 |
function allows customizing a JSON encoder class. |
| 345 |
|
| 346 |
* The private internal vendored copy of ``urllib.parse.urlsplit()`` now strips |
| 347 |
``'\r'``, ``'\n'``, and ``'\t'`` (see :cve:`2022-0391` and :bpo:`43882`). |
| 348 |
This is to protect projects that may be incorrectly using the internal |
| 349 |
``url_has_allowed_host_and_scheme()`` function, instead of using one of the |
| 350 |
documented functions for handling URL redirects. The Django functions were |
| 351 |
not affected. |
| 352 |
|
| 353 |
* The new :func:`django.utils.http.content_disposition_header` function returns |
| 354 |
a ``Content-Disposition`` HTTP header value as specified by :rfc:`6266`. |
| 355 |
|
| 356 |
Validators |
| 357 |
~~~~~~~~~~ |
| 358 |
|
| 359 |
* The list of common passwords used by ``CommonPasswordValidator`` is updated |
| 360 |
to the most recent version. |
| 361 |
|
| 362 |
.. _backwards-incompatible-4.2: |
| 363 |
|
| 364 |
Backwards incompatible changes in 4.2 |
| 365 |
===================================== |
| 366 |
|
| 367 |
Database backend API |
| 368 |
-------------------- |
| 369 |
|
| 370 |
This section describes changes that may be needed in third-party database |
| 371 |
backends. |
| 372 |
|
| 373 |
* ``DatabaseFeatures.allows_group_by_pk`` is removed as it only remained to |
| 374 |
accommodate a MySQL extension that has been supplanted by proper functional |
| 375 |
dependency detection in MySQL 5.7.15. Note that |
| 376 |
``DatabaseFeatures.allows_group_by_selected_pks`` is still supported and |
| 377 |
should be enabled if your backend supports functional dependency detection in |
| 378 |
``GROUP BY`` clauses as specified by the ``SQL:1999`` standard. |
| 379 |
|
| 380 |
* :djadmin:`inspectdb` now uses ``display_size`` from |
| 381 |
``DatabaseIntrospection.get_table_description()`` rather than |
| 382 |
``internal_size`` for ``CharField``. |
| 383 |
|
| 384 |
Dropped support for MariaDB 10.3 |
| 385 |
-------------------------------- |
| 386 |
|
| 387 |
Upstream support for MariaDB 10.3 ends in May 2023. Django 4.2 supports MariaDB |
| 388 |
10.4 and higher. |
| 389 |
|
| 390 |
Dropped support for MySQL 5.7 |
| 391 |
----------------------------- |
| 392 |
|
| 393 |
Upstream support for MySQL 5.7 ends in October 2023. Django 4.2 supports MySQL |
| 394 |
8 and higher. |
| 395 |
|
| 396 |
Dropped support for PostgreSQL 11 |
| 397 |
--------------------------------- |
| 398 |
|
| 399 |
Upstream support for PostgreSQL 11 ends in November 2023. Django 4.2 supports |
| 400 |
PostgreSQL 12 and higher. |
| 401 |
|
| 402 |
Setting ``update_fields`` in ``Model.save()`` may now be required |
| 403 |
----------------------------------------------------------------- |
| 404 |
|
| 405 |
In order to avoid updating unnecessary columns, |
| 406 |
:meth:`.QuerySet.update_or_create` now passes ``update_fields`` to the |
| 407 |
:meth:`Model.save() <django.db.models.Model.save>` calls. As a consequence, any |
| 408 |
fields modified in the custom ``save()`` methods should be added to the |
| 409 |
``update_fields`` keyword argument before calling ``super()``. See |
| 410 |
:ref:`overriding-model-methods` for more details. |
| 411 |
|
| 412 |
Dropped support for raw aggregations on MySQL |
| 413 |
--------------------------------------------- |
| 414 |
|
| 415 |
MySQL 8+ allows functional dependencies on ``GROUP BY`` columns, so the |
| 416 |
pre-Django 4.2 workaround of grouping by primary keys of the main table is |
| 417 |
removed. As a consequence, using ``RawSQL()`` aggregations is no longer |
| 418 |
supported on MySQL as there is no way to determine if such aggregations are |
| 419 |
needed or valid in the ``GROUP BY`` clause. Use :ref:`aggregation-functions` |
| 420 |
instead. |
| 421 |
|
| 422 |
Miscellaneous |
| 423 |
------------- |
| 424 |
|
| 425 |
* The undocumented ``django.http.multipartparser.parse_header()`` function is |
| 426 |
removed. Use ``django.utils.http.parse_header_parameters()`` instead. |
| 427 |
|
| 428 |
* :ttag:`{% blocktranslate asvar … %}<blocktranslate>` result is now marked as |
| 429 |
safe for (HTML) output purposes. |
| 430 |
|
| 431 |
* The ``autofocus`` HTML attribute in the admin search box is removed as it can |
| 432 |
be confusing for screen readers. |
| 433 |
|
| 434 |
* The :option:`makemigrations --check` option no longer creates missing |
| 435 |
migration files. |
| 436 |
|
| 437 |
* The ``alias`` argument for :meth:`.Expression.get_group_by_cols` is removed. |
| 438 |
|
| 439 |
* The minimum supported version of ``sqlparse`` is increased from 0.2.2 to |
| 440 |
0.3.1. |
| 441 |
|
| 442 |
* The undocumented ``negated`` parameter of the |
| 443 |
:class:`~django.db.models.Exists` expression is removed. |
| 444 |
|
| 445 |
* The ``is_summary`` argument of the undocumented ``Query.add_annotation()`` |
| 446 |
method is removed. |
| 447 |
|
| 448 |
* The minimum supported version of SQLite is increased from 3.9.0 to 3.21.0. |
| 449 |
|
| 450 |
* The minimum supported version of ``asgiref`` is increased from 3.5.2 to |
| 451 |
3.6.0. |
| 452 |
|
| 453 |
* :class:`~django.contrib.auth.forms.UserCreationForm` now rejects usernames |
| 454 |
that differ only in case. If you need the previous behavior, use |
| 455 |
:class:`~django.contrib.auth.forms.BaseUserCreationForm` instead. |
| 456 |
|
| 457 |
* The minimum supported version of ``mysqlclient`` is increased from 1.4.0 to |
| 458 |
1.4.3. |
| 459 |
|
| 460 |
* The minimum supported version of ``argon2-cffi`` is increased from 19.1.0 to |
| 461 |
19.2.0. |
| 462 |
|
| 463 |
* The minimum supported version of ``Pillow`` is increased from 6.2.0 to 6.2.1. |
| 464 |
|
| 465 |
* The minimum supported version of ``jinja2`` is increased from 2.9.2 to |
| 466 |
2.11.0. |
| 467 |
|
| 468 |
* The minimum supported version of :pypi:`redis-py <redis>` is increased from |
| 469 |
3.0.0 to 3.4.0. |
| 470 |
|
| 471 |
* Manually instantiated ``WSGIRequest`` objects must be provided a file-like |
| 472 |
object for ``wsgi.input``. Previously, Django was more lax than the expected |
| 473 |
behavior as specified by the WSGI specification. |
| 474 |
|
| 475 |
* Support for ``PROJ`` < 5 is removed. |
| 476 |
|
| 477 |
* :class:`~django.core.mail.backends.smtp.EmailBackend` now verifies a |
| 478 |
:py:attr:`hostname <ssl.SSLContext.check_hostname>` and |
| 479 |
:py:attr:`certificates <ssl.SSLContext.verify_mode>`. If you need the |
| 480 |
previous behavior that is less restrictive and not recommended, subclass |
| 481 |
``EmailBackend`` and override the ``ssl_context`` property. |
| 482 |
|
| 483 |
.. _deprecated-features-4.2: |
| 484 |
|
| 485 |
Features deprecated in 4.2 |
| 486 |
========================== |
| 487 |
|
| 488 |
``index_together`` option is deprecated in favor of ``indexes`` |
| 489 |
--------------------------------------------------------------- |
| 490 |
|
| 491 |
The ``Meta.index_together`` option is deprecated in favor of the |
| 492 |
:attr:`~django.db.models.Options.indexes` option. |
| 493 |
|
| 494 |
Migrating existing ``index_together`` should be handled as a migration. For |
| 495 |
example:: |
| 496 |
|
| 497 |
class Author(models.Model): |
| 498 |
rank = models.IntegerField() |
| 499 |
name = models.CharField(max_length=30) |
| 500 |
|
| 501 |
class Meta: |
| 502 |
index_together = [["rank", "name"]] |
| 503 |
|
| 504 |
Should become:: |
| 505 |
|
| 506 |
class Author(models.Model): |
| 507 |
rank = models.IntegerField() |
| 508 |
name = models.CharField(max_length=30) |
| 509 |
|
| 510 |
class Meta: |
| 511 |
indexes = [models.Index(fields=["rank", "name"])] |
| 512 |
|
| 513 |
Running the :djadmin:`makemigrations` command will generate a migration |
| 514 |
containing a :class:`~django.db.migrations.operations.RenameIndex` operation |
| 515 |
which will rename the existing index. Next, consider squashing migrations to |
| 516 |
remove ``index_together`` from historical migrations. |
| 517 |
|
| 518 |
The ``AlterIndexTogether`` migration operation is now officially supported only |
| 519 |
for pre-Django 4.2 migration files. For backward compatibility reasons, it's |
| 520 |
still part of the public API, and there's no plan to deprecate or remove it, |
| 521 |
but it should not be used for new migrations. Use |
| 522 |
:class:`~django.db.migrations.operations.AddIndex` and |
| 523 |
:class:`~django.db.migrations.operations.RemoveIndex` operations instead. |
| 524 |
|
| 525 |
Passing encoded JSON string literals to ``JSONField`` is deprecated |
| 526 |
------------------------------------------------------------------- |
| 527 |
|
| 528 |
``JSONField`` and its associated lookups and aggregates used to allow passing |
| 529 |
JSON encoded string literals which caused ambiguity on whether string literals |
| 530 |
were already encoded from database backend's perspective. |
| 531 |
|
| 532 |
During the deprecation period string literals will be attempted to be JSON |
| 533 |
decoded and a warning will be emitted on success that points at passing |
| 534 |
non-encoded forms instead. |
| 535 |
|
| 536 |
Code that used to pass JSON encoded string literals:: |
| 537 |
|
| 538 |
Document.objects.bulk_create( |
| 539 |
Document(data=Value("null")), |
| 540 |
Document(data=Value("[]")), |
| 541 |
Document(data=Value('"foo-bar"')), |
| 542 |
) |
| 543 |
Document.objects.annotate( |
| 544 |
JSONBAgg("field", default=Value("[]")), |
| 545 |
) |
| 546 |
|
| 547 |
Should become:: |
| 548 |
|
| 549 |
Document.objects.bulk_create( |
| 550 |
Document(data=Value(None, JSONField())), |
| 551 |
Document(data=[]), |
| 552 |
Document(data="foo-bar"), |
| 553 |
) |
| 554 |
Document.objects.annotate( |
| 555 |
JSONBAgg("field", default=[]), |
| 556 |
) |
| 557 |
|
| 558 |
From Django 5.1+ string literals will be implicitly interpreted as JSON string |
| 559 |
literals. |
| 560 |
|
| 561 |
Miscellaneous |
| 562 |
------------- |
| 563 |
|
| 564 |
* The ``BaseUserManager.make_random_password()`` method is deprecated. See |
| 565 |
`recipes and best practices |
| 566 |
<https://docs.python.org/3/library/secrets.html#recipes-and-best-practices>`_ |
| 567 |
for using Python's :py:mod:`secrets` module to generate passwords. |
| 568 |
|
| 569 |
* The ``length_is`` template filter is deprecated in favor of :tfilter:`length` |
| 570 |
and the ``==`` operator within an :ttag:`{% if %}<if>` tag. For example |
| 571 |
|
| 572 |
.. code-block:: html+django |
| 573 |
|
| 574 |
{% if value|length == 4 %}…{% endif %} |
| 575 |
{% if value|length == 4 %}True{% else %}False{% endif %} |
| 576 |
|
| 577 |
instead of: |
| 578 |
|
| 579 |
.. code-block:: html+django |
| 580 |
|
| 581 |
{% if value|length_is:4 %}…{% endif %} |
| 582 |
{{ value|length_is:4 }} |
| 583 |
|
| 584 |
* ``django.contrib.auth.hashers.SHA1PasswordHasher``, |
| 585 |
``django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher``, and |
| 586 |
``django.contrib.auth.hashers.UnsaltedMD5PasswordHasher`` are deprecated. |
| 587 |
|
| 588 |
* ``django.contrib.postgres.fields.CICharField`` is deprecated in favor of |
| 589 |
``CharField(db_collation="…")`` with a case-insensitive non-deterministic |
| 590 |
collation. |
| 591 |
|
| 592 |
* ``django.contrib.postgres.fields.CIEmailField`` is deprecated in favor of |
| 593 |
``EmailField(db_collation="…")`` with a case-insensitive non-deterministic |
| 594 |
collation. |
| 595 |
|
| 596 |
* ``django.contrib.postgres.fields.CITextField`` is deprecated in favor of |
| 597 |
``TextField(db_collation="…")`` with a case-insensitive non-deterministic |
| 598 |
collation. |
| 599 |
|
| 600 |
* ``django.contrib.postgres.fields.CIText`` mixin is deprecated. |
| 601 |
|
| 602 |
* The ``map_height`` and ``map_width`` attributes of ``BaseGeometryWidget`` are |
| 603 |
deprecated, use CSS to size map widgets instead. |
| 604 |
|
| 605 |
* ``SimpleTestCase.assertFormsetError()`` is deprecated in favor of |
| 606 |
``assertFormSetError()``. |
| 607 |
|
| 608 |
* ``TransactionTestCase.assertQuerysetEqual()`` is deprecated in favor of |
| 609 |
``assertQuerySetEqual()``. |
| 610 |
|
| 611 |
* Passing positional arguments to ``Signer`` and ``TimestampSigner`` is |
| 612 |
deprecated in favor of keyword-only arguments. |
| 613 |
|
| 614 |
* The ``DEFAULT_FILE_STORAGE`` setting is deprecated in favor of |
| 615 |
``STORAGES["default"]``. |
| 616 |
|
| 617 |
* The ``STATICFILES_STORAGE`` setting is deprecated in favor of |
| 618 |
``STORAGES["staticfiles"]``. |
| 619 |
|
| 620 |
* The ``django.core.files.storage.get_storage_class()`` function is deprecated. |