272 lines
11 KiB
Plaintext
272 lines
11 KiB
Plaintext
============================================
|
|
Django 1.4 release notes - UNDER DEVELOPMENT
|
|
============================================
|
|
|
|
This page documents release notes for the as-yet-unreleased Django
|
|
1.4. As such, it's tentative and subject to change. It provides
|
|
up-to-date information for those who are following trunk.
|
|
|
|
Django 1.4 includes various `new features`_ and some minor `backwards
|
|
incompatible changes`_. There are also some features that have been dropped,
|
|
which are detailed in :doc:`our deprecation plan </internals/deprecation>`.
|
|
|
|
.. _new features: `What's new in Django 1.4`_
|
|
.. _backwards incompatible changes: backwards-incompatible-changes-1.4_
|
|
|
|
What's new in Django 1.4
|
|
========================
|
|
|
|
``SELECT FOR UPDATE`` support
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Django 1.4 now includes a :meth:`QuerySet.select_for_update()
|
|
<django.db.models.query.QuerySet.select_for_update>` method which generates a
|
|
``SELECT ... FOR UPDATE`` SQL query. This will lock rows until the end of the
|
|
transaction, meaning that other transactions cannot modify or delete rows
|
|
matched by a ``FOR UPDATE`` query.
|
|
|
|
For more details, see the documentation for
|
|
:meth:`~django.db.models.query.QuerySet.select_for_update`.
|
|
|
|
HTML5
|
|
~~~~~
|
|
|
|
We've switched the admin and other bundled templates to use the HTML5
|
|
doctype. While Django will be careful in its use of HTML5 features, to maintain
|
|
compatibility with old browsers, this change means that you can use any HTML5
|
|
features you need in admin pages without having to lose HTML validity or
|
|
override the provided templates to change the doctype.
|
|
|
|
List filters in admin interface
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Prior to Django 1.4, the Django admin app allowed specifying change list
|
|
filters by specifying a field lookup (including spanning relations), and
|
|
not custom filters. This has been rectified with a simple API previously
|
|
known as "FilterSpec" which was used internally. For more details, see the
|
|
documentation for :attr:`~django.contrib.admin.ModelAdmin.list_filter`.
|
|
|
|
Tools for cryptographic signing
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Django 1.4 adds both a low-level API for signing values and a high-level API
|
|
for setting and reading signed cookies, one of the most common uses of
|
|
signing in Web applications.
|
|
|
|
See :doc:`cryptographic signing </topics/signing>` docs for more information.
|
|
|
|
New form wizard
|
|
~~~~~~~~~~~~~~~
|
|
|
|
The previously shipped ``FormWizard`` of the formtools contrib app has been
|
|
replaced with a new implementation that is based on the class based views
|
|
introduced in Django 1.3. It features a pluggable storage API and doesn't
|
|
require the wizard to pass around hidden fields for every previous step.
|
|
|
|
Django 1.4 ships with a session based storage backend and a cookie based
|
|
storage backend. The latter uses the tools for
|
|
:doc:`cryptographic signing </topics/signing>` also introduced in
|
|
Django 1.4 to store the wizard state in the user's cookies.
|
|
|
|
See the :doc:`form wizard </ref/contrib/formtools/form-wizard>` docs for
|
|
more information.
|
|
|
|
Simple clickjacking protection
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
We've added a middleware to provide easy protection against `clickjacking
|
|
<http://en.wikipedia.org/wiki/Clickjacking>`_ using the X-Frame-Options
|
|
header. It's not enabled by default for backwards compatibility reasons, but
|
|
you'll almost certainly want to :doc:`enable it </ref/clickjacking/>` to help
|
|
plug that security hole for browsers that support the header.
|
|
|
|
``reverse_lazy``
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
A lazily evaluated version of :func:`django.core.urlresolvers.reverse` was
|
|
added to allow using URL reversals before the project's URLConf gets loaded.
|
|
|
|
Assignment template tags
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A new helper function,
|
|
:ref:`assignment_tag<howto-custom-template-tags-assignment-tags>`, was added to
|
|
``template.Library`` to ease the creation of template tags that store some
|
|
data in a specified context variable.
|
|
|
|
CSRF improvements
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
We've made various improvements to our CSRF features, including the
|
|
:func:`~django.views.decorators.csrf.ensure_csrf_cookie` decorator which can
|
|
help with AJAX heavy sites, protection for PUT and DELETE, and settings
|
|
:setting:`CSRF_COOKIE_SECURE` and :setting:`CSRF_COOKIE_PATH` which can improve
|
|
the security and usefulness of the CSRF protection. See the :doc:`CSRF docs
|
|
</ref/contrib/csrf>` for more information.
|
|
|
|
.. _backwards-incompatible-changes-1.4:
|
|
|
|
Backwards incompatible changes in 1.4
|
|
=====================================
|
|
|
|
Compatibility with old signed data
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Django 1.3 changed the cryptographic signing mechanisms used in a number of
|
|
places in Django. While Django 1.3 kept fallbacks that would accept hashes
|
|
produced by the previous methods, these fallbacks are removed in Django 1.4.
|
|
|
|
So, if you upgrade to Django 1.4 directly from 1.2 or earlier, you may
|
|
lose/invalidate certain pieces of data that have been cryptographically signed
|
|
using an old method. To avoid this, use Django 1.3 first, for a period of time,
|
|
to allow the signed data to expire naturally. The affected parts are detailed
|
|
below, with 1) the consequences of ignoring this advice and 2) the amount of
|
|
time you need to run Django 1.3 for the data to expire or become irrelevant.
|
|
|
|
* contrib.sessions data integrity check
|
|
|
|
* consequences: the user will be logged out, and session data will be lost.
|
|
|
|
* time period: defined by SESSION_COOKIE_AGE.
|
|
|
|
* contrib.auth password reset hash
|
|
|
|
* consequences: password reset links from before the upgrade will not work.
|
|
|
|
* time period: defined by PASSWORD_RESET_TIMEOUT_DAYS.
|
|
|
|
Form related hashes — these are much shorter lifetime, and are relevant only for
|
|
the short window where a user might fill in a form generated by the pre-upgrade
|
|
Django instance, and try to submit it to the upgraded Django instance:
|
|
|
|
* contrib.comments form security hash
|
|
|
|
* consequences: the user will see a validation error "Security hash failed".
|
|
|
|
* time period: the amount of time you expect users to take filling out comment
|
|
forms.
|
|
|
|
* FormWizard security hash
|
|
|
|
* consequences: the user will see an error about the form having expired,
|
|
and will be sent back to the first page of the wizard, losing the data
|
|
they have inputted so far.
|
|
|
|
* time period: the amount of time you expect users to take filling out the
|
|
affected forms.
|
|
|
|
* CSRF check
|
|
|
|
* Note: This is actually a Django 1.1 fallback, not Django 1.2,
|
|
and applies only if you are upgrading from 1.1.
|
|
|
|
* consequences: the user will see a 403 error with any CSRF protected POST
|
|
form.
|
|
|
|
* time period: the amount of time you expect user to take filling out
|
|
such forms.
|
|
|
|
django.contrib.flatpages
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Starting in the 1.4 release the
|
|
:class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` only
|
|
adds a trailing slash and redirects if the resulting URL refers to an existing
|
|
flatpage. For example, requesting ``/notaflatpageoravalidurl`` in a previous
|
|
version would redirect to ``/notaflatpageoravalidurl/``, which would
|
|
subsequently raise a 404. Requesting ``/notaflatpageoravalidurl`` now will
|
|
immediately raise a 404. Additionally redirects returned by flatpages are now
|
|
permanent (301 status code) to match the behavior of the
|
|
:class:`~django.middleware.common.CommonMiddleware`.
|
|
|
|
`COMMENTS_BANNED_USERS_GROUP` setting
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Django's :doc:`comments app </ref/contrib/comments/index>` has historically
|
|
supported excluding the comments of a special user group, but we've never
|
|
documented the feature properly and didn't enforce the exclusion in other parts
|
|
of the app, e.g., the template tags. To fix this problem, we removed the code
|
|
from the feed class.
|
|
|
|
If you rely on the feature and want to restore the old behavior, simply use
|
|
a custom comment model manager to exclude the user group, like this::
|
|
|
|
from django.conf import settings
|
|
from django.contrib.comments.managers import CommentManager
|
|
|
|
class BanningCommentManager(CommentManager):
|
|
def get_query_set(self):
|
|
qs = super(BanningCommentManager, self).get_query_set()
|
|
if getattr(settings, 'COMMENTS_BANNED_USERS_GROUP', None):
|
|
where = ['user_id NOT IN (SELECT user_id FROM auth_user_groups WHERE group_id = %s)']
|
|
params = [settings.COMMENTS_BANNED_USERS_GROUP]
|
|
qs = qs.extra(where=where, params=params)
|
|
return qs
|
|
|
|
Save this model manager in your custom comment app (e.g. in
|
|
``my_comments_app/managers.py``) and add it your
|
|
:ref:`custom comment app model <custom-comment-app-api>`::
|
|
|
|
from django.db import models
|
|
from django.contrib.comments.models import Comment
|
|
|
|
from my_comments_app.managers import BanningCommentManager
|
|
|
|
class CommentWithTitle(Comment):
|
|
title = models.CharField(max_length=300)
|
|
|
|
objects = BanningCommentManager()
|
|
|
|
For more details, see the documentation about
|
|
:doc:`customizing the comments framework </ref/contrib/comments/custom>`.
|
|
|
|
`IGNORABLE_404_STARTS` and `IGNORABLE_404_ENDS` settings
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Django can report 404 errors: see :doc:`/howto/error-reporting`.
|
|
Until Django 1.3, it was possible to exclude some URLs from the reporting
|
|
by adding prefixes to :setting:`IGNORABLE_404_STARTS` and suffixes to
|
|
:setting:`IGNORABLE_404_ENDS`.
|
|
|
|
In Django 1.4, these two settings are superseded by
|
|
:setting:`IGNORABLE_404_URLS`, which is a list of compiled regular expressions.
|
|
Django won't send an email for 404 errors on URLs that match any of them.
|
|
|
|
Furthermore, the previous settings had some rather arbitrary default values::
|
|
|
|
IGNORABLE_404_STARTS = ('/cgi-bin/', '/_vti_bin', '/_vti_inf')
|
|
IGNORABLE_404_ENDS = ('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi',
|
|
'favicon.ico', '.php')
|
|
|
|
It's not Django's role to decide if your website has a legacy ``/cgi-bin/``
|
|
section or a ``favicon.ico``. As a consequence, the default values of
|
|
:setting:`IGNORABLE_404_URLS`, :setting:`IGNORABLE_404_STARTS` and
|
|
:setting:`IGNORABLE_404_ENDS` are all now empty.
|
|
|
|
If you have customized :setting:`IGNORABLE_404_STARTS` or
|
|
:setting:`IGNORABLE_404_ENDS`, or if you want to keep the old default value,
|
|
you should add the following lines in your settings file::
|
|
|
|
import re
|
|
IGNORABLE_404_URLS = (
|
|
# for each <prefix> in IGNORABLE_404_STARTS
|
|
re.compile(r'^<prefix>'),
|
|
# for each <suffix> in IGNORABLE_404_ENDS
|
|
re.compile(r'<suffix>$'),
|
|
)
|
|
|
|
Don't forget to escape characters that have a special meaning in a regular
|
|
expression.
|
|
|
|
CSRF protection extended to PUT and DELETE
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Previously, Django's :doc:`CSRF protection </ref/contrib/csrf/>` provided
|
|
protection against only POST requests. Since use of PUT and DELETE methods in
|
|
AJAX applications is becoming more common, we now protect all methods not
|
|
defined as safe by RFC 2616 i.e. we exempt GET, HEAD, OPTIONS and TRACE, and
|
|
enforce protection on everything.
|
|
|
|
If you using PUT or DELETE methods in AJAX applications, please see the
|
|
:ref:`instructions about using AJAX and CSRF <csrf-ajax>`.
|