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 defaultstartproject
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
, andUserPassesTestMixin
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.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 specialGeoManager
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 worksfor 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 asdjango.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, thefield_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 Transform
s to be used on the right hand side of an expression, just like regular Func
s. This allows registering some database functions like Length
, Lower
, andUpper
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()
, andbulk_create()
.HttpResponse.reason_phrase
is explicitly set, it now is determined by the current value ofHttpResponse.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 thejson.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 theas
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 toinclude()
.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 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 asField.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 ofdatetime
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 toadapt_<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 theDatabaseOperations.datetime_cast_date_sql()
method.
The DatabaseOperations.time_extract_sql()
method was added. It calls the existingdate_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 withDatabaseOperations.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 adjustDatabaseCreation.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.
Direct assignment of related objects in the ORM used to perform a clear()
followed by a call to add()
. This caused needlessly large data changes and prevented using the m2m_changed
signal to track individual changes in many-to-many relations.
Direct assignment now relies on the the new set()
method on related managers which by default only processes changes between the existing related set and the one that’s newly assigned. The previous behavior can be restored by replacing direct assignment by a call to set()
with the keyword argument clear=True
.
ModelForm
, and therefore ModelAdmin
, internally rely on direct assignment for many-to-many relations and as a consequence now use the new behavior.
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.
add()
method of related managers¶To improve performance, the add()
methods of the related managers created by ForeignKey
andGenericForeignKey
changed from a series of Model.save()
calls to a single QuerySet.update()
call. The change means that pre_save
and post_save
signals aren’t sent anymore. You can use the bulk=False
keyword argument to revert to the previous behavior.
LoaderOrigin
and StringOrigin
are removed¶In previous versions of Django, when a template engine was initialized with debug as True
, an instance ofdjango.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:
INFO
level and only active if DEBUG=True
.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, theExceptionReporterFilter.get_request_repr()
method and the undocumenteddjango.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 theExceptionReporter.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 aDjangoTemplates
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 likeinclusion_tag
, this is not a problem because the included template will perform autoescaping. Forassignment_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_tag
s, 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.responsesfor Python 2.ValuesQuerySet
and ValuesListQuerySet
have been removed.admin/base.html
template no longer sets window.__admin_media_prefix__
orwindow.__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 newFormMixin.get_context_data()
method. This may be backwards incompatible if you have overridden theget_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 newmsgid 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 ForwardManyToOneDescriptor
SingleRelatedObjectDescriptor
is ReverseOneToOneDescriptor
ForeignRelatedObjectsDescriptor
is ReverseManyToOneDescriptor
ManyRelatedObjectsDescriptor
is ManyToManyDescriptor
handler404
view, it must return a response with an HTTP 404 status code. UseHttpResponseNotFound
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
andOneToOneField
will be required in Django 2.0.
Update models and existing migrations to explicitly set the argument. Since the default is models.CASCADE
, addon_delete=models.CASCADE
to all ForeignKey
and OneToOneField
s 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 thenamespace
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, passadmin.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 indjango.contrib.auth
.exception
positional parameter.django.utils.feedgenerator.Atom1Feed.mime_type
anddjango.utils.feedgenerator.RssFeed.mime_type
attributes are deprecated in favor ofcontent_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 ofField.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 newenclosures
argument which accepts a list of Enclosure
objects instead of a single one.django.template.loader.LoaderOrigin
and django.template.base.StringOrigin
aliases fordjango.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.util
django.contrib.gis.db.backends.util
django.db.backends.util
django.forms.util
ModelAdmin.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 ofdjango.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 ofdjango.contrib.flatpages.sitemaps.FlatPageSitemap
.django.test.utils.TestTemplateLoader
is removed.django.contrib.contenttypes.generic
module is removed.