Changelog
### 2.9.1
```
-------------
Bugfixes
~~~~~~~~
* The internal locale-data loading functions now validate the name of the locale file to be loaded and only
allow files within Babel's data directory. Thank you to Chris Lyne of Tenable, Inc. for discovering the issue!
```
### 2.9.0
```
-------------
Upcoming version support changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* This version, Babel 2.9, is the last version of Babel to support Python 2.7, Python 3.4, and Python 3.5.
Improvements
~~~~~~~~~~~~
* CLDR: Use CLDR 37 – Aarni Koskela (734)
* Dates: Handle ZoneInfo objects in get_timezone_location, get_timezone_name - Alessio Bogon (741)
* Numbers: Add group_separator feature in number formatting - Abdullah Javed Nesar (726)
Bugfixes
~~~~~~~~
* Dates: Correct default Format().timedelta format to 'long' to mute deprecation warnings – Aarni Koskela
* Import: Simplify iteration code in "import_cldr.py" – Felix Schwarz
* Import: Stop using deprecated ElementTree methods "getchildren()" and "getiterator()" – Felix Schwarz
* Messages: Fix unicode printing error on Python 2 without TTY. – Niklas Hambüchen
* Messages: Introduce invariant that _invalid_pofile() takes unicode line. – Niklas Hambüchen
* Tests: fix tests when using Python 3.9 – Felix Schwarz
* Tests: Remove deprecated 'sudo: false' from Travis configuration – Jon Dufresne
* Tests: Support Py.test 6.x – Aarni Koskela
* Utilities: LazyProxy: Handle AttributeError in specified func – Nikiforov Konstantin (724)
* Utilities: Replace usage of parser.suite with ast.parse – Miro Hrončok
Documentation
~~~~~~~~~~~~~
* Update parse_number comments – Brad Martin (708)
* Add __iter__ to Catalog documentation – CyanNani123
```
### 2.8.1
```
-------------
This is solely a patch release to make running tests on Py.test 6+ possible.
Bugfixes
~~~~~~~~
* Support Py.test 6 - Aarni Koskela (747, 750, 752)
```
### 2.8.0
```
-------------
Improvements
~~~~~~~~~~~~
* CLDR: Upgrade to CLDR 36.0 - Aarni Koskela (679)
* Messages: Don't even open files with the "ignore" extraction method - sebleblanc (678)
Bugfixes
~~~~~~~~
* Numbers: Fix formatting very small decimals when quantization is disabled - Lev Lybin, miluChen (662)
* Messages: Attempt to sort all messages – Mario Frasca (651, 606)
Docs
~~~~
* Add years to changelog - Romuald Brunet
* Note that installation requires pytz - Steve (Gadget) Barnes
```
### 2.7.0
```
-------------
Possibly incompatible changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These may be backward incompatible in some cases, as some more-or-less internal
APIs have changed. Please feel free to file issues if you bump into anything
strange and we'll try to help!
* General: Internal uses of ``babel.util.odict`` have been replaced with
``collections.OrderedDict`` from The Python standard library.
Improvements
~~~~~~~~~~~~
* CLDR: Upgrade to CLDR 35.1 - Alberto Mardegan, Aarni Koskela (626, 643)
* General: allow anchoring path patterns to the start of a string - Brian Cappello (600)
* General: Bumped version requirement on pytz - chrisbrake (592)
* Messages: `pybabel compile`: exit with code 1 if errors were encountered - Aarni Koskela (647)
* Messages: Add omit-header to update_catalog - Cédric Krier (633)
* Messages: Catalog update: keep user comments from destination by default - Aarni Koskela (648)
* Messages: Skip empty message when writing mo file - Cédric Krier (564)
* Messages: Small fixes to avoid crashes on badly formatted .po files - Bryn Truscott (597)
* Numbers: `parse_decimal()` `strict` argument and `suggestions` - Charly C (590)
* Numbers: don't repeat suggestions in parse_decimal strict - Serban Constantin (599)
* Numbers: implement currency formatting with long display names - Luke Plant (585)
* Numbers: parse_decimal(): assume spaces are equivalent to non-breaking spaces when not in strict mode - Aarni Koskela (649)
* Performance: Cache locale_identifiers() - Aarni Koskela (644)
Bugfixes
~~~~~~~~
* CLDR: Skip alt=... for week data (minDays, firstDay, weekendStart, weekendEnd) - Aarni Koskela (634)
* Dates: Fix wrong weeknumber for 31.12.2018 - BT-sschmid (621)
* Locale: Avoid KeyError trying to get data on WindowsXP - mondeja (604)
* Locale: get_display_name(): Don't attempt to concatenate variant information to None - Aarni Koskela (645)
* Messages: pofile: Add comparison operators to _NormalizedString - Aarni Koskela (646)
* Messages: pofile: don't crash when message.locations can't be sorted - Aarni Koskela (646)
Tooling & docs
~~~~~~~~~~~~~~
* Docs: Remove all references to deprecated easy_install - Jon Dufresne (610)
* Docs: Switch print statement in docs to print function - NotAFile
* Docs: Update all pypi.python.org URLs to pypi.org - Jon Dufresne (587)
* Docs: Use https URLs throughout project where available - Jon Dufresne (588)
* Support: Add testing and document support for Python 3.7 - Jon Dufresne (611)
* Support: Test on Python 3.8-dev - Aarni Koskela (642)
* Support: Using ABCs from collections instead of collections.abc is deprecated. - Julien Palard (609)
* Tests: Fix conftest.py compatibility with pytest 4.3 - Miro Hrončok (635)
* Tests: Update pytest and pytest-cov - Miro Hrončok (635)
```
Links
- PyPI: https://pypi.org/project/babel
- Changelog: https://pyup.io/changelogs/babel/
- Homepage: http://babel.pocoo.org/
- Docs: https://pythonhosted.org/Babel/
Changelog
### 4.0
```
========================
*December 7, 2021*
Welcome to Django 4.0!
These release notes cover the :ref:`new features <whats-new-4.0>`, as well as
some :ref:`backwards incompatible changes <backwards-incompatible-4.0>` you'll
want to be aware of when upgrading from Django 3.2 or earlier. We've
:ref:`begun the deprecation process for some features
<deprecated-features-4.0>`.
See the :doc:`/howto/upgrade-version` guide if you're updating an existing
project.
Python compatibility
====================
Django 4.0 supports Python 3.8, 3.9, and 3.10. We **highly recommend** and only
officially support the latest release of each series.
The Django 3.2.x series is the last to support Python 3.6 and 3.7.
.. _whats-new-4.0:
What's new in Django 4.0
========================
``zoneinfo`` default timezone implementation
--------------------------------------------
The Python standard library's :mod:`zoneinfo` is now the default timezone
implementation in Django.
This is the next step in the migration from using ``pytz`` to using
:mod:`zoneinfo`. Django 3.2 allowed the use of non-``pytz`` time zones. Django
4.0 makes ``zoneinfo`` the default implementation. Support for ``pytz`` is now
deprecated and will be removed in Django 5.0.
:mod:`zoneinfo` is part of the Python standard library from Python 3.9. The
``backports.zoneinfo`` package is automatically installed alongside Django if
you are using Python 3.8.
The move to ``zoneinfo`` should be largely transparent. Selection of the
current timezone, conversion of datetime instances to the current timezone in
forms and templates, as well as operations on aware datetimes in UTC are
unaffected.
However, if you are working with non-UTC time zones, and using the ``pytz``
``normalize()`` and ``localize()`` APIs, possibly with the :setting:`TIME_ZONE
<DATABASE-TIME_ZONE>` setting, you will need to audit your code, since ``pytz``
and ``zoneinfo`` are not entirely equivalent.
To give time for such an audit, the transitional :setting:`USE_DEPRECATED_PYTZ`
setting allows continued use of ``pytz`` during the 4.x release cycle. This
setting will be removed in Django 5.0.
In addition, a `pytz_deprecation_shim`_ package, created by the ``zoneinfo``
author, can be used to assist with the migration from ``pytz``. This package
provides shims to help you safely remove ``pytz``, and has a detailed
`migration guide`_ showing how to move to the new ``zoneinfo`` APIs.
Using `pytz_deprecation_shim`_ and the :setting:`USE_DEPRECATED_PYTZ`
transitional setting is recommended if you need a gradual update path.
.. _pytz_deprecation_shim: https://pytz-deprecation-shim.readthedocs.io/en/latest/index.html
.. _migration guide: https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html
Functional unique constraints
-----------------------------
The new :attr:`*expressions <django.db.models.UniqueConstraint.expressions>`
positional argument of
:class:`UniqueConstraint() <django.db.models.UniqueConstraint>` enables
creating functional unique constraints on expressions and database functions.
For example::
from django.db import models
from django.db.models import UniqueConstraint
from django.db.models.functions import Lower
class MyModel(models.Model):
first_name = models.CharField(max_length=255)
last_name = models.CharField(max_length=255)
class Meta:
constraints = [
UniqueConstraint(
Lower('first_name'),
Lower('last_name').desc(),
name='first_last_name_unique',
),
]
Functional unique constraints are added to models using the
:attr:`Meta.constraints <django.db.models.Options.constraints>` option.
``scrypt`` password hasher
--------------------------
The new :ref:`scrypt password hasher <scrypt-usage>` is more secure and
recommended over PBKDF2. However, it's not the default as it requires OpenSSL
1.1+ and more memory.
Redis cache backend
-------------------
The new ``django.core.cache.backends.redis.RedisCache`` cache backend provides
built-in support for caching with Redis. `redis-py`_ 3.0.0 or higher is
required. For more details, see the :ref:`documentation on caching with Redis
in Django <redis>`.
.. _`redis-py`: https://pypi.org/project/redis/
Template based form rendering
-----------------------------
To enhance customization of :class:`Forms <django.forms.Form>`,
:doc:`Formsets </topics/forms/formsets>`, and
:class:`~django.forms.ErrorList` they are now rendered using the template
engine. See the new :meth:`~django.forms.Form.render`,
:meth:`~django.forms.Form.get_context`, and
:attr:`~django.forms.Form.template_name` for ``Form`` and
:ref:`formset rendering <formset-rendering>` for ``Formset``.
Minor features
--------------
:mod:`django.contrib.admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The ``admin/base.html`` template now has a new block ``header`` which
contains the admin site header.
* The new :meth:`.ModelAdmin.get_formset_kwargs` method allows customizing the
keyword arguments passed to the constructor of a formset.
* The navigation sidebar now has a quick filter toolbar.
* The new context variable ``model`` which contains the model class for each
model is added to the :meth:`.AdminSite.each_context` method.
* The new :attr:`.ModelAdmin.search_help_text` attribute allows specifying a
descriptive text for the search box.
* The :attr:`.InlineModelAdmin.verbose_name_plural` attribute now fallbacks to
the :attr:`.InlineModelAdmin.verbose_name` + ``'s'``.
* jQuery is upgraded from version 3.5.1 to 3.6.0.
:mod:`django.contrib.admindocs`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The admindocs now allows esoteric setups where :setting:`ROOT_URLCONF` is not
a string.
* The model section of the ``admindocs`` now shows cached properties.
:mod:`django.contrib.auth`
~~~~~~~~~~~~~~~~~~~~~~~~~~
* The default iteration count for the PBKDF2 password hasher is increased from
260,000 to 320,000.
* The new
:attr:`LoginView.next_page <django.contrib.auth.views.LoginView.next_page>`
attribute and
:meth:`~django.contrib.auth.views.LoginView.get_default_redirect_url` method
allow customizing the redirect after login.
:mod:`django.contrib.gis`
~~~~~~~~~~~~~~~~~~~~~~~~~
* Added support for SpatiaLite 5.
* :class:`~django.contrib.gis.gdal.GDALRaster` now allows creating rasters in
any GDAL virtual filesystem.
* The new :class:`~django.contrib.gis.admin.GISModelAdmin` class allows
customizing the widget used for ``GeometryField``. This is encouraged instead
of deprecated ``GeoModelAdmin`` and ``OSMGeoAdmin``.
:mod:`django.contrib.postgres`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The PostgreSQL backend now supports connecting by a service name. See
:ref:`postgresql-connection-settings` for more details.
* The new :class:`~django.contrib.postgres.operations.AddConstraintNotValid`
operation allows creating check constraints on PostgreSQL without verifying
that all existing rows satisfy the new constraint.
* The new :class:`~django.contrib.postgres.operations.ValidateConstraint`
operation allows validating check constraints which were created using
:class:`~django.contrib.postgres.operations.AddConstraintNotValid` on
PostgreSQL.
* The new
:class:`ArraySubquery() <django.contrib.postgres.expressions.ArraySubquery>`
expression allows using subqueries to construct lists of values on
PostgreSQL.
* The new :lookup:`trigram_word_similar` lookup, and the
:class:`TrigramWordDistance()
<django.contrib.postgres.search.TrigramWordDistance>` and
:class:`TrigramWordSimilarity()
<django.contrib.postgres.search.TrigramWordSimilarity>` expressions allow
using trigram word similarity.
:mod:`django.contrib.staticfiles`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` now
replaces paths to JavaScript source map references with their hashed
counterparts.
* The new ``manifest_storage`` argument of
:class:`~django.contrib.staticfiles.storage.ManifestFilesMixin` and
:class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage`
allows customizing the manifest file storage.
Cache
~~~~~
* The new async API for ``django.core.cache.backends.base.BaseCache`` begins
the process of making cache backends async-compatible. The new async methods
all have ``a`` prefixed names, e.g. ``aadd()``, ``aget()``, ``aset()``,
``aget_or_set()``, or ``adelete_many()``.
Going forward, the ``a`` prefix will be used for async variants of methods
generally.
CSRF
~~~~
* CSRF protection now consults the ``Origin`` header, if present. To facilitate
this, :ref:`some changes <csrf-trusted-origins-changes-4.0>` to the
:setting:`CSRF_TRUSTED_ORIGINS` setting are required.
Forms
~~~~~
* :class:`~django.forms.ModelChoiceField` now includes the provided value in
the ``params`` argument of a raised
:exc:`~django.core.exceptions.ValidationError` for the ``invalid_choice``
error message. This allows custom error messages to use the ``%(value)s``
placeholder.
* :class:`~django.forms.formsets.BaseFormSet` now renders non-form errors with
an additional class of ``nonform`` to help distinguish them from
form-specific errors.
* :class:`~django.forms.formsets.BaseFormSet` now allows customizing the widget
used when deleting forms via
:attr:`~django.forms.formsets.BaseFormSet.can_delete` by setting the
:attr:`~django.forms.formsets.BaseFormSet.deletion_widget` attribute or
overriding :meth:`~django.forms.formsets.BaseFormSet.get_deletion_widget`
method.
Internationalization
~~~~~~~~~~~~~~~~~~~~
* Added support and translations for the Malay language.
Generic Views
~~~~~~~~~~~~~
* :class:`~django.views.generic.edit.DeleteView` now uses
:class:`~django.views.generic.edit.FormMixin`, allowing you to provide a
:class:`~django.forms.Form` subclass, with a checkbox for example, to confirm
deletion. In addition, this allows ``DeleteView`` to function with
:class:`django.contrib.messages.views.SuccessMessageMixin`.
In accordance with ``FormMixin``, object deletion for POST requests is
handled in ``form_valid()``. Custom delete logic in ``delete()`` handlers
should be moved to ``form_valid()``, or a shared helper method, as needed.
Logging
~~~~~~~
* The alias of the database used in an SQL call is now passed as extra context
along with each message to the :ref:`django-db-logger` logger.
Management Commands
~~~~~~~~~~~~~~~~~~~
* The :djadmin:`runserver` management command now supports the
:option:`--skip-checks` option.
* On PostgreSQL, :djadmin:`dbshell` now supports specifying a password file.
* The :djadmin:`shell` command now respects :py:data:`sys.__interactivehook__`
at startup. This allows loading shell history between interactive sessions.
As a consequence, ``readline`` is no longer loaded if running in *isolated*
mode.
* The new :attr:`BaseCommand.suppressed_base_arguments
<django.core.management.BaseCommand.suppressed_base_arguments>` attribute
allows suppressing unsupported default command options in the help output.
* The new :option:`startapp --exclude` and :option:`startproject --exclude`
options allow excluding directories from the template.
Models
~~~~~~
* New :meth:`QuerySet.contains(obj) <.QuerySet.contains>` method returns
whether the queryset contains the given object. This tries to perform the
query in the simplest and fastest way possible.
* The new ``precision`` argument of the
:class:`Round() <django.db.models.functions.Round>` database function allows
specifying the number of decimal places after rounding.
* :meth:`.QuerySet.bulk_create` now sets the primary key on objects when using
SQLite 3.35+.
* :class:`~django.db.models.DurationField` now supports multiplying and
dividing by scalar values on SQLite.
* :meth:`.QuerySet.bulk_update` now returns the number of objects updated.
* The new :attr:`.Expression.empty_result_set_value` attribute allows
specifying a value to return when the function is used over an empty result
set.
* The ``skip_locked`` argument of :meth:`.QuerySet.select_for_update()` is now
allowed on MariaDB 10.6+.
* :class:`~django.db.models.Lookup` expressions may now be used in ``QuerySet``
annotations, aggregations, and directly in filters.
* The new :ref:`default <aggregate-default>` argument for built-in aggregates
allows specifying a value to be returned when the queryset (or grouping)
contains no entries, rather than ``None``.
Requests and Responses
~~~~~~~~~~~~~~~~~~~~~~
* The :class:`~django.middleware.security.SecurityMiddleware` now adds the
:ref:`Cross-Origin Opener Policy <cross-origin-opener-policy>` header with a
value of ``'same-origin'`` to prevent cross-origin popups from sharing the
same browsing context. You can prevent this header from being added by
setting the :setting:`SECURE_CROSS_ORIGIN_OPENER_POLICY` setting to ``None``.
Signals
~~~~~~~
* The new ``stdout`` argument for :func:`~django.db.models.signals.pre_migrate`
and :func:`~django.db.models.signals.post_migrate` signals allows redirecting
output to a stream-like object. It should be preferred over
:py:data:`sys.stdout` and :py:func:`print` when emitting verbose output in
order to allow proper capture when testing.
Templates
~~~~~~~~~
* :tfilter:`floatformat` template filter now allows using the ``u`` suffix to
force disabling localization.
Tests
~~~~~
* The new ``serialized_aliases`` argument of
:func:`django.test.utils.setup_databases` determines which
:setting:`DATABASES` aliases test databases should have their state
serialized to allow usage of the
:ref:`serialized_rollback <test-case-serialized-rollback>` feature.
* Django test runner now supports a :option:`--buffer <test --buffer>` option
with parallel tests.
* The new ``logger`` argument to :class:`~django.test.runner.DiscoverRunner`
allows a Python :py:ref:`logger <logger>` to be used for logging.
* The new :meth:`.DiscoverRunner.log` method provides a way to log messages
that uses the ``DiscoverRunner.logger``, or prints to the console if not set.
* Django test runner now supports a :option:`--shuffle <test --shuffle>` option
to execute tests in a random order.
* The :option:`test --parallel` option now supports the value ``auto`` to run
one test process for each processor core.
* :meth:`.TestCase.captureOnCommitCallbacks` now captures new callbacks added
while executing :func:`.transaction.on_commit` callbacks.
.. _backwards-incompatible-4.0:
Backwards incompatible changes in 4.0
=====================================
Database backend API
--------------------
This section describes changes that may be needed in third-party database
backends.
* ``DatabaseOperations.year_lookup_bounds_for_date_field()`` and
``year_lookup_bounds_for_datetime_field()`` methods now take the optional
``iso_year`` argument in order to support bounds for ISO-8601 week-numbering
years.
* The second argument of ``DatabaseSchemaEditor._unique_sql()`` and
``_create_unique_sql()`` methods is now ``fields`` instead of ``columns``.
:mod:`django.contrib.gis`
-------------------------
* Support for PostGIS 2.3 is removed.
* Support for GDAL 2.0 and GEOS 3.5 is removed.
Dropped support for PostgreSQL 9.6
----------------------------------
Upstream support for PostgreSQL 9.6 ends in November 2021. Django 4.0 supports
PostgreSQL 10 and higher.
Dropped support for Oracle 12.2 and 18c
---------------------------------------
Upstream support for Oracle 12.2 ends in March 2022 and for Oracle 18c it ends
in June 2021. Django 3.2 will be supported until April 2024. Django 4.0
officially supports Oracle 19c.
.. _csrf-trusted-origins-changes-4.0:
``CSRF_TRUSTED_ORIGINS`` changes
--------------------------------
Format change
~~~~~~~~~~~~~
Values in the :setting:`CSRF_TRUSTED_ORIGINS` setting must include the scheme
(e.g. ``'http://'`` or ``'https://'``) instead of only the hostname.
Also, values that started with a dot, must now also include an asterisk before
the dot. For example, change ``'.example.com'`` to ``'https://*.example.com'``.
A system check detects any required changes.
Configuring it may now be required
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As CSRF protection now consults the ``Origin`` header, you may need to set
:setting:`CSRF_TRUSTED_ORIGINS`, particularly if you allow requests from
subdomains by setting :setting:`CSRF_COOKIE_DOMAIN` (or
:setting:`SESSION_COOKIE_DOMAIN` if :setting:`CSRF_USE_SESSIONS` is enabled) to
a value starting with a dot.
``SecurityMiddleware`` no longer sets the ``X-XSS-Protection`` header
---------------------------------------------------------------------
The :class:`~django.middleware.security.SecurityMiddleware` no longer sets the
``X-XSS-Protection`` header if the ``SECURE_BROWSER_XSS_FILTER`` setting is
``True``. The setting is removed.
Most modern browsers don't honor the ``X-XSS-Protection`` HTTP header. You can
use Content-Security-Policy_ without allowing ``'unsafe-inline'`` scripts
instead.
If you want to support legacy browsers and set the header, use this line in a
custom middleware::
response.headers.setdefault('X-XSS-Protection', '1; mode=block')
.. _Content-Security-Policy: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy
Migrations autodetector changes
-------------------------------
The migrations autodetector now uses model states instead of model classes.
Also, migration operations for ``ForeignKey`` and ``ManyToManyField`` fields no
longer specify attributes which were not passed to the fields during
initialization.
As a side-effect, running ``makemigrations`` might generate no-op
``AlterField`` operations for ``ManyToManyField`` and ``ForeignKey`` fields in
some cases.
``DeleteView`` changes
----------------------
:class:`~django.views.generic.edit.DeleteView` now uses
:class:`~django.views.generic.edit.FormMixin` to handle POST requests. As a
consequence, any custom deletion logic in ``delete()`` handlers should be
moved to ``form_valid()``, or a shared helper method, if required.
Miscellaneous
-------------
* Support for ``cx_Oracle`` < 7.0 is removed.
* To allow serving a Django site on a subpath without changing the value of
:setting:`STATIC_URL`, the leading slash is removed from that setting (now
``'static/'``) in the default :djadmin:`startproject` template.
* The :class:`~django.contrib.admin.AdminSite` method for the admin ``index``
view is no longer decorated with ``never_cache`` when accessed directly,
rather than via the recommended ``AdminSite.urls`` property, or
``AdminSite.get_urls()`` method.
* Unsupported operations on a sliced queryset now raise ``TypeError`` instead
of ``AssertionError``.
* The undocumented ``django.test.runner.reorder_suite()`` function is renamed
to ``reorder_tests()``. It now accepts an iterable of tests rather than a
test suite, and returns an iterator of tests.
* Calling ``FileSystemStorage.delete()`` with an empty ``name`` now raises
``ValueError`` instead of ``AssertionError``.
* Calling ``EmailMultiAlternatives.attach_alternative()`` or
``EmailMessage.attach()`` with an invalid ``content`` or ``mimetype``
arguments now raise ``ValueError`` instead of ``AssertionError``.
* :meth:`~django.test.SimpleTestCase.assertHTMLEqual` no longer considers a
non-boolean attribute without a value equal to an attribute with the same
name and value.
* Tests that fail to load, for example due to syntax errors, now always match
when using :option:`test --tag`.
* The undocumented ``django.contrib.admin.utils.lookup_needs_distinct()``
function is renamed to ``lookup_spawns_duplicates()``.
* The undocumented ``HttpRequest.get_raw_uri()`` method is removed. The
:meth:`.HttpRequest.build_absolute_uri` method may be a suitable alternative.
* The ``object`` argument of undocumented ``ModelAdmin.log_addition()``,
``log_change()``, and ``log_deletion()`` methods is renamed to ``obj``.
* :class:`~django.utils.feedgenerator.RssFeed`,
:class:`~django.utils.feedgenerator.Atom1Feed`, and their subclasses now emit
elements with no content as self-closing tags.
* ``NodeList.render()`` no longer casts the output of ``render()`` method for
individual nodes to a string. ``Node.render()`` should always return a string
as documented.
* The ``where_class`` property of ``django.db.models.sql.query.Query`` and the
``where_class`` argument to the private ``get_extra_restriction()`` method of
``ForeignObject`` and ``ForeignObjectRel`` are removed. If needed, initialize
``django.db.models.sql.where.WhereNode`` instead.
* The ``filter_clause`` argument of the undocumented ``Query.add_filter()``
method is replaced by two positional arguments ``filter_lhs`` and
``filter_rhs``.
* :class:`~django.middleware.csrf.CsrfViewMiddleware` now uses
``request.META['CSRF_COOKIE_NEEDS_UPDATE']`` in place of
``request.META['CSRF_COOKIE_USED']``, ``request.csrf_cookie_needs_reset``,
and ``response.csrf_cookie_set`` to track whether the CSRF cookie should be
sent. This is an undocumented, private API.
* The undocumented ``TRANSLATOR_COMMENT_MARK`` constant is moved from
``django.template.base`` to ``django.utils.translation.template``.
* The ``real_apps`` argument of the undocumented
``django.db.migrations.state.ProjectState.__init__()`` method must now be a
set if provided.
* :class:`~django.forms.RadioSelect` and
:class:`~django.forms.CheckboxSelectMultiple` widgets are now rendered in
``<div>`` tags so they are announced more concisely by screen readers. If you
need the previous behavior, :ref:`override the widget template
<overriding-built-in-widget-templates>` with the appropriate template from
Django 3.2.
* The :tfilter:`floatformat` template filter no longer depends on the
``USE_L10N`` setting and always returns localized output. Use the ``u``
suffix to disable localization.
* The default value of the ``USE_L10N`` setting is changed to ``True``. See the
:ref:`Localization section <use_l10n_deprecation>` above for more details.
* As part of the :ref:`move to zoneinfo <whats-new-4.0>`,
:attr:`django.utils.timezone.utc` is changed to alias
:attr:`datetime.timezone.utc`.
* The minimum supported version of ``asgiref`` is increased from 3.3.2 to
3.4.1.
.. _deprecated-features-4.0:
Features deprecated in 4.0
==========================
Use of ``pytz`` time zones
--------------------------
As part of the :ref:`move to zoneinfo <whats-new-4.0>`, use of ``pytz`` time
zones is deprecated.
Accordingly, the ``is_dst`` arguments to the following are also deprecated:
* :meth:`django.db.models.query.QuerySet.datetimes`
* :func:`django.db.models.functions.Trunc`
* :func:`django.db.models.functions.TruncSecond`
* :func:`django.db.models.functions.TruncMinute`
* :func:`django.db.models.functions.TruncHour`
* :func:`django.db.models.functions.TruncDay`
* :func:`django.db.models.functions.TruncWeek`
* :func:`django.db.models.functions.TruncMonth`
* :func:`django.db.models.functions.TruncQuarter`
* :func:`django.db.models.functions.TruncYear`
* :func:`django.utils.timezone.make_aware`
Support for use of ``pytz`` will be removed in Django 5.0.
Time zone support
-----------------
In order to follow good practice, the default value of the :setting:`USE_TZ`
setting will change from ``False`` to ``True``, and time zone support will be
enabled by default, in Django 5.0.
Note that the default :file:`settings.py` file created by
:djadmin:`django-admin startproject <startproject>` includes
:setting:`USE_TZ = True <USE_TZ>` since Django 1.4.
You can set ``USE_TZ`` to ``False`` in your project settings before then to
opt-out.
.. _use_l10n_deprecation:
Localization
------------
In order to follow good practice, the default value of the ``USE_L10N`` setting
is changed from ``False`` to ``True``.
Moreover ``USE_L10N`` is deprecated as of this release. Starting with Django
5.0, by default, any date or number displayed by Django will be localized.
The :ttag:`{% localize %} <localize>` tag and the :tfilter:`localize`/
:tfilter:`unlocalize` filters will still be honored by Django.
Miscellaneous
-------------
* ``SERIALIZE`` test setting is deprecated as it can be inferred from the
:attr:`~django.test.TestCase.databases` with the
:ref:`serialized_rollback <test-case-serialized-rollback>` option enabled.
* The undocumented ``django.utils.baseconv`` module is deprecated.
* The undocumented ``django.utils.datetime_safe`` module is deprecated.
* The default sitemap protocol for sitemaps built outside the context of a
request will change from ``'http'`` to ``'https'`` in Django 5.0.
* The ``extra_tests`` argument for :meth:`.DiscoverRunner.build_suite` and
:meth:`.DiscoverRunner.run_tests` is deprecated.
* The :class:`~django.contrib.postgres.aggregates.ArrayAgg`,
:class:`~django.contrib.postgres.aggregates.JSONBAgg`, and
:class:`~django.contrib.postgres.aggregates.StringAgg` aggregates will return
``None`` when there are no rows instead of ``[]``, ``[]``, and ``''``
respectively in Django 5.0. If you need the previous behavior, explicitly set
``default`` to ``Value([])``, ``Value('[]')``, or ``Value('')``.
* The ``django.contrib.gis.admin.GeoModelAdmin`` and ``OSMGeoAdmin`` classes
are deprecated. Use :class:`~django.contrib.admin.ModelAdmin` and
:class:`~django.contrib.gis.admin.GISModelAdmin` instead.
* Since form rendering now uses the template engine, the undocumented
``BaseForm._html_output()`` helper method is deprecated.
* The ability to return a ``str`` from ``ErrorList`` and ``ErrorDict`` is
deprecated. It is expected these methods return a ``SafeString``.
Features removed in 4.0
=======================
These features have reached the end of their deprecation cycle and are removed
in Django 4.0.
See :ref:`deprecated-features-3.0` for details on these changes, including how
to remove usage of these features.
* ``django.utils.http.urlquote()``, ``urlquote_plus()``, ``urlunquote()``, and
``urlunquote_plus()`` are removed.
* ``django.utils.encoding.force_text()`` and ``smart_text()`` are removed.
* ``django.utils.translation.ugettext()``, ``ugettext_lazy()``,
``ugettext_noop()``, ``ungettext()``, and ``ungettext_lazy()`` are removed.
* ``django.views.i18n.set_language()`` doesn't set the user language in
``request.session`` (key ``_language``).
* ``alias=None`` is required in the signature of
``django.db.models.Expression.get_group_by_cols()`` subclasses.
* ``django.utils.text.unescape_entities()`` is removed.
* ``django.utils.http.is_safe_url()`` is removed.
See :ref:`deprecated-features-3.1` for details on these changes, including how
to remove usage of these features.
* The ``PASSWORD_RESET_TIMEOUT_DAYS`` setting is removed.
* The :lookup:`isnull` lookup no longer allows using non-boolean values as the
right-hand side.
* The ``django.db.models.query_utils.InvalidQuery`` exception class is removed.
* The ``django-admin.py`` entry point is removed.
* The ``HttpRequest.is_ajax()`` method is removed.
* Support for the pre-Django 3.1 encoding format of cookies values used by
``django.contrib.messages.storage.cookie.CookieStorage`` is removed.
* Support for the pre-Django 3.1 password reset tokens in the admin site (that
use the SHA-1 hashing algorithm) is removed.
* Support for the pre-Django 3.1 encoding format of sessions is removed.
* Support for the pre-Django 3.1 ``django.core.signing.Signer`` signatures
(encoded with the SHA-1 algorithm) is removed.
* Support for the pre-Django 3.1 ``django.core.signing.dumps()`` signatures
(encoded with the SHA-1 algorithm) in ``django.core.signing.loads()`` is
removed.
* Support for the pre-Django 3.1 user sessions (that use the SHA-1 algorithm)
is removed.
* The ``get_response`` argument for
``django.utils.deprecation.MiddlewareMixin.__init__()`` is required and
doesn't accept ``None``.
* The ``providing_args`` argument for ``django.dispatch.Signal`` is removed.
* The ``length`` argument for ``django.utils.crypto.get_random_string()`` is
required.
* The ``list`` message for ``ModelMultipleChoiceField`` is removed.
* Support for passing raw column aliases to ``QuerySet.order_by()`` is removed.
* The ``NullBooleanField`` model field is removed, except for support in
historical migrations.
* ``django.conf.urls.url()`` is removed.
* The ``django.contrib.postgres.fields.JSONField`` model field is removed,
except for support in historical migrations.
* ``django.contrib.postgres.fields.jsonb.KeyTransform`` and
``django.contrib.postgres.fields.jsonb.KeyTextTransform`` are removed.
* ``django.contrib.postgres.forms.JSONField`` is removed.
* The ``{% ifequal %}`` and ``{% ifnotequal %}`` template tags are removed.
* The ``DEFAULT_HASHING_ALGORITHM`` transitional setting is removed.
===========================
```
### 3.2.10
```
===========================
*December 7, 2021*
Django 3.2.10 fixes a security issue with severity "low" and a bug in 3.2.9.
CVE-2021-44420: Potential bypass of an upstream access control based on URL paths
=================================================================================
HTTP requests for URLs with trailing newlines could bypass an upstream access
control based on URL paths.
Bugfixes
========
* Fixed a regression in Django 3.2 that caused a crash of ``setUpTestData()``
with ``BinaryField`` on PostgreSQL, which is ``memoryview``-backed
(:ticket:`33333`).
==========================
```
### 3.2.9
```
==========================
*November 1, 2021*
Django 3.2.9 fixes a bug in 3.2.8 and adds compatibility with Python 3.10.
Bugfixes
========
* Fixed a bug in Django 3.2 that caused a migration crash on SQLite when
altering a field with a functional index (:ticket:`33194`).
==========================
```
### 3.2.8
```
==========================
*October 5, 2021*
Django 3.2.8 fixes two bugs in 3.2.7.
Bugfixes
========
* Fixed a bug in Django 3.2 that caused incorrect links on read-only fields in
the admin (:ticket:`33077`).
* Fixed a regression in Django 3.2 that caused incorrect selection of items
across all pages when actions were placed both on the top and bottom of the
admin change-list view (:ticket:`33083`).
==========================
```
### 3.2.7
```
==========================
*September 1, 2021*
Django 3.2.7 fixes a bug in 3.2.6.
Bugfixes
========
* Fixed a regression in Django 3.2 that caused the incorrect offset extraction
from fixed offset timezones (:ticket:`32992`).
==========================
```
### 3.2.6
```
==========================
*August 2, 2021*
Django 3.2.6 fixes several bugs in 3.2.5.
Bugfixes
========
* Fixed a regression in Django 3.2 that caused a crash validating ``"NaN"``
input with a ``forms.DecimalField`` when additional constraints, e.g.
``max_value``, were specified (:ticket:`32949`).
* Fixed a bug in Django 3.2 where a system check would crash on a model with a
reverse many-to-many relation inherited from a parent class
(:ticket:`32947`).
==========================
```
### 3.2.5
```
==========================
*July 1, 2021*
Django 3.2.5 fixes a security issue with severity "high" and several bugs in
3.2.4. Also, the latest string translations from Transifex are incorporated.
CVE-2021-35042: Potential SQL injection via unsanitized ``QuerySet.order_by()`` input
=====================================================================================
Unsanitized user input passed to ``QuerySet.order_by()`` could bypass intended
column reference validation in path marked for deprecation resulting in a
potential SQL injection even if a deprecation warning is emitted.
As a mitigation the strict column reference validation was restored for the
duration of the deprecation period. This regression appeared in 3.1 as a side
effect of fixing :ticket:`31426`.
The issue is not present in the main branch as the deprecated path has been
removed.
Bugfixes
========
* Fixed a regression in Django 3.2 that caused a crash of
``QuerySet.values_list(…, named=True)`` after ``prefetch_related()``
(:ticket:`32812`).
* Fixed a bug in Django 3.2 that caused a migration crash on MySQL 8.0.13+ when
altering ``BinaryField``, ``JSONField``, or ``TextField`` to non-nullable
(:ticket:`32503`).
* Fixed a regression in Django 3.2 that caused a migration crash on MySQL
8.0.13+ when adding nullable ``BinaryField``, ``JSONField``, or ``TextField``
with a default value (:ticket:`32832`).
* Fixed a bug in Django 3.2 where a system check would crash on a model with an
invalid ``app_label`` (:ticket:`32863`).
==========================
```
### 3.2.4
```
==========================
*June 2, 2021*
Django 3.2.4 fixes two security issues and several bugs in 3.2.3.
CVE-2021-33203: Potential directory traversal via ``admindocs``
===============================================================
Staff members could use the :mod:`~django.contrib.admindocs`
``TemplateDetailView`` view to check the existence of arbitrary files.
Additionally, if (and only if) the default admindocs templates have been
customized by the developers to also expose the file contents, then not only
the existence but also the file contents would have been exposed.
As a mitigation, path sanitation is now applied and only files within the
template root directories can be loaded.
CVE-2021-33571: Possible indeterminate SSRF, RFI, and LFI attacks since validators accepted leading zeros in IPv4 addresses
===========================================================================================================================
:class:`~django.core.validators.URLValidator`,
:func:`~django.core.validators.validate_ipv4_address`, and
:func:`~django.core.validators.validate_ipv46_address` didn't prohibit leading
zeros in octal literals. If you used such values you could suffer from
indeterminate SSRF, RFI, and LFI attacks.
:func:`~django.core.validators.validate_ipv4_address` and
:func:`~django.core.validators.validate_ipv46_address` validators were not
affected on Python 3.9.5+.
Bugfixes
========
* Fixed a bug in Django 3.2 where a final catch-all view in the admin didn't
respect the server-provided value of ``SCRIPT_NAME`` when redirecting
unauthenticated users to the login page (:ticket:`32754`).
* Fixed a bug in Django 3.2 where a system check would crash on an abstract
model (:ticket:`32733`).
* Prevented unnecessary initialization of unused caches following a regression
in Django 3.2 (:ticket:`32747`).
* Fixed a crash in Django 3.2 that could occur when running ``mod_wsgi`` with
the recommended settings while the Windows ``colorama`` library was installed
(:ticket:`32740`).
* Fixed a bug in Django 3.2 that would trigger the auto-reloader for template
changes when directory paths were specified with strings (:ticket:`32744`).
* Fixed a regression in Django 3.2 that caused a crash of auto-reloader with
``AttributeError``, e.g. inside a ``Conda`` environment (:ticket:`32783`).
* Fixed a regression in Django 3.2 that caused a loss of precision for
operations with ``DecimalField`` on MySQL (:ticket:`32793`).
==========================
```
### 3.2.3
```
==========================
*May 13, 2021*
Django 3.2.3 fixes several bugs in 3.2.2.
Bugfixes
========
* Prepared for ``mysqlclient`` > 2.0.3 support (:ticket:`32732`).
* Fixed a regression in Django 3.2 that caused the incorrect filtering of
querysets combined with the ``|`` operator (:ticket:`32717`).
* Fixed a regression in Django 3.2.1 where saving ``FileField`` would raise a
``SuspiciousFileOperation`` even when a custom
:attr:`~django.db.models.FileField.upload_to` returns a valid file path
(:ticket:`32718`).
==========================
```
### 3.2.2
```
==========================
*May 6, 2021*
Django 3.2.2 fixes a security issue and a bug in 3.2.1.
CVE-2021-32052: Header injection possibility since ``URLValidator`` accepted newlines in input on Python 3.9.5+
===============================================================================================================
On Python 3.9.5+, :class:`~django.core.validators.URLValidator` didn't prohibit
newlines and tabs. If you used values with newlines in HTTP response, you could
suffer from header injection attacks. Django itself wasn't vulnerable because
:class:`~django.http.HttpResponse` prohibits newlines in HTTP headers.
Moreover, the ``URLField`` form field which uses ``URLValidator`` silently
removes newlines and tabs on Python 3.9.5+, so the possibility of newlines
entering your data only existed if you are using this validator outside of the
form fields.
This issue was introduced by the :bpo:`43882` fix.
Bugfixes
========
* Prevented, following a regression in Django 3.2.1, :djadmin:`makemigrations`
from generating infinite migrations for a model with ``Meta.ordering``
contained ``OrderBy`` expressions (:ticket:`32714`).
==========================
```
### 3.2.1
```
==========================
*May 4, 2021*
Django 3.2.1 fixes a security issue and several bugs in 3.2.
CVE-2021-31542: Potential directory-traversal via uploaded files
================================================================
``MultiPartParser``, ``UploadedFile``, and ``FieldFile`` allowed
directory-traversal via uploaded files with suitably crafted file names.
In order to mitigate this risk, stricter basename and path sanitation is now
applied.
Bugfixes
========
* Corrected detection of GDAL 3.2 on Windows (:ticket:`32544`).
* Fixed a bug in Django 3.2 where subclasses of ``BigAutoField`` and
``SmallAutoField`` were not allowed for the :setting:`DEFAULT_AUTO_FIELD`
setting (:ticket:`32620`).
* Fixed a regression in Django 3.2 that caused a crash of
``QuerySet.values()/values_list()`` after ``QuerySet.union()``,
``intersection()``, and ``difference()`` when it was ordered by an
unannotated field (:ticket:`32627`).
* Restored, following a regression in Django 3.2, displaying an exception
message on the technical 404 debug page (:ticket:`32637`).
* Fixed a bug in Django 3.2 where a system check would crash on a reverse
one-to-one relationships in ``CheckConstraint.check`` or
``UniqueConstraint.condition`` (:ticket:`32635`).
* Fixed a regression in Django 3.2 that caused a crash of
:attr:`.ModelAdmin.search_fields` when searching against phrases with
unbalanced quotes (:ticket:`32649`).
* Fixed a bug in Django 3.2 where variable lookup errors were logged rendering
the sitemap template if alternates were not defined (:ticket:`32648`).
* Fixed a regression in Django 3.2 that caused a crash when combining ``Q()``
objects which contains boolean expressions (:ticket:`32548`).
* Fixed a regression in Django 3.2 that caused a crash of ``QuerySet.update()``
on a queryset ordered by inherited or joined fields on MySQL and MariaDB
(:ticket:`32645`).
* Fixed a regression in Django 3.2 that caused a crash when decoding a cookie
value, used by ``django.contrib.messages.storage.cookie.CookieStorage``, in
the pre-Django 3.2 format (:ticket:`32643`).
* Fixed a regression in Django 3.2 that stopped the shift-key modifier
selecting multiple rows in the admin changelist (:ticket:`32647`).
* Fixed a bug in Django 3.2 where a system check would crash on the
:setting:`STATICFILES_DIRS` setting with a list of 2-tuples of
``(prefix, path)`` (:ticket:`32665`).
* Fixed a long standing bug involving queryset bitwise combination when used
with subqueries that began manifesting in Django 3.2, due to a separate fix
using ``Exists`` to ``exclude()`` multi-valued relationships
(:ticket:`32650`).
* Fixed a bug in Django 3.2 where variable lookup errors were logged when
rendering some admin templates (:ticket:`32681`).
* Fixed a bug in Django 3.2 where an admin changelist would crash when deleting
objects filtered against multi-valued relationships (:ticket:`32682`). The
admin changelist now uses ``Exists()`` instead ``QuerySet.distinct()``
because calling ``delete()`` after ``distinct()`` is not allowed in Django
3.2 to address a data loss possibility.
* Fixed a regression in Django 3.2 where the calling process environment would
not be passed to the ``dbshell`` command on PostgreSQL (:ticket:`32687`).
* Fixed a performance regression in Django 3.2 when building complex filters
with subqueries (:ticket:`32632`). As a side-effect the private API to check
``django.db.sql.query.Query`` equality is removed.
========================
```
### 3.2
```
========================
*April 6, 2021*
Welcome to Django 3.2!
These release notes cover the :ref:`new features <whats-new-3.2>`, as well as
some :ref:`backwards incompatible changes <backwards-incompatible-3.2>` you'll
want to be aware of when upgrading from Django 3.1 or earlier. We've
:ref:`begun the deprecation process for some features
<deprecated-features-3.2>`.
See the :doc:`/howto/upgrade-version` guide if you're updating an existing
project.
Django 3.2 is designated as a :term:`long-term support release
<Long-term support release>`. It will receive security updates for at least
three years after its release. Support for the previous LTS, Django 2.2, will
end in April 2022.
Python compatibility
====================
Django 3.2 supports Python 3.6, 3.7, 3.8, 3.9, and 3.10 (as of 3.2.9). We
**highly recommend** and only officially support the latest release of each
series.
.. _whats-new-3.2:
What's new in Django 3.2
========================
Automatic :class:`~django.apps.AppConfig` discovery
---------------------------------------------------
Most pluggable applications define an :class:`~django.apps.AppConfig` subclass
in an ``apps.py`` submodule. Many define a ``default_app_config`` variable
pointing to this class in their ``__init__.py``.
When the ``apps.py`` submodule exists and defines a single
:class:`~django.apps.AppConfig` subclass, Django now uses that configuration
automatically, so you can remove ``default_app_config``.
``default_app_config`` made it possible to declare only the application's path
in :setting:`INSTALLED_APPS` (e.g. ``'django.contrib.admin'``) rather than the
app config's path (e.g. ``'django.contrib.admin.apps.AdminConfig'``). It was
introduced for backwards-compatibility with the former style, with the intent
to switch the ecosystem to the latter, but the switch didn't happen.
With automatic ``AppConfig`` discovery, ``default_app_config`` is no longer
needed. As a consequence, it's deprecated.
See :ref:`configuring-applications-ref` for full details.
Customizing type of auto-created primary keys
---------------------------------------------
When defining a model, if no field in a model is defined with
:attr:`primary_key=True <django.db.models.Field.primary_key>` an implicit
primary key is added. The type of this implicit primary key can now be
controlled via the :setting:`DEFAULT_AUTO_FIELD` setting and
:attr:`AppConfig.default_auto_field <django.apps.AppConfig.default_auto_field>`
attribute. No more needing to override primary keys in all models.
Maintaining the historical behavior, the default value for
:setting:`DEFAULT_AUTO_FIELD` is :class:`~django.db.models.AutoField`. Starting
with 3.2 new projects are generated with :setting:`DEFAULT_AUTO_FIELD` set to
:class:`~django.db.models.BigAutoField`. Also, new apps are generated with
:attr:`AppConfig.default_auto_field <django.apps.AppConfig.default_auto_field>`
set to :class:`~django.db.models.BigAutoField`. In a future Django release the
default value of :setting:`DEFAULT_AUTO_FIELD` will be changed to
:class:`~django.db.models.BigAutoField`.
To avoid unwanted migrations in the future, either explicitly set
:setting:`DEFAULT_AUTO_FIELD` to :class:`~django.db.models.AutoField`::
DEFAULT_AUTO_FIELD = 'django.db.models.AutoField'
or configure it on a per-app basis::
from django.apps import AppConfig
class MyAppConfig(AppConfig):
default_auto_field = 'django.db.models.AutoField'
name = 'my_app'
or on a per-model basis::
from django.db import models
class MyModel(models.Model):
id = models.AutoField(primary_key=True)
In anticipation of the changing default, a system check will provide a warning
if you do not have an explicit setting for :setting:`DEFAULT_AUTO_FIELD`.
When changing the value of :setting:`DEFAULT_AUTO_FIELD`, migrations for the
primary key of existing auto-created through tables cannot be generated
currently. See the :setting:`DEFAULT_AUTO_FIELD` docs for details on migrating
such tables.
.. _new_functional_indexes:
Functional indexes
------------------
The new :attr:`*expressions <django.db.models.Index.expressions>` positional
argument of :class:`Index() <django.db.models.Index>` enables creating
functional indexes on expressions and database functions. For example::
from django.db import models
from django.db.models import F, Index, Value
from django.db.models.functions import Lower, Upper
class MyModel(models.Model):
first_name = models.CharField(max_length=255)
last_name = models.CharField(max_length=255)
height = models.IntegerField()
weight = models.IntegerField()
class Meta:
indexes = [
Index(
Lower('first_name'),
Upper('last_name').desc(),
name='first_last_name_idx',
),
Index(
F('height') / (F('weight') + Value(5)),
name='calc_idx',
),
]
Functional indexes are added to models using the
:attr:`Meta.indexes <django.db.models.Options.indexes>` option.
``pymemcache`` support
----------------------
The new ``django.core.cache.backends.memcached.PyMemcacheCache`` cache backend
allows using the pymemcache_ library for memcached. ``pymemcache`` 3.4.0 or
higher is required. For more details, see the :doc:`documentation on caching in
Django </topics/cache>`.
.. _pymemcache: https://pypi.org/project/pymemcache/
New decorators for the admin site
---------------------------------
The new :func:`~django.contrib.admin.display` decorator allows for easily
adding options to custom display functions that can be used with
:attr:`~django.contrib.admin.ModelAdmin.list_display` or
:attr:`~django.contrib.admin.ModelAdmin.readonly_fields`.
Likewise, the new :func:`~django.contrib.admin.action` decorator allows for
easily adding options to action functions that can be used with
:attr:`~django.contrib.admin.ModelAdmin.actions`.
Using the ``display`` decorator has the advantage that it is now
possible to use the ``property`` decorator when needing to specify attributes
on the custom method. Prior to this it was necessary to use the ``property()``
function instead after assigning the required attributes to the method.
Using decorators has the advantage that these options are more discoverable as
they can be suggested by completion utilities in code editors. They are merely
a convenience and still set the same attributes on the functions under the
hood.
Minor features
--------------
:mod:`django.contrib.admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :attr:`.ModelAdmin.search_fields` now allows searching against quoted phrases
with spaces.
* Read-only related fields are now rendered as navigable links if target models
are registered in the admin.
* The admin now supports theming, and includes a dark theme that is enabled
according to browser settings. See :ref:`admin-theming` for more details.
* :attr:`.ModelAdmin.autocomplete_fields` now respects
:attr:`ForeignKey.to_field <django.db.models.ForeignKey.to_field>` and
:attr:`ForeignKey.limit_choices_to
<django.db.models.ForeignKey.limit_choices_to>` when searching a related
model.
* The admin now installs a final catch-all view that redirects unauthenticated
users to the login page, regardless of whether the URL is otherwise valid.
This protects against a potential model enumeration privacy issue.
Although not recommended, you may set the new
:attr:`.AdminSite.final_catch_all_view` to ``False`` to disable the
catch-all view.
:mod:`django.contrib.auth`
~~~~~~~~~~~~~~~~~~~~~~~~~~
* The default iteration count for the PBKDF2 password hasher is increased from
216,000 to 260,000.
* The default variant for the Argon2 password hasher is changed to Argon2id.
``memory_cost`` and ``parallelism`` are increased to 102,400 and 8
respectively to match the ``argon2-cffi`` defaults.
Increasing the ``memory_cost`` pushes the required memory from 512 KB to 100
MB. This is still rather conservative but can lead to problems in memory
constrained environments. If this is the case, the existing hasher can be
subclassed to override the defaults.
* The default salt entropy for the Argon2, MD5, PBKDF2, SHA-1 password hashers
is increased from 71 to 128 bits.
:mod:`django.contrib.contenttypes`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The new ``absolute_max`` argument for
:func:`~django.contrib.contenttypes.forms.generic_inlineformset_factory`
allows customizing the maximum number of forms that can be instantiated when
supplying ``POST`` data. See :ref:`formsets-absolute-max` for more details.
* The new ``can_delete_extra`` argument for
:func:`~django.contrib.contenttypes.forms.generic_inlineformset_factory`
allows removal of the option to delete extra forms. See
:attr:`~.BaseFormSet.can_delete_extra` for more information.
:mod:`django.contrib.gis`
~~~~~~~~~~~~~~~~~~~~~~~~~
* The :meth:`.GDALRaster.transform` method now supports
:class:`~django.contrib.gis.gdal.SpatialReference`.
* The :class:`~django.contrib.gis.gdal.DataSource` class now supports
:class:`pathlib.Path`.
* The :class:`~django.contrib.gis.utils.LayerMapping` class now supports
:class:`pathlib.Path`.
:mod:`django.contrib.postgres`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The new :attr:`.ExclusionConstraint.include` attribute allows creating
covering exclusion constraints on PostgreSQL 12+.
* The new :attr:`.ExclusionConstraint.opclasses` attribute allows setting
PostgreSQL operator classes.
* The new :attr:`.JSONBAgg.ordering` attribute determines the ordering of the
aggregated elements.
* The new :attr:`.JSONBAgg.distinct` attribute determines if aggregated values
will be distinct.
* The :class:`~django.contrib.postgres.operations.CreateExtension` operation
now checks that the extension already exists in the database and skips the
migration if so.
* The new :class:`~django.contrib.postgres.operations.CreateCollation` and
:class:`~django.contrib.postgres.operations.RemoveCollation` operations
allow creating and dropping collations on PostgreSQL. See
:ref:`manage-postgresql-collations` for more details.
* Lookups for :class:`~django.contrib.postgres.fields.ArrayField` now allow
(non-nested) arrays containing expressions as right-hand sides.
* The new :class:`OpClass() <django.contrib.postgres.indexes.OpClass>`
expression allows creating functional indexes on expressions with a custom
operator class. See :ref:`new_functional_indexes` for more details.
:mod:`django.contrib.sitemaps`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The new :class:`~django.contrib.sitemaps.Sitemap` attributes
:attr:`~django.contrib.sitemaps.Sitemap.alternates`,
:attr:`~django.contrib.sitemaps.Sitemap.languages` and
:attr:`~django.contrib.sitemaps.Sitemap.x_default` allow
generating sitemap *alternates* to localized versions of your pages.
:mod:`django.contrib.syndication`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The new ``item_comments`` hook allows specifying a comments URL per feed
item.
Database backends
~~~~~~~~~~~~~~~~~
* Third-party database backends can now skip or mark as expected failures
tests in Django's test suite using the new
``DatabaseFeatures.django_test_skips`` and
``django_test_expected_failures`` attributes.
Decorators
~~~~~~~~~~
* The new :func:`~django.views.decorators.common.no_append_slash` decorator
allows individual views to be excluded from :setting:`APPEND_SLASH` URL
normalization.
Error Reporting
~~~~~~~~~~~~~~~
* Custom :class:`~django.views.debug.ExceptionReporter` subclasses can now
define the :attr:`~django.views.debug.ExceptionReporter.html_template_path`
and :attr:`~django.views.debug.ExceptionReporter.text_template_path`
properties to override the templates used to render exception reports.
File Uploads
~~~~~~~~~~~~
* The new :meth:`FileUploadHandler.upload_interrupted()
<django.core.files.uploadhandler.FileUploadHandler.upload_interrupted>`
callback allows handling interrupted uploads.
Forms
~~~~~
* The new ``absolute_max`` argument for :func:`.formset_factory`,
:func:`.inlineformset_factory`, and :func:`.modelformset_factory` allows
customizing the maximum number of forms that can be instantiated when
supplying ``POST`` data. See :ref:`formsets-absolute-max` for more details.
* The new ``can_delete_extra`` argument for :func:`.formset_factory`,
:func:`.inlineformset_factory`, and :func:`.modelformset_factory` allows
removal of the option to delete extra forms. See
:attr:`~.BaseFormSet.can_delete_extra` for more information.
* :class:`~django.forms.formsets.BaseFormSet` now reports a user facing error,
rather than raising an exception, when the management form is missing or has
been tampered with. To customize this error message, pass the
``error_messages`` argument with the key ``'missing_management_form'`` when
instantiating the formset.
Generic Views
~~~~~~~~~~~~~
* The ``week_format`` attributes of
:class:`~django.views.generic.dates.WeekMixin` and
:class:`~django.views.generic.dates.WeekArchiveView` now support the
``'%V'`` ISO 8601 week format.
Management Commands
~~~~~~~~~~~~~~~~~~~
* :djadmin:`loaddata` now supports fixtures stored in XZ archives (``.xz``) and
LZMA archives (``.lzma``).
* :djadmin:`dumpdata` now can compress data in the ``bz2``, ``gz``, ``lzma``,
or ``xz`` formats.
* :djadmin:`makemigrations` can now be called without an active database
connection. In that case, check for a consistent migration history is
skipped.
* :attr:`.BaseCommand.requires_system_checks` now supports specifying a list of
tags. System checks registered in the chosen tags will be checked for errors
prior to executing the command. In previous versions, either all or none
of the system checks were performed.
* Support for colored terminal output on Windows is updated. Various modern
terminal environments are automatically detected, and the options for
enabling support in other cases are improved. See :ref:`syntax-coloring` for
more details.
Migrations
~~~~~~~~~~
* The new ``Operation.migration_name_fragment`` property allows providing a
filename fragment that will be used to name a migration containing only that
operation.
* Migrations now support serialization of pure and concrete path objects from
:mod:`pathlib`, and :class:`os.PathLike` instances.
Models
~~~~~~
* The new ``no_key`` parameter for :meth:`.QuerySet.select_for_update()`,
supported on PostgreSQL, allows acquiring weaker locks that don't block the
creation of rows that reference locked rows through a foreign key.
* :class:`When() <django.db.models.expressions.When>` expression now allows
using the ``condition`` argument with ``lookups``.
* The new :attr:`.Index.include` and :attr:`.UniqueConstraint.include`
attributes allow creating covering indexes and covering unique constraints on
PostgreSQL 11+.
* The new :attr:`.UniqueConstraint.opclasses` attribute allows setting
PostgreSQL operator classes.
* The :meth:`.QuerySet.update` method now respects the ``order_by()`` clause on
MySQL and MariaDB.
* :class:`FilteredRelation() <django.db.models.FilteredRelation>` now supports
nested relations.
* The ``of`` argument of :meth:`.QuerySet.select_for_update()` is now allowed
on MySQL 8.0.1+.
* :class:`Value() <django.db.models.Value>` expression now
automatically resolves its ``output_field`` to the appropriate
:class:`Field <django.db.models.Field>` subclass based on the type of
its provided ``value`` for :py:class:`bool`, :py:class:`bytes`,
:py:class:`float`, :py:class:`int`, :py:class:`str`,
:py:class:`datetime.date`, :py:class:`datetime.datetime`,
:py:class:`datetime.time`, :py:class:`datetime.timedelta`,
:py:class:`decimal.Decimal`, and :py:class:`uuid.UUID` instances. As a
consequence, resolving an ``output_field`` for database functions and
combined expressions may now crash with mixed types when using ``Value()``.
You will need to explicitly set the ``output_field`` in such cases.
* The new :meth:`.QuerySet.alias` method allows creating reusable aliases for
expressions that don't need to be selected but are used for filtering,
ordering, or as a part of complex expressions.
* The new :class:`~django.db.models.functions.Collate` function allows
filtering and orde
Update babel from 2.6.0 to 2.9.1.
Changelog
### 2.9.1 ``` ------------- Bugfixes ~~~~~~~~ * The internal locale-data loading functions now validate the name of the locale file to be loaded and only allow files within Babel's data directory. Thank you to Chris Lyne of Tenable, Inc. for discovering the issue! ``` ### 2.9.0 ``` ------------- Upcoming version support changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * This version, Babel 2.9, is the last version of Babel to support Python 2.7, Python 3.4, and Python 3.5. Improvements ~~~~~~~~~~~~ * CLDR: Use CLDR 37 – Aarni Koskela (734) * Dates: Handle ZoneInfo objects in get_timezone_location, get_timezone_name - Alessio Bogon (741) * Numbers: Add group_separator feature in number formatting - Abdullah Javed Nesar (726) Bugfixes ~~~~~~~~ * Dates: Correct default Format().timedelta format to 'long' to mute deprecation warnings – Aarni Koskela * Import: Simplify iteration code in "import_cldr.py" – Felix Schwarz * Import: Stop using deprecated ElementTree methods "getchildren()" and "getiterator()" – Felix Schwarz * Messages: Fix unicode printing error on Python 2 without TTY. – Niklas Hambüchen * Messages: Introduce invariant that _invalid_pofile() takes unicode line. – Niklas Hambüchen * Tests: fix tests when using Python 3.9 – Felix Schwarz * Tests: Remove deprecated 'sudo: false' from Travis configuration – Jon Dufresne * Tests: Support Py.test 6.x – Aarni Koskela * Utilities: LazyProxy: Handle AttributeError in specified func – Nikiforov Konstantin (724) * Utilities: Replace usage of parser.suite with ast.parse – Miro Hrončok Documentation ~~~~~~~~~~~~~ * Update parse_number comments – Brad Martin (708) * Add __iter__ to Catalog documentation – CyanNani123 ``` ### 2.8.1 ``` ------------- This is solely a patch release to make running tests on Py.test 6+ possible. Bugfixes ~~~~~~~~ * Support Py.test 6 - Aarni Koskela (747, 750, 752) ``` ### 2.8.0 ``` ------------- Improvements ~~~~~~~~~~~~ * CLDR: Upgrade to CLDR 36.0 - Aarni Koskela (679) * Messages: Don't even open files with the "ignore" extraction method - sebleblanc (678) Bugfixes ~~~~~~~~ * Numbers: Fix formatting very small decimals when quantization is disabled - Lev Lybin, miluChen (662) * Messages: Attempt to sort all messages – Mario Frasca (651, 606) Docs ~~~~ * Add years to changelog - Romuald Brunet * Note that installation requires pytz - Steve (Gadget) Barnes ``` ### 2.7.0 ``` ------------- Possibly incompatible changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These may be backward incompatible in some cases, as some more-or-less internal APIs have changed. Please feel free to file issues if you bump into anything strange and we'll try to help! * General: Internal uses of ``babel.util.odict`` have been replaced with ``collections.OrderedDict`` from The Python standard library. Improvements ~~~~~~~~~~~~ * CLDR: Upgrade to CLDR 35.1 - Alberto Mardegan, Aarni Koskela (626, 643) * General: allow anchoring path patterns to the start of a string - Brian Cappello (600) * General: Bumped version requirement on pytz - chrisbrake (592) * Messages: `pybabel compile`: exit with code 1 if errors were encountered - Aarni Koskela (647) * Messages: Add omit-header to update_catalog - Cédric Krier (633) * Messages: Catalog update: keep user comments from destination by default - Aarni Koskela (648) * Messages: Skip empty message when writing mo file - Cédric Krier (564) * Messages: Small fixes to avoid crashes on badly formatted .po files - Bryn Truscott (597) * Numbers: `parse_decimal()` `strict` argument and `suggestions` - Charly C (590) * Numbers: don't repeat suggestions in parse_decimal strict - Serban Constantin (599) * Numbers: implement currency formatting with long display names - Luke Plant (585) * Numbers: parse_decimal(): assume spaces are equivalent to non-breaking spaces when not in strict mode - Aarni Koskela (649) * Performance: Cache locale_identifiers() - Aarni Koskela (644) Bugfixes ~~~~~~~~ * CLDR: Skip alt=... for week data (minDays, firstDay, weekendStart, weekendEnd) - Aarni Koskela (634) * Dates: Fix wrong weeknumber for 31.12.2018 - BT-sschmid (621) * Locale: Avoid KeyError trying to get data on WindowsXP - mondeja (604) * Locale: get_display_name(): Don't attempt to concatenate variant information to None - Aarni Koskela (645) * Messages: pofile: Add comparison operators to _NormalizedString - Aarni Koskela (646) * Messages: pofile: don't crash when message.locations can't be sorted - Aarni Koskela (646) Tooling & docs ~~~~~~~~~~~~~~ * Docs: Remove all references to deprecated easy_install - Jon Dufresne (610) * Docs: Switch print statement in docs to print function - NotAFile * Docs: Update all pypi.python.org URLs to pypi.org - Jon Dufresne (587) * Docs: Use https URLs throughout project where available - Jon Dufresne (588) * Support: Add testing and document support for Python 3.7 - Jon Dufresne (611) * Support: Test on Python 3.8-dev - Aarni Koskela (642) * Support: Using ABCs from collections instead of collections.abc is deprecated. - Julien Palard (609) * Tests: Fix conftest.py compatibility with pytest 4.3 - Miro Hrončok (635) * Tests: Update pytest and pytest-cov - Miro Hrončok (635) ```Links
- PyPI: https://pypi.org/project/babel - Changelog: https://pyup.io/changelogs/babel/ - Homepage: http://babel.pocoo.org/ - Docs: https://pythonhosted.org/Babel/Update certifi from 2018.11.29 to 2021.10.8.
The bot wasn't able to find a changelog for this release. Got an idea?
Links
- PyPI: https://pypi.org/project/certifi - Docs: https://certifiio.readthedocs.io/en/latest/Update chardet from 3.0.4 to 4.0.0.
Changelog
### 4.0.0 ``` Benchmarking chardet 4.0.0 on CPython 3.7.5 (default, Sep 8 2020, 12:19:42) [Clang 11.0.3 (clang-1103.0.32.62)] -------------------------------------------------------------------------------- ....................................................................................................................................................................................................................................................................................................................................................................... Calls per second for each encoding: ```Links
- PyPI: https://pypi.org/project/chardet - Changelog: https://pyup.io/changelogs/chardet/ - Repo: https://github.com/chardet/chardetUpdate django from 2.1.4 to 4.0.
Changelog
### 4.0 ``` ======================== *December 7, 2021* Welcome to Django 4.0! These release notes cover the :ref:`new features <whats-new-4.0>`, as well as some :ref:`backwards incompatible changes <backwards-incompatible-4.0>` you'll want to be aware of when upgrading from Django 3.2 or earlier. We've :ref:`begun the deprecation process for some features <deprecated-features-4.0>`. See the :doc:`/howto/upgrade-version` guide if you're updating an existing project. Python compatibility ==================== Django 4.0 supports Python 3.8, 3.9, and 3.10. We **highly recommend** and only officially support the latest release of each series. The Django 3.2.x series is the last to support Python 3.6 and 3.7. .. _whats-new-4.0: What's new in Django 4.0 ======================== ``zoneinfo`` default timezone implementation -------------------------------------------- The Python standard library's :mod:`zoneinfo` is now the default timezone implementation in Django. This is the next step in the migration from using ``pytz`` to using :mod:`zoneinfo`. Django 3.2 allowed the use of non-``pytz`` time zones. Django 4.0 makes ``zoneinfo`` the default implementation. Support for ``pytz`` is now deprecated and will be removed in Django 5.0. :mod:`zoneinfo` is part of the Python standard library from Python 3.9. The ``backports.zoneinfo`` package is automatically installed alongside Django if you are using Python 3.8. The move to ``zoneinfo`` should be largely transparent. Selection of the current timezone, conversion of datetime instances to the current timezone in forms and templates, as well as operations on aware datetimes in UTC are unaffected. However, if you are working with non-UTC time zones, and using the ``pytz`` ``normalize()`` and ``localize()`` APIs, possibly with the :setting:`TIME_ZONE <DATABASE-TIME_ZONE>` setting, you will need to audit your code, since ``pytz`` and ``zoneinfo`` are not entirely equivalent. To give time for such an audit, the transitional :setting:`USE_DEPRECATED_PYTZ` setting allows continued use of ``pytz`` during the 4.x release cycle. This setting will be removed in Django 5.0. In addition, a `pytz_deprecation_shim`_ package, created by the ``zoneinfo`` author, can be used to assist with the migration from ``pytz``. This package provides shims to help you safely remove ``pytz``, and has a detailed `migration guide`_ showing how to move to the new ``zoneinfo`` APIs. Using `pytz_deprecation_shim`_ and the :setting:`USE_DEPRECATED_PYTZ` transitional setting is recommended if you need a gradual update path. .. _pytz_deprecation_shim: https://pytz-deprecation-shim.readthedocs.io/en/latest/index.html .. _migration guide: https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html Functional unique constraints ----------------------------- The new :attr:`*expressions <django.db.models.UniqueConstraint.expressions>` positional argument of :class:`UniqueConstraint() <django.db.models.UniqueConstraint>` enables creating functional unique constraints on expressions and database functions. For example:: from django.db import models from django.db.models import UniqueConstraint from django.db.models.functions import Lower class MyModel(models.Model): first_name = models.CharField(max_length=255) last_name = models.CharField(max_length=255) class Meta: constraints = [ UniqueConstraint( Lower('first_name'), Lower('last_name').desc(), name='first_last_name_unique', ), ] Functional unique constraints are added to models using the :attr:`Meta.constraints <django.db.models.Options.constraints>` option. ``scrypt`` password hasher -------------------------- The new :ref:`scrypt password hasher <scrypt-usage>` is more secure and recommended over PBKDF2. However, it's not the default as it requires OpenSSL 1.1+ and more memory. Redis cache backend ------------------- The new ``django.core.cache.backends.redis.RedisCache`` cache backend provides built-in support for caching with Redis. `redis-py`_ 3.0.0 or higher is required. For more details, see the :ref:`documentation on caching with Redis in Django <redis>`. .. _`redis-py`: https://pypi.org/project/redis/ Template based form rendering ----------------------------- To enhance customization of :class:`Forms <django.forms.Form>`, :doc:`Formsets </topics/forms/formsets>`, and :class:`~django.forms.ErrorList` they are now rendered using the template engine. See the new :meth:`~django.forms.Form.render`, :meth:`~django.forms.Form.get_context`, and :attr:`~django.forms.Form.template_name` for ``Form`` and :ref:`formset rendering <formset-rendering>` for ``Formset``. Minor features -------------- :mod:`django.contrib.admin` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The ``admin/base.html`` template now has a new block ``header`` which contains the admin site header. * The new :meth:`.ModelAdmin.get_formset_kwargs` method allows customizing the keyword arguments passed to the constructor of a formset. * The navigation sidebar now has a quick filter toolbar. * The new context variable ``model`` which contains the model class for each model is added to the :meth:`.AdminSite.each_context` method. * The new :attr:`.ModelAdmin.search_help_text` attribute allows specifying a descriptive text for the search box. * The :attr:`.InlineModelAdmin.verbose_name_plural` attribute now fallbacks to the :attr:`.InlineModelAdmin.verbose_name` + ``'s'``. * jQuery is upgraded from version 3.5.1 to 3.6.0. :mod:`django.contrib.admindocs` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The admindocs now allows esoteric setups where :setting:`ROOT_URLCONF` is not a string. * The model section of the ``admindocs`` now shows cached properties. :mod:`django.contrib.auth` ~~~~~~~~~~~~~~~~~~~~~~~~~~ * The default iteration count for the PBKDF2 password hasher is increased from 260,000 to 320,000. * The new :attr:`LoginView.next_page <django.contrib.auth.views.LoginView.next_page>` attribute and :meth:`~django.contrib.auth.views.LoginView.get_default_redirect_url` method allow customizing the redirect after login. :mod:`django.contrib.gis` ~~~~~~~~~~~~~~~~~~~~~~~~~ * Added support for SpatiaLite 5. * :class:`~django.contrib.gis.gdal.GDALRaster` now allows creating rasters in any GDAL virtual filesystem. * The new :class:`~django.contrib.gis.admin.GISModelAdmin` class allows customizing the widget used for ``GeometryField``. This is encouraged instead of deprecated ``GeoModelAdmin`` and ``OSMGeoAdmin``. :mod:`django.contrib.postgres` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The PostgreSQL backend now supports connecting by a service name. See :ref:`postgresql-connection-settings` for more details. * The new :class:`~django.contrib.postgres.operations.AddConstraintNotValid` operation allows creating check constraints on PostgreSQL without verifying that all existing rows satisfy the new constraint. * The new :class:`~django.contrib.postgres.operations.ValidateConstraint` operation allows validating check constraints which were created using :class:`~django.contrib.postgres.operations.AddConstraintNotValid` on PostgreSQL. * The new :class:`ArraySubquery() <django.contrib.postgres.expressions.ArraySubquery>` expression allows using subqueries to construct lists of values on PostgreSQL. * The new :lookup:`trigram_word_similar` lookup, and the :class:`TrigramWordDistance() <django.contrib.postgres.search.TrigramWordDistance>` and :class:`TrigramWordSimilarity() <django.contrib.postgres.search.TrigramWordSimilarity>` expressions allow using trigram word similarity. :mod:`django.contrib.staticfiles` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` now replaces paths to JavaScript source map references with their hashed counterparts. * The new ``manifest_storage`` argument of :class:`~django.contrib.staticfiles.storage.ManifestFilesMixin` and :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` allows customizing the manifest file storage. Cache ~~~~~ * The new async API for ``django.core.cache.backends.base.BaseCache`` begins the process of making cache backends async-compatible. The new async methods all have ``a`` prefixed names, e.g. ``aadd()``, ``aget()``, ``aset()``, ``aget_or_set()``, or ``adelete_many()``. Going forward, the ``a`` prefix will be used for async variants of methods generally. CSRF ~~~~ * CSRF protection now consults the ``Origin`` header, if present. To facilitate this, :ref:`some changes <csrf-trusted-origins-changes-4.0>` to the :setting:`CSRF_TRUSTED_ORIGINS` setting are required. Forms ~~~~~ * :class:`~django.forms.ModelChoiceField` now includes the provided value in the ``params`` argument of a raised :exc:`~django.core.exceptions.ValidationError` for the ``invalid_choice`` error message. This allows custom error messages to use the ``%(value)s`` placeholder. * :class:`~django.forms.formsets.BaseFormSet` now renders non-form errors with an additional class of ``nonform`` to help distinguish them from form-specific errors. * :class:`~django.forms.formsets.BaseFormSet` now allows customizing the widget used when deleting forms via :attr:`~django.forms.formsets.BaseFormSet.can_delete` by setting the :attr:`~django.forms.formsets.BaseFormSet.deletion_widget` attribute or overriding :meth:`~django.forms.formsets.BaseFormSet.get_deletion_widget` method. Internationalization ~~~~~~~~~~~~~~~~~~~~ * Added support and translations for the Malay language. Generic Views ~~~~~~~~~~~~~ * :class:`~django.views.generic.edit.DeleteView` now uses :class:`~django.views.generic.edit.FormMixin`, allowing you to provide a :class:`~django.forms.Form` subclass, with a checkbox for example, to confirm deletion. In addition, this allows ``DeleteView`` to function with :class:`django.contrib.messages.views.SuccessMessageMixin`. In accordance with ``FormMixin``, object deletion for POST requests is handled in ``form_valid()``. Custom delete logic in ``delete()`` handlers should be moved to ``form_valid()``, or a shared helper method, as needed. Logging ~~~~~~~ * The alias of the database used in an SQL call is now passed as extra context along with each message to the :ref:`django-db-logger` logger. Management Commands ~~~~~~~~~~~~~~~~~~~ * The :djadmin:`runserver` management command now supports the :option:`--skip-checks` option. * On PostgreSQL, :djadmin:`dbshell` now supports specifying a password file. * The :djadmin:`shell` command now respects :py:data:`sys.__interactivehook__` at startup. This allows loading shell history between interactive sessions. As a consequence, ``readline`` is no longer loaded if running in *isolated* mode. * The new :attr:`BaseCommand.suppressed_base_arguments <django.core.management.BaseCommand.suppressed_base_arguments>` attribute allows suppressing unsupported default command options in the help output. * The new :option:`startapp --exclude` and :option:`startproject --exclude` options allow excluding directories from the template. Models ~~~~~~ * New :meth:`QuerySet.contains(obj) <.QuerySet.contains>` method returns whether the queryset contains the given object. This tries to perform the query in the simplest and fastest way possible. * The new ``precision`` argument of the :class:`Round() <django.db.models.functions.Round>` database function allows specifying the number of decimal places after rounding. * :meth:`.QuerySet.bulk_create` now sets the primary key on objects when using SQLite 3.35+. * :class:`~django.db.models.DurationField` now supports multiplying and dividing by scalar values on SQLite. * :meth:`.QuerySet.bulk_update` now returns the number of objects updated. * The new :attr:`.Expression.empty_result_set_value` attribute allows specifying a value to return when the function is used over an empty result set. * The ``skip_locked`` argument of :meth:`.QuerySet.select_for_update()` is now allowed on MariaDB 10.6+. * :class:`~django.db.models.Lookup` expressions may now be used in ``QuerySet`` annotations, aggregations, and directly in filters. * The new :ref:`default <aggregate-default>` argument for built-in aggregates allows specifying a value to be returned when the queryset (or grouping) contains no entries, rather than ``None``. Requests and Responses ~~~~~~~~~~~~~~~~~~~~~~ * The :class:`~django.middleware.security.SecurityMiddleware` now adds the :ref:`Cross-Origin Opener Policy <cross-origin-opener-policy>` header with a value of ``'same-origin'`` to prevent cross-origin popups from sharing the same browsing context. You can prevent this header from being added by setting the :setting:`SECURE_CROSS_ORIGIN_OPENER_POLICY` setting to ``None``. Signals ~~~~~~~ * The new ``stdout`` argument for :func:`~django.db.models.signals.pre_migrate` and :func:`~django.db.models.signals.post_migrate` signals allows redirecting output to a stream-like object. It should be preferred over :py:data:`sys.stdout` and :py:func:`print` when emitting verbose output in order to allow proper capture when testing. Templates ~~~~~~~~~ * :tfilter:`floatformat` template filter now allows using the ``u`` suffix to force disabling localization. Tests ~~~~~ * The new ``serialized_aliases`` argument of :func:`django.test.utils.setup_databases` determines which :setting:`DATABASES` aliases test databases should have their state serialized to allow usage of the :ref:`serialized_rollback <test-case-serialized-rollback>` feature. * Django test runner now supports a :option:`--buffer <test --buffer>` option with parallel tests. * The new ``logger`` argument to :class:`~django.test.runner.DiscoverRunner` allows a Python :py:ref:`logger <logger>` to be used for logging. * The new :meth:`.DiscoverRunner.log` method provides a way to log messages that uses the ``DiscoverRunner.logger``, or prints to the console if not set. * Django test runner now supports a :option:`--shuffle <test --shuffle>` option to execute tests in a random order. * The :option:`test --parallel` option now supports the value ``auto`` to run one test process for each processor core. * :meth:`.TestCase.captureOnCommitCallbacks` now captures new callbacks added while executing :func:`.transaction.on_commit` callbacks. .. _backwards-incompatible-4.0: Backwards incompatible changes in 4.0 ===================================== Database backend API -------------------- This section describes changes that may be needed in third-party database backends. * ``DatabaseOperations.year_lookup_bounds_for_date_field()`` and ``year_lookup_bounds_for_datetime_field()`` methods now take the optional ``iso_year`` argument in order to support bounds for ISO-8601 week-numbering years. * The second argument of ``DatabaseSchemaEditor._unique_sql()`` and ``_create_unique_sql()`` methods is now ``fields`` instead of ``columns``. :mod:`django.contrib.gis` ------------------------- * Support for PostGIS 2.3 is removed. * Support for GDAL 2.0 and GEOS 3.5 is removed. Dropped support for PostgreSQL 9.6 ---------------------------------- Upstream support for PostgreSQL 9.6 ends in November 2021. Django 4.0 supports PostgreSQL 10 and higher. Dropped support for Oracle 12.2 and 18c --------------------------------------- Upstream support for Oracle 12.2 ends in March 2022 and for Oracle 18c it ends in June 2021. Django 3.2 will be supported until April 2024. Django 4.0 officially supports Oracle 19c. .. _csrf-trusted-origins-changes-4.0: ``CSRF_TRUSTED_ORIGINS`` changes -------------------------------- Format change ~~~~~~~~~~~~~ Values in the :setting:`CSRF_TRUSTED_ORIGINS` setting must include the scheme (e.g. ``'http://'`` or ``'https://'``) instead of only the hostname. Also, values that started with a dot, must now also include an asterisk before the dot. For example, change ``'.example.com'`` to ``'https://*.example.com'``. A system check detects any required changes. Configuring it may now be required ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As CSRF protection now consults the ``Origin`` header, you may need to set :setting:`CSRF_TRUSTED_ORIGINS`, particularly if you allow requests from subdomains by setting :setting:`CSRF_COOKIE_DOMAIN` (or :setting:`SESSION_COOKIE_DOMAIN` if :setting:`CSRF_USE_SESSIONS` is enabled) to a value starting with a dot. ``SecurityMiddleware`` no longer sets the ``X-XSS-Protection`` header --------------------------------------------------------------------- The :class:`~django.middleware.security.SecurityMiddleware` no longer sets the ``X-XSS-Protection`` header if the ``SECURE_BROWSER_XSS_FILTER`` setting is ``True``. The setting is removed. Most modern browsers don't honor the ``X-XSS-Protection`` HTTP header. You can use Content-Security-Policy_ without allowing ``'unsafe-inline'`` scripts instead. If you want to support legacy browsers and set the header, use this line in a custom middleware:: response.headers.setdefault('X-XSS-Protection', '1; mode=block') .. _Content-Security-Policy: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy Migrations autodetector changes ------------------------------- The migrations autodetector now uses model states instead of model classes. Also, migration operations for ``ForeignKey`` and ``ManyToManyField`` fields no longer specify attributes which were not passed to the fields during initialization. As a side-effect, running ``makemigrations`` might generate no-op ``AlterField`` operations for ``ManyToManyField`` and ``ForeignKey`` fields in some cases. ``DeleteView`` changes ---------------------- :class:`~django.views.generic.edit.DeleteView` now uses :class:`~django.views.generic.edit.FormMixin` to handle POST requests. As a consequence, any custom deletion logic in ``delete()`` handlers should be moved to ``form_valid()``, or a shared helper method, if required. Miscellaneous ------------- * Support for ``cx_Oracle`` < 7.0 is removed. * To allow serving a Django site on a subpath without changing the value of :setting:`STATIC_URL`, the leading slash is removed from that setting (now ``'static/'``) in the default :djadmin:`startproject` template. * The :class:`~django.contrib.admin.AdminSite` method for the admin ``index`` view is no longer decorated with ``never_cache`` when accessed directly, rather than via the recommended ``AdminSite.urls`` property, or ``AdminSite.get_urls()`` method. * Unsupported operations on a sliced queryset now raise ``TypeError`` instead of ``AssertionError``. * The undocumented ``django.test.runner.reorder_suite()`` function is renamed to ``reorder_tests()``. It now accepts an iterable of tests rather than a test suite, and returns an iterator of tests. * Calling ``FileSystemStorage.delete()`` with an empty ``name`` now raises ``ValueError`` instead of ``AssertionError``. * Calling ``EmailMultiAlternatives.attach_alternative()`` or ``EmailMessage.attach()`` with an invalid ``content`` or ``mimetype`` arguments now raise ``ValueError`` instead of ``AssertionError``. * :meth:`~django.test.SimpleTestCase.assertHTMLEqual` no longer considers a non-boolean attribute without a value equal to an attribute with the same name and value. * Tests that fail to load, for example due to syntax errors, now always match when using :option:`test --tag`. * The undocumented ``django.contrib.admin.utils.lookup_needs_distinct()`` function is renamed to ``lookup_spawns_duplicates()``. * The undocumented ``HttpRequest.get_raw_uri()`` method is removed. The :meth:`.HttpRequest.build_absolute_uri` method may be a suitable alternative. * The ``object`` argument of undocumented ``ModelAdmin.log_addition()``, ``log_change()``, and ``log_deletion()`` methods is renamed to ``obj``. * :class:`~django.utils.feedgenerator.RssFeed`, :class:`~django.utils.feedgenerator.Atom1Feed`, and their subclasses now emit elements with no content as self-closing tags. * ``NodeList.render()`` no longer casts the output of ``render()`` method for individual nodes to a string. ``Node.render()`` should always return a string as documented. * The ``where_class`` property of ``django.db.models.sql.query.Query`` and the ``where_class`` argument to the private ``get_extra_restriction()`` method of ``ForeignObject`` and ``ForeignObjectRel`` are removed. If needed, initialize ``django.db.models.sql.where.WhereNode`` instead. * The ``filter_clause`` argument of the undocumented ``Query.add_filter()`` method is replaced by two positional arguments ``filter_lhs`` and ``filter_rhs``. * :class:`~django.middleware.csrf.CsrfViewMiddleware` now uses ``request.META['CSRF_COOKIE_NEEDS_UPDATE']`` in place of ``request.META['CSRF_COOKIE_USED']``, ``request.csrf_cookie_needs_reset``, and ``response.csrf_cookie_set`` to track whether the CSRF cookie should be sent. This is an undocumented, private API. * The undocumented ``TRANSLATOR_COMMENT_MARK`` constant is moved from ``django.template.base`` to ``django.utils.translation.template``. * The ``real_apps`` argument of the undocumented ``django.db.migrations.state.ProjectState.__init__()`` method must now be a set if provided. * :class:`~django.forms.RadioSelect` and :class:`~django.forms.CheckboxSelectMultiple` widgets are now rendered in ``<div>`` tags so they are announced more concisely by screen readers. If you need the previous behavior, :ref:`override the widget template <overriding-built-in-widget-templates>` with the appropriate template from Django 3.2. * The :tfilter:`floatformat` template filter no longer depends on the ``USE_L10N`` setting and always returns localized output. Use the ``u`` suffix to disable localization. * The default value of the ``USE_L10N`` setting is changed to ``True``. See the :ref:`Localization section <use_l10n_deprecation>` above for more details. * As part of the :ref:`move to zoneinfo <whats-new-4.0>`, :attr:`django.utils.timezone.utc` is changed to alias :attr:`datetime.timezone.utc`. * The minimum supported version of ``asgiref`` is increased from 3.3.2 to 3.4.1. .. _deprecated-features-4.0: Features deprecated in 4.0 ========================== Use of ``pytz`` time zones -------------------------- As part of the :ref:`move to zoneinfo <whats-new-4.0>`, use of ``pytz`` time zones is deprecated. Accordingly, the ``is_dst`` arguments to the following are also deprecated: * :meth:`django.db.models.query.QuerySet.datetimes` * :func:`django.db.models.functions.Trunc` * :func:`django.db.models.functions.TruncSecond` * :func:`django.db.models.functions.TruncMinute` * :func:`django.db.models.functions.TruncHour` * :func:`django.db.models.functions.TruncDay` * :func:`django.db.models.functions.TruncWeek` * :func:`django.db.models.functions.TruncMonth` * :func:`django.db.models.functions.TruncQuarter` * :func:`django.db.models.functions.TruncYear` * :func:`django.utils.timezone.make_aware` Support for use of ``pytz`` will be removed in Django 5.0. Time zone support ----------------- In order to follow good practice, the default value of the :setting:`USE_TZ` setting will change from ``False`` to ``True``, and time zone support will be enabled by default, in Django 5.0. Note that the default :file:`settings.py` file created by :djadmin:`django-admin startproject <startproject>` includes :setting:`USE_TZ = True <USE_TZ>` since Django 1.4. You can set ``USE_TZ`` to ``False`` in your project settings before then to opt-out. .. _use_l10n_deprecation: Localization ------------ In order to follow good practice, the default value of the ``USE_L10N`` setting is changed from ``False`` to ``True``. Moreover ``USE_L10N`` is deprecated as of this release. Starting with Django 5.0, by default, any date or number displayed by Django will be localized. The :ttag:`{% localize %} <localize>` tag and the :tfilter:`localize`/ :tfilter:`unlocalize` filters will still be honored by Django. Miscellaneous ------------- * ``SERIALIZE`` test setting is deprecated as it can be inferred from the :attr:`~django.test.TestCase.databases` with the :ref:`serialized_rollback <test-case-serialized-rollback>` option enabled. * The undocumented ``django.utils.baseconv`` module is deprecated. * The undocumented ``django.utils.datetime_safe`` module is deprecated. * The default sitemap protocol for sitemaps built outside the context of a request will change from ``'http'`` to ``'https'`` in Django 5.0. * The ``extra_tests`` argument for :meth:`.DiscoverRunner.build_suite` and :meth:`.DiscoverRunner.run_tests` is deprecated. * The :class:`~django.contrib.postgres.aggregates.ArrayAgg`, :class:`~django.contrib.postgres.aggregates.JSONBAgg`, and :class:`~django.contrib.postgres.aggregates.StringAgg` aggregates will return ``None`` when there are no rows instead of ``[]``, ``[]``, and ``''`` respectively in Django 5.0. If you need the previous behavior, explicitly set ``default`` to ``Value([])``, ``Value('[]')``, or ``Value('')``. * The ``django.contrib.gis.admin.GeoModelAdmin`` and ``OSMGeoAdmin`` classes are deprecated. Use :class:`~django.contrib.admin.ModelAdmin` and :class:`~django.contrib.gis.admin.GISModelAdmin` instead. * Since form rendering now uses the template engine, the undocumented ``BaseForm._html_output()`` helper method is deprecated. * The ability to return a ``str`` from ``ErrorList`` and ``ErrorDict`` is deprecated. It is expected these methods return a ``SafeString``. Features removed in 4.0 ======================= These features have reached the end of their deprecation cycle and are removed in Django 4.0. See :ref:`deprecated-features-3.0` for details on these changes, including how to remove usage of these features. * ``django.utils.http.urlquote()``, ``urlquote_plus()``, ``urlunquote()``, and ``urlunquote_plus()`` are removed. * ``django.utils.encoding.force_text()`` and ``smart_text()`` are removed. * ``django.utils.translation.ugettext()``, ``ugettext_lazy()``, ``ugettext_noop()``, ``ungettext()``, and ``ungettext_lazy()`` are removed. * ``django.views.i18n.set_language()`` doesn't set the user language in ``request.session`` (key ``_language``). * ``alias=None`` is required in the signature of ``django.db.models.Expression.get_group_by_cols()`` subclasses. * ``django.utils.text.unescape_entities()`` is removed. * ``django.utils.http.is_safe_url()`` is removed. See :ref:`deprecated-features-3.1` for details on these changes, including how to remove usage of these features. * The ``PASSWORD_RESET_TIMEOUT_DAYS`` setting is removed. * The :lookup:`isnull` lookup no longer allows using non-boolean values as the right-hand side. * The ``django.db.models.query_utils.InvalidQuery`` exception class is removed. * The ``django-admin.py`` entry point is removed. * The ``HttpRequest.is_ajax()`` method is removed. * Support for the pre-Django 3.1 encoding format of cookies values used by ``django.contrib.messages.storage.cookie.CookieStorage`` is removed. * Support for the pre-Django 3.1 password reset tokens in the admin site (that use the SHA-1 hashing algorithm) is removed. * Support for the pre-Django 3.1 encoding format of sessions is removed. * Support for the pre-Django 3.1 ``django.core.signing.Signer`` signatures (encoded with the SHA-1 algorithm) is removed. * Support for the pre-Django 3.1 ``django.core.signing.dumps()`` signatures (encoded with the SHA-1 algorithm) in ``django.core.signing.loads()`` is removed. * Support for the pre-Django 3.1 user sessions (that use the SHA-1 algorithm) is removed. * The ``get_response`` argument for ``django.utils.deprecation.MiddlewareMixin.__init__()`` is required and doesn't accept ``None``. * The ``providing_args`` argument for ``django.dispatch.Signal`` is removed. * The ``length`` argument for ``django.utils.crypto.get_random_string()`` is required. * The ``list`` message for ``ModelMultipleChoiceField`` is removed. * Support for passing raw column aliases to ``QuerySet.order_by()`` is removed. * The ``NullBooleanField`` model field is removed, except for support in historical migrations. * ``django.conf.urls.url()`` is removed. * The ``django.contrib.postgres.fields.JSONField`` model field is removed, except for support in historical migrations. * ``django.contrib.postgres.fields.jsonb.KeyTransform`` and ``django.contrib.postgres.fields.jsonb.KeyTextTransform`` are removed. * ``django.contrib.postgres.forms.JSONField`` is removed. * The ``{% ifequal %}`` and ``{% ifnotequal %}`` template tags are removed. * The ``DEFAULT_HASHING_ALGORITHM`` transitional setting is removed. =========================== ``` ### 3.2.10 ``` =========================== *December 7, 2021* Django 3.2.10 fixes a security issue with severity "low" and a bug in 3.2.9. CVE-2021-44420: Potential bypass of an upstream access control based on URL paths ================================================================================= HTTP requests for URLs with trailing newlines could bypass an upstream access control based on URL paths. Bugfixes ======== * Fixed a regression in Django 3.2 that caused a crash of ``setUpTestData()`` with ``BinaryField`` on PostgreSQL, which is ``memoryview``-backed (:ticket:`33333`). ========================== ``` ### 3.2.9 ``` ========================== *November 1, 2021* Django 3.2.9 fixes a bug in 3.2.8 and adds compatibility with Python 3.10. Bugfixes ======== * Fixed a bug in Django 3.2 that caused a migration crash on SQLite when altering a field with a functional index (:ticket:`33194`). ========================== ``` ### 3.2.8 ``` ========================== *October 5, 2021* Django 3.2.8 fixes two bugs in 3.2.7. Bugfixes ======== * Fixed a bug in Django 3.2 that caused incorrect links on read-only fields in the admin (:ticket:`33077`). * Fixed a regression in Django 3.2 that caused incorrect selection of items across all pages when actions were placed both on the top and bottom of the admin change-list view (:ticket:`33083`). ========================== ``` ### 3.2.7 ``` ========================== *September 1, 2021* Django 3.2.7 fixes a bug in 3.2.6. Bugfixes ======== * Fixed a regression in Django 3.2 that caused the incorrect offset extraction from fixed offset timezones (:ticket:`32992`). ========================== ``` ### 3.2.6 ``` ========================== *August 2, 2021* Django 3.2.6 fixes several bugs in 3.2.5. Bugfixes ======== * Fixed a regression in Django 3.2 that caused a crash validating ``"NaN"`` input with a ``forms.DecimalField`` when additional constraints, e.g. ``max_value``, were specified (:ticket:`32949`). * Fixed a bug in Django 3.2 where a system check would crash on a model with a reverse many-to-many relation inherited from a parent class (:ticket:`32947`). ========================== ``` ### 3.2.5 ``` ========================== *July 1, 2021* Django 3.2.5 fixes a security issue with severity "high" and several bugs in 3.2.4. Also, the latest string translations from Transifex are incorporated. CVE-2021-35042: Potential SQL injection via unsanitized ``QuerySet.order_by()`` input ===================================================================================== Unsanitized user input passed to ``QuerySet.order_by()`` could bypass intended column reference validation in path marked for deprecation resulting in a potential SQL injection even if a deprecation warning is emitted. As a mitigation the strict column reference validation was restored for the duration of the deprecation period. This regression appeared in 3.1 as a side effect of fixing :ticket:`31426`. The issue is not present in the main branch as the deprecated path has been removed. Bugfixes ======== * Fixed a regression in Django 3.2 that caused a crash of ``QuerySet.values_list(…, named=True)`` after ``prefetch_related()`` (:ticket:`32812`). * Fixed a bug in Django 3.2 that caused a migration crash on MySQL 8.0.13+ when altering ``BinaryField``, ``JSONField``, or ``TextField`` to non-nullable (:ticket:`32503`). * Fixed a regression in Django 3.2 that caused a migration crash on MySQL 8.0.13+ when adding nullable ``BinaryField``, ``JSONField``, or ``TextField`` with a default value (:ticket:`32832`). * Fixed a bug in Django 3.2 where a system check would crash on a model with an invalid ``app_label`` (:ticket:`32863`). ========================== ``` ### 3.2.4 ``` ========================== *June 2, 2021* Django 3.2.4 fixes two security issues and several bugs in 3.2.3. CVE-2021-33203: Potential directory traversal via ``admindocs`` =============================================================== Staff members could use the :mod:`~django.contrib.admindocs` ``TemplateDetailView`` view to check the existence of arbitrary files. Additionally, if (and only if) the default admindocs templates have been customized by the developers to also expose the file contents, then not only the existence but also the file contents would have been exposed. As a mitigation, path sanitation is now applied and only files within the template root directories can be loaded. CVE-2021-33571: Possible indeterminate SSRF, RFI, and LFI attacks since validators accepted leading zeros in IPv4 addresses =========================================================================================================================== :class:`~django.core.validators.URLValidator`, :func:`~django.core.validators.validate_ipv4_address`, and :func:`~django.core.validators.validate_ipv46_address` didn't prohibit leading zeros in octal literals. If you used such values you could suffer from indeterminate SSRF, RFI, and LFI attacks. :func:`~django.core.validators.validate_ipv4_address` and :func:`~django.core.validators.validate_ipv46_address` validators were not affected on Python 3.9.5+. Bugfixes ======== * Fixed a bug in Django 3.2 where a final catch-all view in the admin didn't respect the server-provided value of ``SCRIPT_NAME`` when redirecting unauthenticated users to the login page (:ticket:`32754`). * Fixed a bug in Django 3.2 where a system check would crash on an abstract model (:ticket:`32733`). * Prevented unnecessary initialization of unused caches following a regression in Django 3.2 (:ticket:`32747`). * Fixed a crash in Django 3.2 that could occur when running ``mod_wsgi`` with the recommended settings while the Windows ``colorama`` library was installed (:ticket:`32740`). * Fixed a bug in Django 3.2 that would trigger the auto-reloader for template changes when directory paths were specified with strings (:ticket:`32744`). * Fixed a regression in Django 3.2 that caused a crash of auto-reloader with ``AttributeError``, e.g. inside a ``Conda`` environment (:ticket:`32783`). * Fixed a regression in Django 3.2 that caused a loss of precision for operations with ``DecimalField`` on MySQL (:ticket:`32793`). ========================== ``` ### 3.2.3 ``` ========================== *May 13, 2021* Django 3.2.3 fixes several bugs in 3.2.2. Bugfixes ======== * Prepared for ``mysqlclient`` > 2.0.3 support (:ticket:`32732`). * Fixed a regression in Django 3.2 that caused the incorrect filtering of querysets combined with the ``|`` operator (:ticket:`32717`). * Fixed a regression in Django 3.2.1 where saving ``FileField`` would raise a ``SuspiciousFileOperation`` even when a custom :attr:`~django.db.models.FileField.upload_to` returns a valid file path (:ticket:`32718`). ========================== ``` ### 3.2.2 ``` ========================== *May 6, 2021* Django 3.2.2 fixes a security issue and a bug in 3.2.1. CVE-2021-32052: Header injection possibility since ``URLValidator`` accepted newlines in input on Python 3.9.5+ =============================================================================================================== On Python 3.9.5+, :class:`~django.core.validators.URLValidator` didn't prohibit newlines and tabs. If you used values with newlines in HTTP response, you could suffer from header injection attacks. Django itself wasn't vulnerable because :class:`~django.http.HttpResponse` prohibits newlines in HTTP headers. Moreover, the ``URLField`` form field which uses ``URLValidator`` silently removes newlines and tabs on Python 3.9.5+, so the possibility of newlines entering your data only existed if you are using this validator outside of the form fields. This issue was introduced by the :bpo:`43882` fix. Bugfixes ======== * Prevented, following a regression in Django 3.2.1, :djadmin:`makemigrations` from generating infinite migrations for a model with ``Meta.ordering`` contained ``OrderBy`` expressions (:ticket:`32714`). ========================== ``` ### 3.2.1 ``` ========================== *May 4, 2021* Django 3.2.1 fixes a security issue and several bugs in 3.2. CVE-2021-31542: Potential directory-traversal via uploaded files ================================================================ ``MultiPartParser``, ``UploadedFile``, and ``FieldFile`` allowed directory-traversal via uploaded files with suitably crafted file names. In order to mitigate this risk, stricter basename and path sanitation is now applied. Bugfixes ======== * Corrected detection of GDAL 3.2 on Windows (:ticket:`32544`). * Fixed a bug in Django 3.2 where subclasses of ``BigAutoField`` and ``SmallAutoField`` were not allowed for the :setting:`DEFAULT_AUTO_FIELD` setting (:ticket:`32620`). * Fixed a regression in Django 3.2 that caused a crash of ``QuerySet.values()/values_list()`` after ``QuerySet.union()``, ``intersection()``, and ``difference()`` when it was ordered by an unannotated field (:ticket:`32627`). * Restored, following a regression in Django 3.2, displaying an exception message on the technical 404 debug page (:ticket:`32637`). * Fixed a bug in Django 3.2 where a system check would crash on a reverse one-to-one relationships in ``CheckConstraint.check`` or ``UniqueConstraint.condition`` (:ticket:`32635`). * Fixed a regression in Django 3.2 that caused a crash of :attr:`.ModelAdmin.search_fields` when searching against phrases with unbalanced quotes (:ticket:`32649`). * Fixed a bug in Django 3.2 where variable lookup errors were logged rendering the sitemap template if alternates were not defined (:ticket:`32648`). * Fixed a regression in Django 3.2 that caused a crash when combining ``Q()`` objects which contains boolean expressions (:ticket:`32548`). * Fixed a regression in Django 3.2 that caused a crash of ``QuerySet.update()`` on a queryset ordered by inherited or joined fields on MySQL and MariaDB (:ticket:`32645`). * Fixed a regression in Django 3.2 that caused a crash when decoding a cookie value, used by ``django.contrib.messages.storage.cookie.CookieStorage``, in the pre-Django 3.2 format (:ticket:`32643`). * Fixed a regression in Django 3.2 that stopped the shift-key modifier selecting multiple rows in the admin changelist (:ticket:`32647`). * Fixed a bug in Django 3.2 where a system check would crash on the :setting:`STATICFILES_DIRS` setting with a list of 2-tuples of ``(prefix, path)`` (:ticket:`32665`). * Fixed a long standing bug involving queryset bitwise combination when used with subqueries that began manifesting in Django 3.2, due to a separate fix using ``Exists`` to ``exclude()`` multi-valued relationships (:ticket:`32650`). * Fixed a bug in Django 3.2 where variable lookup errors were logged when rendering some admin templates (:ticket:`32681`). * Fixed a bug in Django 3.2 where an admin changelist would crash when deleting objects filtered against multi-valued relationships (:ticket:`32682`). The admin changelist now uses ``Exists()`` instead ``QuerySet.distinct()`` because calling ``delete()`` after ``distinct()`` is not allowed in Django 3.2 to address a data loss possibility. * Fixed a regression in Django 3.2 where the calling process environment would not be passed to the ``dbshell`` command on PostgreSQL (:ticket:`32687`). * Fixed a performance regression in Django 3.2 when building complex filters with subqueries (:ticket:`32632`). As a side-effect the private API to check ``django.db.sql.query.Query`` equality is removed. ======================== ``` ### 3.2 ``` ======================== *April 6, 2021* Welcome to Django 3.2! These release notes cover the :ref:`new features <whats-new-3.2>`, as well as some :ref:`backwards incompatible changes <backwards-incompatible-3.2>` you'll want to be aware of when upgrading from Django 3.1 or earlier. We've :ref:`begun the deprecation process for some features <deprecated-features-3.2>`. See the :doc:`/howto/upgrade-version` guide if you're updating an existing project. Django 3.2 is designated as a :term:`long-term support release <Long-term support release>`. It will receive security updates for at least three years after its release. Support for the previous LTS, Django 2.2, will end in April 2022. Python compatibility ==================== Django 3.2 supports Python 3.6, 3.7, 3.8, 3.9, and 3.10 (as of 3.2.9). We **highly recommend** and only officially support the latest release of each series. .. _whats-new-3.2: What's new in Django 3.2 ======================== Automatic :class:`~django.apps.AppConfig` discovery --------------------------------------------------- Most pluggable applications define an :class:`~django.apps.AppConfig` subclass in an ``apps.py`` submodule. Many define a ``default_app_config`` variable pointing to this class in their ``__init__.py``. When the ``apps.py`` submodule exists and defines a single :class:`~django.apps.AppConfig` subclass, Django now uses that configuration automatically, so you can remove ``default_app_config``. ``default_app_config`` made it possible to declare only the application's path in :setting:`INSTALLED_APPS` (e.g. ``'django.contrib.admin'``) rather than the app config's path (e.g. ``'django.contrib.admin.apps.AdminConfig'``). It was introduced for backwards-compatibility with the former style, with the intent to switch the ecosystem to the latter, but the switch didn't happen. With automatic ``AppConfig`` discovery, ``default_app_config`` is no longer needed. As a consequence, it's deprecated. See :ref:`configuring-applications-ref` for full details. Customizing type of auto-created primary keys --------------------------------------------- When defining a model, if no field in a model is defined with :attr:`primary_key=True <django.db.models.Field.primary_key>` an implicit primary key is added. The type of this implicit primary key can now be controlled via the :setting:`DEFAULT_AUTO_FIELD` setting and :attr:`AppConfig.default_auto_field <django.apps.AppConfig.default_auto_field>` attribute. No more needing to override primary keys in all models. Maintaining the historical behavior, the default value for :setting:`DEFAULT_AUTO_FIELD` is :class:`~django.db.models.AutoField`. Starting with 3.2 new projects are generated with :setting:`DEFAULT_AUTO_FIELD` set to :class:`~django.db.models.BigAutoField`. Also, new apps are generated with :attr:`AppConfig.default_auto_field <django.apps.AppConfig.default_auto_field>` set to :class:`~django.db.models.BigAutoField`. In a future Django release the default value of :setting:`DEFAULT_AUTO_FIELD` will be changed to :class:`~django.db.models.BigAutoField`. To avoid unwanted migrations in the future, either explicitly set :setting:`DEFAULT_AUTO_FIELD` to :class:`~django.db.models.AutoField`:: DEFAULT_AUTO_FIELD = 'django.db.models.AutoField' or configure it on a per-app basis:: from django.apps import AppConfig class MyAppConfig(AppConfig): default_auto_field = 'django.db.models.AutoField' name = 'my_app' or on a per-model basis:: from django.db import models class MyModel(models.Model): id = models.AutoField(primary_key=True) In anticipation of the changing default, a system check will provide a warning if you do not have an explicit setting for :setting:`DEFAULT_AUTO_FIELD`. When changing the value of :setting:`DEFAULT_AUTO_FIELD`, migrations for the primary key of existing auto-created through tables cannot be generated currently. See the :setting:`DEFAULT_AUTO_FIELD` docs for details on migrating such tables. .. _new_functional_indexes: Functional indexes ------------------ The new :attr:`*expressions <django.db.models.Index.expressions>` positional argument of :class:`Index() <django.db.models.Index>` enables creating functional indexes on expressions and database functions. For example:: from django.db import models from django.db.models import F, Index, Value from django.db.models.functions import Lower, Upper class MyModel(models.Model): first_name = models.CharField(max_length=255) last_name = models.CharField(max_length=255) height = models.IntegerField() weight = models.IntegerField() class Meta: indexes = [ Index( Lower('first_name'), Upper('last_name').desc(), name='first_last_name_idx', ), Index( F('height') / (F('weight') + Value(5)), name='calc_idx', ), ] Functional indexes are added to models using the :attr:`Meta.indexes <django.db.models.Options.indexes>` option. ``pymemcache`` support ---------------------- The new ``django.core.cache.backends.memcached.PyMemcacheCache`` cache backend allows using the pymemcache_ library for memcached. ``pymemcache`` 3.4.0 or higher is required. For more details, see the :doc:`documentation on caching in Django </topics/cache>`. .. _pymemcache: https://pypi.org/project/pymemcache/ New decorators for the admin site --------------------------------- The new :func:`~django.contrib.admin.display` decorator allows for easily adding options to custom display functions that can be used with :attr:`~django.contrib.admin.ModelAdmin.list_display` or :attr:`~django.contrib.admin.ModelAdmin.readonly_fields`. Likewise, the new :func:`~django.contrib.admin.action` decorator allows for easily adding options to action functions that can be used with :attr:`~django.contrib.admin.ModelAdmin.actions`. Using the ``display`` decorator has the advantage that it is now possible to use the ``property`` decorator when needing to specify attributes on the custom method. Prior to this it was necessary to use the ``property()`` function instead after assigning the required attributes to the method. Using decorators has the advantage that these options are more discoverable as they can be suggested by completion utilities in code editors. They are merely a convenience and still set the same attributes on the functions under the hood. Minor features -------------- :mod:`django.contrib.admin` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ * :attr:`.ModelAdmin.search_fields` now allows searching against quoted phrases with spaces. * Read-only related fields are now rendered as navigable links if target models are registered in the admin. * The admin now supports theming, and includes a dark theme that is enabled according to browser settings. See :ref:`admin-theming` for more details. * :attr:`.ModelAdmin.autocomplete_fields` now respects :attr:`ForeignKey.to_field <django.db.models.ForeignKey.to_field>` and :attr:`ForeignKey.limit_choices_to <django.db.models.ForeignKey.limit_choices_to>` when searching a related model. * The admin now installs a final catch-all view that redirects unauthenticated users to the login page, regardless of whether the URL is otherwise valid. This protects against a potential model enumeration privacy issue. Although not recommended, you may set the new :attr:`.AdminSite.final_catch_all_view` to ``False`` to disable the catch-all view. :mod:`django.contrib.auth` ~~~~~~~~~~~~~~~~~~~~~~~~~~ * The default iteration count for the PBKDF2 password hasher is increased from 216,000 to 260,000. * The default variant for the Argon2 password hasher is changed to Argon2id. ``memory_cost`` and ``parallelism`` are increased to 102,400 and 8 respectively to match the ``argon2-cffi`` defaults. Increasing the ``memory_cost`` pushes the required memory from 512 KB to 100 MB. This is still rather conservative but can lead to problems in memory constrained environments. If this is the case, the existing hasher can be subclassed to override the defaults. * The default salt entropy for the Argon2, MD5, PBKDF2, SHA-1 password hashers is increased from 71 to 128 bits. :mod:`django.contrib.contenttypes` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The new ``absolute_max`` argument for :func:`~django.contrib.contenttypes.forms.generic_inlineformset_factory` allows customizing the maximum number of forms that can be instantiated when supplying ``POST`` data. See :ref:`formsets-absolute-max` for more details. * The new ``can_delete_extra`` argument for :func:`~django.contrib.contenttypes.forms.generic_inlineformset_factory` allows removal of the option to delete extra forms. See :attr:`~.BaseFormSet.can_delete_extra` for more information. :mod:`django.contrib.gis` ~~~~~~~~~~~~~~~~~~~~~~~~~ * The :meth:`.GDALRaster.transform` method now supports :class:`~django.contrib.gis.gdal.SpatialReference`. * The :class:`~django.contrib.gis.gdal.DataSource` class now supports :class:`pathlib.Path`. * The :class:`~django.contrib.gis.utils.LayerMapping` class now supports :class:`pathlib.Path`. :mod:`django.contrib.postgres` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The new :attr:`.ExclusionConstraint.include` attribute allows creating covering exclusion constraints on PostgreSQL 12+. * The new :attr:`.ExclusionConstraint.opclasses` attribute allows setting PostgreSQL operator classes. * The new :attr:`.JSONBAgg.ordering` attribute determines the ordering of the aggregated elements. * The new :attr:`.JSONBAgg.distinct` attribute determines if aggregated values will be distinct. * The :class:`~django.contrib.postgres.operations.CreateExtension` operation now checks that the extension already exists in the database and skips the migration if so. * The new :class:`~django.contrib.postgres.operations.CreateCollation` and :class:`~django.contrib.postgres.operations.RemoveCollation` operations allow creating and dropping collations on PostgreSQL. See :ref:`manage-postgresql-collations` for more details. * Lookups for :class:`~django.contrib.postgres.fields.ArrayField` now allow (non-nested) arrays containing expressions as right-hand sides. * The new :class:`OpClass() <django.contrib.postgres.indexes.OpClass>` expression allows creating functional indexes on expressions with a custom operator class. See :ref:`new_functional_indexes` for more details. :mod:`django.contrib.sitemaps` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The new :class:`~django.contrib.sitemaps.Sitemap` attributes :attr:`~django.contrib.sitemaps.Sitemap.alternates`, :attr:`~django.contrib.sitemaps.Sitemap.languages` and :attr:`~django.contrib.sitemaps.Sitemap.x_default` allow generating sitemap *alternates* to localized versions of your pages. :mod:`django.contrib.syndication` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The new ``item_comments`` hook allows specifying a comments URL per feed item. Database backends ~~~~~~~~~~~~~~~~~ * Third-party database backends can now skip or mark as expected failures tests in Django's test suite using the new ``DatabaseFeatures.django_test_skips`` and ``django_test_expected_failures`` attributes. Decorators ~~~~~~~~~~ * The new :func:`~django.views.decorators.common.no_append_slash` decorator allows individual views to be excluded from :setting:`APPEND_SLASH` URL normalization. Error Reporting ~~~~~~~~~~~~~~~ * Custom :class:`~django.views.debug.ExceptionReporter` subclasses can now define the :attr:`~django.views.debug.ExceptionReporter.html_template_path` and :attr:`~django.views.debug.ExceptionReporter.text_template_path` properties to override the templates used to render exception reports. File Uploads ~~~~~~~~~~~~ * The new :meth:`FileUploadHandler.upload_interrupted() <django.core.files.uploadhandler.FileUploadHandler.upload_interrupted>` callback allows handling interrupted uploads. Forms ~~~~~ * The new ``absolute_max`` argument for :func:`.formset_factory`, :func:`.inlineformset_factory`, and :func:`.modelformset_factory` allows customizing the maximum number of forms that can be instantiated when supplying ``POST`` data. See :ref:`formsets-absolute-max` for more details. * The new ``can_delete_extra`` argument for :func:`.formset_factory`, :func:`.inlineformset_factory`, and :func:`.modelformset_factory` allows removal of the option to delete extra forms. See :attr:`~.BaseFormSet.can_delete_extra` for more information. * :class:`~django.forms.formsets.BaseFormSet` now reports a user facing error, rather than raising an exception, when the management form is missing or has been tampered with. To customize this error message, pass the ``error_messages`` argument with the key ``'missing_management_form'`` when instantiating the formset. Generic Views ~~~~~~~~~~~~~ * The ``week_format`` attributes of :class:`~django.views.generic.dates.WeekMixin` and :class:`~django.views.generic.dates.WeekArchiveView` now support the ``'%V'`` ISO 8601 week format. Management Commands ~~~~~~~~~~~~~~~~~~~ * :djadmin:`loaddata` now supports fixtures stored in XZ archives (``.xz``) and LZMA archives (``.lzma``). * :djadmin:`dumpdata` now can compress data in the ``bz2``, ``gz``, ``lzma``, or ``xz`` formats. * :djadmin:`makemigrations` can now be called without an active database connection. In that case, check for a consistent migration history is skipped. * :attr:`.BaseCommand.requires_system_checks` now supports specifying a list of tags. System checks registered in the chosen tags will be checked for errors prior to executing the command. In previous versions, either all or none of the system checks were performed. * Support for colored terminal output on Windows is updated. Various modern terminal environments are automatically detected, and the options for enabling support in other cases are improved. See :ref:`syntax-coloring` for more details. Migrations ~~~~~~~~~~ * The new ``Operation.migration_name_fragment`` property allows providing a filename fragment that will be used to name a migration containing only that operation. * Migrations now support serialization of pure and concrete path objects from :mod:`pathlib`, and :class:`os.PathLike` instances. Models ~~~~~~ * The new ``no_key`` parameter for :meth:`.QuerySet.select_for_update()`, supported on PostgreSQL, allows acquiring weaker locks that don't block the creation of rows that reference locked rows through a foreign key. * :class:`When() <django.db.models.expressions.When>` expression now allows using the ``condition`` argument with ``lookups``. * The new :attr:`.Index.include` and :attr:`.UniqueConstraint.include` attributes allow creating covering indexes and covering unique constraints on PostgreSQL 11+. * The new :attr:`.UniqueConstraint.opclasses` attribute allows setting PostgreSQL operator classes. * The :meth:`.QuerySet.update` method now respects the ``order_by()`` clause on MySQL and MariaDB. * :class:`FilteredRelation() <django.db.models.FilteredRelation>` now supports nested relations. * The ``of`` argument of :meth:`.QuerySet.select_for_update()` is now allowed on MySQL 8.0.1+. * :class:`Value() <django.db.models.Value>` expression now automatically resolves its ``output_field`` to the appropriate :class:`Field <django.db.models.Field>` subclass based on the type of its provided ``value`` for :py:class:`bool`, :py:class:`bytes`, :py:class:`float`, :py:class:`int`, :py:class:`str`, :py:class:`datetime.date`, :py:class:`datetime.datetime`, :py:class:`datetime.time`, :py:class:`datetime.timedelta`, :py:class:`decimal.Decimal`, and :py:class:`uuid.UUID` instances. As a consequence, resolving an ``output_field`` for database functions and combined expressions may now crash with mixed types when using ``Value()``. You will need to explicitly set the ``output_field`` in such cases. * The new :meth:`.QuerySet.alias` method allows creating reusable aliases for expressions that don't need to be selected but are used for filtering, ordering, or as a part of complex expressions. * The new :class:`~django.db.models.functions.Collate` function allows filtering and orde