December 1, 2015
Welcome to Django 1.9!
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.8 or older versions. 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 Upgrading Django to a newer version guide if you’re updating an existing project.
Django 1.9 requires Python 2.7, 3.4, or 3.5. We highly recommend and only officially support the latest release of each series.
The Django 1.8 series is the last to support Python 3.2 and 3.3.
The new on_commit() hook allows performing actions
after a database transaction is successfully committed. This is useful for
tasks such as sending notification emails, creating queued tasks, or
invalidating caches.
This functionality from the django-transaction-hooks package has been integrated into Django.
Django now offers password validation to help prevent the usage of weak
passwords by users. The validation is integrated in the included password
change and reset forms and is simple to integrate in any other code.
Validation is performed by one or more validators, configured in the new
AUTH_PASSWORD_VALIDATORS setting.
Four validators are included in Django, which can enforce a minimum length, compare the password to the user’s attributes like their name, ensure passwords aren’t entirely numeric, or check against an included list of common passwords. You can combine multiple validators, and some validators have custom configuration options. For example, you can choose to provide a custom list of common passwords. Each validator provides a help text to explain its requirements to the user.
By default, no validation is performed and all passwords are accepted, so if
you don’t set AUTH_PASSWORD_VALIDATORS, you will not see any
change. In new projects created with the default startproject
template, a simple set of validators is enabled. To enable basic validation in
the included auth forms for your project, you could set, for example:
AUTH_PASSWORD_VALIDATORS = [
{
'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
},
{
'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
},
{
'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
},
{
'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
},
]
See Password validation for more details.
Django now ships with the mixins
AccessMixin,
LoginRequiredMixin,
PermissionRequiredMixin, and
UserPassesTestMixin to provide the
functionality of the django.contrib.auth.decorators for class-based views.
These mixins have been taken from, or are at least inspired by, the
django-braces project.
There are a few differences between Django’s and django-braces’
implementation, though:
raise_exception attribute
can only be True or False. Custom exceptions or callables are not
supported.handle_no_permission()
method does not take a request argument. The current request is available
in self.request.test_func() of UserPassesTestMixin
does not take a user argument. The current user is available in
self.request.user.permission_required
attribute supports a string (defining one permission) or a list/tuple of
strings (defining multiple permissions) that need to be fulfilled to grant
access.permission_denied_message
attribute allows passing a message to the PermissionDenied exception.contrib.admin¶The admin sports a modern, flat design with new SVG icons which look perfect on HiDPI screens. It still provides a fully-functional experience to YUI’s A-grade browsers. Older browser may experience varying levels of graceful degradation.
The test command now supports a --parallel option to run a project’s tests in multiple processes in parallel.
Each process gets its own database. You must ensure that different test cases don’t access the same resources. For instance, test cases that touch the filesystem should create a temporary directory for their own use.
This option is enabled by default for Django’s own test suite provided:
django.contrib.admin¶model_admin or admin_site attributes./admin/<app>/<model>/<pk>/ by default and is now at
/admin/<app>/<model>/<pk>/change/). This should not affect your
application unless you have hardcoded admin URLs. In that case, replace those
links by reversing admin URLs instead. Note that
the old URL still redirects to the new one for backwards compatibility, but
it may be removed in a future version.ModelAdmin.get_list_select_related() was added to allow
changing the select_related() values used in the admin’s changelist query
based on the request.available_apps context variable, which lists the available
applications for the current user, has been added to the
AdminSite.each_context()
method.AdminSite.empty_value_display and
ModelAdmin.empty_value_display were added to override
the display of empty values in admin change list. You can also customize the
value for each field.django.contrib.admindocs¶admindocs now also describes methods that take
arguments, rather than ignoring them.django.contrib.auth¶django.contrib.auth.hashers.PBKDF2PasswordHasher to change the
default value.BCryptSHA256PasswordHasher will now update passwords if its
rounds attribute is changed.AbstractBaseUser and BaseUserManager were moved to a new
django.contrib.auth.base_user module so that they can be imported without
including django.contrib.auth in INSTALLED_APPS (doing so
raised a deprecation warning in older versions and is no longer supported in
Django 1.9).permission_required() accepts all
kinds of iterables, not only list and tuples.PersistentRemoteUserMiddleware
makes it possible to use REMOTE_USER for setups where the header is only
populated on login pages instead of every request in the session.django.contrib.auth.views.password_reset() view accepts an
extra_email_context parameter.django.contrib.contenttypes¶order_with_respect_to with a
GenericForeignKey.django.contrib.gis¶GeoQuerySet methods have been deprecated and replaced by
equivalent database functions. As soon
as the legacy methods have been replaced in your code, you should even be
able to remove the special GeoManager from your GIS-enabled classes.RasterField
allows storing GDALRaster objects.
It supports automatic spatial index creation and reprojection when saving a
model. It does not yet support spatial querying.GDALRaster.warp()
method allows warping a raster by specifying target raster properties such as
origin, width, height, or pixel size (amongst others).GDALRaster.transform() method allows transforming a
raster into a different spatial reference system by specifying a target
srid.GeoIP2 class allows using
MaxMind’s GeoLite2 databases which includes support for IPv6 addresses.django.contrib.postgres¶rangefield.contained_by lookup for some built
in fields which correspond to the range fields.JSONField.TransactionNow database
function.django.contrib.sessions¶SessionStore classes for the db and
cached_db backends are refactored to allow a custom database session
backend to build upon them. See
Extending database-backed session engines for more details.django.contrib.sites¶get_current_site() now handles the case
where request.get_host() returns domain:port, e.g.
example.com:80. If the lookup fails because the host does not match a
record in the database and the host has a port, the port is stripped and the
lookup is retried with the domain part only.django.contrib.syndication¶django.core.cache.backends.base.BaseCache now has a get_or_set()
method.django.views.decorators.cache.never_cache() now sends more persuasive
headers (added no-cache, no-store, must-revalidate to Cache-Control)
to better prevent caching. This was also added in Django 1.8.8.CSRF_HEADER_NAME.CSRF_COOKIE_DOMAIN setting if set. See How it works for
details.CSRF_TRUSTED_ORIGINS setting provides a way to allow
cross-origin unsafe requests (e.g. POST) over HTTPS.django.db.backends.postgresql_psycopg2) is also
available as django.db.backends.postgresql. The old name will continue to
be available for backwards compatibility.Storage.get_valid_name() is now called when
the upload_to is a callable.File now has the seekable() method when using
Python 3.ModelForm accepts the new Meta option
field_classes to customize the type of the fields. See
Overriding the default fields for details.field_order attribute, the field_order
constructor argument , or the order_fields() method.SlugField now accepts an
allow_unicode argument to allow Unicode
characters in slugs.CharField now accepts a
strip argument to strip input data of leading
and trailing whitespace. As this defaults to True this is different
behavior from previous releases.disabled argument,
allowing the field widget to be displayed disabled by browsers.get_bound_field() method.as_view() now have view_class
and view_initkwargs attributes.method_decorator() can now be used with a list
or tuple of decorators. It can also be used to decorate classes instead
of methods.django.views.i18n.set_language() view now properly redirects to
translated URLs, when available.django.views.i18n.javascript_catalog() view now works correctly
if used multiple times with different configurations on the same page.django.utils.timezone.make_aware() function gained an is_dst
argument to help resolve ambiguous times during DST transitions.be@latin).django.views.i18n.json_catalog() view to help build a custom
client-side i18n library upon Django translations. It returns a JSON object
containing a translations catalog, formatting settings, and a plural rule.name_translated attribute to the object returned by the
get_language_info template tag. Also added a corresponding template
filter: language_name_translated.compilemessages from the root directory of your
project and it will find all the app message files that were created by
makemessages.makemessages now calls xgettext once per locale directory rather
than once per translatable file. This speeds up localization builds.blocktrans supports assigning its output to a variable using
asvar.sendtestemail command lets you send a test email to
easily confirm that email sending through Django is working.sqlmigrate, the SQL code generated for each migration operation is
preceded by the operation’s description.dumpdata command output is now deterministically ordered.
Moreover, when the --output option is specified, it also shows a progress
bar in the terminal.createcachetable command now has a --dry-run flag to
print out the SQL rather than execute it.startapp command creates an apps.py file. Since it doesn’t
use default_app_config (a discouraged API), you must specify the app config’s path,
e.g. 'polls.apps.PollsConfig', in INSTALLED_APPS for it to be
used (instead of just 'polls').dbshell command can connect
to the database using the password from your settings file (instead of
requiring it to be manually entered).django package may be run as a script, i.e. python -m django,
which will behave the same as django-admin.--noinput option now also take
--no-input as an alias for that option.Initial migrations are now marked with an initial = True class attribute which allows
migrate --fake-initial to more easily detect initial migrations.
Added support for serialization of functools.partial and LazyObject
instances.
When supplying None as a value in MIGRATION_MODULES, Django
will consider the app an app without migrations.
When applying migrations, the “Rendering model states” step that’s displayed when running migrate with verbosity 2 or higher now computes only the states for the migrations that have already been applied. The model states for migrations being applied are generated on demand, drastically reducing the amount of required memory.
However, this improvement is not available when unapplying migrations and therefore still requires the precomputation and storage of the intermediate migration states.
This improvement also requires that Django no longer supports mixed migration plans. Mixed plans consist of a list of migrations where some are being applied and others are being unapplied. This was never officially supported and never had a public API that supports this behavior.
The squashmigrations command now supports specifying the starting
migration from which migrations will be squashed.
QuerySet.bulk_create()
now works on proxy models.TIME_ZONE
option for interacting with databases that store datetimes in local time and
don’t support time zones when USE_TZ is True.RelatedManager.set() method to the related
managers created by ForeignKey, GenericForeignKey, and
ManyToManyField.add() method on
a reverse foreign key now has a bulk parameter to allow executing one
query regardless of the number of objects being added rather than one query
per object.keep_parents parameter to Model.delete() to allow deleting only a child’s data in a
model that uses multi-table inheritance.Model.delete()
and QuerySet.delete() return
the number of objects deleted.Meta.ordering and
order_with_respect_to on the same model.Date and time lookups can be chained with other lookups
(such as exact, gt, lt, etc.). For example:
Entry.objects.filter(pub_date__month__gt=6).TimeField for all database backends. Support for
backends other than SQLite was added but undocumented in Django 1.7.output_field parameter of the
Avg aggregate in order to aggregate over
non-numeric columns, such as DurationField.date lookup to DateTimeField
to allow querying the field by only the date portion.Greatest and
Least database functions.Now database function, which
returns the current date and time.Transform is now a subclass of
Func() which allows Transforms to be used on
the right hand side of an expression, just like regular Funcs. This
allows registering some database functions like
Length,
Lower, and
Upper as transforms.SlugField now accepts an
allow_unicode argument to allow Unicode
characters in slugs.QuerySet.distinct().connection.queries shows queries with substituted parameters on SQLite.save(), create(), and
bulk_create().HttpResponse.reason_phrase is explicitly set, it now is
determined by the current value of HttpResponse.status_code. Modifying the value of
status_code outside of the constructor will also modify the value of
reason_phrase.TemplateResponse, commonly used with
class-based views.render() method are now passed to the
process_exception() method of each middleware.HttpRequest.urlconf to None to revert any changes made
by previous middleware and return to using the ROOT_URLCONF.DISALLOWED_USER_AGENTS check in
CommonMiddleware now raises a
PermissionDenied exception as opposed to
returning an HttpResponseForbidden so that
handler403 is invoked.HttpRequest.get_port() to
fetch the originating port of the request.json_dumps_params parameter to
JsonResponse to allow passing keyword arguments to the
json.dumps() call used to generate the response.BrokenLinkEmailsMiddleware now
ignores 404s when the referer is equal to the requested URL. To circumvent
the empty referer check already implemented, some Web bots set the referer to
the requested URL.simple_tag()
helper can now store results in a template variable by using the as
argument.Context.setdefault()
method.DEBUG level message for missing context variables.WARNING level message for uncaught exceptions raised
during the rendering of an {% include %} when debug mode is off
(helpful since {% include %} silences the exception and returns an
empty string).firstof template tag supports storing the output in a variable
using ‘as’.Context.update() can now be used as
a context manager.DjangoTemplates backend gained
the ability to register libraries and builtins explicitly through the
template OPTIONS.timesince and timeuntil filters were improved to deal with leap
years when given large time spans.include tag now caches parsed templates objects during template
rendering, speeding up reuse in places such as for loops.json() method to test client
responses to give access to the response body as JSON.force_login() method to the test
client. Use this method to simulate the effect of a user logging into the
site while skipping the authentication and verification steps of
login().app_name attribute
on the included module or object. It can also be set by passing a 2-tuple
of (<list of patterns>, <application namespace>) as the first argument to
include().django.core.validators.int_list_validator() to generate
validators of strings containing integers separated with a custom character.EmailValidator now limits the length of
domain name labels to 63 characters per RFC 1034.validate_unicode_slug() to validate slugs
that may contain Unicode characters.Warning
In addition to the changes outlined in this section, be sure to review the Features removed in 1.9 for the features that have reached the end of their deprecation cycle and therefore been removed. If you haven’t updated your code within the deprecation timeline for a given feature, its removal may appear as a backwards incompatible change.
A couple of new tests rely on the ability of the backend to introspect column
defaults (returning the result as Field.default). You can set the
can_introspect_default database feature to False if your backend
doesn’t implement this. You may want to review the implementation on the
backends that Django includes for reference (#24245).
Registering a global adapter or converter at the level of the DB-API module
to handle time zone information of datetime values passed
as query parameters or returned as query results on databases that don’t
support time zones is discouraged. It can conflict with other libraries.
The recommended way to add a time zone to datetime values
fetched from the database is to register a converter for DateTimeField
in DatabaseOperations.get_db_converters().
The needs_datetime_string_cast database feature was removed. Database
backends that set it must register a converter instead, as explained above.
The DatabaseOperations.value_to_db_<type>() methods were renamed to
adapt_<type>field_value() to mirror the convert_<type>field_value()
methods.
To use the new date lookup, third-party database backends may need to
implement the DatabaseOperations.datetime_cast_date_sql() method.
The DatabaseOperations.time_extract_sql() method was added. It calls the
existing date_extract_sql() method. This method is overridden by the
SQLite backend to add time lookups (hour, minute, second) to
TimeField, and may be needed by third-party
database backends.
The DatabaseOperations.datetime_cast_sql() method (not to be confused
with DatabaseOperations.datetime_cast_date_sql() mentioned above)
has been removed. This method served to format dates on Oracle long
before 1.0, but hasn’t been overridden by any core backend in years
and hasn’t been called anywhere in Django’s code or tests.
In order to support test parallelization, you must implement the
DatabaseCreation._clone_test_db() method and set
DatabaseFeatures.can_clone_databases = True. You may have to adjust
DatabaseCreation.get_test_db_clone_settings().
The default settings in django.conf.global_settings were a combination of
lists and tuples. All settings that were formerly tuples are now lists.
is_usable attribute on template loaders is removed¶Django template loaders previously required an is_usable attribute to be
defined. If a loader was configured in the template settings and this attribute
was False, the loader would be silently ignored. In practice, this was only
used by the egg loader to detect if setuptools was installed. The is_usable
attribute is now removed and the egg loader instead fails at runtime if
setuptools is not installed.
When using the filesystem.Loader
or app_directories.Loader
template loaders, earlier versions of Django raised a
TemplateDoesNotExist error if a template source existed
but was unreadable. This could happen under many circumstances, such as if
Django didn’t have permissions to open the file, or if the template source was
a directory. Now, Django only silences the exception if the template source
does not exist. All other situations result in the original IOError being
raised.
Relative redirects are no longer converted to absolute URIs. RFC 2616
required the Location header in redirect responses to be an absolute URI,
but it has been superseded by RFC 7231 which allows relative URIs in
Location, recognizing the actual practice of user agents, almost all of
which support them.
Consequently, the expected URLs passed to assertRedirects should generally
no longer include the scheme and domain part of the URLs. For example,
self.assertRedirects(response, 'http://testserver/some-url/') should be
replaced by self.assertRedirects(response, '/some-url/') (unless the
redirection specifically contained an absolute URL, of course).
In the rare case that you need the old behavior (discovered with an ancient
version of Apache with mod_scgi that interprets a relative redirect as an
“internal redirect”), you can restore it by writing a custom middleware:
class LocationHeaderFix(object):
def process_response(self, request, response):
if 'Location' in response:
response['Location'] = request.build_absolute_uri(response['Location'])
return response
Upstream support for PostgreSQL 9.0 ended in September 2015. As a consequence, Django 1.9 sets 9.1 as the minimum PostgreSQL version it officially supports.
Upstream support for Oracle 11.1 ended in August 2015. As a consequence, Django 1.9 sets 11.2 as the minimum Oracle version it officially supports.
LoaderOrigin and StringOrigin are removed¶In previous versions of Django, when a template engine was initialized with
debug as True, an instance of django.template.loader.LoaderOrigin or
django.template.base.StringOrigin was set as the origin attribute on the
template object. These classes have been combined into
Origin and is now always set regardless of the
engine debug setting. For a minimal level of backwards compatibility, the old
class names will be kept as aliases to the new Origin class until
Django 2.0.
To make it easier to write custom logging configurations, Django’s default
logging configuration no longer defines django.request and
django.security loggers. Instead, it defines a single django logger,
filtered at the INFO level, with two handlers:
console: filtered at the INFO level and only active if DEBUG=True.mail_admins: filtered at the ERROR level and only active if
DEBUG=False.If you aren’t overriding Django’s default logging, you should see minimal
changes in behavior, but you might see some new logging to the runserver
console, for example.
If you are overriding Django’s default logging, you should check to see how your configuration merges with the new defaults.
HttpRequest details in error reporting¶It was redundant to display the full details of the
HttpRequest each time it appeared as a stack frame
variable in the HTML version of the debug page and error email. Thus, the HTTP
request will now display the same standard representation as other variables
(repr(request)). As a result, the
ExceptionReporterFilter.get_request_repr() method and the undocumented
django.http.build_request_repr() function were removed.
The contents of the text version of the email were modified to provide a
traceback of the same structure as in the case of AJAX requests. The traceback
details are rendered by the ExceptionReporter.get_traceback_text() method.
Django no longer registers global adapters and converters for managing time
zone information on datetime values sent to the database as
query parameters or read from the database in query results. This change
affects projects that meet all the following conditions:
USE_TZ setting is True.connection.features.supports_timezones.cursor.execute(sql, params).If you’re passing aware datetime parameters to such
queries, you should turn them into naive datetimes in UTC:
from django.utils import timezone
param = timezone.make_naive(param, timezone.utc)
If you fail to do so, the conversion will be performed as in earlier versions (with a deprecation warning) up until Django 1.11. Django 2.0 won’t perform any conversion, which may result in data corruption.
If you’re reading datetime values from the results, they
will be naive instead of aware. You can compensate as follows:
from django.utils import timezone
value = timezone.make_aware(value, timezone.utc)
You don’t need any of this if you’re querying the database through the ORM,
even if you’re using raw()
queries. The ORM takes care of managing time zone information.
The DjangoTemplates backend now
performs discovery on installed template tag modules when instantiated. This
update enables libraries to be provided explicitly via the 'libraries'
key of OPTIONS when defining a
DjangoTemplates backend. Import
or syntax errors in template tag modules now fail early at instantiation time
rather than when a template with a {% load %} tag is first
compiled.
django.template.base.add_to_builtins() is removed¶Although it was a private API, projects commonly used add_to_builtins() to
make template tags and filters available without using the
{% load %} tag. This API has been formalized. Projects should now
define built-in libraries via the 'builtins' key of OPTIONS when defining a
DjangoTemplates backend.
simple_tag now wraps tag output in conditional_escape¶In general, template tags do not autoescape their contents, and this behavior is
documented. For tags like
inclusion_tag, this is not a problem because
the included template will perform autoescaping. For assignment_tag(),
the output will be escaped when it is used as a variable in the template.
For the intended use cases of simple_tag,
however, it is very easy to end up with incorrect HTML and possibly an XSS
exploit. For example:
@register.simple_tag(takes_context=True)
def greeting(context):
return "Hello {0}!".format(context['request'].user.first_name)
In older versions of Django, this will be an XSS issue because
user.first_name is not escaped.
In Django 1.9, this is fixed: if the template context has autoescape=True
set (the default), then simple_tag will wrap the output of the tag function
with conditional_escape().
To fix your simple_tags, it is best to apply the following practices:
format_html().simple_tag needs escaping, use
escape() or
conditional_escape().mark_safe().Tags that follow these rules will be correct and safe whether they are run on Django 1.9+ or earlier.
Paginator.page_range¶Paginator.page_range is
now an iterator instead of a list.
In versions of Django previous to 1.8, Paginator.page_range returned a
list in Python 2 and a range in Python 3. Django 1.8 consistently
returned a list, but an iterator is more efficient.
Existing code that depends on list specific features, such as indexing,
can be ported by converting the iterator into a list using list().
QuerySet __in lookup removed¶In earlier versions, queries such as:
Model.objects.filter(related_id=RelatedModel.objects.all())
would implicitly convert to:
Model.objects.filter(related_id__in=RelatedModel.objects.all())
resulting in SQL like "related_id IN (SELECT id FROM ...)".
This implicit __in no longer happens so the “IN” SQL is now “=”, and if the
subquery returns multiple results, at least some databases will throw an error.
contrib.admin browser support¶The admin no longer supports Internet Explorer 8 and below, as these browsers have reached end-of-life.
CSS and images to support Internet Explorer 6 and 7 have been removed. PNG and GIF icons have been replaced with SVG icons, which are not supported by Internet Explorer 8 and earlier.
The jQuery library embedded in the admin has been upgraded from version 1.11.2 to 2.1.4. jQuery 2.x has the same API as jQuery 1.x, but does not support Internet Explorer 6, 7, or 8, allowing for better performance and a smaller file size. If you need to support IE8 and must also use the latest version of Django, you can override the admin’s copy of jQuery with your own by creating a Django application with this structure:
app/static/admin/js/vendor/
jquery.js
jquery.min.js
SyntaxError when installing Django setuptools 5.5.x¶When installing Django 1.9 or 1.9.1 with setuptools 5.5.x, you’ll see:
Compiling django/conf/app_template/apps.py ...
File "django/conf/app_template/apps.py", line 4
class {{ camel_case_app_name }}Config(AppConfig):
^
SyntaxError: invalid syntax
Compiling django/conf/app_template/models.py ...
File "django/conf/app_template/models.py", line 1
{{ unicode_literals }}from django.db import models
^
SyntaxError: invalid syntax
It’s safe to ignore these errors (Django will still install just fine), but you
can avoid them by upgrading setuptools to a more recent version. If you’re
using pip, you can upgrade pip using pip install -U pip which will also
upgrade setuptools. This is resolved in later versions of Django as described
in the Django 1.9.2 release notes.
contrib.admin have been moved into a
vendor/jquery subdirectory.list_display
cells has changed from (None) (or its translated equivalent) to - (a
dash).django.http.responses.REASON_PHRASES and
django.core.handlers.wsgi.STATUS_CODE_TEXT have been removed. Use
Python’s stdlib instead: http.client.responses for Python 3 and
httplib.responses for Python 2.ValuesQuerySet and ValuesListQuerySet have been removed.admin/base.html template no longer sets
window.__admin_media_prefix__ or window.__admin_utc_offset__. Image
references in JavaScript that used that value to construct absolute URLs have
been moved to CSS for easier customization. The UTC offset is stored on a
data attribute of the <body> tag.CommaSeparatedIntegerField validation has been refined to forbid values
like ',', ',1', and '1,,2'.ProcessFormView.get() method to the new
FormMixin.get_context_data() method. This may be
backwards incompatible if you have overridden the get_context_data()
method without calling super().django.contrib.sites.models.Site.domain field was changed to be
unique.SimpleTestCase tests anymore. You
can disable this behavior by setting the
allow_database_queries class attribute
to True on your test class.ResolverMatch.app_name was changed to contain the full namespace path in
the case of nested namespaces. For consistency with
ResolverMatch.namespace, the empty value is now an empty string instead
of None.django.utils.functional.total_ordering() has been
removed. It contained a workaround for a functools.total_ordering() bug
in Python versions older than 2.7.3.dumpdata or the syndication
framework) used to output any characters it received. Now if the content to
be serialized contains any control characters not allowed in the XML 1.0
standard, the serialization will fail with a ValueError.CharField now strips input of leading and trailing
whitespace by default. This can be disabled by setting the new
strip argument to False."%%", may have a new msgid after makemessages is run
(most likely the translation will be marked fuzzy). The new msgid will be
marked "#, python-format".request.current_app
nor Context.current_app are set, the
url template tag will now use the namespace of the current request.
Set request.current_app to None if you don’t want to use a namespace
hint.SILENCED_SYSTEM_CHECKS setting now silences messages of all
levels. Previously, messages of ERROR level or higher were printed to the
console.FlatPage.enable_comments field is removed from the FlatPageAdmin
as it’s unused by the application. If your project or a third-party app makes
use of it, create a custom ModelAdmin to add it back.setup_databases() and the first
argument of teardown_databases()
changed. They used to be (old_names, mirrors) tuples. Now they’re just
the first item, old_names.LiveServerTestCase attempts to find an
available port in the 8081-8179 range instead of just trying port 8081.ModelAdmin now check
instances rather than classes.django.db.models.fields.related (private API) are moved from the
related module to related_descriptors and renamed as follows:ReverseSingleRelatedObjectDescriptor is ForwardManyToOneDescriptorSingleRelatedObjectDescriptor is ReverseOneToOneDescriptorForeignRelatedObjectsDescriptor is ReverseManyToOneDescriptorManyRelatedObjectsDescriptor is ManyToManyDescriptorhandler404 view, it must
return a response with an HTTP 404 status code. Use
HttpResponseNotFound or pass status=404 to the
HttpResponse. Otherwise, APPEND_SLASH won’t
work correctly with DEBUG=False.assignment_tag()¶Django 1.4 added the assignment_tag helper to ease the creation of
template tags that store results in a template variable. The
simple_tag() helper has gained this same
ability, making the assignment_tag obsolete. Tags that use
assignment_tag should be updated to use simple_tag.
{% cycle %} syntax with comma-separated arguments¶The cycle tag supports an inferior old syntax from previous Django
versions:
{% cycle row1,row2,row3 %}
Its parsing caused bugs with the current syntax, so support for the old syntax will be removed in Django 1.10 following an accelerated deprecation.
ForeignKey and OneToOneField on_delete argument¶In order to increase awareness about cascading model deletion, the
on_delete argument of ForeignKey and OneToOneField will be required
in Django 2.0.
Update models and existing migrations to explicitly set the argument. Since the
default is models.CASCADE, add on_delete=models.CASCADE to all
ForeignKey and OneToOneFields that don’t use a different option. You
can also pass it as the second positional argument if you don’t care about
compatibility with older versions of Django.
Field.rel changes¶Field.rel and its methods and attributes have changed to match the related
fields API. The Field.rel attribute is renamed to remote_field and many
of its methods and attributes are either changed or renamed.
The aim of these changes is to provide a documented API for relation fields.
GeoManager and GeoQuerySet custom methods¶All custom GeoQuerySet methods (area(), distance(), gml(), …)
have been replaced by equivalent geographic expressions in annotations (see in
new features). Hence the need to set a custom GeoManager to GIS-enabled
models is now obsolete. As soon as your code doesn’t call any of the deprecated
methods, you can simply remove the objects = GeoManager() lines from your
models.
Django template loaders have been updated to allow recursive template
extending. This change necessitated a new template loader API. The old
load_template() and load_template_sources() methods are now deprecated.
Details about the new API can be found in the template loader
documentation.
app_name to include()¶The instance namespace part of passing a tuple as an argument to include()
has been replaced by passing the namespace argument to include(). For
example:
polls_patterns = [
url(...),
]
urlpatterns = [
url(r'^polls/', include((polls_patterns, 'polls', 'author-polls'))),
]
becomes:
polls_patterns = ([
url(...),
], 'polls') # 'polls' is the app_name
urlpatterns = [
url(r'^polls/', include(polls_patterns, namespace='author-polls')),
]
The app_name argument to include() has been replaced by passing a
2-tuple (as above), or passing an object or module with an app_name
attribute (as below). If the app_name is set in this new way, the
namespace argument is no longer required. It will default to the value of
app_name. For example, the URL patterns in the tutorial are changed from:
urlpatterns = [
url(r'^polls/', include('polls.urls', namespace="polls")),
...
]
to:
urlpatterns = [
url(r'^polls/', include('polls.urls')), # 'namespace="polls"' removed
...
]
app_name = 'polls' # added
urlpatterns = [...]
This change also means that the old way of including an AdminSite instance
is deprecated. Instead, pass admin.site.urls directly to
url():
from django.conf.urls import url
from django.contrib import admin
urlpatterns = [
url(r'^admin/', admin.site.urls),
]
In the past, an instance namespace without an application namespace would serve the same purpose as the application namespace, but it was impossible to reverse the patterns if there was an application namespace with the same name. Includes that specify an instance namespace require that the included URLconf sets an application namespace.
current_app parameter to contrib.auth views¶All views in django.contrib.auth.views have the following structure:
def view(request, ..., current_app=None, ...):
...
if current_app is not None:
request.current_app = current_app
return TemplateResponse(request, template_name, context)
As of Django 1.8, current_app is set on the request object. For
consistency, these views will require the caller to set current_app on the
request instead of passing it in a separate argument.
django.contrib.gis.geoip¶The django.contrib.gis.geoip2 module supersedes
django.contrib.gis.geoip. The new module provides a similar API except that
it doesn’t provide the legacy GeoIP-Python API compatibility methods.
weak argument to django.dispatch.signals.Signal.disconnect() has
been deprecated as it has no effect.check_aggregate_support() method of
django.db.backends.base.BaseDatabaseOperations has been deprecated and
will be removed in Django 2.0. The more general check_expression_support()
should be used instead.django.forms.extras is deprecated. You can find
SelectDateWidget in django.forms.widgets
(or simply django.forms) instead.django.db.models.fields.add_lazy_relation() is deprecated.django.contrib.auth.tests.utils.skipIfCustomUser() decorator is
deprecated. With the test discovery changes in Django 1.6, the tests for
django.contrib apps are no longer run as part of the user’s project.
Therefore, the @skipIfCustomUser decorator is no longer needed to
decorate tests in django.contrib.auth.exception positional parameter.django.utils.feedgenerator.Atom1Feed.mime_type and
django.utils.feedgenerator.RssFeed.mime_type attributes are deprecated in
favor of content_type.Signer now issues a warning if an invalid
separator is used. This will become an exception in Django 1.10.django.db.models.Field._get_val_from_obj() is deprecated in favor of
Field.value_from_object().django.template.loaders.eggs.Loader is deprecated as distributing
applications as eggs is not recommended.callable_obj keyword argument to
SimpleTestCase.assertRaisesMessage() is deprecated. Pass the callable as
a positional argument instead.allow_tags attribute on methods of ModelAdmin has been
deprecated. Use format_html(),
format_html_join(), or
mark_safe() when constructing the method’s
return value instead.enclosure keyword argument to SyndicationFeed.add_item() is
deprecated. Use the new enclosures argument which accepts a list of
Enclosure objects instead of a single one.django.template.loader.LoaderOrigin and
django.template.base.StringOrigin aliases for
django.template.base.Origin are deprecated.These features have reached the end of their deprecation cycle and are removed in Django 1.9. See Features deprecated in 1.7 for details, including how to remove usage of these features.
django.utils.dictconfig is removed.django.utils.importlib is removed.django.utils.tzinfo is removed.django.utils.unittest is removed.syncdb command is removed.django.db.models.signals.pre_syncdb and
django.db.models.signals.post_syncdb is removed.allow_syncdb on database routers is removed.migrate --run-syncdb
option.sql, sqlall,
sqlclear, sqldropindexes, and sqlindexes, are removed.initial_data fixtures and initial SQL
data is removed.app_label. Furthermore, it isn’t
possible to import them before their application is loaded. In particular, it
isn’t possible to import models inside the root package of an application.IPAddressField is removed. A stub field remains for
compatibility with historical migrations.AppCommand.handle_app() is no longer supported.RequestSite and get_current_site() are no longer importable from
django.contrib.sites.models.runfcgi management command is removed.django.utils.datastructures.SortedDict is removed.ModelAdmin.declared_fieldsets is removed.util modules that provided backwards compatibility are removed:django.contrib.admin.utildjango.contrib.gis.db.backends.utildjango.db.backends.utildjango.forms.utilModelAdmin.get_formsets is removed.BaseMemcachedCache._get_memcache_timeout() method to
get_backend_timeout() is removed.--natural and -n options for dumpdata are removed.use_natural_keys argument for serializers.serialize() is removed.django.forms.forms.get_declared_fields() is removed.SplitDateTimeWidget with DateTimeField is
removed.WSGIRequest.REQUEST property is removed.django.utils.datastructures.MergeDict is removed.zh-cn and zh-tw language codes are removed.django.utils.functional.memoize() is removed.django.core.cache.get_cache is removed.django.db.models.loading is removed.BaseCommand.requires_model_validation is removed in favor of
requires_system_checks. Admin validators is replaced by admin checks.ModelAdmin.validator_class and default_validator_class attributes
are removed.ModelAdmin.validate() is removed.django.db.backends.DatabaseValidation.validate_field is removed in
favor of the check_field method.validate management command is removed.django.utils.module_loading.import_by_path is removed in favor of
django.utils.module_loading.import_string.ssi and url template tags are removed from the future template
tag library.django.utils.text.javascript_quote() is removed.TEST_, are no longer supported.ModelChoiceField and
ModelMultipleChoiceField is removed.RedirectView.permanent
attribute has changed from True to False.django.contrib.sitemaps.FlatPageSitemap is removed in favor of
django.contrib.flatpages.sitemaps.FlatPageSitemap.django.test.utils.TestTemplateLoader is removed.django.contrib.contenttypes.generic module is removed.Oct 31, 2018