March 23, 2011
\nWelcome to Django 1.3!
\nNearly a year in the making, Django 1.3 includes quite a few new features and plenty of bug fixes and improvements to existing features.\nThese release notes cover the new features in 1.3, as well as some\nbackwards-incompatible changes\nyou’ll want to be aware of when upgrading from Django 1.2 or older versions.
\nDjango 1.3’s focus has mostly been on resolving smaller, long-standing\nfeature requests, but that hasn’t prevented a few fairly significant\nnew features from landing, including:
\nA framework for writing class-based views.
Built-in support for using Python’s logging facilities.
Contrib support for easy handling of static files.
Django’s testing framework now supports (and ships with a copy of)\nthe unittest2 library.
Wherever possible, new features are introduced in a backwards-compatible manner\nper our API stability policy policy. As a result\nof this policy, Django 1.3 begins the deprecation process for some\nfeatures.
\nThe release of Django 1.2 was notable for having the first shift in\nDjango’s Python compatibility policy; prior to Django 1.2, Django\nsupported any 2.x version of Python from 2.3 up. As of Django 1.2, the\nminimum requirement was raised to Python 2.4.
\nDjango 1.3 continues to support Python 2.4, but will be the final\nDjango release series to do so; beginning with Django 1.4, the minimum\nsupported Python version will be 2.5. A document outlining our full\ntimeline for deprecating Python 2.x and moving to Python 3.x will be\npublished shortly after the release of Django 1.3.
\nDjango 1.3 adds a framework that allows you to use a class as a view.\nThis means you can compose a view out of a collection of methods that\ncan be subclassed and overridden to provide common views of data without\nhaving to write too much code.
\nAnalogs of all the old function-based generic views have been\nprovided, along with a completely generic view base class that can be\nused as the basis for reusable applications that can be easily\nextended.
\nSee the documentation on class-based generic views for more details. There is also a document\nto help you convert your function-based generic views to class-based views.
\nDjango 1.3 adds framework-level support for Python’s logging\nmodule. This means you can now easily configure and control logging\nas part of your Django project. A number of logging handlers and\nlogging calls have been added to Django’s own code as well – most\nnotably, the error emails sent on an HTTP 500 server error are now\nhandled as a logging activity. See the documentation on Django’s\nlogging interface for more details.
Django 1.3 ships with a new contrib app –\ndjango.contrib.staticfiles – to help developers handle the static\nmedia files (images, CSS, JavaScript, etc.) that are needed to render\na complete web page.
In previous versions of Django, it was common to place static assets\nin MEDIA_ROOT along with user-uploaded files, and serve\nthem both at MEDIA_URL. Part of the purpose of introducing\nthe staticfiles app is to make it easier to keep static files\nseparate from user-uploaded files. Static assets should now go in\nstatic/ subdirectories of your apps or in other static assets\ndirectories listed in STATICFILES_DIRS, and will be served\nat STATIC_URL.
See the reference documentation of the app\nfor more details or learn how to manage static files.
\nunittest2 supportLink to this heading#Python 2.7 introduced some major changes to the unittest library,\nadding some extremely useful features. To ensure that every Django\nproject can benefit from these new features, Django ships with a copy\nof unittest2, a copy of the Python 2.7 unittest library,\nbackported for Python 2.4 compatibility.
To access this library, Django provides the django.utils.unittest\nmodule alias. If you are using Python 2.7, or you have installed\nunittest2 locally, Django will map the alias to the installed\nversion of the unittest library. Otherwise, Django will use its own\nbundled version of unittest2.
To take advantage of this alias, simply use:
\nfrom django.utils import unittest\nwherever you would have historically used:
\nimport unittest\nIf you want to continue to use the base unittest library, you can –\nyou just won’t get any of the nice new unittest2 features.
Users of Python 2.5 and above may now use transaction management functions as\ncontext managers. For example:
\nwith transaction.autocommit():\n ...\nForeignKey and\nOneToOneField now accept an\non_delete argument to customize behavior\nwhen the referenced object is deleted. Previously, deletes were always\ncascaded; available alternatives now include set null, set default, set to any\nvalue, protect, or do nothing.
For more information, see the on_delete\ndocumentation.
For translation strings with ambiguous meaning, you can now\nuse the pgettext function to specify the context of the string.
And if you just want to add some information for translators, you\ncan also add special translator comments in the source.
\nFor more information, see Contextual markers and\nComments for translators.
\nIt can sometimes be beneficial to allow decorators or middleware to\nmodify a response after it has been constructed by the view. For\nexample, you may want to change the template that is used, or put\nadditional data into the context.
\nHowever, you can’t (easily) modify the content of a basic\nHttpResponse after it has been constructed. To\novercome this limitation, Django 1.3 adds a new\nTemplateResponse class. Unlike basic\nHttpResponse objects,\nTemplateResponse objects retain the details\nof the template and context that was provided by the view to compute\nthe response. The final output of the response is not computed until\nit is needed, later in the response process.
For more details, see the documentation\non the TemplateResponse class.
Django 1.3 sees the introduction of several improvements to the\nDjango’s caching infrastructure.
\nFirstly, Django now supports multiple named caches. In the same way\nthat Django 1.2 introduced support for multiple database connections,\nDjango 1.3 allows you to use the new CACHES setting to\ndefine multiple named cache connections.
Secondly, versioning, site-wide\nprefixing and transformation have been added to the cache API.
\nThirdly, cache key creation has been\nupdated to take the request query string into account on GET\nrequests.
Finally, support for pylibmc has been added to the memcached cache\nbackend.
\nFor more details, see the documentation on\ncaching in Django.
\nIf you provide a custom auth backend with supports_inactive_user\nset to True, an inactive User instance will check the backend\nfor permissions. This is useful for further centralizing the\npermission handling. See the authentication docs\nfor more details.
The GeoDjango test suite is now included when\nrunning the Django test suite with runtests.py\nwhen using spatial database backends.
MEDIA_URL and STATIC_URL must end in a slashLink to this heading#Previously, the MEDIA_URL setting only required a trailing slash if\nit contained a suffix beyond the domain name.
A trailing slash is now required for MEDIA_URL and the new\nSTATIC_URL setting as long as it is not blank. This ensures there is\na consistent way to combine paths in templates.
Project settings which provide either of both settings without a trailing\nslash will now raise a PendingDeprecationWarning.
In Django 1.4 this same condition will raise DeprecationWarning,\nand in Django 1.5 will raise an ImproperlyConfigured exception.
Django 1.1 and 1.2 added\nlots of big ticket items to Django, like multiple-database support,\nmodel validation, and a session-based messages framework. However,\nthis focus on big features came at the cost of lots of smaller\nfeatures.
\nTo compensate for this, the focus of the Django 1.3 development\nprocess has been on adding lots of smaller, long standing feature\nrequests. These include:
\nImproved tools for accessing and manipulating the current\nSite object in\nthe sites framework.
A RequestFactory for mocking requests\nin tests.
A new test assertion –\nassertNumQueries() – making it\neasier to test the database activity associated with a view.
Support for lookups spanning relations in admin’s\nlist_filter.
Support for HttpOnly cookies.
mail_admins() and\nmail_managers() now support easily attaching\nHTML content to messages.
EmailMessage now supports CC’s.
Error emails now include more of the detail and formatting of the\ndebug server error page.
simple_tag() now accepts a\ntakes_context argument, making it easier to write simple\ntemplate tags that require access to template context.
A new render() shortcut – an alternative\nto django.shortcuts.render_to_response() providing a\nRequestContext by default.
Support for combining F expressions\nwith timedelta values when retrieving or updating database values.
Prior to Django 1.2.5, Django’s CSRF-prevention system exempted AJAX\nrequests from CSRF verification; due to security issues reported to\nus, however, all requests are now subjected to CSRF\nverification. Consult the Django CSRF documentation for details on how to handle CSRF verification in\nAJAX requests.
\nPrior to Django 1.2.5, the Django administrative interface allowed\nfiltering on any model field or relation – not just those specified\nin list_filter – via query string manipulation. Due to security\nissues reported to us, however, query string lookup arguments in the\nadmin must be for fields or relations specified in list_filter or\ndate_hierarchy.
In earlier Django versions, when a model instance containing a\nFileField was deleted,\nFileField took it upon itself to also delete the\nfile from the backend storage. This opened the door to several data-loss\nscenarios, including rolled-back transactions and fields on different models\nreferencing the same file. In Django 1.3, when a model is deleted the\nFileField’s delete() method won’t be called. If\nyou need cleanup of orphaned files, you’ll need to handle it yourself (for\ninstance, with a custom management command that can be run manually or\nscheduled to run periodically via e.g. cron).
The PasswordInput form widget, intended for use\nwith form fields which represent passwords, accepts a boolean keyword\nargument render_value indicating whether to send its data back to\nthe browser when displaying a submitted form with errors. Prior to\nDjango 1.3, this argument defaulted to True, meaning that the\nsubmitted password would be sent back to the browser as part of the\nform. Developers who wished to add a bit of additional security by\nexcluding that value from the redisplayed form could instantiate a\nPasswordInput passing render_value=False .
Due to the sensitive nature of passwords, however, Django 1.3 takes\nthis step automatically; the default value of render_value is now\nFalse, and developers who want the password value returned to the\nbrowser on a submission with errors (the previous behavior) must now\nexplicitly indicate this. For example:
class LoginForm(forms.Form):\n username = forms.CharField(max_length=100)\n password = forms.CharField(widget=forms.PasswordInput(render_value=True))\nDjango 1.3 now includes a ClearableFileInput form widget\nin addition to FileInput. ClearableFileInput renders\nwith a checkbox to clear the field’s value (if the field has a value and is not\nrequired); FileInput provided no means for clearing an existing file from\na FileField.
ClearableFileInput is now the default widget for a FileField, so\nexisting forms including FileField without assigning a custom widget will\nneed to account for the possible extra checkbox in the rendered form output.
To return to the previous rendering (without the ability to clear the\nFileField), use the FileInput widget in place of\nClearableFileInput. For instance, in a ModelForm for a hypothetical\nDocument model with a FileField named document:
from django import forms\nfrom myapp.models import Document\n\n\nclass DocumentForm(forms.ModelForm):\n class Meta:\n model = Document\n widgets = {"document": forms.FileInput}\nPrior to Django 1.3, the database table used by the database backend\nfor the sessions app had no index on\nthe expire_date column. As a result, date-based queries on the\nsession table – such as the query that is needed to purge old\nsessions – would be very slow if there were lots of sessions.
If you have an existing project that is using the database session\nbackend, you don’t have to do anything to accommodate this change.\nHowever, you may get a significant performance boost if you manually\nadd the new index to the session table. The SQL that will add the\nindex can be found by running the sqlindexes admin command:
python manage.py sqlindexes sessions\nDjango has historically provided (and enforced) a list of profanities.\nThe comments app has enforced this list of profanities, preventing people from\nsubmitting comments that contained one of those profanities.
\nUnfortunately, the technique used to implement this profanities list\nwas woefully naive, and prone to the Scunthorpe problem. Improving\nthe built-in filter to fix this problem would require significant\neffort, and since natural language processing isn’t the normal domain\nof a web framework, we have “fixed” the problem by making the list of\nprohibited words an empty list.
\nIf you want to restore the old behavior, simply put a\nPROFANITIES_LIST setting in your settings file that includes the\nwords that you want to prohibit (see the commit that implemented this\nchange if you want to see the list\nof words that was historically prohibited). However, if avoiding profanities is\nimportant to you, you would be well advised to seek out a better, less naive\napproach to the problem.
Django 1.3 introduces the following backwards-incompatible changes to\nlocal flavors:
\nCanada (ca) – The province “Newfoundland and Labrador” has had its\nprovince code updated to “NL”, rather than the older “NF”. In\naddition, the Yukon Territory has had its province code corrected to\n“YT”, instead of “YK”.
Indonesia (id) – The province “Nanggroe Aceh Darussalam (NAD)” has\nbeen removed from the province list in favor of the new official\ndesignation “Aceh (ACE)”.
United States of America (us) – The list of “states” used by\nUSStateField has expanded to include Armed Forces postal\ncodes. This is backwards-incompatible if you were relying on\nUSStateField not including them.
In Django 1.3 FormSet creation behavior is modified slightly. Historically\nthe class didn’t make a distinction between not being passed data and being\npassed empty dictionary. This was inconsistent with behavior in other parts of\nthe framework. Starting with 1.3 if you pass in empty dictionary the\nFormSet will raise a ValidationError.
For example with a FormSet:
>>> class ArticleForm(Form):\n... title = CharField()\n... pub_date = DateField()\n...\n>>> ArticleFormSet = formset_factory(ArticleForm)\nthe following code will raise a ValidationError:
>>> ArticleFormSet({})\nTraceback (most recent call last):\n...\nValidationError: [u'ManagementForm data is missing or has been tampered with']\nif you need to instantiate an empty FormSet, don’t pass in the data or use\nNone:
>>> formset = ArticleFormSet()\n>>> formset = ArticleFormSet(data=None)\nPreviously, a callable in a template would only be called automatically as part\nof the variable resolution process if it was retrieved via attribute\nlookup. This was an inconsistency that could result in confusing and unhelpful\nbehavior:
\n>>> Template("{{ user.get_full_name }}").render(Context({"user": user}))\nu'Joe Bloggs'\n>>> Template("{{ full_name }}").render(Context({"full_name": user.get_full_name}))\nu'<bound method User.get_full_name of <...\nThis has been resolved in Django 1.3 - the result in both cases will be u'Joe\nBloggs'. Although the previous behavior was not useful for a template\nlanguage designed for web designers, and was never deliberately supported, it\nis possible that some templates may be broken by this change.
Django provides a custom SQL hooks as a way to inject hand-crafted SQL\ninto the database synchronization process. One of the possible uses\nfor this custom SQL is to insert data into your database. If your\ncustom SQL contains INSERT statements, those insertions will be\nperformed every time your database is synchronized. This includes the\nsynchronization of any test databases that are created when you run a\ntest suite.
However, in the process of testing the Django 1.3, it was discovered\nthat this feature has never completely worked as advertised. When\nusing database backends that don’t support transactions, or when using\na TransactionTestCase, data that has been inserted using custom SQL\nwill not be visible during the testing process.
\nUnfortunately, there was no way to rectify this problem without\nintroducing a backwards incompatibility. Rather than leave\nSQL-inserted initial data in an uncertain state, Django now enforces\nthe policy that data inserted by custom SQL will not be visible\nduring testing.
\nThis change only affects the testing process. You can still use custom\nSQL to load data into your production database as part of the syncdb\nprocess. If you require data to exist during test conditions, you\nshould either insert it using test fixtures, or using the setUp() method of your\ntest case.
Work has been done to simplify, rationalize and properly document the algorithm\nused by Django at runtime to build translations from the different translations\nfound on disk, namely:
\nFor translatable literals found in Python code and templates ('django'\ngettext domain):
Priorities of translations included with applications listed in the\nINSTALLED_APPS setting were changed. To provide a behavior\nconsistent with other parts of Django that also use such setting (templates,\netc.) now, when building the translation that will be made available, the\napps listed first have higher precedence than the ones listed later.
Now it is possible to override the translations shipped with applications by\nusing the LOCALE_PATHS setting whose translations have now higher\nprecedence than the translations of INSTALLED_APPS applications.\nThe relative priority among the values listed in this setting has also been\nmodified so the paths listed first have higher precedence than the\nones listed later.
The locale subdirectory of the directory containing the settings, that\nusually coincides with and is known as the project directory is being\ndeprecated in this release as a source of translations. (the precedence of\nthese translations is intermediate between applications and\nLOCALE_PATHS translations). See the corresponding deprecated\nfeatures section of this document.
For translatable literals found in JavaScript code ('djangojs' gettext\ndomain):
Similarly to the 'django' domain translations: Overriding of\ntranslations shipped with applications by using the LOCALE_PATHS\nsetting is now possible for this domain too. These translations have higher\nprecedence than the translations of Python packages passed to the\njavascript_catalog() view. Paths listed first have higher precedence than\nthe ones listed later.
Translations under the locale subdirectory of the project directory\nhave never been taken in account for JavaScript translations and remain in\nthe same situation considering the deprecation of such location.
When using managed transactions – that is, anything but the default\nautocommit mode – it is important when a transaction is marked as\n“dirty”. Dirty transactions are committed by the commit_on_success\ndecorator or the django.middleware.transaction.TransactionMiddleware, and\ncommit_manually forces them to be closed explicitly; clean transactions\n“get a pass”, which means they are usually rolled back at the end of a request\nwhen the connection is closed.
Until Django 1.3, transactions were only marked dirty when Django was\naware of a modifying operation performed in them; that is, either some\nmodel was saved, some bulk update or delete was performed, or the user\nexplicitly called transaction.set_dirty(). In Django 1.3, a\ntransaction is marked dirty when any database operation is\nperformed.
As a result of this change, you no longer need to set a transaction\ndirty explicitly when you execute raw SQL or use a data-modifying\nSELECT. However, you do need to explicitly close any read-only\ntransactions that are being managed using commit_manually(). For example:
@transaction.commit_manually\ndef my_view(request, name):\n obj = get_object_or_404(MyObject, name__iexact=name)\n return render_to_response("template", {"object": obj})\nPrior to Django 1.3, this would work without error. However, under\nDjango 1.3, this will raise a\nTransactionManagementError because\nthe read operation that retrieves the MyObject instance leaves the\ntransaction in a dirty state.
Prior to Django 1.3, inactive users were able to request a password reset email\nand reset their password. In Django 1.3 inactive users will receive the same\nmessage as a nonexistent account.
\nfrom_emailLink to this heading#The django.contrib.auth.views.password_reset() view now accepts a\nfrom_email parameter, which is passed to the password_reset_form’s\nsave() method as a keyword argument. If you are using this view with a\ncustom password reset form, then you will need to ensure your form’s save()\nmethod accepts this keyword argument.
Django 1.3 deprecates some features from earlier releases.\nThese features are still supported, but will be gradually phased out\nover the next few release cycles.
\nCode taking advantage of any of the features below will raise a\nPendingDeprecationWarning in Django 1.3. This warning will be\nsilent by default, but may be turned on using Python’s warnings\nmodule, or by running Python with a -Wd or -Wall flag.
In Django 1.4, these warnings will become a DeprecationWarning,\nwhich is not silent. In Django 1.5 support for these features will\nbe removed entirely.
mod_python supportLink to this heading#The mod_python library has not had a release since 2007 or a commit since\n2008. The Apache Foundation board voted to remove mod_python from the set\nof active projects in its version control repositories, and its lead developer\nhas shifted all of his efforts toward the lighter, slimmer, more stable, and\nmore flexible mod_wsgi backend.
If you are currently using the mod_python request handler, you\nshould redeploy your Django projects using another request handler.\nmod_wsgi is the request handler\nrecommended by the Django project, but FastCGI is also supported. Support for\nmod_python deployment will be removed in Django 1.5.
As a result of the introduction of class-based generic views, the\nfunction-based generic views provided by Django have been deprecated.\nThe following modules and the views they contain have been deprecated:
\ndjango.views.generic.create_update
django.views.generic.date_based
django.views.generic.list_detail
django.views.generic.simple
template attributeLink to this heading#Django’s test client returns\nResponse objects annotated with extra testing\ninformation. In Django versions prior to 1.3, this included a template\nattribute containing information about templates rendered in generating the\nresponse: either None, a single Template object, or a\nlist of Template objects. This inconsistency in\nreturn values (sometimes a list, sometimes not) made the attribute difficult\nto work with.
In Django 1.3 the template attribute is deprecated in favor of a new\ntemplates attribute, which is always a\nlist, even if it has only a single element or no elements.
DjangoTestRunnerLink to this heading#As a result of the introduction of support for unittest2, the features\nof django.test.simple.DjangoTestRunner (including fail-fast\nand Ctrl-C test termination) have been made redundant. In view of this\nredundancy, DjangoTestRunner has been turned into an empty placeholder\nclass, and will be removed entirely in Django 1.5.
url and ssiLink to this heading#Most template tags will allow you to pass in either constants or\nvariables as arguments – for example:
\n{% extends "base.html" %}\nallows you to specify a base template as a constant, but if you have a\ncontext variable templ that contains the value base.html:
{% extends templ %}\nis also legal.
\nHowever, due to an accident of history, the url and ssi are different.\nThese tags use the second, quoteless syntax, but interpret the argument as a\nconstant. This means it isn’t possible to use a context variable as the target\nof a url and ssi tag.
Django 1.3 marks the start of the process to correct this historical\naccident. Django 1.3 adds a new template library – future – that\nprovides alternate implementations of the url and ssi\ntemplate tags. This future library implement behavior that makes\nthe handling of the first argument consistent with the handling of all\nother variables. So, an existing template that contains:
{% url sample %}\nshould be replaced with:
\n{% load url from future %}\n{% url 'sample' %}\nThe tags implementing the old behavior have been deprecated, and in\nDjango 1.5, the old behavior will be replaced with the new behavior.\nTo ensure compatibility with future versions of Django, existing\ntemplates should be modified to use the new future libraries and\nsyntax.
In previous version the admin app defined login methods in multiple locations\nand ignored the almost identical implementation in the already used auth app.\nA side effect of this duplication was the missing adoption of the changes made\nin r12634 to support a\nbroader set of characters for usernames.
\nThis release refactors the admin’s login mechanism to use a subclass of the\nAuthenticationForm instead of a manual\nform validation. The previously undocumented method\n'django.contrib.admin.sites.AdminSite.display_login_form' has been removed\nin favor of a new login_form\nattribute.
reset and sqlreset management commandsLink to this heading#Those commands have been deprecated. The flush and sqlflush commands\ncan be used to delete everything. You can also use ALTER TABLE or DROP TABLE\nstatements manually.
The function-based TEST_RUNNER previously used to execute\nthe GeoDjango test suite, django.contrib.gis.tests.run_gis_tests, was\ndeprecated for the class-based runner,\ndjango.contrib.gis.tests.GeoDjangoTestSuiteRunner.
Previously, calling\ntransform() would\nsilently do nothing when GDAL wasn’t available. Now, a\nGEOSException is properly raised\nto indicate possible faulty application code. A warning is now\nraised if transform() is\ncalled when the SRID of the geometry is less than 0 or None.
CZBirthNumberField.cleanLink to this heading#Previously this field’s clean() method accepted a second, gender, argument\nwhich allowed stronger validation checks to be made, however since this\nargument could never actually be passed from the Django form machinery it is\nnow pending deprecation.
This release of Django starts the deprecation process for inclusion of\ntranslations located under the so-called project path in the translation\nbuilding process performed at runtime. The LOCALE_PATHS setting can\nbe used for the same task by adding the filesystem path to a locale\ndirectory containing project-level translations to the value of that setting.
Rationale for this decision:
\nThe project path has always been a loosely defined concept\n(actually, the directory used for locating project-level\ntranslations is the directory containing the settings module) and\nthere has been a shift in other parts of the framework to stop using\nit as a reference for location of assets at runtime.
Detection of the locale subdirectory tends to fail when the\ndeployment scenario is more complex than the basic one. e.g. it\nfails when the settings module is a directory (ticket #10765).
There are potential strange development- and deployment-time\nproblems like the fact that the project_dir/locale/ subdir can\ngenerate spurious error messages when the project directory is added\nto the Python path (manage.py runserver does this) and then it\nclashes with the equally named standard library module, this is a\ntypical warning message:
/usr/lib/python2.6/gettext.py:49: ImportWarning: Not importing directory '/path/to/project/locale': missing __init__.py.\nimport locale, copy, os, re, struct, sys\nThis location wasn’t included in the translation building process\nfor JavaScript literals. This deprecation removes such\ninconsistency.
PermWrapper moved to django.contrib.auth.context_processorsLink to this heading#In Django 1.2, we began the process of changing the location of the\nauth context processor from django.core.context_processors to\ndjango.contrib.auth.context_processors. However, the\nPermWrapper support class was mistakenly omitted from that\nmigration. In Django 1.3, the PermWrapper class has also been\nmoved to django.contrib.auth.context_processors, along with the\nPermLookupDict support class. The new classes are functionally\nidentical to their old versions; only the module location has changed.
XMLFieldLink to this heading#When Django was first released, Django included an XMLField that performed\nautomatic XML validation for any field input. However, this validation function\nhasn’t been performed since the introduction of newforms, prior to the 1.0\nrelease. As a result, XMLField as currently implemented is functionally\nindistinguishable from a simple TextField.
For this reason, Django 1.3 has fast-tracked the deprecation of\nXMLField – instead of a two-release deprecation, XMLField\nwill be removed entirely in Django 1.4.
It’s easy to update your code to accommodate this change – just\nreplace all uses of XMLField with TextField, and remove the\nschema_path keyword argument (if it is specified).