308 lines
12 KiB
Plaintext
308 lines
12 KiB
Plaintext
============================================
|
|
Django 1.3 release notes - UNDER DEVELOPMENT
|
|
============================================
|
|
|
|
This page documents release notes for the as-yet-unreleased Django
|
|
1.3. As such, it's tentative and subject to change. It provides
|
|
up-to-date information for those who are following trunk.
|
|
|
|
Django 1.3 includes a number of nifty `new features`_, lots of bug
|
|
fixes, some minor `backwards incompatible changes`_ and an easy
|
|
upgrade path from Django 1.2.
|
|
|
|
.. _new features: `What's new in Django 1.3`_
|
|
|
|
.. _backwards incompatible changes: backwards-incompatible-changes-1.3_
|
|
|
|
What's new in Django 1.3
|
|
========================
|
|
|
|
Class-based views
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
Django 1.3 adds a framework that allows you to use a class as a view.
|
|
This means you can compose a view out of a collection of methods that
|
|
can be subclassed and overridden to provide
|
|
|
|
Analogs of all the old function-based generic views have been
|
|
provided, along with a completely generic view base class that can be
|
|
used as the basis for reusable applications that can be easily
|
|
extended.
|
|
|
|
See :doc:`the documentation on Generic Views</topics/generic-views>`
|
|
for more details. There is also a document to help you :doc:`convert
|
|
your function-based generic views to class-based
|
|
views</topics/generic-views-migration>`.
|
|
|
|
Logging
|
|
~~~~~~~
|
|
|
|
Django 1.3 adds framework-level support for Python's logging module.
|
|
This means you can now easily configure and control logging as part of
|
|
your Django project. A number of logging handlers and logging calls
|
|
have been added to Django's own code as well -- most notably, the
|
|
error emails sent on a HTTP 500 server error are now handled as a
|
|
logging activity. See :doc:`the documentation on Django's logging
|
|
interface </topics/logging>` for more details.
|
|
|
|
``unittest2`` support
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Python 2.7 introduced some major changes to the unittest library,
|
|
adding some extremely useful features. To ensure that every Django
|
|
project can benefit from these new features, Django ships with a
|
|
copy of unittest2_, a copy of the Python 2.7 unittest library,
|
|
backported for Python 2.4 compatibility.
|
|
|
|
To access this library, Django provides the
|
|
``django.utils.unittest`` module alias. If you are using Python
|
|
2.7, or you have installed unittest2 locally, Django will map the
|
|
alias to the installed version of the unittest library. Otherwise,
|
|
Django will use it's own bundled version of unittest2.
|
|
|
|
To use this alias, simply use::
|
|
|
|
from django.utils import unittest
|
|
|
|
wherever you would have historically used::
|
|
|
|
import unittest
|
|
|
|
If you want to continue to use the base unittest libary, you can --
|
|
you just won't get any of the nice new unittest2 features.
|
|
|
|
.. _unittest2: http://pypi.python.org/pypi/unittest2
|
|
|
|
Transaction context managers
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Users of Python 2.5 and above may now use :ref:`transaction management functions
|
|
<transaction-management-functions>` as `context managers`_. For example::
|
|
|
|
with transaction.autocommit():
|
|
# ...
|
|
|
|
.. _context managers: http://docs.python.org/glossary.html#term-context-manager
|
|
|
|
For more information, see :ref:`transaction-management-functions`.
|
|
|
|
Contextual markers in translatable strings
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
For translation strings with ambiguous meaning, you can now
|
|
use the ``pgettext`` function to specify the context of the string.
|
|
|
|
For more information, see :ref:`contextual-markers`
|
|
|
|
Everything else
|
|
~~~~~~~~~~~~~~~
|
|
|
|
Django :doc:`1.1 <1.1>` and :doc:`1.2 <1.2>` added
|
|
lots of big ticket items to Django, like multiple-database support,
|
|
model validation, and a session-based messages framework. However,
|
|
this focus on big features came at the cost of lots of smaller
|
|
features.
|
|
|
|
To compensate for this, the focus of the Django 1.3 development
|
|
process has been on adding lots of smaller, long standing feature
|
|
requests. These include:
|
|
|
|
* Improved tools for accessing and manipulating the current Site.
|
|
|
|
* A :class:`~django.test.client.RequestFactory` for mocking
|
|
requests in tests.
|
|
|
|
* A new test assertion --
|
|
:meth:`~django.test.client.Client.assertNumQueries` -- making it
|
|
easier to test the database activity associated with a view.
|
|
|
|
|
|
.. _backwards-incompatible-changes-1.3:
|
|
|
|
Backwards-incompatible changes in 1.3
|
|
=====================================
|
|
|
|
PasswordInput default rendering behavior
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Prior to Django 1.3, a :class:`~django.forms.PasswordInput` would render
|
|
data values like any other form. If a form submission raised an error,
|
|
the password that was submitted would be reflected to the client as form
|
|
data populating the form for resubmission.
|
|
|
|
This had the potential to leak passwords, as any failed password
|
|
attempt would cause the password that was typed to be sent back to the
|
|
client.
|
|
|
|
In Django 1.3, the default behavior of
|
|
:class:`~django.forms.PasswordInput` is to suppress the display of
|
|
password values. This change doesn't alter the way form data is
|
|
validated or handled. It only affects the user experience with
|
|
passwords on a form when they make an error submitting form data (such
|
|
as on unsuccessful logins, or when completing a registration form).
|
|
|
|
If you want restore the pre-Django 1.3 behavior, you need to pass in a
|
|
custom widget to your form that sets the ``render_value`` argument::
|
|
|
|
class LoginForm(forms.Form):
|
|
username = forms.CharField(max_length=100)
|
|
password = forms.CharField(widget=forms.PasswordInput(render_value=True))
|
|
|
|
Clearable default widget for FileField
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Django 1.3 now includes a ``ClearableFileInput`` form widget in addition to
|
|
``FileInput``. ``ClearableFileInput`` renders with a checkbox to clear the
|
|
field's value (if the field has a value and is not required); ``FileInput``
|
|
provided no means for clearing an existing file from a ``FileField``.
|
|
|
|
``ClearableFileInput`` is now the default widget for a ``FileField``, so
|
|
existing forms including ``FileField`` without assigning a custom widget will
|
|
need to account for the possible extra checkbox in the rendered form output.
|
|
|
|
To return to the previous rendering (without the ability to clear the
|
|
``FileField``), use the ``FileInput`` widget in place of
|
|
``ClearableFileInput``. For instance, in a ``ModelForm`` for a hypothetical
|
|
``Document`` model with a ``FileField`` named ``document``::
|
|
|
|
from django import forms
|
|
from myapp.models import Document
|
|
|
|
class DocumentForm(forms.ModelForm):
|
|
class Meta:
|
|
model = Document
|
|
widgets = {'document': forms.FileInput}
|
|
|
|
New index on database session table
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Prior to Django 1.3, the database table used by the database backend
|
|
for the :doc:`sessions </topics/http/sessions>` app had no index on
|
|
the ``expire_date`` column. As a result, date-based queries on the
|
|
session table -- such as the query that is needed to purge old
|
|
sessions -- would be very slow if there were lots of sessions.
|
|
|
|
If you have an existing project that is using the database session
|
|
backend, you don't have to do anything to accommodate this change.
|
|
However, you may get a significant performance boost if you manually
|
|
add the new index to the session table. The SQL that will add the
|
|
index can be found by running the :djadmin:`sqlindexes` admin
|
|
command::
|
|
|
|
python manage.py sqlindexes sessions
|
|
|
|
No more naughty words
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Django has historically provided (and enforced) a list of profanities.
|
|
The :doc:`comments app </ref/contrib/comments/index>` has enforced this
|
|
list of profanities, preventing people from submitting comments that
|
|
contained one of those profanities.
|
|
|
|
Unfortunately, the technique used to implement this profanities list
|
|
was woefully naive, and prone to the `Scunthorpe problem`_. Fixing the
|
|
built in filter to fix this problem would require significant effort,
|
|
and since natural language processing isn't the normal domain of a web
|
|
framework, we have "fixed" the problem by making the list of
|
|
prohibited words an empty list.
|
|
|
|
If you want to restore the old behavior, simply put a
|
|
``PROFANITIES_LIST`` setting in your settings file that includes the
|
|
words that you want to prohibit (see the `commit that implemented this
|
|
change`_ if you want to see the list of words that was historically
|
|
prohibited). However, if avoiding profanities is important to you, you
|
|
would be well advised to seek out a better, less naive approach to the
|
|
problem.
|
|
|
|
.. _Scunthorpe problem: http://en.wikipedia.org/wiki/Scunthorpe_problem
|
|
.. _commit that implemented this change: http://code.djangoproject.com/changeset/13996
|
|
|
|
Localflavor changes
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
Django 1.3 introduces the following backwards-incompatible changes to
|
|
local flavors:
|
|
|
|
* Indonesia (id) -- The province "Nanggroe Aceh Darussalam (NAD)"
|
|
has been removed from the province list in favor of the new
|
|
official designation "Aceh (ACE)".
|
|
|
|
|
|
.. _deprecated-features-1.3:
|
|
|
|
Features deprecated in 1.3
|
|
==========================
|
|
|
|
Django 1.3 deprecates some features from earlier releases.
|
|
These features are still supported, but will be gradually phased out
|
|
over the next few release cycles.
|
|
|
|
Code taking advantage of any of the features below will raise a
|
|
``PendingDeprecationWarning`` in Django 1.3. This warning will be
|
|
silent by default, but may be turned on using Python's `warnings
|
|
module`_, or by running Python with a ``-Wd`` or `-Wall` flag.
|
|
|
|
.. _warnings module: http://docs.python.org/library/warnings.html
|
|
|
|
In Django 1.4, these warnings will become a ``DeprecationWarning``,
|
|
which is *not* silent. In Django 1.5 support for these features will
|
|
be removed entirely.
|
|
|
|
.. seealso::
|
|
|
|
For more details, see the documentation :doc:`Django's release process
|
|
</internals/release-process>` and our :doc:`deprecation timeline
|
|
</internals/deprecation>`.`
|
|
|
|
``mod_python`` support
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The ``mod_python`` library has not had a release since 2007 or a commit since
|
|
2008. The Apache Foundation board voted to remove ``mod_python`` from the set
|
|
of active projects in its version control repositories, and its lead developer
|
|
has shifted all of his efforts toward the lighter, slimmer, more stable, and
|
|
more flexible ``mod_wsgi`` backend.
|
|
|
|
If you are currently using the ``mod_python`` request handler, it is strongly
|
|
encouraged you redeploy your Django instances using :doc:`mod_wsgi
|
|
</howto/deployment/modwsgi>`.
|
|
|
|
Function-based generic views
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
As a result of the introduction of class-based generic views, the
|
|
function-based generic views provided by Django have been deprecated.
|
|
The following modules and the views they contain have been deprecated:
|
|
|
|
* :mod:`django.views.generic.create_update`
|
|
* :mod:`django.views.generic.date_based`
|
|
* :mod:`django.views.generic.list_detail`
|
|
* :mod:`django.views.generic.simple`
|
|
|
|
Test client response ``template`` attribute
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Django's :ref:`test client <test-client>` returns
|
|
:class:`~django.test.client.Response` objects annotated with extra testing
|
|
information. In Django versions prior to 1.3, this included a
|
|
:attr:`~django.test.client.Response.template` attribute containing information
|
|
about templates rendered in generating the response: either None, a single
|
|
:class:`~django.template.Template` object, or a list of
|
|
:class:`~django.template.Template` objects. This inconsistency in return values
|
|
(sometimes a list, sometimes not) made the attribute difficult to work with.
|
|
|
|
In Django 1.3 the :attr:`~django.test.client.Response.template` attribute is
|
|
deprecated in favor of a new :attr:`~django.test.client.Response.templates`
|
|
attribute, which is always a list, even if it has only a single element or no
|
|
elements.
|
|
|
|
``DjangoTestRunner``
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
As a result of the introduction of support for unittest2, the features
|
|
of :class:`django.test.simple.DjangoTestRunner` (including fail-fast
|
|
and Ctrl-C test termination) have been made redundant. In view of this
|
|
redundancy, :class:`~django.test.simple.DjangoTestRunner` has been
|
|
turned into an empty placeholder class, and will be removed entirely
|
|
in Django 1.5.
|