| 1 |
======================== |
| 2 |
Django 3.0 release notes |
| 3 |
======================== |
| 4 |
|
| 5 |
*December 2, 2019* |
| 6 |
|
| 7 |
Welcome to Django 3.0! |
| 8 |
|
| 9 |
These release notes cover the :ref:`new features <whats-new-3.0>`, as well as |
| 10 |
some :ref:`backwards incompatible changes <backwards-incompatible-3.0>` you'll |
| 11 |
want to be aware of when upgrading from Django 2.2 or earlier. We've |
| 12 |
:ref:`dropped some features<removed-features-3.0>` that have reached the end of |
| 13 |
their deprecation cycle, and we've :ref:`begun the deprecation process for |
| 14 |
some features <deprecated-features-3.0>`. |
| 15 |
|
| 16 |
See the :doc:`/howto/upgrade-version` guide if you're updating an existing |
| 17 |
project. |
| 18 |
|
| 19 |
Python compatibility |
| 20 |
==================== |
| 21 |
|
| 22 |
Django 3.0 supports Python 3.6, 3.7, 3.8, and 3.9 (as of 3.0.11). We **highly |
| 23 |
recommend** and only officially support the latest release of each series. |
| 24 |
|
| 25 |
The Django 2.2.x series is the last to support Python 3.5. |
| 26 |
|
| 27 |
Third-party library support for older version of Django |
| 28 |
======================================================= |
| 29 |
|
| 30 |
Following the release of Django 3.0, we suggest that third-party app authors |
| 31 |
drop support for all versions of Django prior to 2.2. At that time, you should |
| 32 |
be able to run your package's tests using ``python -Wd`` so that deprecation |
| 33 |
warnings appear. After making the deprecation warning fixes, your app should be |
| 34 |
compatible with Django 3.0. |
| 35 |
|
| 36 |
.. _whats-new-3.0: |
| 37 |
|
| 38 |
What's new in Django 3.0 |
| 39 |
======================== |
| 40 |
|
| 41 |
MariaDB support |
| 42 |
--------------- |
| 43 |
|
| 44 |
Django now officially supports `MariaDB <https://mariadb.org/>`_ 10.1 and |
| 45 |
higher. See :ref:`MariaDB notes <mariadb-notes>` for more details. |
| 46 |
|
| 47 |
ASGI support |
| 48 |
------------ |
| 49 |
|
| 50 |
Django 3.0 begins our journey to making Django fully async-capable by providing |
| 51 |
support for running as an `ASGI <https://asgi.readthedocs.io/>`_ application. |
| 52 |
|
| 53 |
This is in addition to our existing WSGI support. Django intends to support |
| 54 |
both for the foreseeable future. Async features will only be available to |
| 55 |
applications that run under ASGI, however. |
| 56 |
|
| 57 |
At this stage async support only applies to the outer ASGI application. |
| 58 |
Internally everything remains synchronous. Asynchronous middleware, views, etc. |
| 59 |
are not yet supported. You can, however, use ASGI middleware around Django's |
| 60 |
application, allowing you to combine Django with other ASGI frameworks. |
| 61 |
|
| 62 |
There is no need to switch your applications over unless you want to start |
| 63 |
experimenting with asynchronous code, but we have |
| 64 |
:doc:`documentation on deploying with ASGI </howto/deployment/asgi/index>` if |
| 65 |
you want to learn more. |
| 66 |
|
| 67 |
Note that as a side-effect of this change, Django is now aware of asynchronous |
| 68 |
event loops and will block you calling code marked as "async unsafe" - such as |
| 69 |
ORM operations - from an asynchronous context. If you were using Django from |
| 70 |
async code before, this may trigger if you were doing it incorrectly. If you |
| 71 |
see a ``SynchronousOnlyOperation`` error, then closely examine your code and |
| 72 |
move any database operations to be in a synchronous child thread. |
| 73 |
|
| 74 |
Exclusion constraints on PostgreSQL |
| 75 |
----------------------------------- |
| 76 |
|
| 77 |
The new :class:`~django.contrib.postgres.constraints.ExclusionConstraint` class |
| 78 |
enable adding exclusion constraints on PostgreSQL. Constraints are added to |
| 79 |
models using the |
| 80 |
:attr:`Meta.constraints <django.db.models.Options.constraints>` option. |
| 81 |
|
| 82 |
Filter expressions |
| 83 |
------------------ |
| 84 |
|
| 85 |
Expressions that output :class:`~django.db.models.BooleanField` may now be |
| 86 |
used directly in ``QuerySet`` filters, without having to first annotate and |
| 87 |
then filter against the annotation. |
| 88 |
|
| 89 |
Enumerations for model field choices |
| 90 |
------------------------------------ |
| 91 |
|
| 92 |
Custom enumeration types ``TextChoices``, ``IntegerChoices``, and ``Choices`` |
| 93 |
are now available as a way to define :attr:`.Field.choices`. ``TextChoices`` |
| 94 |
and ``IntegerChoices`` types are provided for text and integer fields. The |
| 95 |
``Choices`` class allows defining a compatible enumeration for other concrete |
| 96 |
data types. These custom enumeration types support human-readable labels that |
| 97 |
can be translated and accessed via a property on the enumeration or its |
| 98 |
members. See :ref:`Enumeration types <field-choices-enum-types>` for more |
| 99 |
details and examples. |
| 100 |
|
| 101 |
Minor features |
| 102 |
-------------- |
| 103 |
|
| 104 |
:mod:`django.contrib.admin` |
| 105 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 106 |
|
| 107 |
* Added support for the ``admin_order_field`` attribute on properties in |
| 108 |
:attr:`.ModelAdmin.list_display`. |
| 109 |
|
| 110 |
* The new :meth:`ModelAdmin.get_inlines() |
| 111 |
<django.contrib.admin.ModelAdmin.get_inlines>` method allows specifying the |
| 112 |
inlines based on the request or model instance. |
| 113 |
|
| 114 |
* Select2 library is upgraded from version 4.0.3 to 4.0.7. |
| 115 |
|
| 116 |
* jQuery is upgraded from version 3.3.1 to 3.4.1. |
| 117 |
|
| 118 |
:mod:`django.contrib.auth` |
| 119 |
~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 120 |
|
| 121 |
* The new ``reset_url_token`` attribute in |
| 122 |
:class:`~django.contrib.auth.views.PasswordResetConfirmView` allows |
| 123 |
specifying a token parameter displayed as a component of password reset |
| 124 |
URLs. |
| 125 |
|
| 126 |
* Added :class:`~django.contrib.auth.backends.BaseBackend` class to ease |
| 127 |
customization of authentication backends. |
| 128 |
|
| 129 |
* Added :meth:`~django.contrib.auth.models.User.get_user_permissions()` method |
| 130 |
to mirror the existing |
| 131 |
:meth:`~django.contrib.auth.models.User.get_group_permissions()` method. |
| 132 |
|
| 133 |
* Added HTML ``autocomplete`` attribute to widgets of username, email, and |
| 134 |
password fields in :mod:`django.contrib.auth.forms` for better interaction |
| 135 |
with browser password managers. |
| 136 |
|
| 137 |
* :djadmin:`createsuperuser` now falls back to environment variables for |
| 138 |
password and required fields, when a corresponding command line argument |
| 139 |
isn't provided in non-interactive mode. |
| 140 |
|
| 141 |
* :attr:`~django.contrib.auth.models.CustomUser.REQUIRED_FIELDS` now supports |
| 142 |
:class:`~django.db.models.ManyToManyField`\s. |
| 143 |
|
| 144 |
* The new :meth:`.UserManager.with_perm` method returns users that have the |
| 145 |
specified permission. |
| 146 |
|
| 147 |
* The default iteration count for the PBKDF2 password hasher is increased from |
| 148 |
150,000 to 180,000. |
| 149 |
|
| 150 |
:mod:`django.contrib.gis` |
| 151 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 152 |
|
| 153 |
* Allowed MySQL spatial lookup functions to operate on real geometries. |
| 154 |
Previous support was limited to bounding boxes. |
| 155 |
|
| 156 |
* Added the :class:`~django.contrib.gis.db.models.functions.GeometryDistance` |
| 157 |
function, supported on PostGIS. |
| 158 |
|
| 159 |
* Added support for the ``furlong`` unit in |
| 160 |
:class:`~django.contrib.gis.measure.Distance`. |
| 161 |
|
| 162 |
* The :setting:`GEOIP_PATH` setting now supports :class:`pathlib.Path`. |
| 163 |
|
| 164 |
* The :class:`~django.contrib.gis.geoip2.GeoIP2` class now accepts |
| 165 |
:class:`pathlib.Path` ``path``. |
| 166 |
|
| 167 |
:mod:`django.contrib.postgres` |
| 168 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 169 |
|
| 170 |
* The new :class:`~django.contrib.postgres.fields.RangeOperators` helps to |
| 171 |
avoid typos in SQL operators that can be used together with |
| 172 |
:class:`~django.contrib.postgres.fields.RangeField`. |
| 173 |
|
| 174 |
* The new :class:`~django.contrib.postgres.fields.RangeBoundary` expression |
| 175 |
represents the range boundaries. |
| 176 |
|
| 177 |
* The new :class:`~django.contrib.postgres.operations.AddIndexConcurrently` |
| 178 |
and :class:`~django.contrib.postgres.operations.RemoveIndexConcurrently` |
| 179 |
classes allow creating and dropping indexes ``CONCURRENTLY`` on PostgreSQL. |
| 180 |
|
| 181 |
:mod:`django.contrib.sessions` |
| 182 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 183 |
|
| 184 |
* The new |
| 185 |
:meth:`~django.contrib.sessions.backends.base.SessionBase.get_session_cookie_age()` |
| 186 |
method allows dynamically specifying the session cookie age. |
| 187 |
|
| 188 |
:mod:`django.contrib.syndication` |
| 189 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 190 |
|
| 191 |
* Added the ``language`` class attribute to the |
| 192 |
:class:`django.contrib.syndication.views.Feed` to customize a feed language. |
| 193 |
The default value is :func:`~django.utils.translation.get_language()` instead |
| 194 |
of :setting:`LANGUAGE_CODE`. |
| 195 |
|
| 196 |
Cache |
| 197 |
~~~~~ |
| 198 |
|
| 199 |
* :func:`~django.utils.cache.add_never_cache_headers` and |
| 200 |
:func:`~django.views.decorators.cache.never_cache` now add the ``private`` |
| 201 |
directive to ``Cache-Control`` headers. |
| 202 |
|
| 203 |
File Storage |
| 204 |
~~~~~~~~~~~~ |
| 205 |
|
| 206 |
* The new :meth:`.Storage.get_alternative_name` method allows customizing the |
| 207 |
algorithm for generating filenames if a file with the uploaded name already |
| 208 |
exists. |
| 209 |
|
| 210 |
Forms |
| 211 |
~~~~~ |
| 212 |
|
| 213 |
* Formsets may control the widget used when ordering forms via |
| 214 |
:attr:`~django.forms.formsets.BaseFormSet.can_order` by setting the |
| 215 |
:attr:`~django.forms.formsets.BaseFormSet.ordering_widget` attribute or |
| 216 |
overriding :attr:`~django.forms.formsets.BaseFormSet.get_ordering_widget()`. |
| 217 |
|
| 218 |
Internationalization |
| 219 |
~~~~~~~~~~~~~~~~~~~~ |
| 220 |
|
| 221 |
* Added the :setting:`LANGUAGE_COOKIE_HTTPONLY`, |
| 222 |
:setting:`LANGUAGE_COOKIE_SAMESITE`, and :setting:`LANGUAGE_COOKIE_SECURE` |
| 223 |
settings to set the ``HttpOnly``, ``SameSite``, and ``Secure`` flags on |
| 224 |
language cookies. The default values of these settings preserve the previous |
| 225 |
behavior. |
| 226 |
|
| 227 |
* Added support and translations for the Uzbek language. |
| 228 |
|
| 229 |
Logging |
| 230 |
~~~~~~~ |
| 231 |
|
| 232 |
* The new ``reporter_class`` parameter of |
| 233 |
:class:`~django.utils.log.AdminEmailHandler` allows providing an |
| 234 |
``django.views.debug.ExceptionReporter`` subclass to customize the traceback |
| 235 |
text sent to site :setting:`ADMINS` when :setting:`DEBUG` is ``False``. |
| 236 |
|
| 237 |
Management Commands |
| 238 |
~~~~~~~~~~~~~~~~~~~ |
| 239 |
|
| 240 |
* The new :option:`compilemessages --ignore` option allows ignoring specific |
| 241 |
directories when searching for ``.po`` files to compile. |
| 242 |
|
| 243 |
* :option:`showmigrations --list` now shows the applied datetimes when |
| 244 |
``--verbosity`` is 2 and above. |
| 245 |
|
| 246 |
* On PostgreSQL, :djadmin:`dbshell` now supports client-side TLS certificates. |
| 247 |
|
| 248 |
* :djadmin:`inspectdb` now introspects :class:`~django.db.models.OneToOneField` |
| 249 |
when a foreign key has a unique or primary key constraint. |
| 250 |
|
| 251 |
* The new :option:`--skip-checks` option skips running system checks prior to |
| 252 |
running the command. |
| 253 |
|
| 254 |
* The :option:`startapp --template` and :option:`startproject --template` |
| 255 |
options now support templates stored in XZ archives (``.tar.xz``, ``.txz``) |
| 256 |
and LZMA archives (``.tar.lzma``, ``.tlz``). |
| 257 |
|
| 258 |
Models |
| 259 |
~~~~~~ |
| 260 |
|
| 261 |
* Added hash database functions :class:`~django.db.models.functions.MD5`, |
| 262 |
:class:`~django.db.models.functions.SHA1`, |
| 263 |
:class:`~django.db.models.functions.SHA224`, |
| 264 |
:class:`~django.db.models.functions.SHA256`, |
| 265 |
:class:`~django.db.models.functions.SHA384`, and |
| 266 |
:class:`~django.db.models.functions.SHA512`. |
| 267 |
|
| 268 |
* Added the :class:`~django.db.models.functions.Sign` database function. |
| 269 |
|
| 270 |
* The new ``is_dst`` parameter of the |
| 271 |
:class:`~django.db.models.functions.Trunc` database functions determines the |
| 272 |
treatment of nonexistent and ambiguous datetimes. |
| 273 |
|
| 274 |
* ``connection.queries`` now shows ``COPY … TO`` statements on PostgreSQL. |
| 275 |
|
| 276 |
* :class:`~django.db.models.FilePathField` now accepts a callable for ``path``. |
| 277 |
|
| 278 |
* Allowed symmetrical intermediate table for self-referential |
| 279 |
:class:`~django.db.models.ManyToManyField`. |
| 280 |
|
| 281 |
* The ``name`` attributes of :class:`~django.db.models.CheckConstraint`, |
| 282 |
:class:`~django.db.models.UniqueConstraint`, and |
| 283 |
:class:`~django.db.models.Index` now support app label and class |
| 284 |
interpolation using the ``'%(app_label)s'`` and ``'%(class)s'`` placeholders. |
| 285 |
|
| 286 |
* The new :attr:`.Field.descriptor_class` attribute allows model fields to |
| 287 |
customize the get and set behavior by overriding their |
| 288 |
:py:ref:`descriptors <descriptors>`. |
| 289 |
|
| 290 |
* :class:`~django.db.models.Avg` and :class:`~django.db.models.Sum` now support |
| 291 |
the ``distinct`` argument. |
| 292 |
|
| 293 |
* Added :class:`~django.db.models.SmallAutoField` which acts much like an |
| 294 |
:class:`~django.db.models.AutoField` except that it only allows values under |
| 295 |
a certain (database-dependent) limit. Values from ``1`` to ``32767`` are safe |
| 296 |
in all databases supported by Django. |
| 297 |
|
| 298 |
* :class:`~django.db.models.AutoField`, |
| 299 |
:class:`~django.db.models.BigAutoField`, and |
| 300 |
:class:`~django.db.models.SmallAutoField` now inherit from |
| 301 |
``IntegerField``, ``BigIntegerField`` and ``SmallIntegerField`` respectively. |
| 302 |
System checks and validators are now also properly inherited. |
| 303 |
|
| 304 |
* :attr:`.FileField.upload_to` now supports :class:`pathlib.Path`. |
| 305 |
|
| 306 |
* :class:`~django.db.models.CheckConstraint` is now supported on MySQL 8.0.16+. |
| 307 |
|
| 308 |
* The new ``allows_group_by_selected_pks_on_model()`` method of |
| 309 |
``django.db.backends.base.BaseDatabaseFeatures`` allows optimization of |
| 310 |
``GROUP BY`` clauses to require only the selected models' primary keys. By |
| 311 |
default, it's supported only for managed models on PostgreSQL. |
| 312 |
|
| 313 |
To enable the ``GROUP BY`` primary key-only optimization for unmanaged |
| 314 |
models, you have to subclass the PostgreSQL database engine, overriding the |
| 315 |
features class ``allows_group_by_selected_pks_on_model()`` method as you |
| 316 |
require. See :ref:`Subclassing the built-in database backends |
| 317 |
<subclassing-database-backends>` for an example. |
| 318 |
|
| 319 |
Requests and Responses |
| 320 |
~~~~~~~~~~~~~~~~~~~~~~ |
| 321 |
|
| 322 |
* Allowed :class:`~django.http.HttpResponse` to be initialized with |
| 323 |
:class:`memoryview` content. |
| 324 |
|
| 325 |
* For use in, for example, Django templates, :attr:`.HttpRequest.headers` now |
| 326 |
allows lookups using underscores (e.g. ``user_agent``) in place of hyphens. |
| 327 |
|
| 328 |
.. _whats-new-security-3.0: |
| 329 |
|
| 330 |
Security |
| 331 |
~~~~~~~~ |
| 332 |
|
| 333 |
* :setting:`X_FRAME_OPTIONS` now defaults to ``'DENY'``. In older versions, the |
| 334 |
:setting:`X_FRAME_OPTIONS` setting defaults to ``'SAMEORIGIN'``. If your site |
| 335 |
uses frames of itself, you will need to explicitly set ``X_FRAME_OPTIONS = |
| 336 |
'SAMEORIGIN'`` for them to continue working. |
| 337 |
|
| 338 |
* :setting:`SECURE_CONTENT_TYPE_NOSNIFF` now defaults to ``True``. With this |
| 339 |
enabled, :class:`~django.middleware.security.SecurityMiddleware` sets the |
| 340 |
:ref:`x-content-type-options` header on all responses that do not already |
| 341 |
have it. |
| 342 |
|
| 343 |
* :class:`~django.middleware.security.SecurityMiddleware` can now send the |
| 344 |
:ref:`Referrer-Policy <referrer-policy>` header. |
| 345 |
|
| 346 |
Tests |
| 347 |
~~~~~ |
| 348 |
|
| 349 |
* The new test :class:`~django.test.Client` argument |
| 350 |
``raise_request_exception`` allows controlling whether or not exceptions |
| 351 |
raised during the request should also be raised in the test. The value |
| 352 |
defaults to ``True`` for backwards compatibility. If it is ``False`` and an |
| 353 |
exception occurs, the test client will return a 500 response with the |
| 354 |
attribute :attr:`~django.test.Response.exc_info`, a tuple providing |
| 355 |
information of the exception that occurred. |
| 356 |
|
| 357 |
* Tests and test cases to run can be selected by test name pattern using the |
| 358 |
new :option:`test -k` option. |
| 359 |
|
| 360 |
* HTML comparison, as used by |
| 361 |
:meth:`~django.test.SimpleTestCase.assertHTMLEqual`, now treats text, character |
| 362 |
references, and entity references that refer to the same character as |
| 363 |
equivalent. |
| 364 |
|
| 365 |
* :class:`~django.test.runner.DiscoverRunner` can now spawn a debugger at each |
| 366 |
error or failure using the :option:`test --pdb` option. |
| 367 |
|
| 368 |
.. _backwards-incompatible-3.0: |
| 369 |
|
| 370 |
Backwards incompatible changes in 3.0 |
| 371 |
===================================== |
| 372 |
|
| 373 |
``Model.save()`` when providing a default for the primary key |
| 374 |
------------------------------------------------------------- |
| 375 |
|
| 376 |
:meth:`.Model.save` no longer attempts to find a row when saving a new |
| 377 |
``Model`` instance and a default value for the primary key is provided, and |
| 378 |
always performs a single ``INSERT`` query. In older Django versions, |
| 379 |
``Model.save()`` performed either an ``INSERT`` or an ``UPDATE`` based on |
| 380 |
whether or not the row exists. |
| 381 |
|
| 382 |
This makes calling ``Model.save()`` while providing a default primary key value |
| 383 |
equivalent to passing :ref:`force_insert=True <ref-models-force-insert>` to |
| 384 |
model's ``save()``. Attempts to use a new ``Model`` instance to update an |
| 385 |
existing row will result in an ``IntegrityError``. |
| 386 |
|
| 387 |
In order to update an existing model for a specific primary key value, use the |
| 388 |
:meth:`~django.db.models.query.QuerySet.update_or_create` method or |
| 389 |
``QuerySet.filter(pk=…).update(…)`` instead. For example: |
| 390 |
|
| 391 |
.. code-block:: pycon |
| 392 |
|
| 393 |
>>> MyModel.objects.update_or_create(pk=existing_pk, defaults={"name": "new name"}) |
| 394 |
>>> MyModel.objects.filter(pk=existing_pk).update(name="new name") |
| 395 |
|
| 396 |
Database backend API |
| 397 |
-------------------- |
| 398 |
|
| 399 |
This section describes changes that may be needed in third-party database |
| 400 |
backends. |
| 401 |
|
| 402 |
* The second argument of ``DatabaseIntrospection.get_geometry_type()`` is now |
| 403 |
the row description instead of the column name. |
| 404 |
|
| 405 |
* ``DatabaseIntrospection.get_field_type()`` may no longer return tuples. |
| 406 |
|
| 407 |
* If the database can create foreign keys in the same SQL statement that adds a |
| 408 |
field, add ``SchemaEditor.sql_create_column_inline_fk`` with the appropriate |
| 409 |
SQL; otherwise, set ``DatabaseFeatures.can_create_inline_fk = False``. |
| 410 |
|
| 411 |
* ``DatabaseFeatures.can_return_id_from_insert`` and |
| 412 |
``can_return_ids_from_bulk_insert`` are renamed to |
| 413 |
``can_return_columns_from_insert`` and ``can_return_rows_from_bulk_insert``. |
| 414 |
|
| 415 |
* Database functions now handle :class:`datetime.timezone` formats when created |
| 416 |
using :class:`datetime.timedelta` instances (e.g. |
| 417 |
``timezone(timedelta(hours=5))``, which would output ``'UTC+05:00'``). |
| 418 |
Third-party backends should handle this format when preparing |
| 419 |
:class:`~django.db.models.DateTimeField` in ``datetime_cast_date_sql()``, |
| 420 |
``datetime_extract_sql()``, etc. |
| 421 |
|
| 422 |
* Entries for ``AutoField``, ``BigAutoField``, and ``SmallAutoField`` are added |
| 423 |
to ``DatabaseOperations.integer_field_ranges`` to support the integer range |
| 424 |
validators on these field types. Third-party backends may need to customize |
| 425 |
the default entries. |
| 426 |
|
| 427 |
* ``DatabaseOperations.fetch_returned_insert_id()`` is replaced by |
| 428 |
``fetch_returned_insert_columns()`` which returns a list of values returned |
| 429 |
by the ``INSERT … RETURNING`` statement, instead of a single value. |
| 430 |
|
| 431 |
* ``DatabaseOperations.return_insert_id()`` is replaced by |
| 432 |
``return_insert_columns()`` that accepts a ``fields`` |
| 433 |
argument, which is an iterable of fields to be returned after insert. Usually |
| 434 |
this is only the auto-generated primary key. |
| 435 |
|
| 436 |
:mod:`django.contrib.admin` |
| 437 |
--------------------------- |
| 438 |
|
| 439 |
* Admin's model history change messages now prefers more readable field labels |
| 440 |
instead of field names. |
| 441 |
|
| 442 |
:mod:`django.contrib.gis` |
| 443 |
------------------------- |
| 444 |
|
| 445 |
* Support for PostGIS 2.1 is removed. |
| 446 |
|
| 447 |
* Support for SpatiaLite 4.1 and 4.2 is removed. |
| 448 |
|
| 449 |
* Support for GDAL 1.11 and GEOS 3.4 is removed. |
| 450 |
|
| 451 |
Dropped support for PostgreSQL 9.4 |
| 452 |
---------------------------------- |
| 453 |
|
| 454 |
Upstream support for PostgreSQL 9.4 ends in December 2019. Django 3.0 supports |
| 455 |
PostgreSQL 9.5 and higher. |
| 456 |
|
| 457 |
Dropped support for Oracle 12.1 |
| 458 |
------------------------------- |
| 459 |
|
| 460 |
Upstream support for Oracle 12.1 ends in July 2021. Django 2.2 will be |
| 461 |
supported until April 2022. Django 3.0 officially supports Oracle 12.2 and 18c. |
| 462 |
|
| 463 |
Removed private Python 2 compatibility APIs |
| 464 |
------------------------------------------- |
| 465 |
|
| 466 |
While Python 2 support was removed in Django 2.0, some private APIs weren't |
| 467 |
removed from Django so that third party apps could continue using them until |
| 468 |
the Python 2 end-of-life. |
| 469 |
|
| 470 |
Since we expect apps to drop Python 2 compatibility when adding support for |
| 471 |
Django 3.0, we're removing these APIs at this time. |
| 472 |
|
| 473 |
* ``django.test.utils.str_prefix()`` - Strings don't have 'u' prefixes in |
| 474 |
Python 3. |
| 475 |
|
| 476 |
* ``django.test.utils.patch_logger()`` - Use |
| 477 |
:meth:`unittest.TestCase.assertLogs` instead. |
| 478 |
|
| 479 |
* ``django.utils.lru_cache.lru_cache()`` - Alias of |
| 480 |
:func:`functools.lru_cache`. |
| 481 |
|
| 482 |
* ``django.utils.decorators.available_attrs()`` - This function returns |
| 483 |
``functools.WRAPPER_ASSIGNMENTS``. |
| 484 |
|
| 485 |
* ``django.utils.decorators.ContextDecorator`` - Alias of |
| 486 |
:class:`contextlib.ContextDecorator`. |
| 487 |
|
| 488 |
* ``django.utils._os.abspathu()`` - Alias of :func:`os.path.abspath`. |
| 489 |
|
| 490 |
* ``django.utils._os.upath()`` and ``npath()`` - These functions do nothing on |
| 491 |
Python 3. |
| 492 |
|
| 493 |
* ``django.utils.six`` - Remove usage of this vendored library or switch to |
| 494 |
:pypi:`six`. |
| 495 |
|
| 496 |
* ``django.utils.encoding.python_2_unicode_compatible()`` - Alias of |
| 497 |
``six.python_2_unicode_compatible()``. |
| 498 |
|
| 499 |
* ``django.utils.functional.curry()`` - Use :func:`functools.partial` or |
| 500 |
:class:`functools.partialmethod`. See |
| 501 |
:commit:`5b1c389603a353625ae1603ba345147356336afb`. |
| 502 |
|
| 503 |
* ``django.utils.safestring.SafeBytes`` - Unused since Django 2.0. |
| 504 |
|
| 505 |
New default value for the ``FILE_UPLOAD_PERMISSIONS`` setting |
| 506 |
------------------------------------------------------------- |
| 507 |
|
| 508 |
In older versions, the :setting:`FILE_UPLOAD_PERMISSIONS` setting defaults to |
| 509 |
``None``. With the default :setting:`FILE_UPLOAD_HANDLERS`, this results in |
| 510 |
uploaded files having different permissions depending on their size and which |
| 511 |
upload handler is used. |
| 512 |
|
| 513 |
``FILE_UPLOAD_PERMISSIONS`` now defaults to ``0o644`` to avoid this |
| 514 |
inconsistency. |
| 515 |
|
| 516 |
New default values for security settings |
| 517 |
---------------------------------------- |
| 518 |
|
| 519 |
To make Django projects more secure by default, some security settings now have |
| 520 |
more secure default values: |
| 521 |
|
| 522 |
* :setting:`X_FRAME_OPTIONS` now defaults to ``'DENY'``. |
| 523 |
|
| 524 |
* :setting:`SECURE_CONTENT_TYPE_NOSNIFF` now defaults to ``True``. |
| 525 |
|
| 526 |
See the *What's New* :ref:`Security section <whats-new-security-3.0>` above for |
| 527 |
more details on these changes. |
| 528 |
|
| 529 |
Miscellaneous |
| 530 |
------------- |
| 531 |
|
| 532 |
* ``ContentType.__str__()`` now includes the model's ``app_label`` to |
| 533 |
disambiguate models with the same name in different apps. |
| 534 |
|
| 535 |
* Because accessing the language in the session rather than in the cookie is |
| 536 |
deprecated, ``LocaleMiddleware`` no longer looks for the user's language in |
| 537 |
the session and :func:`django.contrib.auth.logout` no longer preserves the |
| 538 |
session's language after logout. |
| 539 |
|
| 540 |
* :func:`django.utils.html.escape` now uses :func:`html.escape` to escape HTML. |
| 541 |
This converts ``'`` to ``'`` instead of the previous equivalent decimal |
| 542 |
code ``'``. |
| 543 |
|
| 544 |
* The ``django-admin test -k`` option now works as the :option:`unittest |
| 545 |
-k<unittest.-k>` option rather than as a shortcut for ``--keepdb``. |
| 546 |
|
| 547 |
* Support for ``pywatchman`` < 1.2.0 is removed. |
| 548 |
|
| 549 |
* :func:`~django.utils.http.urlencode` now encodes iterable values as they are |
| 550 |
when ``doseq=False``, rather than iterating them, bringing it into line with |
| 551 |
the standard library :func:`urllib.parse.urlencode` function. |
| 552 |
|
| 553 |
* ``intword`` template filter now translates ``1.0`` as a singular phrase and |
| 554 |
all other numeric values as plural. This may be incorrect for some languages. |
| 555 |
|
| 556 |
* Assigning a value to a model's :class:`~django.db.models.ForeignKey` or |
| 557 |
:class:`~django.db.models.OneToOneField` ``'_id'`` attribute now unsets the |
| 558 |
corresponding field. Accessing the field afterward will result in a query. |
| 559 |
|
| 560 |
* :func:`~django.utils.cache.patch_vary_headers` now handles an asterisk |
| 561 |
``'*'`` according to :rfc:`7231#section-7.1.4`, i.e. if a list of header |
| 562 |
field names contains an asterisk, then the ``Vary`` header will consist of a |
| 563 |
single asterisk ``'*'``. |
| 564 |
|
| 565 |
* On MySQL 8.0.16+, ``PositiveIntegerField`` and ``PositiveSmallIntegerField`` |
| 566 |
now include a check constraint to prevent negative values in the database. |
| 567 |
|
| 568 |
* ``alias=None`` is added to the signature of |
| 569 |
:meth:`.Expression.get_group_by_cols`. |
| 570 |
|
| 571 |
* ``RegexPattern``, used by :func:`~django.urls.re_path`, no longer returns |
| 572 |
keyword arguments with ``None`` values to be passed to the view for the |
| 573 |
optional named groups that are missing. |
| 574 |
|
| 575 |
.. _deprecated-features-3.0: |
| 576 |
|
| 577 |
Features deprecated in 3.0 |
| 578 |
========================== |
| 579 |
|
| 580 |
``django.utils.encoding.force_text()`` and ``smart_text()`` |
| 581 |
----------------------------------------------------------- |
| 582 |
|
| 583 |
The ``smart_text()`` and ``force_text()`` aliases (since Django 2.0) of |
| 584 |
``smart_str()`` and ``force_str()`` are deprecated. Ignore this deprecation if |
| 585 |
your code supports Python 2 as the behavior of ``smart_str()`` and |
| 586 |
``force_str()`` is different there. |
| 587 |
|
| 588 |
Miscellaneous |
| 589 |
------------- |
| 590 |
|
| 591 |
* ``django.utils.http.urlquote()``, ``urlquote_plus()``, ``urlunquote()``, and |
| 592 |
``urlunquote_plus()`` are deprecated in favor of the functions that they're |
| 593 |
aliases for: :func:`urllib.parse.quote`, :func:`~urllib.parse.quote_plus`, |
| 594 |
:func:`~urllib.parse.unquote`, and :func:`~urllib.parse.unquote_plus`. |
| 595 |
|
| 596 |
* ``django.utils.translation.ugettext()``, ``ugettext_lazy()``, |
| 597 |
``ugettext_noop()``, ``ungettext()``, and ``ungettext_lazy()`` are deprecated |
| 598 |
in favor of the functions that they're aliases for: |
| 599 |
:func:`django.utils.translation.gettext`, |
| 600 |
:func:`~django.utils.translation.gettext_lazy`, |
| 601 |
:func:`~django.utils.translation.gettext_noop`, |
| 602 |
:func:`~django.utils.translation.ngettext`, and |
| 603 |
:func:`~django.utils.translation.ngettext_lazy`. |
| 604 |
|
| 605 |
* To limit creation of sessions and hence favor some caching strategies, |
| 606 |
:func:`django.views.i18n.set_language` will stop setting the user's language |
| 607 |
in the session in Django 4.0. Since Django 2.1, the language is always stored |
| 608 |
in the :setting:`LANGUAGE_COOKIE_NAME` cookie. |
| 609 |
|
| 610 |
* ``django.utils.text.unescape_entities()`` is deprecated in favor of |
| 611 |
:func:`html.unescape`. Note that unlike ``unescape_entities()``, |
| 612 |
``html.unescape()`` evaluates lazy strings immediately. |
| 613 |
|
| 614 |
* To avoid possible confusion as to effective scope, the private internal |
| 615 |
utility ``is_safe_url()`` is renamed to |
| 616 |
``url_has_allowed_host_and_scheme()``. That a URL has an allowed host and |
| 617 |
scheme doesn't in general imply that it's "safe". It may still be quoted |
| 618 |
incorrectly, for example. Ensure to also use |
| 619 |
:func:`~django.utils.encoding.iri_to_uri` on the path component of untrusted |
| 620 |
URLs. |
| 621 |
|
| 622 |
.. _removed-features-3.0: |
| 623 |
|
| 624 |
Features removed in 3.0 |
| 625 |
======================= |
| 626 |
|
| 627 |
These features have reached the end of their deprecation cycle and are removed |
| 628 |
in Django 3.0. |
| 629 |
|
| 630 |
See :ref:`deprecated-features-2.0` for details on these changes, including how |
| 631 |
to remove usage of these features. |
| 632 |
|
| 633 |
* The ``django.db.backends.postgresql_psycopg2`` module is removed. |
| 634 |
|
| 635 |
* ``django.shortcuts.render_to_response()`` is removed. |
| 636 |
|
| 637 |
* The ``DEFAULT_CONTENT_TYPE`` setting is removed. |
| 638 |
|
| 639 |
* ``HttpRequest.xreadlines()`` is removed. |
| 640 |
|
| 641 |
* Support for the ``context`` argument of ``Field.from_db_value()`` and |
| 642 |
``Expression.convert_value()`` is removed. |
| 643 |
|
| 644 |
* The ``field_name`` keyword argument of ``QuerySet.earliest()`` and |
| 645 |
``latest()`` is removed. |
| 646 |
|
| 647 |
See :ref:`deprecated-features-2.1` for details on these changes, including how |
| 648 |
to remove usage of these features. |
| 649 |
|
| 650 |
* The ``ForceRHR`` GIS function is removed. |
| 651 |
|
| 652 |
* ``django.utils.http.cookie_date()`` is removed. |
| 653 |
|
| 654 |
* The ``staticfiles`` and ``admin_static`` template tag libraries are removed. |
| 655 |
|
| 656 |
* ``django.contrib.staticfiles.templatetags.staticfiles.static()`` is removed. |