- Language: en
Django 1.5 release notes¶
February 26, 2013
Welcome to Django 1.5!
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.4 or older versions. We’ve also dropped some features, which are detailed in our deprecation plan, and we’ve begun the deprecation process for some features.
Overview¶
The biggest new feature in Django 1.5 is the configurable User model. Before
Django 1.5, applications that wanted to use Django’s auth framework
(django.contrib.auth
) were forced to use Django’s definition of a “user”.
In Django 1.5, you can now swap out the User
model for one that you write
yourself. This could be a simple extension to the existing User
model – for
example, you could add a Twitter or Facebook ID field – or you could completely
replace the User
with one totally customized for your site.
Django 1.5 is also the first release with Python 3 support! We’re labeling this support “experimental” because we don’t yet consider it production-ready, but everything’s in place for you to start porting your apps to Python 3. Our next release, Django 1.6, will support Python 3 without reservations.
Other notable new features in Django 1.5 include:
- Support for saving a subset of model’s fields -
Model.save()
now accepts anupdate_fields
argument, letting you specify which fields are written back to the database when you callsave()
. This can help in high-concurrency operations, and can improve performance. - Better support for streaming responses via
the new
StreamingHttpResponse
response class. - GeoDjango now supports PostGIS 2.0.
- … and more; see below.
Wherever possible we try to introduce new features in a backwards-compatible manner per our API stability policy. However, as with previous releases, Django 1.5 ships with some minor backwards incompatible changes; people upgrading from previous versions of Django should read that list carefully.
One deprecated feature worth noting is the shift to “new-style” url
tag.
Prior to Django 1.3, syntax like {% url myview %}
was interpreted
incorrectly (Django considered "myview"
to be a literal name of a view, not
a template variable named myview
). Django 1.3 and above introduced the
{% load url from future %}
syntax to bring in the corrected behavior where
myview
was seen as a variable.
The upshot of this is that if you are not using {% load url from future %}
in your templates, you’ll need to change tags like {% url myview %}
to
{% url "myview" %}
. If you were using {% load url from future %}
you
can simply remove that line under Django 1.5
Python compatibility¶
Django 1.5 requires Python 2.6.5 or above, though we highly recommend Python 2.7.3 or above. Support for Python 2.5 and below has been dropped.
This change should affect only a small number of Django users, as most operating-system vendors today are shipping Python 2.6 or newer as their default version. If you’re still using Python 2.5, however, you’ll need to stick to Django 1.4 until you can upgrade your Python version. Per our support policy, Django 1.4 will continue to receive security support until the release of Django 1.6.
Django 1.5 does not run on a Jython final release, because Jython’s latest release doesn’t currently support Python 2.6. However, Jython currently does offer an alpha release featuring 2.7 support, and Django 1.5 supports that alpha release.
Python 3 support¶
Django 1.5 introduces support for Python 3 - specifically, Python 3.2 and above. This comes in the form of a single codebase; you don’t need to install a different version of Django on Python 3. This means that you can write applications targeted for just Python 2, just Python 3, or single applications that support both platforms.
However, we’re labeling this support “experimental” for now: although it’s received extensive testing via our automated test suite, it’s received very little real-world testing. We’ve done our best to eliminate bugs, but we can’t be sure we covered all possible uses of Django.
Some features of Django aren’t available because they depend on third-party software that hasn’t been ported to Python 3 yet, including:
- the MySQL database backend (depends on MySQLdb)
ImageField
(depends on PIL)LiveServerTestCase
(depends on Selenium WebDriver)
Further, Django’s more than a web framework; it’s an ecosystem of pluggable components. At this point, very few third-party applications have been ported to Python 3, so it’s unlikely that a real-world application will have all its dependencies satisfied under Python 3.
Thus, we’re recommending that Django 1.5 not be used in production under Python 3. Instead, use this opportunity to begin porting applications to Python 3. If you’re an author of a pluggable component, we encourage you to start porting now.
We plan to offer first-class, production-ready support for Python 3 in our next release, Django 1.6.
What’s new in Django 1.5¶
Configurable User model¶
In Django 1.5, you can now use your own model as the store for user-related data. If your project needs a username with more than 30 characters, or if you want to store user’s names in a format other than first name/last name, or you want to put custom profile information onto your User object, you can now do so.
If you have a third-party reusable application that references the User model, you may need to make some changes to the way you reference User instances. You should also document any specific features of the User model that your application relies upon.
See the documentation on custom user models for more details.
Support for saving a subset of model’s fields¶
The method Model.save()
has a new
keyword argument update_fields
. By using this argument it is possible to
save only a select list of model’s fields. This can be useful for performance
reasons or when trying to avoid overwriting concurrent changes.
Deferred instances (those loaded by .only()
or .defer()
) will
automatically save just the loaded fields. If any field is set manually after
load, that field will also get updated on save.
See the Model.save()
documentation for
more details.
Explicit support for streaming responses¶
Before Django 1.5, it was possible to create a streaming response by passing
an iterator to HttpResponse
. But this was unreliable:
any middleware that accessed the content
attribute would consume the iterator prematurely.
You can now explicitly generate a streaming response with the new
StreamingHttpResponse
class. This class exposes a
streaming_content
attribute which
is an iterator.
Since StreamingHttpResponse
does not have a content
attribute, middleware that needs access to the response content must test for
streaming responses and behave accordingly.
{% verbatim %}
template tag¶
To make it easier to deal with JavaScript templates which collide with Django’s
syntax, you can now use the verbatim
block tag to avoid parsing the
tag’s content.
Retrieval of ContentType
instances associated with proxy models¶
The methods ContentTypeManager.get_for_model()
and ContentTypeManager.get_for_models()
have a new keyword argument – respectively for_concrete_model
and for_concrete_models
.
By passing False
using this argument it is now possible to retrieve the
ContentType
associated with proxy models.
New view
variable in class-based views context¶
In all generic class-based views
(or any class-based view inheriting from ContextMixin
), the context dictionary
contains a view
variable that points to the View
instance.
GeoDjango¶
LineString
andMultiLineString
GEOS objects now support theinterpolate()
andproject()
methods (so-called linear referencing).- The
wkb
andhex
properties ofGEOSGeometry
objects preserve the Z dimension. - Support for PostGIS 2.0 has been added and support for GDAL < 1.5 has been dropped.
New tutorials¶
Additions to the docs include a revamped Tutorial 3 and a new tutorial on testing. A new section, “Advanced Tutorials”, offers How to write reusable apps as well as a step-by-step guide for new contributors in Writing your first patch for Django.
Minor features¶
Django 1.5 also includes several smaller improvements worth noting:
The template engine now interprets
True
,False
andNone
as the corresponding Python objects.django.utils.timezone
provides a helper for converting aware datetimes between time zones. Seelocaltime()
.The generic views support OPTIONS requests.
Management commands do not raise
SystemExit
any more when called by code fromcall_command()
. Any exception raised by the command (mostlyCommandError
) is propagated.Moreover, when you output errors or messages in your custom commands, you should now use
self.stdout.write('message')
andself.stderr.write('error')
(see the note on management commands output).The
dumpdata
management command outputs one row at a time, preventing out-of-memory errors when dumping large datasets.In the localflavor for Canada,
pq
was added to the acceptable codes for Quebec. It’s an old abbreviation.The receiver decorator is now able to connect to more than one signal by supplying a list of signals.
In the admin, you can now filter users by groups which they are members of.
QuerySet.bulk_create()
now has a batch_size argument. By default the batch_size is unlimited except for SQLite where single batch is limited so that 999 parameters per query isn’t exceeded.The
LOGIN_URL
andLOGIN_REDIRECT_URL
settings now also accept view function names and named URL patterns. This allows you to reduce configuration duplication. More information can be found in thelogin_required()
documentation.Django now provides a mod_wsgi auth handler.
The
QuerySet.delete()
andModel.delete()
can now take fast-path in some cases. The fast-path allows for less queries and less objects fetched into memory. SeeQuerySet.delete()
for details.An instance of
ResolverMatch
is stored on the request asresolver_match
.By default, all logging messages reaching the
django
logger whenDEBUG
isTrue
are sent to the console (unless you redefine the logger in yourLOGGING
setting).When using
RequestContext
, it is now possible to look up permissions by using{% if 'someapp.someperm' in perms %}
in templates.It’s not required any more to have
404.html
and500.html
templates in the root templates directory. Django will output some basic error messages for both situations when those templates are not found. It’s still recommended as good practice to provide those templates in order to present pretty error pages to the user.django.contrib.auth
provides a new signal that is emitted whenever a user fails to login successfully. Seeuser_login_failed
The new
loaddata --ignorenonexistent
option ignore data for fields that no longer exist.assertXMLEqual()
andassertXMLNotEqual()
new assertions allow you to test equality for XML content at a semantic level, without caring for syntax differences (spaces, attribute order, etc.).RemoteUserMiddleware now forces logout when the REMOTE_USER header disappears during the same browser session.
The cache-based session backend can store session data in a non-default cache.
Multi-column indexes can now be created on models. Read the
index_together
documentation for more information.During Django’s logging configuration verbose Deprecation warnings are enabled and warnings are captured into the logging system. Logged warnings are routed through the
console
logging handler, which by default requiresDEBUG
to be True for output to be generated. The result is that DeprecationWarnings should be printed to the console in development environments the way they have been in Python versions < 2.7.The API for
django.contrib.admin.ModelAdmin.message_user()
method has been modified to accept additional arguments adding capabilities similar todjango.contrib.messages.add_message()
. This is useful for generating error messages from admin actions.The admin’s list filters can now be customized per-request thanks to the new
django.contrib.admin.ModelAdmin.get_list_filter()
method.
Backwards incompatible changes in 1.5¶
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.
ALLOWED_HOSTS
required in production¶
The new ALLOWED_HOSTS
setting validates the request’s Host
header and protects against host-poisoning attacks. This setting is now
required whenever DEBUG
is False
, or else
django.http.HttpRequest.get_host()
will raise
SuspiciousOperation
. For more details see the
full documentation
for the new setting.
Managers on abstract models¶
Abstract models are able to define a custom manager, and that manager will be inherited by any concrete models extending the abstract model. However, if you try to use the abstract model to call a method on the manager, an exception will now be raised. Previously, the call would have been permitted, but would have failed as soon as any database operation was attempted (usually with a “table does not exist” error from the database).
If you have functionality on a manager that you have been invoking using
the abstract class, you should migrate that logic to a Python
staticmethod
or classmethod
on the abstract class.
Context in year archive class-based views¶
For consistency with the other date-based generic views,
YearArchiveView
now passes year
in
the context as a datetime.date
rather than a string. If you are
using {{ year }}
in your templates, you must replace it with {{
year|date:"Y" }}
.
next_year
and previous_year
were also added in the context. They are
calculated according to allow_empty
and allow_future
.
Context in year and month archive class-based views¶
YearArchiveView
and
MonthArchiveView
were documented to
provide a date_list
sorted in ascending order in the context, like their
function-based predecessors, but it actually was in descending order. In 1.5,
the documented order was restored. You may want to add (or remove) the
reversed
keyword when you’re iterating on date_list
in a template:
{% for date in date_list reversed %}
ArchiveIndexView
still provides a
date_list
in descending order.
Context in TemplateView¶
For consistency with the design of the other generic views,
TemplateView
no longer passes a params
dictionary into the context, instead passing the variables from the URLconf
directly into the context.
Non-form data in HTTP requests¶
request.POST
will no longer include data
posted via HTTP requests with non form-specific content-types in the header.
In prior versions, data posted with content-types other than
multipart/form-data or
application/x-www-form-urlencoded would still end up represented in
the request.POST
attribute. Developers
wishing to access the raw POST data for these cases, should use the
request.body
attribute instead.
request_finished
signal¶
Django used to send the request_finished
signal
as soon as the view function returned a response. This interacted badly with
streaming responses that delay content
generation.
This signal is now sent after the content is fully consumed by the WSGI gateway. This might be backwards incompatible if you rely on the signal being fired before sending the response content to the client. If you do, you should consider using middleware instead.
Note
Some WSGI servers and middleware do not always call close
on the
response object after handling a request, most notably uWSGI prior to 1.2.6
and Sentry’s error reporting middleware up to 2.0.7. In those cases the
request_finished
signal isn’t sent at all. This can result in idle
connections to database and memcache servers.
OPTIONS, PUT and DELETE requests in the test client¶
Unlike GET and POST, these HTTP methods aren’t implemented by web browsers. Rather, they’re used in APIs, which transfer data in various formats such as JSON or XML. Since such requests may contain arbitrary data, Django doesn’t attempt to decode their body.
However, the test client used to build a query string for OPTIONS and DELETE requests like for GET, and a request body for PUT requests like for POST. This encoding was arbitrary and inconsistent with Django’s behavior when it receives the requests, so it was removed in Django 1.5.
If you were using the data
parameter in an OPTIONS or a DELETE request,
you must convert it to a query string and append it to the path
parameter.
If you were using the data
parameter in a PUT request without a
content_type
, you must encode your data before passing it to the test
client and set the content_type
argument.
System version of simplejson
no longer used¶
As explained below, Django 1.5 deprecates
django.utils.simplejson
in favor of Python 2.6’s built-in json
module. In theory, this change is harmless. Unfortunately, because of
incompatibilities between versions of simplejson
, it may trigger errors
in some circumstances.
JSON-related features in Django 1.4 always used django.utils.simplejson
.
This module was actually:
- A system version of
simplejson
, if one was available (i.e.import simplejson
works), if it was more recent than Django’s built-in copy or it had the C speedups, or - The
json
module from the standard library, if it was available (i.e. Python 2.6 or greater), or - A built-in copy of version 2.0.7 of
simplejson
.
In Django 1.5, those features use Python’s json
module, which is based
on version 2.0.9 of simplejson
.
There are no known incompatibilities between Django’s copy of version 2.0.7 and
Python’s copy of version 2.0.9. However, there are some incompatibilities
between other versions of simplejson
:
- While the
simplejson
API is documented as always returning Unicode strings, the optional C implementation can return a bytestring. This was fixed in Python 2.7. simplejson.JSONEncoder
gained anamedtuple_as_object
keyword argument in version 2.2.
More information on these incompatibilities is available in ticket #18023.
The net result is that, if you have installed simplejson
and your code
uses Django’s serialization internals directly – for instance
django.core.serializers.json.DjangoJSONEncoder
, the switch from
simplejson
to json
could break your code. (In general, changes to
internals aren’t documented; we’re making an exception here.)
At this point, the maintainers of Django believe that using json
from
the standard library offers the strongest guarantee of backwards-compatibility.
They recommend to use it from now on.
String types of hasher method parameters¶
If you have written a custom password hasher,
your encode()
, verify()
or safe_summary()
methods should accept
Unicode parameters (password
, salt
or encoded
). If any of the
hashing methods need bytestrings, you can use the
force_bytes()
utility to encode the strings.
Validation of previous_page_number and next_page_number¶
When using object pagination,
the previous_page_number()
and next_page_number()
methods of the
Page
object did not check if the returned
number was inside the existing page range.
It does check it now and raises an InvalidPage
exception when the number is either too low or too high.
Behavior of autocommit database option on PostgreSQL changed¶
PostgreSQL’s autocommit option didn’t work as advertised previously. It did work for single transaction block, but after the first block was left the autocommit behavior was never restored. This bug is now fixed in 1.5. While this is only a bug fix, it is worth checking your applications behavior if you are using PostgreSQL together with the autocommit option.
Session not saved on 500 responses¶
Django’s session middleware will skip saving the session data if the response’s status code is 500.
Email checks on failed admin login¶
Prior to Django 1.5, if you attempted to log into the admin interface and mistakenly used your email address instead of your username, the admin interface would provide a warning advising that your email address was not your username. In Django 1.5, the introduction of custom user models has required the removal of this warning. This doesn’t change the login behavior of the admin site; it only affects the warning message that is displayed under one particular mode of login failure.
Changes in tests execution¶
Some changes have been introduced in the execution of tests that might be backward-incompatible for some testing setups:
Database flushing in django.test.TransactionTestCase
¶
Previously, the test database was truncated before each test run in a
TransactionTestCase
.
In order to be able to run unit tests in any order and to make sure they are
always isolated from each other, TransactionTestCase
will
now reset the database after each test run instead.
No more implicit DB sequences reset¶
TransactionTestCase
tests used to reset primary key
sequences automatically together with the database flushing actions described
above.
This has been changed so no sequences are implicitly reset. This can cause
TransactionTestCase
tests that depend on hard-coded
primary key values to break.
The new reset_sequences
attribute can
be used to force the old behavior for TransactionTestCase
that might need it.
Ordering of tests¶
In order to make sure all TestCase
code starts with a clean database,
tests are now executed in the following order:
- First, all unit tests (including
unittest.TestCase
,SimpleTestCase
,TestCase
andTransactionTestCase
) are run with no particular ordering guaranteed nor enforced among them. - Then any other tests (e.g. doctests) that may alter the database without restoring it to its original state are run.
This should not cause any problems unless you have existing doctests which
assume a TransactionTestCase
executed earlier left some
database state behind or unit tests that rely on some form of state being
preserved after the execution of other tests. Such tests are already very
fragile, and must now be changed to be able to run independently.
cleaned_data
dictionary kept for invalid forms¶
The cleaned_data
dictionary is now always present
after form validation. When the form doesn’t validate, it contains only the
fields that passed validation. You should test the success of the validation
with the is_valid()
method and not with the
presence or absence of the cleaned_data
attribute
on the form.
Behavior of syncdb
with multiple databases¶
syncdb
now queries the database routers to determine if content
types (when contenttypes
is enabled) and permissions
(when auth
is enabled) should be created in the target
database. Previously, it created them in the default database, even when
another database was specified with the --database
option.
If you use syncdb
on multiple databases, you should ensure that
your routers allow synchronizing content types and permissions to only one of
them. See the docs on the behavior of contrib apps with multiple
databases for more information.
XML deserializer will not parse documents with a DTD¶
In order to prevent exposure to denial-of-service attacks related to external entity references and entity expansion, the XML model deserializer now refuses to parse XML documents containing a DTD (DOCTYPE definition). Since the XML serializer does not output a DTD, this will not impact typical usage, only cases where custom-created XML documents are passed to Django’s model deserializer.
Formsets default max_num
¶
A (default) value of None
for the max_num
argument to a formset factory
no longer defaults to allowing any number of forms in the formset. Instead, in
order to prevent memory-exhaustion attacks, it now defaults to a limit of 1000
forms. This limit can be raised by explicitly setting a higher value for
max_num
.
Miscellaneous¶
django.forms.ModelMultipleChoiceField
now returns an emptyQuerySet
as the empty value instead of an empty list.int_to_base36()
properly raises aTypeError
instead ofValueError
for non-integer inputs.- The
slugify
template filter is now available as a standard Python function atdjango.utils.text.slugify()
. Similarly,remove_tags
is available atdjango.utils.html.remove_tags()
. - Uploaded files are no longer created as executable by default. If you need
them to be executable change
FILE_UPLOAD_PERMISSIONS
to your needs. The new default value is0o666
(octal) and the current umask value is first masked out. - The
F expressions
supported bitwise operators by&
and|
. These operators are now available using.bitand()
and.bitor()
instead. The removal of&
and|
was done to be consistent with Q() expressions andQuerySet
combining where the operators are used as boolean AND and OR operators. - In a
filter()
call, whenF expressions
contained lookups spanning multi-valued relations, they didn’t always reuse the same relations as other lookups along the same chain. This was changed, and now F() expressions will always use the same relations as other lookups within the samefilter()
call. - The
csrf_token
template tag is no longer enclosed in a div. If you need HTML validation against pre-HTML5 Strict DTDs, you should add a div around it in your pages. - The template tags library
adminmedia
, which only contained the deprecated template tag{% admin_media_prefix %}
, was removed. Attempting to load it with{% load adminmedia %}
will fail. If your templates still contain that line you must remove it. - Because of an implementation oversight, it was possible to use
django.contrib.redirects without enabling
django.contrib.sites. This isn’t allowed any
longer. If you’re using
django.contrib.redirects
, make sureINSTALLED_APPS
containsdjango.contrib.sites
. BoundField.label_tag
now escapes itscontents
argument. To avoid the HTML escaping, usedjango.utils.safestring.mark_safe()
on the argument before passing it.- Accessing reverse one-to-one relations fetched via
select_related()
now raisesDoesNotExist
instead of returningNone
.
Features deprecated in 1.5¶
django.contrib.localflavor
¶
The localflavor contrib app has been split into separate packages.
django.contrib.localflavor
itself will be removed in Django 1.6,
after an accelerated deprecation.
The new packages are available on GitHub. The core team cannot efficiently maintain these packages in the long term — it spans just a dozen countries at this time; similar to translations, maintenance will be handed over to interested members of the community.
django.contrib.markup
¶
The markup contrib module has been deprecated and will follow an accelerated deprecation schedule. Direct use of Python markup libraries or 3rd party tag libraries is preferred to Django maintaining this functionality in the framework.
AUTH_PROFILE_MODULE
¶
With the introduction of custom user models, there is no longer any need for a built-in mechanism to store user profile data.
You can still define user profiles models that have a one-to-one relation with
the User model - in fact, for many applications needing to associate data with
a User account, this will be an appropriate design pattern to follow. However,
the AUTH_PROFILE_MODULE
setting, and the
django.contrib.auth.models.User.get_profile()
method for accessing
the user profile model, should not be used any longer.
Streaming behavior of HttpResponse
¶
Django 1.5 deprecates the ability to stream a response by passing an iterator
to HttpResponse
. If you rely on this behavior, switch to
StreamingHttpResponse
. See
Explicit support for streaming responses above.
In Django 1.7 and above, the iterator will be consumed immediately by
HttpResponse
.
django.utils.simplejson
¶
Since Django 1.5 drops support for Python 2.5, we can now rely on the
json
module being available in Python’s standard library, so we’ve
removed our own copy of simplejson
. You should now import json
instead of django.utils.simplejson
.
Unfortunately, this change might have unwanted side-effects, because of
incompatibilities between versions of simplejson
– see the
backwards-incompatible changes section.
If you rely on features added to simplejson
after it became Python’s
json
, you should import simplejson
explicitly.
django.utils.encoding.StrAndUnicode
¶
The django.utils.encoding.StrAndUnicode
mix-in has been deprecated.
Define a __str__
method and apply the
django.utils.encoding.python_2_unicode_compatible
decorator instead.
django.utils.itercompat.product
¶
The django.utils.itercompat.product
function has been deprecated. Use
the built-in itertools.product()
instead.
cleanup
management command¶
The cleanup
management command has been deprecated and replaced by
clearsessions
.
daily_cleanup.py
script¶
The undocumented daily_cleanup.py
script has been deprecated. Use the
clearsessions
management command instead.