| 1 |
======================== |
| 2 |
Django 4.1 release notes |
| 3 |
======================== |
| 4 |
|
| 5 |
*August 3, 2022* |
| 6 |
|
| 7 |
Welcome to Django 4.1! |
| 8 |
|
| 9 |
These release notes cover the :ref:`new features <whats-new-4.1>`, as well as |
| 10 |
some :ref:`backwards incompatible changes <backwards-incompatible-4.1>` you'll |
| 11 |
want to be aware of when upgrading from Django 4.0 or earlier. We've |
| 12 |
:ref:`begun the deprecation process for some features |
| 13 |
<deprecated-features-4.1>`. |
| 14 |
|
| 15 |
See the :doc:`/howto/upgrade-version` guide if you're updating an existing |
| 16 |
project. |
| 17 |
|
| 18 |
Python compatibility |
| 19 |
==================== |
| 20 |
|
| 21 |
Django 4.1 supports Python 3.8, 3.9, 3.10, and 3.11 (as of 4.1.3). We |
| 22 |
**highly recommend** and only officially support the latest release of each |
| 23 |
series. |
| 24 |
|
| 25 |
.. _whats-new-4.1: |
| 26 |
|
| 27 |
What's new in Django 4.1 |
| 28 |
======================== |
| 29 |
|
| 30 |
Asynchronous handlers for class-based views |
| 31 |
------------------------------------------- |
| 32 |
|
| 33 |
View subclasses may now define async HTTP method handlers:: |
| 34 |
|
| 35 |
import asyncio |
| 36 |
from django.http import HttpResponse |
| 37 |
from django.views import View |
| 38 |
|
| 39 |
|
| 40 |
class AsyncView(View): |
| 41 |
async def get(self, request, *args, **kwargs): |
| 42 |
# Perform view logic using await. |
| 43 |
await asyncio.sleep(1) |
| 44 |
return HttpResponse("Hello async world!") |
| 45 |
|
| 46 |
See :ref:`async-class-based-views` for more details. |
| 47 |
|
| 48 |
Asynchronous ORM interface |
| 49 |
-------------------------- |
| 50 |
|
| 51 |
``QuerySet`` now provides an asynchronous interface for all data access |
| 52 |
operations. These are named as-per the existing synchronous operations but with |
| 53 |
an ``a`` prefix, for example ``acreate()``, ``aget()``, and so on. |
| 54 |
|
| 55 |
The new interface allows you to write asynchronous code without needing to wrap |
| 56 |
ORM operations in ``sync_to_async()``:: |
| 57 |
|
| 58 |
async for author in Author.objects.filter(name__startswith="A"): |
| 59 |
book = await author.books.afirst() |
| 60 |
|
| 61 |
Note that, at this stage, the underlying database operations remain |
| 62 |
synchronous, with contributions ongoing to push asynchronous support down into |
| 63 |
the SQL compiler, and integrate asynchronous database drivers. The new |
| 64 |
asynchronous queryset interface currently encapsulates the necessary |
| 65 |
``sync_to_async()`` operations for you, and will allow your code to take |
| 66 |
advantage of developments in the ORM's asynchronous support as it evolves. |
| 67 |
|
| 68 |
See :ref:`async-queries` for details and limitations. |
| 69 |
|
| 70 |
Validation of Constraints |
| 71 |
------------------------- |
| 72 |
|
| 73 |
:class:`Check <django.db.models.CheckConstraint>`, |
| 74 |
:class:`unique <django.db.models.UniqueConstraint>`, and :class:`exclusion |
| 75 |
<django.contrib.postgres.constraints.ExclusionConstraint>` constraints defined |
| 76 |
in the :attr:`Meta.constraints <django.db.models.Options.constraints>` option |
| 77 |
are now checked during :ref:`model validation <validating-objects>`. |
| 78 |
|
| 79 |
Form rendering accessibility |
| 80 |
---------------------------- |
| 81 |
|
| 82 |
In order to aid users with screen readers, and other assistive technology, new |
| 83 |
``<div>`` based form templates are available from this release. These provide |
| 84 |
more accessible navigation than the older templates, and are able to correctly |
| 85 |
group related controls, such as radio-lists, into fieldsets. |
| 86 |
|
| 87 |
The new templates are recommended, and will become the default form rendering |
| 88 |
style when outputting a form, like ``{{ form }}`` in a template, from Django |
| 89 |
5.0. |
| 90 |
|
| 91 |
In order to ease adopting the new output style, the default form and formset |
| 92 |
templates are now configurable at the project level via the |
| 93 |
:setting:`FORM_RENDERER` setting. |
| 94 |
|
| 95 |
See :ref:`the Forms section (below)<forms-4.1>` for full details. |
| 96 |
|
| 97 |
.. _csrf-cookie-masked-usage: |
| 98 |
|
| 99 |
``CSRF_COOKIE_MASKED`` setting |
| 100 |
------------------------------ |
| 101 |
|
| 102 |
The new ``CSRF_COOKIE_MASKED`` transitional setting allows specifying whether |
| 103 |
to mask the CSRF cookie. |
| 104 |
|
| 105 |
:class:`~django.middleware.csrf.CsrfViewMiddleware` no longer masks the CSRF |
| 106 |
cookie like it does the CSRF token in the DOM. If you are upgrading multiple |
| 107 |
instances of the same project to Django 4.1, you should set |
| 108 |
``CSRF_COOKIE_MASKED`` to ``True`` during the transition, in order to allow |
| 109 |
compatibility with the older versions of Django. Once the transition to 4.1 is |
| 110 |
complete you can stop overriding ``CSRF_COOKIE_MASKED``. |
| 111 |
|
| 112 |
This setting is deprecated as of this release and will be removed in Django |
| 113 |
5.0. |
| 114 |
|
| 115 |
Minor features |
| 116 |
-------------- |
| 117 |
|
| 118 |
:mod:`django.contrib.admin` |
| 119 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 120 |
|
| 121 |
* The admin :ref:`dark mode CSS variables <admin-theming>` are now applied in a |
| 122 |
separate stylesheet and template block. |
| 123 |
|
| 124 |
* :ref:`modeladmin-list-filters` providing custom ``FieldListFilter`` |
| 125 |
subclasses can now control the query string value separator when filtering |
| 126 |
for multiple values using the ``__in`` lookup. |
| 127 |
|
| 128 |
* The admin :meth:`history view <django.contrib.admin.ModelAdmin.history_view>` |
| 129 |
is now paginated. |
| 130 |
|
| 131 |
* Related widget wrappers now have a link to object's change form. |
| 132 |
|
| 133 |
* The :meth:`.AdminSite.get_app_list` method now allows changing the order of |
| 134 |
apps and models on the admin index page. |
| 135 |
|
| 136 |
:mod:`django.contrib.auth` |
| 137 |
~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 138 |
|
| 139 |
* The default iteration count for the PBKDF2 password hasher is increased from |
| 140 |
320,000 to 390,000. |
| 141 |
|
| 142 |
* The :meth:`.RemoteUserBackend.configure_user` method now allows synchronizing |
| 143 |
user attributes with attributes in a remote system such as an LDAP directory. |
| 144 |
|
| 145 |
:mod:`django.contrib.gis` |
| 146 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 147 |
|
| 148 |
* The new :meth:`.GEOSGeometry.make_valid()` method allows converting invalid |
| 149 |
geometries to valid ones. |
| 150 |
|
| 151 |
* The new ``clone`` argument for :meth:`.GEOSGeometry.normalize` allows |
| 152 |
creating a normalized clone of the geometry. |
| 153 |
|
| 154 |
:mod:`django.contrib.postgres` |
| 155 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 156 |
|
| 157 |
* The new :class:`BitXor() <django.contrib.postgres.aggregates.BitXor>` |
| 158 |
aggregate function returns an ``int`` of the bitwise ``XOR`` of all non-null |
| 159 |
input values. |
| 160 |
|
| 161 |
* :class:`~django.contrib.postgres.indexes.SpGistIndex` now supports covering |
| 162 |
indexes on PostgreSQL 14+. |
| 163 |
|
| 164 |
* :class:`~django.contrib.postgres.constraints.ExclusionConstraint` now |
| 165 |
supports covering exclusion constraints using SP-GiST indexes on PostgreSQL |
| 166 |
14+. |
| 167 |
|
| 168 |
* The new ``default_bounds`` attribute of :attr:`DateTimeRangeField |
| 169 |
<django.contrib.postgres.fields.DateTimeRangeField.default_bounds>` and |
| 170 |
:attr:`DecimalRangeField |
| 171 |
<django.contrib.postgres.fields.DecimalRangeField.default_bounds>` allows |
| 172 |
specifying bounds for list and tuple inputs. |
| 173 |
|
| 174 |
* :class:`~django.contrib.postgres.constraints.ExclusionConstraint` now allows |
| 175 |
specifying operator classes with the |
| 176 |
:class:`OpClass() <django.contrib.postgres.indexes.OpClass>` expression. |
| 177 |
|
| 178 |
:mod:`django.contrib.sitemaps` |
| 179 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 180 |
|
| 181 |
* The default sitemap index template ``<sitemapindex>`` now includes the |
| 182 |
``<lastmod>`` timestamp where available, through the new |
| 183 |
:meth:`~django.contrib.sitemaps.Sitemap.get_latest_lastmod` method. Custom |
| 184 |
sitemap index templates should be updated for the adjusted :ref:`context |
| 185 |
variables <sitemap-index-context-variables>`. |
| 186 |
|
| 187 |
:mod:`django.contrib.staticfiles` |
| 188 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 189 |
|
| 190 |
* :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` now |
| 191 |
replaces paths to CSS source map references with their hashed counterparts. |
| 192 |
|
| 193 |
Database backends |
| 194 |
~~~~~~~~~~~~~~~~~ |
| 195 |
|
| 196 |
* Third-party database backends can now specify the minimum required version of |
| 197 |
the database using the ``DatabaseFeatures.minimum_database_version`` |
| 198 |
attribute which is a tuple (e.g. ``(10, 0)`` means "10.0"). If a minimum |
| 199 |
version is specified, backends must also implement |
| 200 |
``DatabaseWrapper.get_database_version()``, which returns a tuple of the |
| 201 |
current database version. The backend's |
| 202 |
``DatabaseWrapper.init_connection_state()`` method must call ``super()`` in |
| 203 |
order for the check to run. |
| 204 |
|
| 205 |
.. _forms-4.1: |
| 206 |
|
| 207 |
Forms |
| 208 |
~~~~~ |
| 209 |
|
| 210 |
* The default template used to render forms when cast to a string, e.g. in |
| 211 |
templates as ``{{ form }}``, is now configurable at the project-level by |
| 212 |
setting :attr:`~django.forms.renderers.BaseRenderer.form_template_name` on |
| 213 |
the class provided for :setting:`FORM_RENDERER`. |
| 214 |
|
| 215 |
:attr:`.Form.template_name` is now a property deferring to the renderer, but |
| 216 |
may be overridden with a string value to specify the template name per-form |
| 217 |
class. |
| 218 |
|
| 219 |
Similarly, the default template used to render formsets can be specified via |
| 220 |
the matching |
| 221 |
:attr:`~django.forms.renderers.BaseRenderer.formset_template_name` renderer |
| 222 |
attribute. |
| 223 |
|
| 224 |
* The new ``div.html`` form template, referencing |
| 225 |
:attr:`.Form.template_name_div` attribute, and matching :meth:`.Form.as_div` |
| 226 |
method, render forms using HTML ``<div>`` elements. |
| 227 |
|
| 228 |
This new output style is recommended over the existing |
| 229 |
:meth:`~.Form.as_table`, :meth:`~.Form.as_p` and :meth:`~.Form.as_ul` styles, |
| 230 |
as the template implements ``<fieldset>`` and ``<legend>`` to group related |
| 231 |
inputs and is easier for screen reader users to navigate. |
| 232 |
|
| 233 |
The div-based output will become the default rendering style from Django 5.0. |
| 234 |
|
| 235 |
* In order to smooth adoption of the new ``<div>`` output style, two |
| 236 |
transitional form renderer classes are available: |
| 237 |
``django.forms.renderers.DjangoDivFormRenderer`` and |
| 238 |
``django.forms.renderers.Jinja2DivFormRenderer``, for the Django and Jinja2 |
| 239 |
template backends respectively. |
| 240 |
|
| 241 |
You can apply one of these via the :setting:`FORM_RENDERER` setting. For |
| 242 |
example:: |
| 243 |
|
| 244 |
FORM_RENDERER = "django.forms.renderers.DjangoDivFormRenderer" |
| 245 |
|
| 246 |
Once the ``<div>`` output style is the default, from Django 5.0, these |
| 247 |
transitional renderers will be deprecated, for removal in Django 6.0. The |
| 248 |
``FORM_RENDERER`` declaration can be removed at that time. |
| 249 |
|
| 250 |
* If the new ``<div>`` output style is not appropriate for your project, you should |
| 251 |
define a renderer subclass specifying |
| 252 |
:attr:`~django.forms.renderers.BaseRenderer.form_template_name` and |
| 253 |
:attr:`~django.forms.renderers.BaseRenderer.formset_template_name` for your |
| 254 |
required style, and set :setting:`FORM_RENDERER` accordingly. |
| 255 |
|
| 256 |
For example, for the ``<p>`` output style used by :meth:`~.Form.as_p`, you |
| 257 |
would define a form renderer setting ``form_template_name`` to |
| 258 |
``"django/forms/p.html"`` and ``formset_template_name`` to |
| 259 |
``"django/forms/formsets/p.html"``. |
| 260 |
|
| 261 |
* The new :meth:`~django.forms.BoundField.legend_tag` allows rendering field |
| 262 |
labels in ``<legend>`` tags via the new ``tag`` argument of |
| 263 |
:meth:`~django.forms.BoundField.label_tag`. |
| 264 |
|
| 265 |
* The new ``edit_only`` argument for :func:`.modelformset_factory` and |
| 266 |
:func:`.inlineformset_factory` allows preventing new objects creation. |
| 267 |
|
| 268 |
* The ``js`` and ``css`` class attributes of :doc:`Media </topics/forms/media>` |
| 269 |
now allow using hashable objects, not only path strings, as long as those |
| 270 |
objects implement the ``__html__()`` method (typically when decorated with |
| 271 |
the :func:`~django.utils.html.html_safe` decorator). |
| 272 |
|
| 273 |
* The new :attr:`.BoundField.use_fieldset` and :attr:`.Widget.use_fieldset` |
| 274 |
attributes help to identify widgets where its inputs should be grouped in a |
| 275 |
``<fieldset>`` with a ``<legend>``. |
| 276 |
|
| 277 |
* The :ref:`formsets-error-messages` argument for |
| 278 |
:class:`~django.forms.formsets.BaseFormSet` now allows customizing |
| 279 |
error messages for invalid number of forms by passing ``'too_few_forms'`` |
| 280 |
and ``'too_many_forms'`` keys. |
| 281 |
|
| 282 |
* :class:`~django.forms.IntegerField`, :class:`~django.forms.FloatField`, and |
| 283 |
:class:`~django.forms.DecimalField` now optionally accept a ``step_size`` |
| 284 |
argument. This is used to set the ``step`` HTML attribute, and is validated |
| 285 |
on form submission. |
| 286 |
|
| 287 |
Internationalization |
| 288 |
~~~~~~~~~~~~~~~~~~~~ |
| 289 |
|
| 290 |
* The :func:`~django.conf.urls.i18n.i18n_patterns` function now supports |
| 291 |
languages with both scripts and regions. |
| 292 |
|
| 293 |
Management Commands |
| 294 |
~~~~~~~~~~~~~~~~~~~ |
| 295 |
|
| 296 |
* :option:`makemigrations --no-input` now logs default answers and reasons why |
| 297 |
migrations cannot be created. |
| 298 |
|
| 299 |
* The new :option:`makemigrations --scriptable` option diverts log output and |
| 300 |
input prompts to ``stderr``, writing only paths of generated migration files |
| 301 |
to ``stdout``. |
| 302 |
|
| 303 |
* The new :option:`migrate --prune` option allows deleting nonexistent |
| 304 |
migrations from the ``django_migrations`` table. |
| 305 |
|
| 306 |
* Python files created by :djadmin:`startproject`, :djadmin:`startapp`, |
| 307 |
:djadmin:`optimizemigration`, :djadmin:`makemigrations`, and |
| 308 |
:djadmin:`squashmigrations` are now formatted using the ``black`` command if |
| 309 |
it is present on your ``PATH``. |
| 310 |
|
| 311 |
* The new :djadmin:`optimizemigration` command allows optimizing operations for |
| 312 |
a migration. |
| 313 |
|
| 314 |
Migrations |
| 315 |
~~~~~~~~~~ |
| 316 |
|
| 317 |
* The new :class:`~django.db.migrations.operations.RenameIndex` operation |
| 318 |
allows renaming indexes defined in the |
| 319 |
:attr:`Meta.indexes <django.db.models.Options.indexes>` or |
| 320 |
``index_together`` options. |
| 321 |
|
| 322 |
* The migrations autodetector now generates |
| 323 |
:class:`~django.db.migrations.operations.RenameIndex` operations instead of |
| 324 |
``RemoveIndex`` and ``AddIndex``, when renaming indexes defined in the |
| 325 |
:attr:`Meta.indexes <django.db.models.Options.indexes>`. |
| 326 |
|
| 327 |
* The migrations autodetector now generates |
| 328 |
:class:`~django.db.migrations.operations.RenameIndex` operations instead of |
| 329 |
``AlterIndexTogether`` and ``AddIndex``, when moving indexes defined in the |
| 330 |
``Meta.index_together`` to the |
| 331 |
:attr:`Meta.indexes <django.db.models.Options.indexes>`. |
| 332 |
|
| 333 |
Models |
| 334 |
~~~~~~ |
| 335 |
|
| 336 |
* The ``order_by`` argument of the |
| 337 |
:class:`~django.db.models.expressions.Window` expression now accepts string |
| 338 |
references to fields and transforms. |
| 339 |
|
| 340 |
* The new :setting:`CONN_HEALTH_CHECKS` setting allows enabling health checks |
| 341 |
for :ref:`persistent database connections <persistent-database-connections>` |
| 342 |
in order to reduce the number of failed requests, e.g. after database server |
| 343 |
restart. |
| 344 |
|
| 345 |
* :meth:`.QuerySet.bulk_create` now supports updating fields when a row |
| 346 |
insertion fails uniqueness constraints. This is supported on MariaDB, MySQL, |
| 347 |
PostgreSQL, and SQLite 3.24+. |
| 348 |
|
| 349 |
* :meth:`.QuerySet.iterator` now supports prefetching related objects as long |
| 350 |
as the ``chunk_size`` argument is provided. In older versions, no prefetching |
| 351 |
was done. |
| 352 |
|
| 353 |
* :class:`~django.db.models.Q` objects and querysets can now be combined using |
| 354 |
``^`` as the exclusive or (``XOR``) operator. ``XOR`` is natively supported |
| 355 |
on MariaDB and MySQL. For databases that do not support ``XOR``, the query |
| 356 |
will be converted to an equivalent using ``AND``, ``OR``, and ``NOT``. |
| 357 |
|
| 358 |
* The new :ref:`Field.non_db_attrs <custom-field-non_db_attrs>` attribute |
| 359 |
allows customizing attributes of fields that don't affect a column |
| 360 |
definition. |
| 361 |
|
| 362 |
* On PostgreSQL, ``AutoField``, ``BigAutoField``, and ``SmallAutoField`` are |
| 363 |
now created as identity columns rather than serial columns with sequences. |
| 364 |
|
| 365 |
Requests and Responses |
| 366 |
~~~~~~~~~~~~~~~~~~~~~~ |
| 367 |
|
| 368 |
* :meth:`.HttpResponse.set_cookie` now supports :class:`~datetime.timedelta` |
| 369 |
objects for the ``max_age`` argument. |
| 370 |
|
| 371 |
Security |
| 372 |
~~~~~~~~ |
| 373 |
|
| 374 |
* The new :setting:`SECRET_KEY_FALLBACKS` setting allows providing a list of |
| 375 |
values for secret key rotation. |
| 376 |
|
| 377 |
* The :setting:`SECURE_PROXY_SSL_HEADER` setting now supports a comma-separated |
| 378 |
list of protocols in the header value. |
| 379 |
|
| 380 |
Signals |
| 381 |
~~~~~~~ |
| 382 |
|
| 383 |
* The :data:`~django.db.models.signals.pre_delete` and |
| 384 |
:data:`~django.db.models.signals.post_delete` signals now dispatch the |
| 385 |
``origin`` of the deletion. |
| 386 |
|
| 387 |
.. _templates-4.1: |
| 388 |
|
| 389 |
Templates |
| 390 |
~~~~~~~~~ |
| 391 |
|
| 392 |
* The HTML ``<script>`` element ``id`` attribute is no longer required when |
| 393 |
wrapping the :tfilter:`json_script` template filter. |
| 394 |
|
| 395 |
* The :class:`cached template loader <django.template.loaders.cached.Loader>` |
| 396 |
is now enabled in development, when :setting:`DEBUG` is ``True``, and |
| 397 |
:setting:`OPTIONS['loaders'] <TEMPLATES-OPTIONS>` isn't specified. You may |
| 398 |
specify ``OPTIONS['loaders']`` to override this, if necessary. |
| 399 |
|
| 400 |
Tests |
| 401 |
~~~~~ |
| 402 |
|
| 403 |
* The :class:`.DiscoverRunner` now supports running tests in parallel on |
| 404 |
macOS, Windows, and any other systems where the default |
| 405 |
:mod:`multiprocessing` start method is ``spawn``. |
| 406 |
|
| 407 |
* A nested atomic block marked as durable in :class:`django.test.TestCase` now |
| 408 |
raises a ``RuntimeError``, the same as outside of tests. |
| 409 |
|
| 410 |
* :meth:`.SimpleTestCase.assertFormError` and |
| 411 |
:meth:`assertFormsetError() <django.test.SimpleTestCase.assertFormSetError>` |
| 412 |
now support passing a form/formset object directly. |
| 413 |
|
| 414 |
URLs |
| 415 |
~~~~ |
| 416 |
|
| 417 |
* The new :attr:`.ResolverMatch.captured_kwargs` attribute stores the captured |
| 418 |
keyword arguments, as parsed from the URL. |
| 419 |
|
| 420 |
* The new :attr:`.ResolverMatch.extra_kwargs` attribute stores the additional |
| 421 |
keyword arguments passed to the view function. |
| 422 |
|
| 423 |
Utilities |
| 424 |
~~~~~~~~~ |
| 425 |
|
| 426 |
* ``SimpleLazyObject`` now supports addition operations. |
| 427 |
|
| 428 |
* :func:`~django.utils.safestring.mark_safe` now preserves lazy objects. |
| 429 |
|
| 430 |
Validators |
| 431 |
~~~~~~~~~~ |
| 432 |
|
| 433 |
* The new :class:`~django.core.validators.StepValueValidator` checks if a value |
| 434 |
is an integral multiple of a given step size. This new validator is used for |
| 435 |
the new ``step_size`` argument added to form fields representing numeric |
| 436 |
values. |
| 437 |
|
| 438 |
.. _backwards-incompatible-4.1: |
| 439 |
|
| 440 |
Backwards incompatible changes in 4.1 |
| 441 |
===================================== |
| 442 |
|
| 443 |
Database backend API |
| 444 |
-------------------- |
| 445 |
|
| 446 |
This section describes changes that may be needed in third-party database |
| 447 |
backends. |
| 448 |
|
| 449 |
* ``BaseDatabaseFeatures.has_case_insensitive_like`` is changed from ``True`` |
| 450 |
to ``False`` to reflect the behavior of most databases. |
| 451 |
|
| 452 |
* ``DatabaseIntrospection.get_key_columns()`` is removed. Use |
| 453 |
``DatabaseIntrospection.get_relations()`` instead. |
| 454 |
|
| 455 |
* ``DatabaseOperations.ignore_conflicts_suffix_sql()`` method is replaced by |
| 456 |
``DatabaseOperations.on_conflict_suffix_sql()`` that accepts the ``fields``, |
| 457 |
``on_conflict``, ``update_fields``, and ``unique_fields`` arguments. |
| 458 |
|
| 459 |
* The ``ignore_conflicts`` argument of the |
| 460 |
``DatabaseOperations.insert_statement()`` method is replaced by |
| 461 |
``on_conflict`` that accepts ``django.db.models.constants.OnConflict``. |
| 462 |
|
| 463 |
* ``DatabaseOperations._convert_field_to_tz()`` is replaced by |
| 464 |
``DatabaseOperations._convert_sql_to_tz()`` that accepts the ``sql``, |
| 465 |
``params``, and ``tzname`` arguments. |
| 466 |
|
| 467 |
* Several date and time methods on ``DatabaseOperations`` now take ``sql`` and |
| 468 |
``params`` arguments instead of ``field_name`` and return 2-tuple containing |
| 469 |
some SQL and the parameters to be interpolated into that SQL. The changed |
| 470 |
methods have these new signatures: |
| 471 |
|
| 472 |
* ``DatabaseOperations.date_extract_sql(lookup_type, sql, params)`` |
| 473 |
* ``DatabaseOperations.datetime_extract_sql(lookup_type, sql, params, tzname)`` |
| 474 |
* ``DatabaseOperations.time_extract_sql(lookup_type, sql, params)`` |
| 475 |
* ``DatabaseOperations.date_trunc_sql(lookup_type, sql, params, tzname=None)`` |
| 476 |
* ``DatabaseOperations.datetime_trunc_sql(self, lookup_type, sql, params, tzname)`` |
| 477 |
* ``DatabaseOperations.time_trunc_sql(lookup_type, sql, params, tzname=None)`` |
| 478 |
* ``DatabaseOperations.datetime_cast_date_sql(sql, params, tzname)`` |
| 479 |
* ``DatabaseOperations.datetime_cast_time_sql(sql, params, tzname)`` |
| 480 |
|
| 481 |
:mod:`django.contrib.gis` |
| 482 |
------------------------- |
| 483 |
|
| 484 |
* Support for GDAL 2.1 is removed. |
| 485 |
|
| 486 |
* Support for PostGIS 2.4 is removed. |
| 487 |
|
| 488 |
Dropped support for PostgreSQL 10 |
| 489 |
--------------------------------- |
| 490 |
|
| 491 |
Upstream support for PostgreSQL 10 ends in November 2022. Django 4.1 supports |
| 492 |
PostgreSQL 11 and higher. |
| 493 |
|
| 494 |
Dropped support for MariaDB 10.2 |
| 495 |
-------------------------------- |
| 496 |
|
| 497 |
Upstream support for MariaDB 10.2 ends in May 2022. Django 4.1 supports MariaDB |
| 498 |
10.3 and higher. |
| 499 |
|
| 500 |
Admin changelist searches spanning multi-valued relationships changes |
| 501 |
--------------------------------------------------------------------- |
| 502 |
|
| 503 |
Admin changelist searches using multiple search terms are now applied in a |
| 504 |
single call to ``filter()``, rather than in sequential ``filter()`` calls. |
| 505 |
|
| 506 |
For multi-valued relationships, this means that rows from the related model |
| 507 |
must match all terms rather than any term. For example, if ``search_fields`` |
| 508 |
is set to ``['child__name', 'child__age']``, and a user searches for |
| 509 |
``'Jamal 17'``, parent rows will be returned only if there is a relationship to |
| 510 |
some 17-year-old child named Jamal, rather than also returning parents who |
| 511 |
merely have a younger or older child named Jamal in addition to some other |
| 512 |
17-year-old. |
| 513 |
|
| 514 |
See the :ref:`spanning-multi-valued-relationships` topic for more discussion of |
| 515 |
this difference. In Django 4.0 and earlier, |
| 516 |
:meth:`~django.contrib.admin.ModelAdmin.get_search_results` followed the |
| 517 |
second example query, but this undocumented behavior led to queries with |
| 518 |
excessive joins. |
| 519 |
|
| 520 |
Reverse foreign key changes for unsaved model instances |
| 521 |
------------------------------------------------------- |
| 522 |
|
| 523 |
In order to unify the behavior with many-to-many relations for unsaved model |
| 524 |
instances, a reverse foreign key now raises ``ValueError`` when calling |
| 525 |
:class:`related managers <django.db.models.fields.related.RelatedManager>` for |
| 526 |
unsaved objects. |
| 527 |
|
| 528 |
Miscellaneous |
| 529 |
------------- |
| 530 |
|
| 531 |
* Related managers for :class:`~django.db.models.ForeignKey`, |
| 532 |
:class:`~django.db.models.ManyToManyField`, and |
| 533 |
:class:`~django.contrib.contenttypes.fields.GenericRelation` are now cached |
| 534 |
on the :class:`~django.db.models.Model` instance to which they belong. *This |
| 535 |
change was reverted in Django 4.1.2.* |
| 536 |
|
| 537 |
* :class:`~django.test.runner.DiscoverRunner` now returns a non-zero error code |
| 538 |
for unexpected successes from tests marked with |
| 539 |
:py:func:`unittest.expectedFailure`. |
| 540 |
|
| 541 |
* :class:`~django.middleware.csrf.CsrfViewMiddleware` no longer masks the CSRF |
| 542 |
cookie like it does the CSRF token in the DOM. |
| 543 |
|
| 544 |
* :class:`~django.middleware.csrf.CsrfViewMiddleware` now uses |
| 545 |
``request.META['CSRF_COOKIE']`` for storing the unmasked CSRF secret rather |
| 546 |
than a masked version. This is an undocumented, private API. |
| 547 |
|
| 548 |
* The :attr:`.ModelAdmin.actions` and |
| 549 |
:attr:`~django.contrib.admin.ModelAdmin.inlines` attributes now default to an |
| 550 |
empty tuple rather than an empty list to discourage unintended mutation. |
| 551 |
|
| 552 |
* The ``type="text/css"`` attribute is no longer included in ``<link>`` tags |
| 553 |
for CSS :doc:`form media </topics/forms/media>`. |
| 554 |
|
| 555 |
* ``formset:added`` and ``formset:removed`` JavaScript events are now pure |
| 556 |
JavaScript events and don't depend on jQuery. See |
| 557 |
:ref:`admin-javascript-inline-form-events` for more details on the change. |
| 558 |
|
| 559 |
* The ``exc_info`` argument of the undocumented |
| 560 |
``django.utils.log.log_response()`` function is replaced by ``exception``. |
| 561 |
|
| 562 |
* The ``size`` argument of the undocumented |
| 563 |
``django.views.static.was_modified_since()`` function is removed. |
| 564 |
|
| 565 |
* The admin log out UI now uses ``POST`` requests. |
| 566 |
|
| 567 |
* The undocumented ``InlineAdminFormSet.non_form_errors`` property is replaced |
| 568 |
by the ``non_form_errors()`` method. This is consistent with ``BaseFormSet``. |
| 569 |
|
| 570 |
* As per :ref:`above<templates-4.1>`, the cached template loader is now |
| 571 |
enabled in development. You may specify ``OPTIONS['loaders']`` to override |
| 572 |
this, if necessary. |
| 573 |
|
| 574 |
* The undocumented ``django.contrib.auth.views.SuccessURLAllowedHostsMixin`` |
| 575 |
mixin is replaced by ``RedirectURLMixin``. |
| 576 |
|
| 577 |
* :class:`~django.db.models.BaseConstraint` subclasses must implement |
| 578 |
:meth:`~django.db.models.BaseConstraint.validate` method to allow those |
| 579 |
constraints to be used for validation. |
| 580 |
|
| 581 |
* The undocumented ``URLResolver._is_callback()``, |
| 582 |
``URLResolver._callback_strs``, and ``URLPattern.lookup_str()`` are |
| 583 |
moved to ``django.contrib.admindocs.utils``. |
| 584 |
|
| 585 |
* The :meth:`.Model.full_clean` method now converts an ``exclude`` value to a |
| 586 |
``set``. It’s also preferable to pass an ``exclude`` value as a ``set`` to |
| 587 |
the :meth:`.Model.clean_fields`, :meth:`.Model.full_clean`, |
| 588 |
:meth:`.Model.validate_unique`, and :meth:`.Model.validate_constraints` |
| 589 |
methods. |
| 590 |
|
| 591 |
* The minimum supported version of ``asgiref`` is increased from 3.4.1 to |
| 592 |
3.5.2. |
| 593 |
|
| 594 |
* Combined expressions no longer use the error-prone behavior of guessing |
| 595 |
``output_field`` when argument types match. As a consequence, resolving an |
| 596 |
``output_field`` for database functions and combined expressions may now |
| 597 |
crash with mixed types. You will need to explicitly set the ``output_field`` |
| 598 |
in such cases. |
| 599 |
|
| 600 |
* The :djadmin:`makemessages` command no longer changes ``.po`` files when up |
| 601 |
to date. In older versions, ``POT-Creation-Date`` was always updated. |
| 602 |
|
| 603 |
.. _deprecated-features-4.1: |
| 604 |
|
| 605 |
Features deprecated in 4.1 |
| 606 |
========================== |
| 607 |
|
| 608 |
Log out via GET |
| 609 |
--------------- |
| 610 |
|
| 611 |
Logging out via ``GET`` requests to the :py:class:`built-in logout view |
| 612 |
<django.contrib.auth.views.LogoutView>` is deprecated. Use ``POST`` requests |
| 613 |
instead. |
| 614 |
|
| 615 |
If you want to retain the user experience of an HTML link, you can use a form |
| 616 |
that is styled to appear as a link: |
| 617 |
|
| 618 |
.. code-block:: html |
| 619 |
|
| 620 |
<form id="logout-form" method="post" action="{% url 'admin:logout' %}"> |
| 621 |
{% csrf_token %} |
| 622 |
<button type="submit">{% translate "Log out" %}</button> |
| 623 |
</form> |
| 624 |
|
| 625 |
.. code-block:: css |
| 626 |
|
| 627 |
#logout-form { |
| 628 |
display: inline; |
| 629 |
} |
| 630 |
#logout-form button { |
| 631 |
background: none; |
| 632 |
border: none; |
| 633 |
cursor: pointer; |
| 634 |
padding: 0; |
| 635 |
text-decoration: underline; |
| 636 |
} |
| 637 |
|
| 638 |
Miscellaneous |
| 639 |
------------- |
| 640 |
|
| 641 |
* The context for sitemap index templates of a flat list of URLs is deprecated. |
| 642 |
Custom sitemap index templates should be updated for the adjusted |
| 643 |
:ref:`context variables <sitemap-index-context-variables>`, expecting a list |
| 644 |
of objects with ``location`` and optional ``lastmod`` attributes. |
| 645 |
|
| 646 |
* ``CSRF_COOKIE_MASKED`` transitional setting is deprecated. |
| 647 |
|
| 648 |
* The ``name`` argument of :func:`django.utils.functional.cached_property` is |
| 649 |
deprecated as it's unnecessary as of Python 3.6. |
| 650 |
|
| 651 |
* The ``opclasses`` argument of |
| 652 |
``django.contrib.postgres.constraints.ExclusionConstraint`` is deprecated in |
| 653 |
favor of using :class:`OpClass() <django.contrib.postgres.indexes.OpClass>` |
| 654 |
in :attr:`.ExclusionConstraint.expressions`. To use it, you need to add |
| 655 |
``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS`. |
| 656 |
|
| 657 |
After making this change, :djadmin:`makemigrations` will generate a new |
| 658 |
migration with two operations: ``RemoveConstraint`` and ``AddConstraint``. |
| 659 |
Since this change has no effect on the database schema, |
| 660 |
the :class:`~django.db.migrations.operations.SeparateDatabaseAndState` |
| 661 |
operation can be used to only update the migration state without running any |
| 662 |
SQL. Move the generated operations into the ``state_operations`` argument of |
| 663 |
:class:`~django.db.migrations.operations.SeparateDatabaseAndState`. For |
| 664 |
example:: |
| 665 |
|
| 666 |
class Migration(migrations.Migration): |
| 667 |
... |
| 668 |
|
| 669 |
operations = [ |
| 670 |
migrations.SeparateDatabaseAndState( |
| 671 |
database_operations=[], |
| 672 |
state_operations=[ |
| 673 |
migrations.RemoveConstraint(...), |
| 674 |
migrations.AddConstraint(...), |
| 675 |
], |
| 676 |
), |
| 677 |
] |
| 678 |
|
| 679 |
* The undocumented ability to pass ``errors=None`` to |
| 680 |
:meth:`.SimpleTestCase.assertFormError` and |
| 681 |
:meth:`assertFormsetError() <django.test.SimpleTestCase.assertFormSetError>` |
| 682 |
is deprecated. Use ``errors=[]`` instead. |
| 683 |
|
| 684 |
* ``django.contrib.sessions.serializers.PickleSerializer`` is deprecated due to |
| 685 |
the risk of remote code execution. |
| 686 |
|
| 687 |
* The usage of ``QuerySet.iterator()`` on a queryset that prefetches related |
| 688 |
objects without providing the ``chunk_size`` argument is deprecated. In older |
| 689 |
versions, no prefetching was done. Providing a value for ``chunk_size`` |
| 690 |
signifies that the additional query per chunk needed to prefetch is desired. |
| 691 |
|
| 692 |
* Passing unsaved model instances to related filters is deprecated. In Django |
| 693 |
5.0, the exception will be raised. |
| 694 |
|
| 695 |
* ``created=True`` is added to the signature of |
| 696 |
:meth:`.RemoteUserBackend.configure_user`. Support for ``RemoteUserBackend`` |
| 697 |
subclasses that do not accept this argument is deprecated. |
| 698 |
|
| 699 |
* The ``django.utils.timezone.utc`` alias to :attr:`datetime.timezone.utc` is |
| 700 |
deprecated. Use :attr:`datetime.timezone.utc` directly. |
| 701 |
|
| 702 |
* Passing a response object and a form/formset name to |
| 703 |
``SimpleTestCase.assertFormError()`` and ``assertFormsetError()`` is |
| 704 |
deprecated. Use:: |
| 705 |
|
| 706 |
assertFormError(response.context["form_name"], ...) |
| 707 |
assertFormsetError(response.context["formset_name"], ...) |
| 708 |
|
| 709 |
or pass the form/formset object directly instead. |
| 710 |
|
| 711 |
* The undocumented ``django.contrib.gis.admin.OpenLayersWidget`` is deprecated. |
| 712 |
|
| 713 |
* ``django.contrib.auth.hashers.CryptPasswordHasher`` is deprecated. |
| 714 |
|
| 715 |
* The ability to pass ``nulls_first=False`` or ``nulls_last=False`` to |
| 716 |
``Expression.asc()`` and ``Expression.desc()`` methods, and the ``OrderBy`` |
| 717 |
expression is deprecated. Use ``None`` instead. |
| 718 |
|
| 719 |
* The ``"django/forms/default.html"`` and |
| 720 |
``"django/forms/formsets/default.html"`` templates which are a proxy to the |
| 721 |
table-based templates are deprecated. Use the specific template instead. |
| 722 |
|
| 723 |
* The undocumented ``LogoutView.get_next_page()`` method is renamed to |
| 724 |
``get_success_url()``. |
| 725 |
|
| 726 |
Features removed in 4.1 |
| 727 |
======================= |
| 728 |
|
| 729 |
These features have reached the end of their deprecation cycle and are removed |
| 730 |
in Django 4.1. |
| 731 |
|
| 732 |
See :ref:`deprecated-features-3.2` for details on these changes, including how |
| 733 |
to remove usage of these features. |
| 734 |
|
| 735 |
* Support for assigning objects which don't support creating deep copies with |
| 736 |
``copy.deepcopy()`` to class attributes in ``TestCase.setUpTestData()`` is |
| 737 |
removed. |
| 738 |
|
| 739 |
* Support for using a boolean value in |
| 740 |
:attr:`.BaseCommand.requires_system_checks` is removed. |
| 741 |
|
| 742 |
* The ``whitelist`` argument and ``domain_whitelist`` attribute of |
| 743 |
``django.core.validators.EmailValidator`` are removed. |
| 744 |
|
| 745 |
* The ``default_app_config`` application configuration variable is removed. |
| 746 |
|
| 747 |
* ``TransactionTestCase.assertQuerysetEqual()`` no longer calls ``repr()`` on a |
| 748 |
queryset when compared to string values. |
| 749 |
|
| 750 |
* The ``django.core.cache.backends.memcached.MemcachedCache`` backend is |
| 751 |
removed. |
| 752 |
|
| 753 |
* Support for the pre-Django 3.2 format of messages used by |
| 754 |
``django.contrib.messages.storage.cookie.CookieStorage`` is removed. |