February 26, 2013
\nWelcome to Django 1.5!
\nThese release notes cover the new features, as well as\nsome backwards incompatible changes you’ll\nwant to be aware of when upgrading from Django 1.4 or older versions. We’ve\nalso dropped some features, which are detailed in our deprecation plan, and we’ve begun the deprecation process\nfor some features.
\nThe biggest new feature in Django 1.5 is the configurable User model. Before\nDjango 1.5, applications that wanted to use Django’s auth framework\n(django.contrib.auth) were forced to use Django’s definition of a\n“user”. In Django 1.5, you can now swap out the User model for one that you\nwrite yourself. This could be a simple extension to the existing User model\n– for example, you could add a Twitter or Facebook ID field – or you could\ncompletely 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\nthis support “experimental” because we don’t yet consider it production-ready,\nbut everything’s in place for you to start porting your apps to Python 3.\nOur next release, Django 1.6, will support Python 3 without reservations.
\nOther notable new features in Django 1.5 include:
\nSupport for saving a subset of model’s fields -\nModel.save() now accepts an\nupdate_fields argument, letting you specify which fields are\nwritten back to the database when you call save(). This can help\nin high-concurrency operations, and can improve performance.
Better support for streaming responses via\nthe 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\nmanner per our API stability policy.\nHowever, as with previous releases, Django 1.5 ships with some minor\nbackwards incompatible changes; people\nupgrading from previous versions of Django should read that list carefully.
\nOne deprecated feature worth noting is the shift to “new-style” url\ntag. Prior to Django 1.3, syntax like {% url myview %} was interpreted\nincorrectly (Django considered "myview" to be a literal name of a view, not\na template variable named myview). Django 1.3 and above introduced the {%\nload url from future %} syntax to bring in the corrected behavior where\nmyview was seen as a variable.
The upshot of this is that if you are not using {% load url from future %}\nin your templates, you’ll need to change tags like {% url myview %} to\n{% url "myview" %}. If you were using {% load url from future %} you\ncan simply remove that line under Django 1.5
Django 1.5 requires Python 2.6.5 or above, though we highly recommend\nPython 2.7.3 or above. Support for Python 2.5 and below has been dropped.
\nThis change should affect only a small number of Django users, as most\noperating-system vendors today are shipping Python 2.6 or newer as their\ndefault version. If you’re still using Python 2.5, however, you’ll need to\nstick to Django 1.4 until you can upgrade your Python version. Per our\nsupport policy, Django 1.4 will continue to\nreceive security support until the release of Django 1.6.
\nDjango 1.5 does not run on a Jython final release, because Jython’s latest\nrelease doesn’t currently support Python 2.6. However, Jython currently does\noffer an alpha release featuring 2.7 support, and Django 1.5 supports that\nalpha release.
\nDjango 1.5 introduces support for Python 3 - specifically, Python\n3.2 and above. This comes in the form of a single codebase; you don’t\nneed to install a different version of Django on Python 3. This means that\nyou can write applications targeted for just Python 2, just Python 3, or single\napplications that support both platforms.
\nHowever, we’re labeling this support “experimental” for now: although it’s\nreceived extensive testing via our automated test suite, it’s received very\nlittle real-world testing. We’ve done our best to eliminate bugs, but we can’t\nbe sure we covered all possible uses of Django.
\nSome features of Django aren’t available because they depend on third-party\nsoftware that hasn’t been ported to Python 3 yet, including:
\nthe 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\ncomponents. At this point, very few third-party applications have been ported\nto Python 3, so it’s unlikely that a real-world application will have all its\ndependencies satisfied under Python 3.
\nThus, we’re recommending that Django 1.5 not be used in production under Python\n3. Instead, use this opportunity to begin porting applications to Python 3. If\nyou’re an author of a pluggable component, we encourage you to start porting\nnow.
\nWe plan to offer first-class, production-ready support for Python 3 in our next\nrelease, Django 1.6.
\nIn Django 1.5, you can now use your own model as the store for user-related\ndata. If your project needs a username with more than 30 characters, or if\nyou want to store user’s names in a format other than first name/last name,\nor you want to put custom profile information onto your User object, you can\nnow do so.
\nIf you have a third-party reusable application that references the User model,\nyou may need to make some changes to the way you reference User instances. You\nshould also document any specific features of the User model that your\napplication relies upon.
\nSee the documentation on custom user models for\nmore details.
\nThe method Model.save() has a new\nkeyword argument update_fields. By using this argument it is possible to\nsave only a select list of model’s fields. This can be useful for performance\nreasons or when trying to avoid overwriting concurrent changes.
Deferred instances (those loaded by .only() or .defer()) will\nautomatically save just the loaded fields. If any field is set manually after\nload, that field will also get updated on save.
See the Model.save() documentation for\nmore details.
Before Django 1.5, it was possible to create a streaming response by passing\nan iterator to HttpResponse. But this was unreliable:\nany middleware that accessed the content\nattribute would consume the iterator prematurely.
You can now explicitly generate a streaming response with the new\nStreamingHttpResponse class. This class exposes a\nstreaming_content attribute which\nis an iterator.
Since StreamingHttpResponse does not have a content\nattribute, middleware that needs access to the response content must test for\nstreaming responses and behave accordingly.
{% verbatim %} template tagLink to this heading#To make it easier to deal with JavaScript templates which collide with Django’s\nsyntax, you can now use the verbatim block tag to avoid parsing the\ntag’s content.
ContentType instances associated with proxy modelsLink to this heading#The methods ContentTypeManager.get_for_model()\nand ContentTypeManager.get_for_models()\nhave a new keyword argument – respectively for_concrete_model and\nfor_concrete_models. By passing False using this argument it is now\npossible to retrieve the ContentType associated with proxy models.
view variable in class-based views contextLink to this heading#In all generic class-based views\n(or any class-based view inheriting from ContextMixin), the context\ndictionary contains a view variable that points to the View instance.
LineString and\nMultiLineString GEOS objects now support\nthe interpolate() and\nproject() methods (so-called\nlinear referencing).
The wkb and hex properties of\nGEOSGeometry objects preserve the Z\ndimension.
Support for PostGIS 2.0 has been added and support for GDAL < 1.5 has been\ndropped.
Additions to the docs include a revamped Tutorial 3\nand a new tutorial on testing. A new section,\n“Advanced Tutorials”, offers How to write reusable apps as well as a step-by-step guide for new contributors in\nWriting your first patch for Django.
\nDjango 1.5 also includes several smaller improvements worth noting:
\nThe template engine now interprets True, False and None as the\ncorresponding Python objects.
django.utils.timezone provides a helper for converting aware\ndatetimes between time zones. See localtime().
The generic views support OPTIONS requests.
Management commands do not raise SystemExit any more when called by code\nfrom call_command(). Any exception raised by\nthe command (mostly CommandError) is\npropagated.
Moreover, when you output errors or messages in your custom commands, you\nshould now use self.stdout.write('message') and\nself.stderr.write('error') (see the note on\nmanagement commands output).
The dumpdata management command outputs one row at a time,\npreventing out-of-memory errors when dumping large datasets.
In the localflavor for Canada, pq was added to the acceptable codes for\nQuebec. It’s an old abbreviation.
The receiver decorator is now able to\nconnect 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\nargument. By default the batch_size is unlimited except for SQLite where\nsingle batch is limited so that 999 parameters per query isn’t exceeded.
The LOGIN_URL and LOGIN_REDIRECT_URL settings now also\naccept view function names and\nnamed URL patterns. This allows you to reduce\nconfiguration duplication. More information can be found in the\nlogin_required() documentation.
Django now provides a mod_wsgi auth handler.
The QuerySet.delete()\nand Model.delete() can now take\nfast-path in some cases. The fast-path allows for less queries and less\nobjects fetched into memory. See QuerySet.delete() for details.
An instance of ResolverMatch is stored on the request as\nresolver_match.
By default, all logging messages reaching the django logger when\nDEBUG is True are sent to the console (unless you redefine the\nlogger in your LOGGING setting).
When using RequestContext, it is now possible to\nlook up permissions by using {% if 'someapp.someperm' in perms %}\nin templates.
It’s not required any more to have 404.html and 500.html templates in\nthe root templates directory. Django will output some basic error messages\nfor both situations when those templates are not found. It’s still\nrecommended as good practice to provide those templates in order to present\npretty error pages to the user.
django.contrib.auth provides a new signal that is emitted\nwhenever a user fails to login successfully. See\nuser_login_failed
The new loaddata --ignorenonexistent option ignore data for fields\nthat no longer exist.
assertXMLEqual() and\nassertXMLNotEqual() new assertions allow\nyou to test equality for XML content at a semantic level, without caring for\nsyntax differences (spaces, attribute order, etc.).
RemoteUserMiddleware now forces logout when the REMOTE_USER header\ndisappears during the same browser session.
The cache-based session backend can store\nsession data in a non-default cache.
Multi-column indexes can now be created on models. Read the\nindex_together documentation for more information.
During Django’s logging configuration verbose Deprecation warnings are\nenabled and warnings are captured into the logging system. Logged warnings\nare routed through the console logging handler, which by default requires\nDEBUG to be True for output to be generated. The result is that\nDeprecationWarnings should be printed to the console in development\nenvironments the way they have been in Python versions < 2.7.
The API for django.contrib.admin.ModelAdmin.message_user() method has\nbeen modified to accept additional arguments adding capabilities similar to\ndjango.contrib.messages.add_message(). This is useful for generating\nerror messages from admin actions.
The admin’s list filters can now be customized per-request thanks to the new\ndjango.contrib.admin.ModelAdmin.get_list_filter() method.
ALLOWED_HOSTS required in productionLink to this heading#The new ALLOWED_HOSTS setting validates the request’s Host\nheader and protects against host-poisoning attacks. This setting is now\nrequired whenever DEBUG is False, or else\ndjango.http.HttpRequest.get_host() will raise\nSuspiciousOperation. For more details see the\nfull documentation for the new setting.
Abstract models are able to define a custom manager, and that manager\nwill be inherited by any concrete models extending the abstract model. However, if you try to use the abstract\nmodel to call a method on the manager, an exception will now be raised.\nPreviously, the call would have been permitted, but would have failed as soon\nas any database operation was attempted (usually with a “table does not exist”\nerror from the database).
\nIf you have functionality on a manager that you have been invoking using\nthe abstract class, you should migrate that logic to a Python\nstaticmethod or classmethod on the abstract class.
For consistency with the other date-based generic views,\nYearArchiveView now passes year in\nthe context as a datetime.date rather than a string. If you are\nusing {{ year }} in your templates, you must replace it with {{\nyear|date:"Y" }}.
next_year and previous_year were also added in the context. They are\ncalculated according to allow_empty and allow_future.
YearArchiveView and\nMonthArchiveView were documented to\nprovide a date_list sorted in ascending order in the context, like their\nfunction-based predecessors, but it actually was in descending order. In 1.5,\nthe documented order was restored. You may want to add (or remove) the\nreversed keyword when you’re iterating on date_list in a template:
{% for date in date_list reversed %}\nArchiveIndexView still provides a\ndate_list in descending order.
For consistency with the design of the other generic views,\nTemplateView no longer passes a params\ndictionary into the context, instead passing the variables from the URLconf\ndirectly into the context.
request.POST will no longer include data\nposted via HTTP requests with non form-specific content-types in the header. In\nprior versions, data posted with content-types other than\nmultipart/form-data or\napplication/x-www-form-urlencoded would still end up represented in\nthe request.POST attribute. Developers\nwishing to access the raw POST data for these cases, should use the\nrequest.body attribute instead.
request_finished signalLink to this heading#Django used to send the request_finished signal\nas soon as the view function returned a response. This interacted badly with\nstreaming responses that delay content\ngeneration.
This signal is now sent after the content is fully consumed by the WSGI\ngateway. This might be backwards incompatible if you rely on the signal being\nfired before sending the response content to the client. If you do, you should\nconsider using middleware instead.
\n\nUnlike GET and POST, these HTTP methods aren’t implemented by web browsers.\nRather, they’re used in APIs, which transfer data in various formats such as\nJSON or XML. Since such requests may contain arbitrary data, Django doesn’t\nattempt to decode their body.
\nHowever, the test client used to build a query string for OPTIONS and DELETE\nrequests like for GET, and a request body for PUT requests like for POST. This\nencoding was arbitrary and inconsistent with Django’s behavior when it\nreceives the requests, so it was removed in Django 1.5.
\nIf you were using the data parameter in an OPTIONS or a DELETE request,\nyou 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\ncontent_type, you must encode your data before passing it to the test\nclient and set the content_type argument.
simplejson no longer usedLink to this heading#As explained below, Django 1.5 deprecates\ndjango.utils.simplejson in favor of Python 2.6’s built-in json\nmodule. In theory, this change is harmless. Unfortunately, because of\nincompatibilities between versions of simplejson, it may trigger errors\nin some circumstances.
JSON-related features in Django 1.4 always used django.utils.simplejson.\nThis module was actually:
A system version of simplejson, if one was available (i.e. import\nsimplejson works), if it was more recent than Django’s built-in copy or it\nhad the C speedups, or
The json module from the standard library, if it was available (i.e.\nPython 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\non version 2.0.9 of simplejson.
There are no known incompatibilities between Django’s copy of version 2.0.7 and\nPython’s copy of version 2.0.9. However, there are some incompatibilities\nbetween other versions of simplejson:
While the simplejson API is documented as always returning Unicode\nstrings, the optional C implementation can return a bytestring. This was\nfixed in Python 2.7.
simplejson.JSONEncoder gained a namedtuple_as_object keyword\nargument in version 2.2.
More information on these incompatibilities is available in\nticket #18023.
\nThe net result is that, if you have installed simplejson and your code\nuses Django’s serialization internals directly – for instance\ndjango.core.serializers.json.DjangoJSONEncoder, the switch from\nsimplejson to json could break your code. (In general, changes to\ninternals aren’t documented; we’re making an exception here.)
At this point, the maintainers of Django believe that using json from\nthe standard library offers the strongest guarantee of backwards-compatibility.\nThey recommend to use it from now on.
If you have written a custom password hasher,\nyour encode(), verify() or safe_summary() methods should accept\nUnicode parameters (password, salt or encoded). If any of the\nhashing methods need bytestrings, you can use the\nforce_bytes() utility to encode the strings.
When using object pagination,\nthe previous_page_number() and next_page_number() methods of the\nPage object did not check if the returned\nnumber was inside the existing page range.\nIt does check it now and raises an InvalidPage\nexception when the number is either too low or too high.
PostgreSQL’s autocommit option didn’t work as advertised previously. It did\nwork for single transaction block, but after the first block was left the\nautocommit behavior was never restored. This bug is now fixed in 1.5. While\nthis is only a bug fix, it is worth checking your applications behavior if\nyou are using PostgreSQL together with the autocommit option.
\nDjango’s session middleware will skip saving the session data if the\nresponse’s status code is 500.
\nPrior to Django 1.5, if you attempted to log into the admin interface and\nmistakenly used your email address instead of your username, the admin\ninterface would provide a warning advising that your email address was\nnot your username. In Django 1.5, the introduction of\ncustom user models has required the removal of this\nwarning. This doesn’t change the login behavior of the admin site; it only\naffects the warning message that is displayed under one particular mode of\nlogin failure.
\nSome changes have been introduced in the execution of tests that might be\nbackward-incompatible for some testing setups:
\ndjango.test.TransactionTestCaseLink to this heading#Previously, the test database was truncated before each test run in a\nTransactionTestCase.
In order to be able to run unit tests in any order and to make sure they are\nalways isolated from each other, TransactionTestCase will\nnow reset the database after each test run instead.
TransactionTestCase tests used to reset primary key\nsequences automatically together with the database flushing actions described\nabove.
This has been changed so no sequences are implicitly reset. This can cause\nTransactionTestCase tests that depend on hardcoded\nprimary key values to break.
The new reset_sequences attribute can\nbe used to force the old behavior for TransactionTestCase\nthat might need it.
In order to make sure all TestCase code starts with a clean database,\ntests are now executed in the following order:
First, all unit tests (including unittest.TestCase,\nSimpleTestCase, TestCase and\nTransactionTestCase) are run with no particular\nordering guaranteed nor enforced among them.
Then any other tests (e.g. doctests) that may alter the database without\nrestoring it to its original state are run.
This should not cause any problems unless you have existing doctests which\nassume a TransactionTestCase executed earlier left some\ndatabase state behind or unit tests that rely on some form of state being\npreserved after the execution of other tests. Such tests are already very\nfragile, and must now be changed to be able to run independently.
cleaned_data dictionary kept for invalid formsLink to this heading#The cleaned_data dictionary is now always present\nafter form validation. When the form doesn’t validate, it contains only the\nfields that passed validation. You should test the success of the validation\nwith the is_valid() method and not with the\npresence or absence of the cleaned_data attribute\non the form.
syncdb with multiple databasesLink to this heading#syncdb now queries the database routers to determine if content\ntypes (when contenttypes is enabled) and permissions\n(when auth is enabled) should be created in the target\ndatabase. Previously, it created them in the default database, even when\nanother database was specified with the --database option.
If you use syncdb on multiple databases, you should ensure that\nyour routers allow synchronizing content types and permissions to only one of\nthem. See the docs on the behavior of contrib apps with multiple\ndatabases for more information.
In order to prevent exposure to denial-of-service attacks related to external\nentity references and entity expansion, the XML model deserializer now refuses\nto parse XML documents containing a DTD (DOCTYPE definition). Since the XML\nserializer does not output a DTD, this will not impact typical usage, only\ncases where custom-created XML documents are passed to Django’s model\ndeserializer.
\nmax_numLink to this heading#A (default) value of None for the max_num argument to a formset factory\nno longer defaults to allowing any number of forms in the formset. Instead, in\norder to prevent memory-exhaustion attacks, it now defaults to a limit of 1000\nforms. This limit can be raised by explicitly setting a higher value for\nmax_num.
django.forms.ModelMultipleChoiceField now returns an empty\nQuerySet as the empty value instead of an empty list.
int_to_base36() properly raises a\nTypeError instead of ValueError for non-integer inputs.
The slugify template filter is now available as a standard Python\nfunction at django.utils.text.slugify(). Similarly, remove_tags is\navailable at django.utils.html.remove_tags().
Uploaded files are no longer created as executable by default. If you need\nthem to be executable change FILE_UPLOAD_PERMISSIONS to your\nneeds. The new default value is 0o666 (octal) and the current umask value\nis first masked out.
The F expressions supported bitwise operators\nby & and |. These operators are now available using .bitand() and\n.bitor() instead. The removal of & and | was done to be\nconsistent with Q() expressions and\nQuerySet combining where the operators are used as boolean AND and OR\noperators.
In a filter() call, when F expressions\ncontained lookups spanning multi-valued relations, they didn’t always reuse\nthe same relations as other lookups along the same chain. This was changed,\nand now F() expressions will always use the same relations as other lookups\nwithin the same filter() call.
The csrf_token template tag is no longer enclosed in a div. If you\nneed HTML validation against pre-HTML5 Strict DTDs, you should add a div\naround it in your pages.
The template tags library adminmedia, which only contained the\ndeprecated template tag {% admin_media_prefix %}, was removed.\nAttempting to load it with {% load adminmedia %} will fail. If your\ntemplates still contain that line you must remove it.
Because of an implementation oversight, it was possible to use\ndjango.contrib.redirects without enabling\ndjango.contrib.sites. This isn’t allowed any\nlonger. If you’re using django.contrib.redirects, make sure\nINSTALLED_APPS contains django.contrib.sites.
BoundField.label_tag now\nescapes its contents argument. To avoid the HTML escaping, use\ndjango.utils.safestring.mark_safe() on the argument before passing it.
Accessing reverse one-to-one relations fetched via\nselect_related() now raises\nDoesNotExist instead of returning None.
django.contrib.localflavorLink to this heading#The localflavor contrib app has been split into separate packages.\ndjango.contrib.localflavor itself will be removed in Django 1.6,\nafter an accelerated deprecation.
The new packages are available on GitHub. The core team cannot\nefficiently maintain these packages in the long term — it spans just a\ndozen countries at this time; similar to translations, maintenance\nwill be handed over to interested members of the community.
\ndjango.contrib.markupLink to this heading#The markup contrib module has been deprecated and will follow an accelerated\ndeprecation schedule. Direct use of Python markup libraries or 3rd party tag\nlibraries is preferred to Django maintaining this functionality in the\nframework.
\nAUTH_PROFILE_MODULELink to this heading#With the introduction of custom user models, there is\nno longer any need for a built-in mechanism to store user profile data.
\nYou can still define user profiles models that have a one-to-one relation with\nthe User model - in fact, for many applications needing to associate data with\na User account, this will be an appropriate design pattern to follow. However,\nthe AUTH_PROFILE_MODULE setting, and the\ndjango.contrib.auth.models.User.get_profile() method for accessing\nthe user profile model, should not be used any longer.
HttpResponseLink to this heading#Django 1.5 deprecates the ability to stream a response by passing an iterator\nto HttpResponse. If you rely on this behavior, switch to\nStreamingHttpResponse. See\nExplicit support for streaming responses above.
In Django 1.7 and above, the iterator will be consumed immediately by\nHttpResponse.
django.utils.simplejsonLink to this heading#Since Django 1.5 drops support for Python 2.5, we can now rely on the\njson module being available in Python’s standard library, so we’ve\nremoved our own copy of simplejson. You should now import json\ninstead of django.utils.simplejson.
Unfortunately, this change might have unwanted side-effects, because of\nincompatibilities between versions of simplejson – see the\nbackwards-incompatible changes section.\nIf you rely on features added to simplejson after it became Python’s\njson, you should import simplejson explicitly.
django.utils.encoding.StrAndUnicodeLink to this heading#The django.utils.encoding.StrAndUnicode mix-in has been deprecated.\nDefine a __str__ method and apply the\ndjango.utils.encoding.python_2_unicode_compatible decorator instead.
django.utils.itercompat.productLink to this heading#The django.utils.itercompat.product function has been deprecated. Use\nthe built-in itertools.product() instead.
cleanup management commandLink to this heading#The cleanup management command has been deprecated and replaced by\nclearsessions.
daily_cleanup.py scriptLink to this heading#The undocumented daily_cleanup.py script has been deprecated. Use the\nclearsessions management command instead.