- Language: en
Django 1.8 release notes¶
April 1, 2015
Welcome to Django 1.8!
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.7 or older versions. We’ve also begun the deprecation process for some features, and some features have reached the end of their deprecation process and have been removed.
See the How to upgrade Django to a newer version guide if you’re updating an existing project.
Django 1.8 has been designated as Django’s second long-term support release. It will receive security updates for at least three years after its release. Support for the previous LTS, Django 1.4, will end 6 months from the release date of Django 1.8.
Python compatibility¶
Django 1.8 requires Python 2.7, 3.2, 3.3, 3.4, or 3.5. We highly recommend and only officially support the latest release of each series.
Django 1.8 is the first release to support Python 3.5.
Due to the end of upstream support for Python 3.2 in February 2016, we won’t test Django 1.8.x on Python 3.2 after the end of 2016.
What’s new in Django 1.8¶
Model._meta
API¶
Django now has a formalized API for Model._meta, providing an officially supported way to retrieve fields and filter fields based on their attributes.
The Model._meta
object has been part of Django since the days of pre-0.96
“Magic Removal” – it just wasn’t an official, stable API. In recognition of
this, we’ve endeavored to maintain backwards-compatibility with the old
API endpoint where possible. However, API endpoints that aren’t part of the
new official API have been deprecated and will eventually be removed.
Multiple template engines¶
Django 1.8 defines a stable API for integrating template backends. It includes
built-in support for the Django template language and for
Jinja2
. It supports rendering
templates with multiple engines within the same project. Learn more about the
new features in the topic guide and check the
upgrade instructions in older versions of the documentation.
Security enhancements¶
Several features of the django-secure third-party library have been
integrated into Django. django.middleware.security.SecurityMiddleware
provides several security enhancements to the request/response cycle. The new
check --deploy
option allows you to check your production settings
file for ways to increase the security of your site.
New PostgreSQL specific functionality¶
Django now has a module with extensions for PostgreSQL specific features, such
as ArrayField
,
HStoreField
, Range Fields, and
unaccent
lookup. A full breakdown of the features is available
in the documentation.
New data types¶
Django now has a
UUIDField
for storing universally unique identifiers. It is stored as the nativeuuid
data type on PostgreSQL and as a fixed length character field on other backends. There is a correspondingform field
.Django now has a
DurationField
for storing periods of time - modeled in Python bytimedelta
. It is stored in the nativeinterval
data type on PostgreSQL, as aINTERVAL DAY(9) TO SECOND(6)
on Oracle, and as abigint
of microseconds on other backends. Date and time related arithmetic has also been improved on all backends. There is a correspondingform field
.
Query Expressions, Conditional Expressions, and Database Functions¶
Query Expressions allow you to create,
customize, and compose complex SQL expressions. This has enabled annotate
to accept expressions other than aggregates. Aggregates are now able to
reference multiple fields, as well as perform arithmetic, similar to F()
objects. order_by()
has also gained the
ability to accept expressions.
Conditional Expressions allow
you to use if
… elif
… else
logic within
queries.
A collection of database functions is
also included with functionality such as
Coalesce
,
Concat
, and
Substr
.
TestCase
data setup¶
TestCase
has been refactored to allow for data
initialization at the class level using transactions and savepoints. Database
backends which do not support transactions, like MySQL with the MyISAM storage
engine, will still be able to run these tests but won’t benefit from the
improvements. Tests are now run within two nested
atomic()
blocks: one for the whole class and one
for each test.
The class method
TestCase.setUpTestData()
adds the ability to set up test data at the class level. Using this technique can speed up the tests as compared to usingsetUp()
.Fixture loading within
TestCase
is now performed once for the wholeTestCase
.
Minor features¶
django.contrib.admin
¶
ModelAdmin
now has ahas_module_permission()
method to allow limiting access to the module on the admin index page.InlineModelAdmin
now has an attributeshow_change_link
that supports showing a link to an inline object’s change form.Use the new
django.contrib.admin.RelatedOnlyFieldListFilter
inModelAdmin.list_filter
to limit thelist_filter
choices to foreign objects which are attached to those from theModelAdmin
.The
ModelAdmin.delete_view()
displays a summary of objects to be deleted on the deletion confirmation page.The jQuery library embedded in the admin has been upgraded to version 1.11.2.
You can now specify
AdminSite.site_url
in order to display a link to the front-end site.You can now specify
ModelAdmin.show_full_result_count
to control whether or not the full count of objects should be displayed on a filtered admin page.The
AdminSite.password_change()
method now has anextra_context
parameter.You can now control who may login to the admin site by overriding only
AdminSite.has_permission()
andAdminSite.login_form
. Thebase.html
template has a new blockusertools
which contains the user-specific header. A new context variablehas_permission
, which gets its value fromhas_permission()
, indicates whether the user may access the site.Foreign key dropdowns now have buttons for changing or deleting related objects using a popup.
django.contrib.admindocs
¶
reStructuredText is now parsed in model docstrings.
django.contrib.auth
¶
Authorization backends can now raise
PermissionDenied
inhas_perm()
andhas_module_perms()
to short-circuit permission checking.PasswordResetForm
now has a methodsend_mail()
that can be overridden to customize the mail to be sent.The
max_length
ofPermission.name
has been increased from 50 to 255 characters. Please run the database migration.USERNAME_FIELD
andREQUIRED_FIELDS
now supportsForeignKey
s.The default iteration count for the PBKDF2 password hasher has been increased by 33%. This backwards compatible change will not affect users who have subclassed
django.contrib.auth.hashers.PBKDF2PasswordHasher
to change the default value.
django.contrib.gis
¶
A new GeoJSON serializer is now available.
It is now allowed to include a subquery as a geographic lookup argument, for example
City.objects.filter(point__within=Country.objects.filter(continent='Africa').values('mpoly'))
.The SpatiaLite backend now supports
Collect
andExtent
aggregates when the database version is 3.0 or later.The PostGIS 2
CREATE EXTENSION postgis
and the SpatiaLiteSELECT InitSpatialMetaData
initialization commands are now automatically run bymigrate
.The GDAL interface now supports retrieving properties of raster (image) data file.
Compatibility shims for
SpatialRefSys
andGeometryColumns
changed in Django 1.2 have been removed.All GDAL-related exceptions are now raised with
GDALException
. The formerOGRException
has been kept for backwards compatibility but should not be used any longer.
django.contrib.sessions
¶
Session cookie is now deleted after
flush()
is called.
django.contrib.sitemaps
¶
The new
Sitemap.i18n
attribute allows you to generate a sitemap based on theLANGUAGES
setting.
django.contrib.sites
¶
get_current_site()
will now lookup the current site based onrequest.get_host()
if theSITE_ID
setting is not defined.The default
Site
created when runningmigrate
now respects theSITE_ID
setting (instead of always usingpk=1
).
Cache¶
The
incr()
method of thedjango.core.cache.backends.locmem.LocMemCache
backend is now thread-safe.
Cryptography¶
The
max_age
parameter of thedjango.core.signing.TimestampSigner.unsign()
method now also accepts adatetime.timedelta
object.
Database backends¶
The MySQL backend no longer strips microseconds from
datetime
values as MySQL 5.6.4 and up supports fractional seconds depending on the declaration of the datetime field (whenDATETIME
includes fractional precision greater than 0). New datetime database columns created with Django 1.8 and MySQL 5.6.4 and up will support microseconds. See the MySQL database notes for more details.The MySQL backend no longer creates explicit indexes for foreign keys when using the InnoDB storage engine, as MySQL already creates them automatically.
The Oracle backend no longer defines the
connection_persists_old_columns
feature asTrue
. Instead, Oracle will now include a cache busting clause when getting the description of a table.
Email¶
Email backends now support the context manager protocol for opening and closing connections.
The SMTP email backend now supports
keyfile
andcertfile
authentication with theEMAIL_SSL_CERTFILE
andEMAIL_SSL_KEYFILE
settings.The SMTP
EmailBackend
now supports setting thetimeout
parameter with theEMAIL_TIMEOUT
setting.EmailMessage
andEmailMultiAlternatives
now support thereply_to
parameter.
File Storage¶
Storage.get_available_name()
andStorage.save()
now take amax_length
argument to implement storage-level maximum filename length constraints. Filenames exceeding this argument will get truncated. This prevents a database error when appending a unique suffix to a long filename that already exists on the storage. See the deprecation note about adding this argument to your custom storage classes.
Forms¶
Form widgets now render attributes with a value of
True
orFalse
as HTML5 boolean attributes.The new
has_error()
method allows checking if a specific error has happened.If
required_css_class
is defined on a form, then the<label>
tags for required fields will have this class present in its attributes.The rendering of non-field errors in unordered lists (
<ul>
) now includesnonfield
in its list of classes to distinguish them from field-specific errors.Field
now accepts alabel_suffix
argument, which will override the form’slabel_suffix
. This enables customizing the suffix on a per-field basis — previously it wasn’t possible to override a form’slabel_suffix
while using shortcuts such as{{ form.as_p }}
in templates.SelectDateWidget
now accepts anempty_label
argument, which will override the top list choice label whenDateField
is not required.After an
ImageField
has been cleaned and validated, theUploadedFile
object will have an additionalimage
attribute containing the PillowImage
instance used to check if the file was a valid image. It will also updateUploadedFile.content_type
with the image’s content type as determined by Pillow.You can now pass a callable that returns an iterable of choices when instantiating a
ChoiceField
.
Generic Views¶
Generic views that use
MultipleObjectMixin
may now specify the ordering applied to thequeryset
by settingordering
or overridingget_ordering()
.The new
SingleObjectMixin.query_pk_and_slug
attribute allows changing the behavior ofget_object()
so that it’ll perform its lookup using both the primary key and the slug.The
get_form()
method doesn’t require aform_class
to be provided anymore. If not providedform_class
defaults toget_form_class()
.Placeholders in
ModelFormMixin.success_url
now support the Pythonstr.format()
syntax. The legacy%(<foo>)s
syntax is still supported but will be removed in Django 1.10.
Internationalization¶
FORMAT_MODULE_PATH
can now be a list of strings representing module paths. This allows importing several format modules from different reusable apps. It also allows overriding those custom formats in your main Django project.
Logging¶
The
django.utils.log.AdminEmailHandler
class now has asend_mail()
method to make it more subclass friendly.
Management Commands¶
Database connections are now always closed after a management command called from the command line has finished doing its job.
Commands from alternate package formats like eggs are now also discovered.
The new
dumpdata --output
option allows specifying a file to which the serialized data is written.The new
makemessages --exclude
andcompilemessages --exclude
options allow excluding specific locales from processing.compilemessages
now has a--use-fuzzy
or-f
option which includes fuzzy translations into compiled files.The
loaddata --ignorenonexistent
option now ignores data for models that no longer exist.runserver
now uses daemon threads for faster reloading.inspectdb
now outputsMeta.unique_together
. It is also able to introspectAutoField
for MySQL and PostgreSQL databases.When calling management commands with options using
call_command()
, the option name can match the command line option name (without the initial dashes) or the final option destination variable name, but in either case, the resulting option received by the command is now always thedest
name specified in the command option definition (as long as the command uses theargparse
module).The
dbshell
command now supports MySQL’s optional SSL certificate authority setting (--ssl-ca
).The new
makemigrations --name
allows giving the migration(s) a custom name instead of a generated one.The
loaddata
command now prevents repeated fixture loading. IfFIXTURE_DIRS
contains duplicates or a default fixture directory path (app_name/fixtures
), an exception is raised.The new
makemigrations --exit
option allows exiting with an error code if no migrations are created.The new
showmigrations
command allows listing all migrations and their dependencies in a project.
Middleware¶
The
CommonMiddleware.response_redirect_class
attribute allows you to customize the redirects issued by the middleware.A debug message will be logged to the
django.request
logger when a middleware raises aMiddlewareNotUsed
exception inDEBUG
mode.
Migrations¶
The
RunSQL
operation can now handle parameters passed to the SQL statements.It is now possible to have migrations (most probably data migrations) for applications without models.
Migrations can now serialize model managers as part of the model state.
A generic mechanism to handle the deprecation of model fields was added.
The
RunPython.noop()
andRunSQL.noop
class method/attribute were added to ease in makingRunPython
andRunSQL
operations reversible.The migration operations
RunPython
andRunSQL
now call theallow_migrate()
method of database routers. The router can use the newly introducedapp_label
andhints
arguments to make a routing decision. To take advantage of this feature you need to update the router to the newallow_migrate
signature, see the deprecation section for more details.
Models¶
Django now logs at most 9000 queries in
connections.queries
, in order to prevent excessive memory usage in long-running processes in debug mode.There is now a model
Meta
option to define adefault related name
for all relational fields of a model.Pickling models and querysets across different versions of Django isn’t officially supported (it may work, but there’s no guarantee). An extra variable that specifies the current Django version is now added to the pickled state of models and querysets, and Django raises a
RuntimeWarning
when these objects are unpickled in a different version than the one in which they were pickled.Added
Model.from_db()
which Django uses whenever objects are loaded using the ORM. The method allows customizing model loading behavior.extra(select={...})
now allows you to escape a literal%s
sequence using%%s
.Custom Lookups can now be registered using a decorator pattern.
The new
Transform.bilateral
attribute allows creating bilateral transformations. These transformations are applied to bothlhs
andrhs
when used in a lookup expression, providing opportunities for more sophisticated lookups.SQL special characters (, %, _) are now escaped properly when a pattern lookup (e.g.
contains
,startswith
, etc.) is used with anF()
expression as the right-hand side. In those cases, the escaping is performed by the database, which can lead to somewhat complex queries involving nestedREPLACE
function calls.You can now refresh model instances by using
Model.refresh_from_db()
.You can now get the set of deferred fields for a model using
Model.get_deferred_fields()
.Model field
default
’s are now used when primary key field’s are set toNone
.
Signals¶
Exceptions from the
(receiver, exception)
tuples returned bySignal.send_robust()
now have their traceback attached as a__traceback__
attribute.The
environ
argument, which contains the WSGI environment structure from the request, was added to therequest_started
signal.You can now import the
setting_changed()
signal fromdjango.core.signals
to avoid loadingdjango.test
in non-test situations. Django no longer does so itself.
System Check Framework¶
register
can now be used as a function.
Templates¶
urlize
now supports domain-only links that include characters after the top-level domain (e.g.djangoproject.com/
anddjangoproject.com/download/
).urlize
doesn’t treat exclamation marks at the end of a domain or its query string as part of the URL (the URL in e.g.'djangoproject.com!
isdjangoproject.com
)Added a
locmem.Loader
class that loads Django templates from a Python dictionary.The
now
tag can now store its output in a context variable with the usual syntax:{% now 'j n Y' as varname %}
.
Requests and Responses¶
WSGIRequest
now respects paths starting with//
.The
HttpRequest.build_absolute_uri()
method now handles paths starting with//
correctly.If
DEBUG
isTrue
and a request raises aSuspiciousOperation
, the response will be rendered with a detailed error page.The
query_string
argument ofQueryDict
is now optional, defaulting toNone
, so a blankQueryDict
can now be instantiated withQueryDict()
instead ofQueryDict(None)
orQueryDict('')
.The
GET
andPOST
attributes of anHttpRequest
object are nowQueryDict
s rather than dictionaries, and theFILES
attribute is now aMultiValueDict
. This brings this class into line with the documentation and withWSGIRequest
.The
HttpResponse.charset
attribute was added.WSGIRequestHandler
now follows RFC in converting URI to IRI, usinguri_to_iri()
.The
HttpRequest.get_full_path()
method now escapes unsafe characters from the path portion of a Uniform Resource Identifier (URI) properly.HttpResponse
now implements a few additional methods likegetvalue()
so that instances can be used as stream objects.The new
HttpResponse.setdefault()
method allows setting a header unless it has already been set.You can use the new
FileResponse
to stream files.The
condition()
decorator for conditional view processing now supports theIf-unmodified-since
header.
Tests¶
The
RequestFactory.trace()
andClient.trace()
methods were implemented, allowing you to createTRACE
requests in your tests.The
count
argument was added toassertTemplateUsed()
. This allows you to assert that a template was rendered a specific number of times.The new
assertJSONNotEqual()
assertion allows you to test that two JSON fragments are not equal.Added options to the
test
command to preserve the test database (--keepdb
), to run the test cases in reverse order (--reverse
), and to enable SQL logging for failing tests (--debug-sql
).Added the
resolver_match
attribute to test client responses.Added several settings that allow customization of test tablespace parameters for Oracle:
DATAFILE
,DATAFILE_TMP
,DATAFILE_MAXSIZE
andDATAFILE_TMP_MAXSIZE
.The
override_settings()
decorator can now affect the master router inDATABASE_ROUTERS
.Added test client support for file uploads with file-like objects.
A shared cache is now used when testing with an SQLite in-memory database when using Python 3.4+ and SQLite 3.7.13+. This allows sharing the database between threads.
Validators¶
URLValidator
now supports IPv6 addresses, Unicode domains, and URLs containing authentication data.
Backwards incompatible changes in 1.8¶
Warning
In addition to the changes outlined in this section, be sure to review the deprecation plan for any features that have 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.
Assigning unsaved objects to relations raises an error¶
Note
To more easily allow in-memory usage of models, this change was reverted in
Django 1.8.4 and replaced with a check during model.save()
. For example:
>>> book = Book.objects.create(name="Django")
>>> book.author = Author(name="John")
>>> book.save()
Traceback (most recent call last):
...
ValueError: save() prohibited to prevent data loss due to unsaved related object 'author'.
A similar check on assignment to reverse one-to-one relations was removed in Django 1.8.5.
Assigning unsaved objects to a ForeignKey
,
GenericForeignKey
, and
OneToOneField
now raises a ValueError
.
Previously, the assignment of an unsaved object would be silently ignored. For example:
>>> book = Book.objects.create(name="Django")
>>> book.author = Author(name="John")
>>> book.author.save()
>>> book.save()
>>> Book.objects.get(name="Django")
>>> book.author
>>>
Now, an error will be raised to prevent data loss:
>>> book.author = Author(name="john")
Traceback (most recent call last):
...
ValueError: Cannot assign "<Author: John>": "Author" instance isn't saved in the database.
If you require allowing the assignment of unsaved instances (the old behavior)
and aren’t concerned about the data loss possibility (e.g. you never save the
objects to the database), you can disable this check by using the
ForeignKey.allow_unsaved_instance_assignment
attribute. (This attribute was
removed in 1.8.4 as it’s no longer relevant.)
Management commands that only accept positional arguments¶
If you have written a custom management command that only accepts positional
arguments and you didn’t specify the args
command variable, you might get
an error like Error: unrecognized arguments: ...
, as variable parsing is
now based on argparse
which doesn’t implicitly accept positional
arguments. You can make your command backwards compatible by simply setting the
args
class variable. However, if you don’t have to keep compatibility with
older Django versions, it’s better to implement the new
add_arguments()
method as described
in How to create custom django-admin commands.
Custom test management command arguments through test runner¶
The method to add custom arguments to the test
management command through
the test runner has changed. Previously, you could provide an option_list
class variable on the test runner to add more arguments (à la
optparse
). Now to implement the same behavior, you have to create an
add_arguments(cls, parser)
class method on the test runner and call
parser.add_argument
to add any custom arguments, as parser is now an
argparse.ArgumentParser
instance.
Model check ensures auto-generated column names are within limits specified by database¶
A field name that’s longer than the column name length supported by a database can create problems. For example, with MySQL you’ll get an exception trying to create the column, and with PostgreSQL the column name is truncated by the database (you may see a warning in the PostgreSQL logs).
A model check has been introduced to better alert users to this scenario before the actual creation of database tables.
If you have an existing model where this check seems to be a false positive,
for example on PostgreSQL where the name was already being truncated, simply
use db_column
to specify the name that’s being
used.
The check also applies to the columns generated in an implicit
ManyToManyField.through
model. If you run into an issue there, use
through
to create an explicit model
and then specify db_column
on its column(s)
as needed.
Query relation lookups now check object types¶
Querying for model lookups now checks if the object passed is of correct type
and raises a ValueError
if not. Previously, Django didn’t care if the
object was of correct type; it just used the object’s related field attribute
(e.g. id
) for the lookup. Now, an error is raised to prevent incorrect
lookups:
>>> book = Book.objects.create(name="Django")
>>> book = Book.objects.filter(author=book)
Traceback (most recent call last):
...
ValueError: Cannot query "<Book: Django>": Must be "Author" instance.
Default EmailField.max_length
increased to 254¶
The old default 75 character max_length
was not capable of storing all
possible RFC3696/5321-compliant email addresses. In order to store all
possible valid email addresses, the max_length
has been increased to 254
characters. You will need to generate and apply database migrations for your
affected models (or add max_length=75
if you wish to keep the length on
your current fields). A migration for
django.contrib.auth.models.User.email
is included.
Support for PostgreSQL versions older than 9.0¶
The end of upstream support periods was reached in July 2014 for PostgreSQL 8.4. As a consequence, Django 1.8 sets 9.0 as the minimum PostgreSQL version it officially supports.
This also includes dropping support for PostGIS 1.3 and 1.4 as these versions are not supported on versions of PostgreSQL later than 8.4.
Django also now requires the use of Psycopg2 version 2.4.5 or higher (or 2.5+
if you want to use django.contrib.postgres
).
Support for MySQL versions older than 5.5¶
The end of upstream support periods was reached in January 2012 for MySQL 5.0 and December 2013 for MySQL 5.1. As a consequence, Django 1.8 sets 5.5 as the minimum MySQL version it officially supports.
Support for Oracle versions older than 11.1¶
The end of upstream support periods was reached in July 2010 for Oracle 9.2, January 2012 for Oracle 10.1, and July 2013 for Oracle 10.2. As a consequence, Django 1.8 sets 11.1 as the minimum Oracle version it officially supports.
Specific privileges used instead of roles for tests on Oracle¶
Earlier versions of Django granted the CONNECT and RESOURCE roles to the test user on Oracle. These roles have been deprecated, so Django 1.8 uses the specific underlying privileges instead. This changes the privileges required of the main user for running tests (unless the project is configured to avoid creating a test user). The exact privileges required now are detailed in Oracle notes.
AbstractUser.last_login
allows null values¶
The AbstractUser.last_login
field now allows null values. Previously, it defaulted to the time when the user
was created which was misleading if the user never logged in. If you are using
the default user (django.contrib.auth.models.User
), run the database
migration included in contrib.auth
.
If you are using a custom user model that inherits from AbstractUser
,
you’ll need to run makemigrations
and generate a migration for your
app that contains that model. Also, if wish to set last_login
to NULL
for users who haven’t logged in, you can run this query:
from django.db import models
from django.contrib.auth import get_user_model
from django.contrib.auth.models import AbstractBaseUser
UserModel = get_user_model()
if issubclass(UserModel, AbstractBaseUser):
UserModel._default_manager.filter(last_login=models.F("date_joined")).update(
last_login=None
)
django.contrib.gis
¶
Support for GEOS 3.1 and GDAL 1.6 has been dropped.
Support for SpatiaLite < 2.4 has been dropped.
GIS-specific lookups have been refactored to use the
django.db.models.Lookup
API.The default
str
representation ofGEOSGeometry
objects has been changed from WKT to EWKT format (including the SRID). As this representation is used in the serialization framework, that means thatdumpdata
output will now contain the SRID value of geometry objects.
Priority of context processors for TemplateResponse
brought in line with render
¶
The TemplateResponse
constructor is designed to be a
drop-in replacement for the render()
function. However,
it had a slight incompatibility, in that for TemplateResponse
, context data
from the passed in context dictionary could be shadowed by context data returned
from context processors, whereas for render
it was the other way
around. This was a bug, and the behavior of render
is more appropriate,
since it allows the globally defined context processors to be overridden locally
in the view. If you were relying on the fact context data in a
TemplateResponse
could be overridden using a context processor, you will
need to change your code.
Overriding setUpClass
/ tearDownClass
in test cases¶
The decorators override_settings()
and
modify_settings()
now act at the class level when used as
class decorators. As a consequence, when overriding setUpClass()
or
tearDownClass()
, the super
implementation should always be called.
Removal of django.contrib.formtools
¶
The formtools contrib app has been moved to a separate package and the relevant documentation pages have been updated or removed.
The new package is available on GitHub and on PyPI.
Database connection reloading between tests¶
Django previously closed database connections between each test within a
TestCase
. This is no longer the case as Django now wraps the whole
TestCase
within a transaction. If some of your tests relied on the old
behavior, you should have them inherit from TransactionTestCase
instead.
Cleanup of the django.template
namespace¶
If you’ve been relying on private APIs exposed in the django.template
module, you may have to import them from django.template.base
instead.
Also private APIs django.template.base.compile_string()
,
django.template.loader.find_template()
, and
django.template.loader.get_template_from_string()
were removed.
model
attribute on private model relations¶
In earlier versions of Django, on a model with a reverse foreign key
relationship (for example), model._meta.get_all_related_objects()
returned
the relationship as a django.db.models.related.RelatedObject
with the
model
attribute set to the source of the relationship. Now, this method
returns the relationship as django.db.models.fields.related.ManyToOneRel
(private API RelatedObject
has been removed), and the model
attribute
is set to the target of the relationship instead of the source. The source
model is accessible on the related_model
attribute instead.
Consider this example from the tutorial in Django 1.8:
>>> p = Poll.objects.get(pk=1)
>>> p._meta.get_all_related_objects()
[<ManyToOneRel: polls.choice>]
>>> p._meta.get_all_related_objects()[0].model
<class 'polls.models.Poll'>
>>> p._meta.get_all_related_objects()[0].related_model
<class 'polls.models.Choice'>
and compare it to the behavior on older versions:
>>> p._meta.get_all_related_objects()
[<RelatedObject: polls:choice related to poll>]
>>> p._meta.get_all_related_objects()[0].model
<class 'polls.models.Choice'>
To access the source model, you can use a pattern like this to write code that will work with both Django 1.8 and older versions:
for relation in opts.get_all_related_objects():
to_model = getattr(relation, "related_model", relation.model)
Also note that get_all_related_objects()
is deprecated in 1.8.
Database backend API¶
The following changes to the database backend API are documented to assist those writing third-party backends in updating their code:
BaseDatabaseXXX
classes have been moved todjango.db.backends.base
. Please import them from the new locations:from django.db.backends.base.base import BaseDatabaseWrapper from django.db.backends.base.client import BaseDatabaseClient from django.db.backends.base.creation import BaseDatabaseCreation from django.db.backends.base.features import BaseDatabaseFeatures from django.db.backends.base.introspection import BaseDatabaseIntrospection from django.db.backends.base.introspection import FieldInfo, TableInfo from django.db.backends.base.operations import BaseDatabaseOperations from django.db.backends.base.schema import BaseDatabaseSchemaEditor from django.db.backends.base.validation import BaseDatabaseValidation
The
data_types
,data_types_suffix
, anddata_type_check_constraints
attributes have moved from theDatabaseCreation
class toDatabaseWrapper
.The
SQLCompiler.as_sql()
method now takes asubquery
parameter (#24164).The
BaseDatabaseOperations.date_interval_sql()
method now only takes atimedelta
parameter.
django.contrib.admin
¶
AdminSite
no longer takes anapp_name
argument and itsapp_name
attribute has been removed. The application name is alwaysadmin
(as opposed to the instance name which you can still customize usingAdminSite(name="...")
.The
ModelAdmin.get_object()
method (private API) now takes a third argument namedfrom_field
in order to specify which field should match the providedobject_id
.The
ModelAdmin.response_delete()
method now takes a second argument namedobj_id
which is the serialized identifier used to retrieve the object before deletion.
Default autoescaping of functions in django.template.defaultfilters
¶
In order to make built-in template filters that output HTML “safe by default”
when calling them in Python code, the following functions in
django.template.defaultfilters
have been changed to automatically escape
their input value:
join
linebreaksbr
linebreaks_filter
linenumbers
unordered_list
urlize
urlizetrunc
You can revert to the old behavior by specifying autoescape=False
if you
are passing trusted content. This change doesn’t have any effect when using
the corresponding filters in templates.
Miscellaneous¶
connections.queries
is now a read-only attribute.Database connections are considered equal only if they’re the same object. They aren’t hashable any more.
GZipMiddleware
used to disable compression for some content types when the request is from Internet Explorer, in order to work around a bug in IE6 and earlier. This behavior could affect performance on IE7 and later. It was removed.URLField.to_python
no longer adds a trailing slash to pathless URLs.The
length
template filter now returns0
for an undefined variable, rather than an empty string.ForeignKey.default_error_message['invalid']
has been changed from'%(model)s instance with pk %(pk)r does not exist.'
to'%(model)s instance with %(field)s %(value)r does not exist.'
If you are using this message in your own code, please update the list of interpolated parameters. Internally, Django will continue to provide thepk
parameter inparams
for backwards compatibility.UserCreationForm.error_messages['duplicate_username']
is no longer used. If you wish to customize that error message, override it on the form using the'unique'
key inMeta.error_messages['username']
or, if you have a custom form field for'username'
, using the'unique'
key in itserror_messages
argument.The block
usertools
in thebase.html
template ofdjango.contrib.admin
now requires thehas_permission
context variable to be set. If you have any custom admin views that use this template, update them to passAdminSite.has_permission()
as this new variable’s value or simply includeAdminSite.each_context(request)
in the context.Internal changes were made to the
ClearableFileInput
widget to allow more customization. The undocumentedurl_markup_template
attribute was removed in favor oftemplate_with_initial
.For consistency with other major vendors, the
en_GB
locale now has Monday as the first day of the week.Seconds have been removed from any locales that had them in
TIME_FORMAT
,DATETIME_FORMAT
, orSHORT_DATETIME_FORMAT
.The default max size of the Oracle test tablespace has increased from 300M (or 200M, before 1.7.2) to 500M.
reverse()
andreverse_lazy()
now return Unicode strings instead of bytestrings.The
CacheClass
shim has been removed from all cache backends. These aliases were provided for backwards compatibility with Django 1.3. If you are still using them, please update your project to use the real class name found in theBACKEND
key of theCACHES
setting.By default,
call_command()
now always skips the check framework (unless you pass itskip_checks=False
).When iterating over lines,
File
now uses universal newlines. The following are recognized as ending a line: the Unix end-of-line convention'\n'
, the Windows convention'\r\n'
, and the old Macintosh convention'\r'
.The Memcached cache backends
MemcachedCache
andPyLibMCCache
will delete a key ifset()
fails. This is necessary to ensure thecache_db
session store always fetches the most current session data.Private APIs
override_template_loaders
andoverride_with_test_loader
indjango.test.utils
were removed. OverrideTEMPLATES
withoverride_settings
instead.Warnings from the MySQL database backend are no longer converted to exceptions when
DEBUG
isTrue
.HttpRequest
now has a simplifiedrepr
(e.g.<WSGIRequest: GET '/somepath/'>
). This won’t change the behavior of theSafeExceptionReporterFilter
class.Class-based views that use
ModelFormMixin
will raise anImproperlyConfigured
exception when both thefields
andform_class
attributes are specified. Previously,fields
was silently ignored.When following redirects, the test client now raises
RedirectCycleError
if it detects a loop or hits a maximum redirect limit (rather than passing silently).Translatable strings set as the
default
parameter of the field are cast to concrete strings later, so the return type ofField.get_default()
is different in some cases. There is no change to default values which are the result of a callable.GenericIPAddressField.empty_strings_allowed
is nowFalse
. Database backends that interpret empty strings as null (only Oracle among the backends that Django includes) will no longer convert null values back to an empty string. This is consistent with other backends.When the
BaseCommand.leave_locale_alone
attribute isFalse
, translations are now deactivated instead of forcing the “en-us” locale. In the case your models contained non-English strings and you counted on English translations to be activated in management commands, this will not happen any longer. It might be that new database migrations are generated (once) after migrating to 1.8.django.utils.translation.get_language()
now returnsNone
instead ofLANGUAGE_CODE
when translations are temporarily deactivated.When a translation doesn’t exist for a specific literal, the fallback is now taken from the
LANGUAGE_CODE
language (instead of from the untranslatedmsgid
message).The
name
field ofdjango.contrib.contenttypes.models.ContentType
has been removed by a migration and replaced by a property. That means it’s not possible to query or filter aContentType
by this field any longer.Be careful if you upgrade to Django 1.8 and skip Django 1.7. If you run
manage.py migrate --fake
, this migration will be skipped and you’ll see aRuntimeError: Error creating new content types.
exception because thename
column won’t be dropped from the database. Usemanage.py migrate --fake-initial
to fake only the initial migration instead.The new
migrate --fake-initial
option allows faking initial migrations. In 1.7, initial migrations were always automatically faked if all tables created in an initial migration already existed.An app without migrations with a
ForeignKey
to an app with migrations may now result in a foreign key constraint error when migrating the database or running tests. In Django 1.7, this could fail silently and result in a missing constraint. To resolve the error, add migrations to the app without them.
Features deprecated in 1.8¶
Selected methods in django.db.models.options.Options
¶
As part of the formalization of the Model._meta
API (from the
django.db.models.options.Options
class), a number of methods have been
deprecated and will be removed in Django 1.10:
get_all_field_names()
get_all_related_objects()
get_all_related_objects_with_model()
get_all_related_many_to_many_objects()
get_all_related_m2m_objects_with_model()
get_concrete_fields_with_model()
get_field_by_name()
get_fields_with_model()
get_m2m_with_model()
django.conf.urls.patterns()
¶
In the olden days of Django, it was encouraged to reference views as strings
in urlpatterns
:
urlpatterns = patterns(
"",
url("^$", "myapp.views.myview"),
)
and Django would magically import myapp.views.myview
internally and turn
the string into a real function reference. In order to reduce repetition when
referencing many views from the same module, the patterns()
function takes
a required initial prefix
argument which is prepended to all
views-as-strings in that set of urlpatterns
:
urlpatterns = patterns(
"myapp.views",
url("^$", "myview"),
url("^other/$", "otherview"),
)
In the modern era, we have updated the tutorial to instead recommend importing your views module and referencing your view functions (or classes) directly. This has a number of advantages, all deriving from the fact that we are using normal Python in place of “Django String Magic”: the errors when you mistype a view name are less obscure, IDEs can help with autocompletion of view names, etc.
So these days, the above use of the prefix
arg is much more likely to be
written (and is better written) as:
from myapp import views
urlpatterns = patterns(
"",
url("^$", views.myview),
url("^other/$", views.otherview),
)
Thus patterns()
serves little purpose and is a burden when teaching new users
(answering the newbie’s question “why do I need this empty string as the first
argument to patterns()
?”). For these reasons, we are deprecating it.
Updating your code is as simple as ensuring that urlpatterns
is a list of
django.conf.urls.url()
instances. For example:
from django.conf.urls import url
from myapp import views
urlpatterns = [
url("^$", views.myview),
url("^other/$", views.otherview),
]
Passing a string as view
to django.conf.urls.url()
¶
Related to the previous item, referencing views as strings in the url()
function is deprecated. Pass the callable view as described in the previous
section instead.
django.core.context_processors
¶
Built-in template context processors have been moved to
django.template.context_processors
.
django.test.SimpleTestCase.urls
¶
The attribute SimpleTestCase.urls
for specifying URLconf configuration in
tests has been deprecated and will be removed in Django 1.10. Use
@override_settings(ROOT_URLCONF=...)
instead.
prefix
argument to i18n_patterns()
¶
Related to the previous item, the prefix
argument to
django.conf.urls.i18n.i18n_patterns()
has been deprecated. Simply pass a
list of django.conf.urls.url()
instances instead.
Using an incorrect count of unpacked values in the for
template tag¶
Using an incorrect count of unpacked values in for
tag will raise an
exception rather than fail silently in Django 1.10.
Passing a dotted path to reverse()
and url
¶
Reversing URLs by Python path is an expensive operation as it causes the path being reversed to be imported. This behavior has also resulted in a security issue. Use named URL patterns for reversing instead.
If you are using django.contrib.sitemaps
, add the name
argument to
the url
that references django.contrib.sitemaps.views.sitemap()
:
from django.contrib.sitemaps.views import sitemap
url(
r"^sitemap\.xml$",
sitemap,
{"sitemaps": sitemaps},
name="django.contrib.sitemaps.views.sitemap",
)
to ensure compatibility when reversing by Python path is removed in Django 1.10.
Similarly for GIS sitemaps, add name='django.contrib.gis.sitemaps.views.kml'
or name='django.contrib.gis.sitemaps.views.kmz'
.
If you are using a Python path for the LOGIN_URL
or
LOGIN_REDIRECT_URL
setting, use the name of the url()
instead.
Aggregate methods and modules¶
The django.db.models.sql.aggregates
and
django.contrib.gis.db.models.sql.aggregates
modules (both private API), have
been deprecated as django.db.models.aggregates
and
django.contrib.gis.db.models.aggregates
are now also responsible
for SQL generation. The old modules will be removed in Django 1.10.
If you were using the old modules, see Query Expressions for instructions on rewriting custom aggregates using the new stable API.
The following methods and properties of django.db.models.sql.query.Query
have also been deprecated and the backwards compatibility shims will be removed
in Django 1.10:
Query.aggregates
, replaced byannotations
.Query.aggregate_select
, replaced byannotation_select
.Query.add_aggregate()
, replaced byadd_annotation()
.Query.set_aggregate_mask()
, replaced byset_annotation_mask()
.Query.append_aggregate_mask()
, replaced byappend_annotation_mask()
.
Extending management command arguments through Command.option_list
¶
Management commands now use argparse
instead of optparse
to
parse command-line arguments passed to commands. This also means that the way
to add custom arguments to commands has changed: instead of extending the
option_list
class list, you should now override the
add_arguments()
method and add
arguments through argparse.add_argument()
. See
this example for more details.
django.core.management.NoArgsCommand
¶
The class NoArgsCommand
is now deprecated and will be removed in Django
1.10. Use BaseCommand
instead, which takes no
arguments by default.
Listing all migrations in a project¶
The --list
option of the migrate
management command is
deprecated and will be removed in Django 1.10. Use showmigrations
instead.
cache_choices
option of ModelChoiceField
and ModelMultipleChoiceField
¶
ModelChoiceField
and
ModelMultipleChoiceField
took an undocumented, untested
option cache_choices
. This cached querysets between multiple renderings of
the same Form
object. This option is subject to an accelerated deprecation
and will be removed in Django 1.9.
django.template.resolve_variable()
¶
The function has been informally marked as “Deprecated” for some time. Replace
resolve_variable(path, context)
with
django.template.Variable(path).resolve(context)
.
django.contrib.webdesign
¶
It provided the lorem
template tag which is now included in the
built-in tags. Simply remove 'django.contrib.webdesign'
from
INSTALLED_APPS
and {% load webdesign %}
from your templates.
error_message
argument to django.forms.RegexField
¶
It provided backwards compatibility for pre-1.0 code, but its functionality is
redundant. Use Field.error_messages['invalid']
instead.
Old unordered_list
syntax¶
An older (pre-1.0), more restrictive and verbose input format for the
unordered_list
template filter has been deprecated:
["States", [["Kansas", [["Lawrence", []], ["Topeka", []]]], ["Illinois", []]]]
Using the new syntax, this becomes:
["States", ["Kansas", ["Lawrence", "Topeka"], "Illinois"]]
django.forms.Field._has_changed()
¶
Rename this method to has_changed()
by removing the
leading underscore. The old name will still work until Django 1.10.
is_admin_site
argument to django.contrib.auth.views.password_reset()
¶
It’s a legacy option that should no longer be necessary.
SubfieldBase
¶
django.db.models.fields.subclassing.SubfieldBase
has been deprecated and
will be removed in Django 1.10. Historically, it was used to handle fields where
type conversion was needed when loading from the database, but it was not used
in .values()
calls or in aggregates. It has been replaced with
from_db_value()
.
The new approach doesn’t call the to_python()
method on assignment as was the case with SubfieldBase
. If you need that
behavior, reimplement the Creator
class from Django’s source code
in your project.
django.utils.checksums
¶
The django.utils.checksums
module has been deprecated and will be removed
in Django 1.10. The functionality it provided (validating checksum using the
Luhn algorithm) was undocumented and not used in Django. The module has been
moved to the django-localflavor package (version 1.1+).
InlineAdminForm.original_content_type_id
¶
The original_content_type_id
attribute on InlineAdminForm
has been
deprecated and will be removed in Django 1.10. Historically, it was used
to construct the “view on site” URL. This URL is now accessible using the
absolute_url
attribute of the form.
django.views.generic.edit.FormMixin.get_form()
’s form_class
argument¶
FormMixin
subclasses that override the get_form()
method should make
sure to provide a default value for the form_class
argument since it’s
now optional.
Rendering templates loaded by get_template()
with a Context
¶
The return type of get_template()
has changed
in Django 1.8: instead of a django.template.Template
, it returns a
Template
instance whose exact type depends on which backend loaded it.
Both classes provide a render()
method, however, the former takes a
django.template.Context
as an argument while the latter expects a
dict
. This change is enforced through a deprecation path for Django
templates.
All this also applies to select_template()
.
Template
and Context
classes in template responses¶
Some methods of SimpleTemplateResponse
and
TemplateResponse
accepted
django.template.Context
and django.template.Template
objects
as arguments. They should now receive dict
and backend-dependent
template objects respectively.
This also applies to the return types if you have subclassed either template response class.
Check the template response API documentation for details.
dictionary
and context_instance
arguments of rendering functions¶
The following functions will no longer accept the dictionary
and
context_instance
parameters in Django 1.10:
django.shortcuts.render()
django.shortcuts.render_to_response()
django.template.loader.render_to_string()
Use the context
parameter instead. When dictionary
is passed as a
positional argument, which is the most common idiom, no changes are needed.
If you’re passing a Context
in context_instance
,
pass a dict
in the context
parameter instead. If you’re passing a
RequestContext
, pass the request separately in the
request
parameter.
dirs
argument of template-finding functions¶
The following functions will no longer accept a dirs
parameter to override
TEMPLATE_DIRS
in Django 1.10:
django.shortcuts.render_to_response()
The parameter didn’t work consistently across different template loaders and didn’t work for included templates.
django.template.loader.BaseLoader
¶
django.template.loader.BaseLoader
was renamed to
django.template.loaders.base.Loader
. If you’ve written a custom template
loader that inherits BaseLoader
, you must inherit Loader
instead.
django.test.utils.TestTemplateLoader
¶
Private API django.test.utils.TestTemplateLoader
is deprecated in favor of
django.template.loaders.locmem.Loader
and will be removed in Django 1.9.
Support for the max_length
argument on custom Storage
classes¶
Storage
subclasses should add max_length=None
as a parameter to
get_available_name()
and/or
save()
if they override either method.
Support for storages that do not accept this argument will be removed in
Django 1.10.
qn
replaced by compiler
¶
In previous Django versions, various internal ORM methods (mostly as_sql
methods) accepted a qn
(for “quote name”) argument, which was a reference
to a function that quoted identifiers for sending to the database. In Django
1.8, that argument has been renamed to compiler
and is now a full
SQLCompiler
instance. For backwards-compatibility, calling a
SQLCompiler
instance performs the same name-quoting that the qn
function used to. However, this backwards-compatibility shim is immediately
deprecated: you should rename your qn
arguments to compiler
, and call
compiler.quote_name_unless_alias(...)
where you previously called
qn(...)
.
Default value of RedirectView.permanent
¶
The default value of the
RedirectView.permanent
attribute will change from True
to False
in Django 1.9.
Using AuthenticationMiddleware
without SessionAuthenticationMiddleware
¶
django.contrib.auth.middleware.SessionAuthenticationMiddleware
was
added in Django 1.7. In Django 1.7.2, its functionality was moved to
auth.get_user()
and, for backwards compatibility, enabled only if
'django.contrib.auth.middleware.SessionAuthenticationMiddleware'
appears in
MIDDLEWARE_CLASSES
.
In Django 1.10, session verification will be enabled regardless of whether or not
SessionAuthenticationMiddleware
is enabled (at which point
SessionAuthenticationMiddleware
will have no significance). You can add it
to your MIDDLEWARE_CLASSES
sometime before then to opt-in. Please read the
upgrade considerations first.
django.contrib.sitemaps.FlatPageSitemap
¶
django.contrib.sitemaps.FlatPageSitemap
has moved to
django.contrib.flatpages.sitemaps.FlatPageSitemap
. The old import location
is deprecated and will be removed in Django 1.9.
ssi
template tag¶
The ssi
template tag allows files to be included in a template by
absolute path. This is of limited use in most deployment situations, and
the include
tag often makes more sense. This tag is now deprecated and
will be removed in Django 1.10.
=
as comparison operator in if
template tag¶
Using a single equals sign with the {% if %}
template tag for equality
testing was undocumented and untested. It’s now deprecated in favor of ==
.
%(<foo>)s
syntax in ModelFormMixin.success_url
¶
The legacy %(<foo>)s
syntax in ModelFormMixin.success_url
is deprecated and
will be removed in Django 1.10.
GeoQuerySet
aggregate methods¶
The collect()
, extent()
, extent3d()
, make_line()
, and
unionagg()
aggregate methods are deprecated and should be replaced by their
function-based aggregate equivalents (Collect
, Extent
, Extent3D
,
MakeLine
, and Union
).
Signature of the allow_migrate
router method¶
The signature of the allow_migrate()
method of database routers has
changed from allow_migrate(db, model)
to
allow_migrate(db, app_label, model_name=None, **hints)
.
When model_name
is set, the value that was previously given through the
model
positional argument may now be found inside the hints
dictionary
under the key 'model'
.
After switching to the new signature the router will also be called by the
RunPython
and
RunSQL
operations.
Features removed in 1.8¶
These features have reached the end of their deprecation cycle and are removed in Django 1.8. See Features deprecated in 1.6 for details, including how to remove usage of these features.
django.contrib.comments
is removed.The following transaction management APIs are removed:
TransactionMiddleware
the decorators and context managers
autocommit
,commit_on_success
, andcommit_manually
, defined indjango.db.transaction
the functions
commit_unless_managed
androllback_unless_managed
, also defined indjango.db.transaction
the
TRANSACTIONS_MANAGED
setting
The
cycle
andfirstof
template tags auto-escape their arguments.The
SEND_BROKEN_LINK_EMAILS
setting is removed.django.middleware.doc.XViewMiddleware
is removed.The
Model._meta.module_name
alias is removed.The backward compatible shims introduced to rename
get_query_set
and similar queryset methods are removed. This affects the following classes:BaseModelAdmin
,ChangeList
,BaseCommentNode
,GenericForeignKey
,Manager
,SingleRelatedObjectDescriptor
andReverseSingleRelatedObjectDescriptor
.The backward compatible shims introduced to rename the attributes
ChangeList.root_query_set
andChangeList.query_set
are removed.django.views.defaults.shortcut
anddjango.conf.urls.shortcut
are removed.Support for the Python Imaging Library (PIL) module is removed.
The following private APIs are removed:
django.db.backend
django.db.close_connection()
django.db.backends.creation.BaseDatabaseCreation.set_autocommit()
django.db.transaction.is_managed()
django.db.transaction.managed()
django.forms.widgets.RadioInput
is removed.The module
django.test.simple
and the classdjango.test.simple.DjangoTestSuiteRunner
are removed.The module
django.test._doctest
is removed.The
CACHE_MIDDLEWARE_ANONYMOUS_ONLY
setting is removed. This change affects bothdjango.middleware.cache.CacheMiddleware
anddjango.middleware.cache.UpdateCacheMiddleware
despite the lack of a deprecation warning in the latter class.Usage of the hard-coded Hold down “Control”, or “Command” on a Mac, to select more than one. string to override or append to user-provided
help_text
in forms forManyToMany
model fields is not performed by Django anymore either at the model or forms layer.The
Model._meta.get_(add|change|delete)_permission
methods are removed.The session key
django_language
is no longer read for backwards compatibility.Geographic Sitemaps are removed (
django.contrib.gis.sitemaps.views.index
anddjango.contrib.gis.sitemaps.views.sitemap
).django.utils.html.fix_ampersands
, thefix_ampersands
template filter, anddjango.utils.html.clean_html
are removed.