April 4, 2017
Welcome to Django 1.11!
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 1.10 or older versions. We’ve begun the deprecation process for some features.
See the Upgrading Django to a newer version guide if you’re updating an existing project.
Django 1.11 is designated as a long-term support release. It will receive security updates for at least three years after its release. Support for the previous LTS, Django 1.8, will end in April 2018.
Django 1.11 requires Python 2.7, 3.4, 3.5, 3.6, or 3.7 (as of 1.11.17). We highly recommend and only officially support the latest release of each series.
The Django 1.11.x series is the last to support Python 2. The next major release, Django 2.0, will only support Python 3.4+.
Unlike older versions of Django, Django’s own deprecation warnings are no longer displayed by default. This is consistent with Python’s default behavior.
This change allows third-party apps to support both Django 1.11 LTS and Django 1.8 LTS without having to add code to avoid deprecation warnings.
Following the release of Django 2.0, we suggest that third-party app authors
drop support for all versions of Django prior to 1.11. At that time, you should
be able run your package’s tests using python -Wd so that deprecation
warnings do appear. After making the deprecation warning fixes, your app should
be compatible with Django 2.0.
The new django.db.models.indexes module contains classes which ease
creating database indexes. Indexes are added to models using the
Meta.indexes option.
The Index class creates a b-tree index, as if you
used db_index on the model field or
index_together on the model Meta class.
It can be subclassed to support different index types, such as
GinIndex. It also allows defining the
order (ASC/DESC) for the columns of the index.
To ease customizing widgets, form widget rendering is now done using the template system rather than in Python. See The form rendering API.
You may need to adjust any custom widgets that you’ve written for a few backwards incompatible changes.
Subquery expressions¶The new Subquery and
Exists database expressions allow creating
explicit subqueries. Subqueries may refer to fields from the outer queryset
using the OuterRef class.
django.contrib.admin¶ModelAdmin.date_hierarchy can now reference fields across relations.ModelAdmin.get_exclude() hook allows specifying the
exclude fields based on the request or model instance.popup_response.html template can now be overridden per app, per
model, or by setting the ModelAdmin.popup_response_template
attribute.django.contrib.auth¶LoginView and
LogoutView class-based views supersede the
deprecated login() and logout() function-based views.PasswordChangeView,
PasswordChangeDoneView,
PasswordResetView,
PasswordResetDoneView,
PasswordResetConfirmView, and
PasswordResetCompleteView class-based
views supersede the deprecated password_change(),
password_change_done(), password_reset(), password_reset_done(),
password_reset_confirm(), and password_reset_complete() function-based
views.post_reset_login attribute for
PasswordResetConfirmView allows
automatically logging in a user after a successful password reset.
If you have multiple AUTHENTICATION_BACKENDS configured, use the
post_reset_login_backend attribute to choose which one to use.PasswordResetConfirmView (but not the
deprecated password_reset_confirm() function-based view) stores the token
in a session and redirects to itself to present the password change form to
the user without the token in the URL.update_session_auth_hash() now rotates the session
key to allow a password change to invalidate stolen session cookies.success_url_allowed_hosts attribute for
LoginView and
LogoutView allows specifying a set of
hosts that are safe for redirecting after login and logout.help_text to
UserCreationForm.HttpRequest is now passed to authenticate()
which in turn passes it to the authentication backend if it accepts a
request argument.user_login_failed() signal now
receives a request argument.PasswordResetForm supports custom user
models that use an email field named something other than 'email'.
Set CustomUser.EMAIL_FIELD to the name of the field.get_user_model() can now be called at import time,
even in modules that define models.django.contrib.contenttypes¶remove_stale_contenttypes command, there’s now a list of related
objects such as auth.Permissions that will also be deleted. Previously,
only the content types were listed (and this prompt was after migrate
rather than in a separate command).django.contrib.gis¶GEOSGeometry.from_gml() and OGRGeometry.from_gml()
methods allow creating geometries from GML.dwithin lookup on SpatiaLite.Area function,
Distance function, and
distance lookups now work with geodetic coordinates on SpatiaLite.OpenLayers.js from
https://cdnjs.cloudflare.com which is more suitable for production use
than the old https://openlayers.org/ source. They are also updated to use
OpenLayers 3.size, shape, and offset parameters
when creating GDALRaster objects.IsValid function,
MakeValid function, and
isvalid lookup.AsGML function,
BoundingCircle function,
IsValid function, and
isvalid lookup.django.contrib.postgres¶distinct argument for
StringAgg determines if
concatenated values will be distinct.GinIndex and
BrinIndex classes allow
creating GIN and BRIN indexes in the database.JSONField accepts a new encoder
parameter to specify a custom class to encode data types not supported by the
standard encoder.CIText mixin and
CITextExtension migration
operation allow using PostgreSQL’s citext extension for case-insensitive
lookups. Three fields are provided: CICharField,
CIEmailField, and CITextField.JSONBAgg allows
aggregating values as a JSON array.HStoreField (model field) and
HStoreField (form field) allow
storing null values.OPTIONS
as keyword arguments to the client constructors, allowing for more advanced
control of client behavior. See the cache arguments
documentation for examples.LOCATION, for convenience with
third-party services that use such strings in environment variables.CSRF_USE_SESSIONS setting to allow storing the CSRF
token in the user’s session rather than in a cookie.skip_locked argument to QuerySet.select_for_update()
on PostgreSQL 9.5+ and Oracle to execute queries with
FOR UPDATE SKIP LOCKED.TEST['TEMPLATE'] setting to let
PostgreSQL users specify a template for creating the test database.QuerySet.iterator() now uses server-side cursors on PostgreSQL. This feature transfers some of
the worker memory load (used to hold query results) to the database and might
increase database memory usage.'isolation_level' option in
OPTIONS to allow specifying the transaction isolation level. To avoid possible data loss, it’s recommended to
switch from MySQL’s default level, repeatable read, to read committed.cx_Oracle 5.3.EMAIL_USE_LOCALTIME setting to allow sending SMTP date
headers in the local time zone rather than in UTC.EmailMessage.attach() and attach_file() now fall back to MIME type
application/octet-stream when binary content that can’t be
decoded as UTF-8 is specified for a text/* attachment.io.TextIOWrapper,
File now has the readable(), writable(),
and seekable() methods.empty_value attribute on CharField,
EmailField, RegexField,
SlugField, and URLField allows
specifying the Python value to use to represent “empty”.Form.get_initial_for_field() method returns initial data for a
form field.NUMBER_GROUPING setting support
non-uniform digit grouping.loaddata --exclude option allows excluding models and apps
while loading data from fixtures.diffsettings --default option allows specifying a settings
module other than Django’s default settings to compare against.app_labels arguments now limit the showmigrations --plan
output.uuid.UUID objects.defaults argument of
QuerySet.update_or_create() and
get_or_create().ImageField now has a default
validate_image_file_extension validator.
(This validator moved to the form field in Django 1.11.2.)Trunc functions.ExtractWeek function to
extract the week from DateField and
DateTimeField and exposed it through the
week lookup.TruncTime function to truncate
DateTimeField to its time component and exposed it
through the time lookup.QuerySet.values() and
values_list().range.unique=True option with
FileField.nulls_first and nulls_last parameters to
Expression.asc() and
desc() to control
the ordering of null values.F expression bitleftshift() and bitrightshift() methods
allow bitwise shift operations.QuerySet.union(), intersection(), and
difference().QueryDict.fromkeys().CommonMiddleware now sets the
Content-Length response header for non-streaming responses.SECURE_HSTS_PRELOAD setting to allow appending the
preload directive to the Strict-Transport-Security header.ConditionalGetMiddleware now adds the
ETag header to responses.django.core.serializers.base.Serializer.stream_class attribute
allows subclasses to customize the default stream.cls keyword argument to the
serializers.serialize() function.DjangoJSONEncoder now serializes
timedelta objects (used by
DurationField).mark_safe() can now be used as a decorator.Jinja2 template backend now
supports context processors by setting the 'context_processors' option in
OPTIONS.regroup tag now returns namedtuples instead of dictionaries
so you can unpack the group object directly in a loop, e.g.
{% for grouper, list in regrouped %}.resetcycle template tag to allow resetting the sequence of
the cycle template tag.filesystem.Loader.DiscoverRunner.get_test_runner_kwargs() to allow customizing the
keyword arguments passed to the test runner.test --debug-mode option to help troubleshoot test
failures by setting the DEBUG setting to True.django.test.utils.setup_databases() (moved from
django.test.runner) and teardown_databases()
functions make it easier to build custom test runners.unittest.TestCase.subTest()’s when using the
test --parallel option.DiscoverRunner now runs the system checks at the start of a test run.
Override the DiscoverRunner.run_checks() method if you want to disable
that.FileExtensionValidator to validate
file extensions and
validate_image_file_extension to validate
image files.django.contrib.gis¶contrib.gis was first released, GDAL is now a required
dependency for GeoDjango. In older versions, it’s only required for SQLite.contrib.gis.maps is removed as it interfaces with a retired version of
the Google Maps API and seems to be unmaintained. If you’re using it,
let us know.GEOSGeometry equality operator now also compares SRID.gis/openlayers.html and gis/openlayers-osm.html templates have been
updated. Check your project if you subclass these widgets or extend the
templates. Also, the new widgets work a bit differently than the old ones.
Instead of using a toolbar in the widget, you click to draw, click and drag
to move the map, and click and drag a point/vertex/corner to move it.contrib.gis.forms.widgets and the admin’s
OpenLayersWidget use the form rendering API
rather than loader.render_to_string(). If you’re using a custom widget
template, you’ll need to be sure your form renderer can locate it. For
example, you could use the TemplatesSetting
renderer.django.contrib.staticfiles¶collectstatic may now fail during post-processing when using a hashed
static files storage if a reference loop exists (e.g. 'foo.css'
references 'bar.css' which itself references 'foo.css') or if the
chain of files referencing other files is too deep to resolve in several
passes. In the latter case, increase the number of passes using
ManifestStaticFilesStorage.max_post_process_passes.ManifestStaticFilesStorage, static files not found in the
manifest at runtime now raise a ValueError instead of returning an
unchanged path. You can revert to the old behavior by setting
ManifestStaticFilesStorage.manifest_strict to False.This section describes changes that may be needed in third-party database backends.
DatabaseOperations.time_trunc_sql() method is added to support
TimeField truncation. It accepts a lookup_type and field_name
arguments and returns the appropriate SQL to truncate the given time field
field_name to a time object with only the given specificity. The
lookup_type argument can be either 'hour', 'minute', or
'second'.DatabaseOperations.datetime_cast_time_sql() method is added to
support the time lookup. It accepts a field_name and tzname
arguments and returns the SQL necessary to cast a datetime value to time value.FOR UPDATE SKIP LOCKED support, set
DatabaseFeatures.has_select_for_update_skip_locked = True.DatabaseFeatures.supports_index_column_ordering attribute
specifies if a database allows defining ordering for columns in indexes. The
default value is True and the DatabaseIntrospection.get_constraints()
method should include an 'orders' key in each of the returned
dictionaries with a list of 'ASC' and/or 'DESC' values corresponding
to the ordering of each column in the index.inspectdb no longer calls DatabaseIntrospection.get_indexes()
which is deprecated. Custom database backends should ensure all types of
indexes are returned by DatabaseIntrospection.get_constraints().ignores_quoted_identifier_case feature to
ignores_table_name_case to more accurately reflect how it is used.name keyword argument is added to the
DatabaseWrapper.create_cursor(self, name=None) method to allow usage of
server-side cursors on backends that support it.Upstream support for PostgreSQL 9.2 ends in September 2017. As a consequence, Django 1.11 sets PostgreSQL 9.3 as the minimum version it officially supports.
Support for PostGIS 2.0 is also removed as PostgreSQL 9.2 is the last version to support it.
Also, the minimum supported version of psycopg2 is increased from 2.4.5 to 2.5.4.
LiveServerTestCase binds to port zero¶Rather than taking a port range and iterating to find a free port,
LiveServerTestCase binds to port zero and relies on the operating system
to assign a free port. The DJANGO_LIVE_TEST_SERVER_ADDRESS environment
variable is no longer used, and as it’s also no longer used, the
manage.py test --liveserver option is removed.
If you need to bind LiveServerTestCase to a specific port, use the port
attribute added in Django 1.11.2.
django.contrib.auth and i18n views¶LoginView, LogoutView (and the deprecated function-based equivalents),
and set_language() protect users from being redirected
to non-HTTPS next URLs when the app is running over HTTPS.
QuerySet.get_or_create() and update_or_create() validate arguments¶To prevent typos from passing silently,
get_or_create() and
update_or_create() check that their
arguments are model fields. This should be backwards-incompatible only in the
fact that it might expose a bug in your project.
pytz is a required dependency and support for settings.TIME_ZONE = None is removed¶To simplify Django’s timezone handling, pytz is now a required dependency.
It’s automatically installed along with Django.
Support for settings.TIME_ZONE = None is removed as the behavior isn’t
commonly used and is questionably useful. If you want to automatically detect
the timezone based on the system timezone, you can use tzlocal:
from tzlocal import get_localzone
TIME_ZONE = get_localzone().zone
This works similar to settings.TIME_ZONE = None except that it also sets
os.environ['TZ']. Let us know
if there’s a use case where you find you can’t adapt your code to set a
TIME_ZONE.
<p class="help"> is replaced with a <div> tag to allow including lists
inside help text.
Read-only fields are wrapped in <div class="readonly">...</div> instead of
<p>...</p> to allow any kind of HTML as the field’s content.
Some undocumented classes in django.forms.widgets are removed:
SubWidgetRendererMixin, ChoiceFieldRenderer, RadioFieldRenderer,
CheckboxFieldRendererChoiceInput, RadioChoiceInput, CheckboxChoiceInputThe undocumented Select.render_option() method is removed.
The Widget.format_output() method is removed. Use a custom widget template
instead.
Some widget values, such as <select> options, are now localized if
settings.USE_L10N=True. You could revert to the old behavior with custom
widget templates that uses the localize template tag to turn off
localization.
django.template.backends.django.Template.render() prohibits non-dict context¶For compatibility with multiple template engines,
django.template.backends.django.Template.render() (returned from high-level
template loader APIs such as loader.get_template()) must receive a
dictionary of context rather than Context or RequestContext. If you
were passing either of the two classes, pass a dictionary instead – doing so
is backwards-compatible with older versions of Django.
To improve the speed of applying migrations, rendering of related models is
delayed until an operation that needs them (e.g. RunPython). If you have a
custom operation that works with model classes or model instances from the
from_state argument in database_forwards() or database_backwards(),
you must render model states using the clear_delayed_apps_cache() method as
described in writing your own migration operation.
The change to make QuerySet.iterator() use server-side cursors on
PostgreSQL prevents running Django with PgBouncer in transaction pooling mode.
To reallow that, use the DISABLE_SERVER_SIDE_CURSORS setting (added in Django 1.11.1) in
DATABASES.
See Transaction pooling and server-side cursors for more discussion.
If no items in the feed have a pubdate or updateddate attribute,
SyndicationFeed.latest_post_date() now returns
the current UTC date/time, instead of a datetime without any timezone
information.
CSRF failures are logged to the django.security.csrf logger instead of
django.request.
ALLOWED_HOSTS validation is no longer disabled when running tests.
If your application includes tests with custom host names, you must include
those host names in ALLOWED_HOSTS. See
Tests and multiple host names.
Using a foreign key’s id (e.g. 'field_id') in ModelAdmin.list_display
displays the related object’s ID. Remove the _id suffix if you want the
old behavior of the string representation of the object.
In model forms, CharField with null=True now
saves NULL for blank values instead of empty strings.
On Oracle, Model.validate_unique() no longer checks empty strings for
uniqueness as the database interprets the value as NULL.
If you subclass AbstractUser and override clean(), be sure it
calls super(). BaseUserManager.normalize_email() is called in a
new AbstractUser.clean() method so that normalization is applied in
cases like model form validation.
EmailField and URLField no longer accept the strip keyword
argument. Remove it because it doesn’t have an effect in older versions of
Django as these fields always strip whitespace.
The checked and selected attribute rendered by form widgets now uses
HTML5 boolean syntax rather than XHTML’s checked='checked' and
selected='selected'.
RelatedManager.add(),
remove(),
clear(), and
set() now
clear the prefetch_related() cache.
To prevent possible loss of saved settings,
setup_test_environment() now raises an exception if
called a second time before calling
teardown_test_environment().
The undocumented DateTimeAwareJSONEncoder alias for
DjangoJSONEncoder (renamed in Django
1.0) is removed.
The cached template loader
is now enabled if OPTIONS['loaders'] isn’t
specified and OPTIONS['debug'] is False
(the latter option defaults to the value of DEBUG). This could
be backwards-incompatible if you have some template tags that aren’t
thread safe.
The prompt for stale content type deletion no longer occurs after running the
migrate command. Use the new remove_stale_contenttypes command
instead.
The admin’s widget for IntegerField uses type="number" rather than
type="text".
Conditional HTTP headers are now parsed and compared according to the RFC 7232 Conditional Requests specification rather than the older RFC 2616.
patch_response_headers() no longer adds a
Last-Modified header. According to the RFC 7234#section-4.2.2, this
header is useless alongside other caching headers that provide an explicit
expiration time, e.g. Expires or Cache-Control.
UpdateCacheMiddleware and
add_never_cache_headers() call
patch_response_headers() and therefore are also affected by this change.
In the admin templates, <p class="help"> is replaced with a <div> tag
to allow including lists inside help text.
ConditionalGetMiddleware no longer sets the
Date header as Web servers set that header. It also no longer sets the
Content-Length header as this is now done by
CommonMiddleware.
If you have a middleware that modifies a response’s content and appears
before CommonMiddleware in the MIDDLEWARE or MIDDLEWARE_CLASSES
settings, you must reorder your middleware so that responses aren’t modified
after Content-Length is set, or have the response modifying middleware
reset the Content-Length header.
get_model() and
get_models() now raise
AppRegistryNotReady if they’re called before
models of all applications have been loaded. Previously they only required
the target application’s models to be loaded and thus could return models
without all their relations set up. If you need the old behavior of
get_model(), set the require_ready argument to False.
The unused BaseCommand.can_import_settings attribute is removed.
The undocumented django.utils.functional.lazy_property is removed.
For consistency with non-multipart requests, MultiPartParser.parse() now
leaves request.POST immutable. If you’re modifying that QueryDict,
you must now first copy it, e.g. request.POST.copy().
Support for cx_Oracle < 5.2 is removed.
Support for IPython < 1.0 is removed from the shell command.
The signature of private API Widget.build_attrs() changed from
extra_attrs=None, **kwargs to base_attrs, extra_attrs=None.
File-like objects (e.g., StringIO and BytesIO)
uploaded to an ImageField using the test client
now require a name attribute with a value that passes the
validate_image_file_extension validator.
See the note in Client.post().
FileField now moves rather than copies the file
it receives. With the default file upload settings, files larger than
FILE_UPLOAD_MAX_MEMORY_SIZE now have the same permissions as
temporary files (often 0o600) rather than the system’s standard umask
(often 0o6644). Set the FILE_UPLOAD_PERMISSIONS if you need
the same permission regardless of file size.
models.permalink() decorator¶Use django.urls.reverse() instead. For example:
from django.db import models
class MyModel(models.Model):
...
@models.permalink
def url(self):
return ('guitarist_detail', [self.slug])
becomes:
from django.db import models
from django.urls import reverse
class MyModel(models.Model):
...
def url(self):
return reverse('guitarist_detail', args=[self.slug])
contrib.auth’s login() and logout() function-based views are
deprecated in favor of new class-based views
LoginView and
LogoutView.extra_context parameter of
contrib.auth.views.logout_then_login() is deprecated.contrib.auth’s password_change(), password_change_done(),
password_reset(), password_reset_done(), password_reset_confirm(),
and password_reset_complete() function-based views are deprecated in favor
of new class-based views
PasswordChangeView,
PasswordChangeDoneView,
PasswordResetView,
PasswordResetDoneView,
PasswordResetConfirmView, and
PasswordResetCompleteView.django.test.runner.setup_databases() is moved to
django.test.utils.setup_databases(). The old location is deprecated.django.utils.translation.string_concat() is deprecated in
favor of django.utils.text.format_lazy(). string_concat(*strings)
can be replaced by format_lazy('{}' * len(strings), *strings).PyLibMCCache cache backend, passing pylibmc behavior settings
as top-level attributes of OPTIONS is deprecated. Set them under a
behaviors key within OPTIONS instead.host parameter of django.utils.http.is_safe_url() is deprecated
in favor of the new allowed_hosts parameter.{% include %} template tag is deprecated as the behavior is
often more confusing than helpful. In Django 2.1, the exception will be
raised.DatabaseIntrospection.get_indexes() is deprecated in favor of
DatabaseIntrospection.get_constraints().authenticate() now passes a request argument
to the authenticate() method of authentication backends. Support for
methods that don’t accept request as the first positional argument will
be removed in Django 2.1.USE_ETAGS setting is deprecated in favor of
ConditionalGetMiddleware which now adds the
ETag header to responses regardless of the setting. CommonMiddleware
and django.utils.cache.patch_response_headers() will no longer set ETags
when the deprecation ends.Model._meta.has_auto_field is deprecated in favor of checking if
Model._meta.auto_field is not None.iLmsu# in url() is deprecated.
The only group that’s useful is (?i) for case-insensitive URLs, however,
case-insensitive URLs aren’t a good practice because they create multiple
entries for search engines, for example. An alternative solution could be to
create a handler404 that looks for uppercase
characters in the URL and redirects to a lowercase equivalent.renderer argument is added to the Widget.render() method. Methods that don’t accept that argument
will work through a deprecation period.Jul 27, 2022