Django 3.1 release notes¶
August 4, 2020
Welcome to Django 3.1!
These release notes cover the new features, as well as some backwards incompatible changes you’ll want to be aware of when upgrading from Django 3.0 or earlier. We’ve dropped some features that have reached the end of their deprecation cycle, and we’ve begun the deprecation process for some features.
See the How to upgrade Django to a newer version guide if you’re updating an existing project.
Python compatibility¶
Django 3.1 supports Python 3.6, 3.7, 3.8, and 3.9 (as of 3.1.3). We highly recommend and only officially support the latest release of each series.
What’s new in Django 3.1¶
Asynchronous views and middleware support¶
Django now supports a fully asynchronous request path, including:
To get started with async views, you need to declare a view using
async def
:
async def my_view(request):
await asyncio.sleep(0.5)
return HttpResponse("Hello, async world!")
All asynchronous features are supported whether you are running under WSGI or ASGI mode. However, there will be performance penalties using async code in WSGI mode. You can read more about the specifics in Asynchronous support documentation.
You are free to mix async and sync views, middleware, and tests as much as you want. Django will ensure that you always end up with the right execution context. We expect most projects will keep the majority of their views synchronous, and only have a select few running in async mode - but it is entirely your choice.
Django’s ORM, cache layer, and other pieces of code that do long-running network calls do not yet support async access. We expect to add support for them in upcoming releases. Async views are ideal, however, if you are doing a lot of API or HTTP calls inside your view, you can now natively do all those HTTP calls in parallel to considerably speed up your view’s execution.
Asynchronous support should be entirely backwards-compatible and we have tried to ensure that it has no speed regressions for your existing, synchronous code. It should have no noticeable effect on any existing Django projects.
JSONField for all supported database backends¶
Django now includes models.JSONField
and
forms.JSONField
that can be used on all
supported database backends. Both fields support the use of custom JSON
encoders and decoders. The model field supports the introspection,
lookups, and transforms that were previously
PostgreSQL-only:
from django.db import models
class ContactInfo(models.Model):
data = models.JSONField()
ContactInfo.objects.create(
data={
"name": "John",
"cities": ["London", "Cambridge"],
"pets": {"dogs": ["Rufus", "Meg"]},
}
)
ContactInfo.objects.filter(
data__name="John",
data__pets__has_key="dogs",
data__cities__contains="London",
).delete()
If your project uses django.contrib.postgres.fields.JSONField
, plus the
related form field and transforms, you should adjust to use the new fields,
and generate and apply a database migration. For now, the old fields and
transforms are left as a reference to the new ones and are deprecated as
of this release.
DEFAULT_HASHING_ALGORITHM
settings¶
The new DEFAULT_HASHING_ALGORITHM
transitional setting allows specifying
the default hashing algorithm to use for encoding cookies, password reset
tokens in the admin site, user sessions, and signatures created by
django.core.signing.Signer
and django.core.signing.dumps()
.
Support for SHA-256 was added in Django 3.1. If you are upgrading multiple
instances of the same project to Django 3.1, you should set
DEFAULT_HASHING_ALGORITHM
to 'sha1'
during the transition, in order to
allow compatibility with the older versions of Django. Note that this requires
Django 3.1.1+. Once the transition to 3.1 is complete you can stop overriding
DEFAULT_HASHING_ALGORITHM
.
This setting is deprecated as of this release, because support for tokens, cookies, sessions, and signatures that use SHA-1 algorithm will be removed in Django 4.0.
Minor features¶
django.contrib.admin
¶
The new
django.contrib.admin.EmptyFieldListFilter
forModelAdmin.list_filter
allows filtering on empty values (empty strings and nulls) in the admin changelist view.Filters in the right sidebar of the admin changelist view now contain a link to clear all filters.
The admin now has a sidebar on larger screens for easier navigation. It is enabled by default but can be disabled by using a custom
AdminSite
and settingAdminSite.enable_nav_sidebar
toFalse
.Rendering the sidebar requires access to the current request in order to set CSS and ARIA role affordances. This requires using
'django.template.context_processors.request'
in the'context_processors'
option ofOPTIONS
.Initially empty
extra
inlines can now be removed, in the same way as dynamically created ones.XRegExp
is upgraded from version 2.0.0 to 3.2.0.jQuery is upgraded from version 3.4.1 to 3.5.1.
Select2 library is upgraded from version 4.0.7 to 4.0.13.
django.contrib.auth
¶
The default iteration count for the PBKDF2 password hasher is increased from 180,000 to 216,000.
The new
PASSWORD_RESET_TIMEOUT
setting allows defining the number of seconds a password reset link is valid for. This is encouraged instead of the deprecatedPASSWORD_RESET_TIMEOUT_DAYS
setting, which will be removed in Django 4.0.The password reset mechanism now uses the SHA-256 hashing algorithm. Support for tokens that use the old hashing algorithm remains until Django 4.0.
AbstractBaseUser.get_session_auth_hash()
now uses the SHA-256 hashing algorithm. Support for user sessions that use the old hashing algorithm remains until Django 4.0.
django.contrib.contenttypes
¶
The new
remove_stale_contenttypes --include-stale-apps
option allows removing stale content types from previously installed apps that have been removed fromINSTALLED_APPS
.
django.contrib.gis
¶
relate
lookup is now supported on MariaDB.Added the
LinearRing.is_counterclockwise
property.AsGeoJSON
is now supported on Oracle.Added support for PostGIS 3 and GDAL 3.
django.contrib.humanize
¶
intword
template filter now supports negative integers.
django.contrib.postgres
¶
The new
BloomIndex
class allows creatingbloom
indexes in the database. The newBloomExtension
migration operation installs thebloom
extension to add support for this index.get_FOO_display()
now supportsArrayField
andRangeField
.The new
rangefield.lower_inc
,rangefield.lower_inf
,rangefield.upper_inc
, andrangefield.upper_inf
lookups allow queryingRangeField
by a bound type.rangefield.contained_by
now supportsSmallAutoField
,AutoField
,BigAutoField
,SmallIntegerField
, andDecimalField
.SearchQuery
now supports'websearch'
search type on PostgreSQL 11+.SearchQuery.value
now supports query expressions.The new
SearchHeadline
class allows highlighting search results.search
lookup now supports query expressions.The new
cover_density
parameter ofSearchRank
allows ranking by cover density.The new
normalization
parameter ofSearchRank
allows rank normalization.The new
ExclusionConstraint.deferrable
attribute allows creating deferrable exclusion constraints.
django.contrib.sessions
¶
The
SESSION_COOKIE_SAMESITE
setting now allows'None'
(string) value to explicitly state that the cookie is sent with all same-site and cross-site requests.
django.contrib.staticfiles
¶
The
STATICFILES_DIRS
setting now supportspathlib.Path
.
Cache¶
The
cache_control()
decorator andpatch_cache_control()
method now support multiple field names in theno-cache
directive for theCache-Control
header, according to RFC 7234 Section 5.2.2.2.delete()
now returnsTrue
if the key was successfully deleted,False
otherwise.
CSRF¶
The
CSRF_COOKIE_SAMESITE
setting now allows'None'
(string) value to explicitly state that the cookie is sent with all same-site and cross-site requests.
Email¶
The
EMAIL_FILE_PATH
setting, used by the file email backend, now supportspathlib.Path
.
Error Reporting¶
django.views.debug.SafeExceptionReporterFilter
now filters sensitive values fromrequest.META
in exception reports.The new
SafeExceptionReporterFilter.cleansed_substitute
andSafeExceptionReporterFilter.hidden_settings
attributes allow customization of sensitive settings andrequest.META
filtering in exception reports.The technical 404 debug view now respects
DEFAULT_EXCEPTION_REPORTER_FILTER
when applying settings filtering.The new
DEFAULT_EXCEPTION_REPORTER
allows providing adjango.views.debug.ExceptionReporter
subclass to customize exception report generation. See Custom error reports for details.
File Storage¶
FileSystemStorage.save()
method now supportspathlib.Path
.FileField
andImageField
now accept a callable forstorage
. This allows you to modify the used storage at runtime, selecting different storages for different environments, for example.
Forms¶
ModelChoiceIterator
, used byModelChoiceField
andModelMultipleChoiceField
, now usesModelChoiceIteratorValue
that can be used by widgets to access model instances. See Iterating relationship choices for details.django.forms.DateTimeField
now accepts dates in a subset of ISO 8601 datetime formats, including optional timezone, e.g.2019-10-10T06:47
,2019-10-10T06:47:23+04:00
, or2019-10-10T06:47:23Z
. The timezone will always be retained if provided, with timezone-aware datetimes being returned even whenUSE_TZ
isFalse
.Additionally,
DateTimeField
now usesDATE_INPUT_FORMATS
in addition toDATETIME_INPUT_FORMATS
when converting a field input to adatetime
value.MultiWidget.widgets
now accepts a dictionary which allows customizing subwidgetname
attributes.The new
BoundField.widget_type
property can be used to dynamically adjust form rendering based upon the widget type.
Internationalization¶
The
LANGUAGE_COOKIE_SAMESITE
setting now allows'None'
(string) value to explicitly state that the cookie is sent with all same-site and cross-site requests.Added support and translations for the Algerian Arabic, Igbo, Kyrgyz, Tajik, and Turkmen languages.
Management Commands¶
The new
check --database
option allows specifying database aliases for running thedatabase
system checks. Previously these checks were enabled for all configuredDATABASES
by passing thedatabase
tag to the command.The new
migrate --check
option makes the command exit with a non-zero status when unapplied migrations are detected.The new
returncode
argument forCommandError
allows customizing the exit status for management commands.The new
dbshell -- ARGUMENTS
option allows passing extra arguments to the command-line client for the database.The
flush
andsqlflush
commands now include SQL to reset sequences on SQLite.
Models¶
The new
ExtractIsoWeekDay
function extracts ISO-8601 week days fromDateField
andDateTimeField
, and the newiso_week_day
lookup allows querying by an ISO-8601 day of week.QuerySet.explain()
now supports:TREE
format on MySQL 8.0.16+,analyze
option on MySQL 8.0.18+ and MariaDB.
Added
PositiveBigIntegerField
which acts much like aPositiveIntegerField
except that it only allows values under a certain (database-dependent) limit. Values from0
to9223372036854775807
are safe in all databases supported by Django.The new
RESTRICT
option foron_delete
argument ofForeignKey
andOneToOneField
emulates the behavior of the SQL constraintON DELETE RESTRICT
.CheckConstraint.check
now supports boolean expressions.The
RelatedManager.add()
,create()
, andset()
methods now accept callables as values in thethrough_defaults
argument.The new
is_dst
parameter of theQuerySet.datetimes()
determines the treatment of nonexistent and ambiguous datetimes.The new
F
expressionbitxor()
method allows bitwise XOR operation.QuerySet.bulk_create()
now sets the primary key on objects when using MariaDB 10.5+.The
DatabaseOperations.sql_flush()
method now generates more efficient SQL on MySQL by usingDELETE
instead ofTRUNCATE
statements for tables which don’t require resetting sequences.SQLite functions are now marked as
deterministic
on Python 3.8+. This allows using them in check constraints and partial indexes.The new
UniqueConstraint.deferrable
attribute allows creating deferrable unique constraints.
Pagination¶
Paginator
can now be iterated over to yield its pages.
Requests and Responses¶
If
ALLOWED_HOSTS
is empty andDEBUG=True
, subdomains of localhost are now allowed in theHost
header, e.g.static.localhost
.HttpResponse.set_cookie()
andHttpResponse.set_signed_cookie()
now allow usingsamesite='None'
(string) to explicitly state that the cookie is sent with all same-site and cross-site requests.The new
HttpRequest.accepts()
method returns whether the request accepts the given MIME type according to theAccept
HTTP header.
Security¶
The
SECURE_REFERRER_POLICY
setting now defaults to'same-origin'
. With this configured,SecurityMiddleware
sets the Referrer Policy header tosame-origin
on all responses that do not already have it. This prevents theReferer
header being sent to other origins. If you need the previous behavior, explicitly setSECURE_REFERRER_POLICY
toNone
.The default algorithm of
django.core.signing.Signer
,django.core.signing.loads()
, anddjango.core.signing.dumps()
is changed to the SHA-256. Support for signatures made with the old SHA-1 algorithm remains until Django 4.0.Also, the new
algorithm
parameter of theSigner
allows customizing the hashing algorithm.
Templates¶
The renamed
translate
andblocktranslate
template tags are introduced for internationalization in template code. The oldertrans
andblocktrans
template tags aliases continue to work, and will be retained for the foreseeable future.The
include
template tag now accepts iterables of template names.
Tests¶
SimpleTestCase
now implements thedebug()
method to allow running a test without collecting the result and catching exceptions. This can be used to support running tests under a debugger.The new
MIGRATE
test database setting allows disabling of migrations during a test database creation.Django test runner now supports a
test --buffer
option to discard output for passing tests.DiscoverRunner
now skips running the system checks on databases not referenced by tests.TransactionTestCase
teardown is now faster on MySQL due toflush
command improvements. As a side effect the latter doesn’t automatically reset sequences on teardown anymore. EnableTransactionTestCase.reset_sequences
if your tests require this feature.
URLs¶
Path converters can now raise
ValueError
into_url()
to indicate no match when reversing URLs.
Utilities¶
filepath_to_uri()
now supportspathlib.Path
.parse_duration()
now supports comma separators for decimal fractions in the ISO 8601 format.parse_datetime()
,parse_duration()
, andparse_time()
now support comma separators for milliseconds.
Miscellaneous¶
The SQLite backend now supports
pathlib.Path
for theNAME
setting.The
settings.py
generated by thestartproject
command now usespathlib.Path
instead ofos.path
for building filesystem paths.The
TIME_ZONE
setting is now allowed on databases that support time zones.
Backwards incompatible changes in 3.1¶
Database backend API¶
This section describes changes that may be needed in third-party database backends.
DatabaseOperations.fetch_returned_insert_columns()
now requires an additionalreturning_params
argument.connection.timezone
property is now'UTC'
by default, or theTIME_ZONE
whenUSE_TZ
isTrue
on databases that support time zones. Previously, it wasNone
on databases that support time zones.connection._nodb_connection
property is changed to theconnection._nodb_cursor()
method and now returns a context manager that yields a cursor and automatically closes the cursor and connection upon exiting thewith
statement.DatabaseClient.runshell()
now requires an additionalparameters
argument as a list of extra arguments to pass on to the command-line client.The
sequences
positional argument ofDatabaseOperations.sql_flush()
is replaced by the boolean keyword-only argumentreset_sequences
. IfTrue
, the sequences of the truncated tables will be reset.The
allow_cascade
argument ofDatabaseOperations.sql_flush()
is now a keyword-only argument.The
using
positional argument ofDatabaseOperations.execute_sql_flush()
is removed. The method now uses the database of the called instance.Third-party database backends must implement support for
JSONField
or setDatabaseFeatures.supports_json_field
toFalse
. If storing primitives is not supported, setDatabaseFeatures.supports_primitives_in_json_field
toFalse
. If there is a true datatype for JSON, setDatabaseFeatures.has_native_json_field
toTrue
. Ifjsonfield.contains
andjsonfield.contained_by
are not supported, setDatabaseFeatures.supports_json_field_contains
toFalse
.Third party database backends must implement introspection for
JSONField
or setcan_introspect_json_field
toFalse
.
Dropped support for MariaDB 10.1¶
Upstream support for MariaDB 10.1 ends in October 2020. Django 3.1 supports MariaDB 10.2 and higher.
contrib.admin
browser support¶
The admin no longer supports the legacy Internet Explorer browser. See the admin FAQ for details on supported browsers.
AbstractUser.first_name
max_length
increased to 150¶
A migration for django.contrib.auth.models.User.first_name
is included.
If you have a custom user model inheriting from AbstractUser
, you’ll need
to generate and apply a database migration for your user model.
If you want to preserve the 30 character limit for first names, use a custom form:
from django import forms
from django.contrib.auth.forms import UserChangeForm
class MyUserChangeForm(UserChangeForm):
first_name = forms.CharField(max_length=30, required=False)
If you wish to keep this restriction in the admin when editing users, set
UserAdmin.form
to use this form:
from django.contrib.auth.admin import UserAdmin
from django.contrib.auth.models import User
class MyUserAdmin(UserAdmin):
form = MyUserChangeForm
admin.site.unregister(User)
admin.site.register(User, MyUserAdmin)
Miscellaneous¶
The cache keys used by
cache
and generated bymake_template_fragment_key()
are different from the keys generated by older versions of Django. After upgrading to Django 3.1, the first request to any previously cached template fragment will be a cache miss.The logic behind the decision to return a redirection fallback or a 204 HTTP response from the
set_language()
view is now based on theAccept
HTTP header instead of theX-Requested-With
HTTP header presence.The compatibility imports of
django.core.exceptions.EmptyResultSet
indjango.db.models.query
,django.db.models.sql
, anddjango.db.models.sql.datastructures
are removed.The compatibility import of
django.core.exceptions.FieldDoesNotExist
indjango.db.models.fields
is removed.The compatibility imports of
django.forms.utils.pretty_name()
anddjango.forms.boundfield.BoundField
indjango.forms.forms
are removed.The compatibility imports of
Context
,ContextPopException
, andRequestContext
indjango.template.base
are removed.The compatibility import of
django.contrib.admin.helpers.ACTION_CHECKBOX_NAME
indjango.contrib.admin
is removed.The
STATIC_URL
andMEDIA_URL
settings set to relative paths are now prefixed by the server-provided value ofSCRIPT_NAME
(or/
if not set). This change should not affect settings set to valid URLs or absolute paths.ConditionalGetMiddleware
no longer adds theETag
header to responses with an emptycontent
.django.utils.decorators.classproperty()
decorator is made public and moved todjango.utils.functional.classproperty()
.floatformat
template filter now outputs (positive)0
for negative numbers which round to zero.Meta.ordering
andMeta.unique_together
options on models indjango.contrib
modules that were formerly tuples are now lists.The admin calendar widget now handles two-digit years according to the Open Group Specification, i.e. values between 69 and 99 are mapped to the previous century, and values between 0 and 68 are mapped to the current century.
Date-only formats are removed from the default list for
DATETIME_INPUT_FORMATS
.The
FileInput
widget no longer renders with therequired
HTML attribute when initial data exists.The undocumented
django.views.debug.ExceptionReporterFilter
class is removed. As per the Custom error reports documentation, classes to be used withDEFAULT_EXCEPTION_REPORTER_FILTER
need to inherit fromdjango.views.debug.SafeExceptionReporterFilter
.The cache timeout set by
cache_page()
decorator now takes precedence over themax-age
directive from theCache-Control
header.Providing a non-local remote field in the
ForeignKey.to_field
argument now raisesFieldError
.SECURE_REFERRER_POLICY
now defaults to'same-origin'
. See the What’s New Security section above for more details.check
management command now runs thedatabase
system checks only for database aliases specified usingcheck --database
option.migrate
management command now runs thedatabase
system checks only for a database to migrate.The admin CSS classes
row1
androw2
are removed in favor of:nth-child(odd)
and:nth-child(even)
pseudo-classes.The
make_password()
function now requires its argument to be a string or bytes. Other types should be explicitly cast to one of these.The undocumented
version
parameter to theAsKML
function is removed.JSON and YAML serializers, used by
dumpdata
, now dump all data with Unicode by default. If you need the previous behavior, passensure_ascii=True
to JSON serializer, orallow_unicode=False
to YAML serializer.The auto-reloader no longer monitors changes in built-in Django translation files.
The minimum supported version of
mysqlclient
is increased from 1.3.13 to 1.4.0.The undocumented
django.contrib.postgres.forms.InvalidJSONInput
anddjango.contrib.postgres.forms.JSONString
are moved todjango.forms.fields
.The undocumented
django.contrib.postgres.fields.jsonb.JsonAdapter
class is removed.The
{% localize off %}
tag andunlocalize
filter no longer respectDECIMAL_SEPARATOR
setting.The minimum supported version of
asgiref
is increased from 3.2 to 3.2.10.The Media class now renders
<script>
tags without thetype
attribute to follow WHATWG recommendations.ModelChoiceIterator
, used byModelChoiceField
andModelMultipleChoiceField
, now yields 2-tuple choices containingModelChoiceIteratorValue
instances as the firstvalue
element in each choice. In most cases this proxies transparently, but if you need thefield
value itself, use theModelChoiceIteratorValue.value
attribute instead.
Features deprecated in 3.1¶
PostgreSQL JSONField
¶
django.contrib.postgres.fields.JSONField
and
django.contrib.postgres.forms.JSONField
are deprecated in favor of
models.JSONField
and
forms.JSONField
.
The undocumented django.contrib.postgres.fields.jsonb.KeyTransform
and
django.contrib.postgres.fields.jsonb.KeyTextTransform
are also deprecated
in favor of the transforms in django.db.models.fields.json
.
The new JSONField
s, KeyTransform
, and KeyTextTransform
can be used
on all supported database backends.
Miscellaneous¶
PASSWORD_RESET_TIMEOUT_DAYS
setting is deprecated in favor ofPASSWORD_RESET_TIMEOUT
.The undocumented usage of the
isnull
lookup with non-boolean values as the right-hand side is deprecated, useTrue
orFalse
instead.The barely documented
django.db.models.query_utils.InvalidQuery
exception class is deprecated in favor ofFieldDoesNotExist
andFieldError
.The
django-admin.py
entry point is deprecated in favor ofdjango-admin
.The
HttpRequest.is_ajax()
method is deprecated as it relied on a jQuery-specific way of signifying AJAX calls, while current usage tends to use the JavaScript Fetch API. Depending on your use case, you can either write your own AJAX detection method, or use the newHttpRequest.accepts()
method if your code depends on the clientAccept
HTTP header.If you are writing your own AJAX detection method,
request.is_ajax()
can be reproduced exactly asrequest.headers.get('x-requested-with') == 'XMLHttpRequest'
.Passing
None
as the first argument todjango.utils.deprecation.MiddlewareMixin.__init__()
is deprecated.The encoding format of cookies values used by
CookieStorage
is different from the format generated by older versions of Django. Support for the old format remains until Django 4.0.The encoding format of sessions is different from the format generated by older versions of Django. Support for the old format remains until Django 4.0.
The purely documentational
providing_args
argument forSignal
is deprecated. If you rely on this argument as documentation, you can move the text to a code comment or docstring.Calling
django.utils.crypto.get_random_string()
without alength
argument is deprecated.The
list
message forModelMultipleChoiceField
is deprecated in favor ofinvalid_list
.Passing raw column aliases to
QuerySet.order_by()
is deprecated. The same result can be achieved by passing aliases in aRawSQL
instead beforehand.The
NullBooleanField
model field is deprecated in favor ofBooleanField(null=True)
.django.conf.urls.url()
alias ofdjango.urls.re_path()
is deprecated.The
{% ifequal %}
and{% ifnotequal %}
template tags are deprecated in favor of{% if %}
.{% if %}
covers all use cases, but if you need to continue using these tags, they can be extracted from Django to a module and included as a built-in tag in the'builtins'
option inOPTIONS
.DEFAULT_HASHING_ALGORITHM
transitional setting is deprecated.
Features removed in 3.1¶
These features have reached the end of their deprecation cycle and are removed in Django 3.1.
See Features deprecated in 2.2 for details on these changes, including how to remove usage of these features.
django.utils.timezone.FixedOffset
is removed.django.core.paginator.QuerySetPaginator
is removed.A model’s
Meta.ordering
doesn’t affectGROUP BY
queries.django.contrib.postgres.fields.FloatRangeField
anddjango.contrib.postgres.forms.FloatRangeField
are removed.The
FILE_CHARSET
setting is removed.django.contrib.staticfiles.storage.CachedStaticFilesStorage
is removed.The
RemoteUserBackend.configure_user()
method requiresrequest
as the first positional argument.Support for
SimpleTestCase.allow_database_queries
andTransactionTestCase.multi_db
is removed.