test0908
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update release notes and other docs for impending 1.3. 

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15892 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
James Bennett 2011-03-22 06:57:12 +00:00
parent 09d163ec47
commit a5d373a463
2 changed files with 179 additions and 188 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/internals/deprecation.txt
View File

@ -102,10 +102,6 @@ their deprecation, as per the :ref:`Django deprecation policy
* Authentication backends need to define the boolean attribute * Authentication backends need to define the boolean attribute
``supports_inactive_user``. ``supports_inactive_user``.
* The ``MEDIA_URL`` or ``STATIC_URL`` settings are required to end
with a trailing slash to ensure there is a consistent way to
combine paths in templates.
* ``django.db.models.fields.XMLField`` will be removed. This was * ``django.db.models.fields.XMLField`` will be removed. This was
deprecated as part of the 1.3 release. An accelerated deprecation deprecated as part of the 1.3 release. An accelerated deprecation
schedule has been used because the field hasn't performed any role schedule has been used because the field hasn't performed any role
@ -171,6 +167,10 @@ their deprecation, as per the :ref:`Django deprecation policy
and :class:`django.contrib.auth.context_processors.PermLookupDict`, and :class:`django.contrib.auth.context_processors.PermLookupDict`,
respectively. respectively.
* The ``MEDIA_URL`` or ``STATIC_URL`` settings are required to end
with a trailing slash to ensure there is a consistent way to
combine paths in templates.
* 2.0 * 2.0
* ``django.views.defaults.shortcut()``. This function has been moved * ``django.views.defaults.shortcut()``. This function has been moved
to ``django.contrib.contenttypes.views.shortcut()`` as part of the to ``django.contrib.contenttypes.views.shortcut()`` as part of the

359
docs/releases/1.3.txt
View File

@ -2,17 +2,52 @@
Django 1.3 release notes - UNDER DEVELOPMENT Django 1.3 release notes - UNDER DEVELOPMENT
============================================ ============================================
This page documents release notes for the as-yet-unreleased Django *Insert release date here*
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 Welcome to Django 1.3!
fixes, some minor `backwards incompatible changes`_ and an easy
upgrade path from Django 1.2. Nearly a year in the making, Django 1.3 includes quite a few `new
features`_ and plenty of bug fixes and improvements to existing
features. These release notes cover the new features in 1.3, as well
as some `backwards-incompatible changes`_ you'll want to be aware of
when upgrading from Django 1.2 or older versions.
Overview
========
Django 1.3's focus has mostly been on resolving smaller, long-standing
feature requests, but that hasn't prevented a few fairly significant
new features from landing, including:
* A 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)
`the unittest2 library`_.
There's plenty more, of course; see the coverage of `new features`_
below for a full rundown and details.
Wherever possible, of course, new features are introduced in a
backwards-compatible manner per :doc:`our API stability policy
</misc/api-stability>` policy. As a result of this policy, Django 1.3
`begins the deprecation process for some features`_.
Some changes, unfortunately, are genuinely backwards-incompatible; in
most cases these are due to security issues or bugs which simply
couldn't be fixed any other way. Django 1.3 includes a few of these,
and descriptions of them -- along with the (minor) modifications
you'll need to make to handle them -- are documented in the list of
`backwards-incompatible changes`_ below.
.. _new features: `What's new in Django 1.3`_ .. _new features: `What's new in Django 1.3`_
.. _backwards-incompatible changes: backwards-incompatible-changes-1.3_
.. _backwards incompatible changes: backwards-incompatible-changes-1.3_ .. _using Python's logging facilities: `Logging`_
.. _easy handling of static files: `Extended static files handling`_
.. _the unittest2 library: `unittest2 support`_
What's new in Django 1.3 What's new in Django 1.3
======================== ========================
@ -30,7 +65,7 @@ provided, along with a completely generic view base class that can be
used as the basis for reusable applications that can be easily used as the basis for reusable applications that can be easily
extended. extended.
See :doc:`the documentation on Class-based Generic Views</topics/class-based-views>` See :doc:`the documentation on class-based generic views</topics/class-based-views>`
for more details. There is also a document to help you :doc:`convert for more details. There is also a document to help you :doc:`convert
your function-based generic views to class-based your function-based generic views to class-based
views</topics/generic-views-migration>`. views</topics/generic-views-migration>`.
@ -38,49 +73,51 @@ views</topics/generic-views-migration>`.
Logging Logging
~~~~~~~ ~~~~~~~
Django 1.3 adds framework-level support for Python's logging module. Django 1.3 adds framework-level support for Python's ``logging``
This means you can now easily configure and control logging as part of module. This means you can now easily configure and control logging
your Django project. A number of logging handlers and logging calls as part of your Django project. A number of logging handlers and
have been added to Django's own code as well -- most notably, the logging calls have been added to Django's own code as well -- most
error emails sent on a HTTP 500 server error are now handled as a notably, the error emails sent on a HTTP 500 server error are now
logging activity. See :doc:`the documentation on Django's logging handled as a logging activity. See :doc:`the documentation on Django's
interface </topics/logging>` for more details. logging interface </topics/logging>` for more details.
Extended static files handling Extended static files handling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Django 1.3 ships with a new contrib app ``'django.contrib.staticfiles'`` Django 1.3 ships with a new contrib app --
to help developers handle the static media files (images, CSS, Javascript, ``django.contrib.staticfiles`` -- to help developers handle the static
etc.) that are needed to render a complete web page. media files (images, CSS, Javascript, etc.) that are needed to render
a complete web page.
In previous versions of Django, it was common to place static assets in In previous versions of Django, it was common to place static assets
:setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both at in :setting:`MEDIA_ROOT` along with user-uploaded files, and serve
:setting:`MEDIA_URL`. Part of the purpose of introducing the ``staticfiles`` them both at :setting:`MEDIA_URL`. Part of the purpose of introducing
app is to make it easier to keep static files separate from user-uploaded the ``staticfiles`` app is to make it easier to keep static files
files. Static assets should now go in ``static/`` subdirectories of your apps separate from user-uploaded files. Static assets should now go in
or in other static assets directories listed in :setting:`STATICFILES_DIRS`, ``static/`` subdirectories of your apps or in other static assets
and will be served at :setting:`STATIC_URL`. directories listed in :setting:`STATICFILES_DIRS`, and will be served
at :setting:`STATIC_URL`.
See the :doc:`reference documentation of the app </ref/contrib/staticfiles>` See the :doc:`reference documentation of the app </ref/contrib/staticfiles>`
for more details or learn how to :doc:`manage static files for more details or learn how to :doc:`manage static files
</howto/static-files>`. </howto/static-files>`.
``unittest2`` support unittest2 support
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
Python 2.7 introduced some major changes to the unittest library, Python 2.7 introduced some major changes to the ``unittest`` library,
adding some extremely useful features. To ensure that every Django adding some extremely useful features. To ensure that every Django
project can benefit from these new features, Django ships with a project can benefit from these new features, Django ships with a copy
copy of unittest2_, a copy of the Python 2.7 unittest library, of unittest2_, a copy of the Python 2.7 unittest library, backported
backported for Python 2.4 compatibility. for Python 2.4 compatibility.
To access this library, Django provides the To access this library, Django provides the ``django.utils.unittest``
``django.utils.unittest`` module alias. If you are using Python module alias. If you are using Python 2.7, or you have installed
2.7, or you have installed unittest2 locally, Django will map the ``unittest2`` locally, Django will map the alias to the installed
alias to the installed version of the unittest library. Otherwise, version of the unittest library. Otherwise, Django will use its own
Django will use it's own bundled version of unittest2. bundled version of unittest2.
To use this alias, simply use:: To take advantage of this alias, simply use::
from django.utils import unittest from django.utils import unittest
@ -180,14 +217,15 @@ that Django 1.2 introduced support for multiple database connections,
Django 1.3 allows you to use the new :setting:`CACHES` setting to Django 1.3 allows you to use the new :setting:`CACHES` setting to
define multiple named cache connections. define multiple named cache connections.
Secondly, :ref:`Versioning <cache_versioning>`, :ref:`site-wide Secondly, :ref:`versioning <cache_versioning>`, :ref:`site-wide
prefixing <cache_key_prefixing>` and :ref:`transformation prefixing <cache_key_prefixing>` and :ref:`transformation
<cache_key_transformation>` has been added to the cache API. <cache_key_transformation>` have been added to the cache API.
Thirdly, the :ref:`cache key creation <using-vary-headers>` has been Thirdly, :ref:`cache key creation <using-vary-headers>` has been
updated to take the GET request query string into account. updated to take the request query string into account on ``GET``
requests.
Lastly, support for pylibmc_ has been added to the memcached cache Finally, support for pylibmc_ has been added to the memcached cache
backend. backend.
For more details, see the :doc:`documentation on For more details, see the :doc:`documentation on
@ -198,10 +236,11 @@ caching in Django</topics/cache>`.
Permissions for inactive users Permissions for inactive users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you provide a custom auth backend with ``supports_inactive_user`` set to If you provide a custom auth backend with ``supports_inactive_user``
``True``, an inactive user model will check the backend for permissions. set to ``True``, an inactive ``User`` instance will check the backend
This is useful for further centralizing the permission handling. See the for permissions. This is useful for further centralizing the
:doc:`authentication docs </topics/auth>` for more details. permission handling. See the :doc:`authentication docs </topics/auth>`
for more details.
GeoDjango GeoDjango
~~~~~~~~~ ~~~~~~~~~
@ -221,10 +260,10 @@ A trailing slash is now *required* for ``MEDIA_URL`` and the new
a consistent way to combine paths in templates. a consistent way to combine paths in templates.
Project settings which provide either of both settings without a trailing Project settings which provide either of both settings without a trailing
slash will now raise a ``PendingDeprecation`` warning. slash will now raise a ``PendingDeprecationWarning``.
In Django 1.4 this same condition will raise an ``ImproperlyConfigured`` In Django 1.4 this same condition will raise ``DeprecationWarning``,
exception. and in Django 1.5 will raise an ``ImproperlyConfigured`` exception.
Everything else Everything else
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
@ -239,38 +278,38 @@ To compensate for this, the focus of the Django 1.3 development
process has been on adding lots of smaller, long standing feature process has been on adding lots of smaller, long standing feature
requests. These include: requests. These include:
* Improved tools for accessing and manipulating the current Site. * Improved tools for accessing and manipulating the current ``Site``
object in :ref:`the sites framework <ref/contrib/sites>`.
* A :class:`~django.test.client.RequestFactory` for mocking * A :class:`~django.test.client.RequestFactory` for mocking requests
requests in tests. in tests.
* A new test assertion -- * A new test assertion --
:meth:`~django.test.client.Client.assertNumQueries` -- making it :meth:`~django.test.client.Client.assertNumQueries` -- making it
easier to test the database activity associated with a view. easier to test the database activity associated with a view.
* Support for lookups spanning relations in admin's ``list_filter``. * Support for lookups spanning relations in admin's ``list_filter``.
* Support for _HTTPOnly cookies. * Support for _HTTPOnly cookies.
* :meth:`mail_admins()` and :meth:`mail_managers()` now support * :meth:`mail_admins()` and :meth:`mail_managers()` now support
easily attaching HTML content to messages. easily attaching HTML content to messages.
* :class:`EmailMessage` now supports CC's. * :class:`EmailMessage` now supports CC's.
* Error emails now include more of the detail and formatting of * Error emails now include more of the detail and formatting of the
the debug server error page. debug server error page.
* :meth:`simple_tag` now accepts a :attr:`takes_context` argument, * :meth:`simple_tag` now accepts a :attr:`takes_context` argument,
making it easier to write simple template tags that require making it easier to write simple template tags that require access
access to template context. to template context.
* A new :meth:`~django.shortcuts.render()` shortcut -- an * A new :meth:`~django.shortcuts.render()` shortcut -- an alternative
alternative to :meth:`~django.shortcuts.render_to_response()` to :meth:`~django.shortcuts.render_to_response()` providing a
providing a :class:`~django.template.RequestContext` by :class:`~django.template.RequestContext` by default.
default.
* Support for combining :ref:`F() expressions <query-expressions>` * Support for combining :ref:`F() expressions <query-expressions>`
with timedelta values when retrieving or updating database values. with timedelta values when retrieving or updating database values.
.. _HTTPOnly: http://www.owasp.org/index.php/HTTPOnly .. _HTTPOnly: http://www.owasp.org/index.php/HTTPOnly
@ -279,85 +318,25 @@ requests. These include:
Backwards-incompatible changes in 1.3 Backwards-incompatible changes in 1.3
===================================== =====================================
CSRF exception for AJAX requests CSRF validation now applies to AJAX requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Django includes a CSRF-protection mechanism, which makes use of a Prior to Django 1.2.5, Django's CSRF-prevention system exempted AJAX
token inserted into outgoing forms. Middleware then checks for the requests from CSRF verification; due to `security issues`_ reported to
token's presence on form submission, and validates it. us, however, *all* requests are now subjected to CSRF
verification. Consult :ref:`the Django CSRF documentation
Prior to Django 1.2.5, our CSRF protection made an exception for AJAX <ref/contrib/csrf>` for details on how to handle CSRF verification in
requests, on the following basis: AJAX requests.
* Many AJAX toolkits add an X-Requested-With header when using
XMLHttpRequest.
* Browsers have strict same-origin policies regarding
XMLHttpRequest.
* In the context of a browser, the only way that a custom header
of this nature can be added is with XMLHttpRequest.
Therefore, for ease of use, we did not apply CSRF checks to requests
that appeared to be AJAX on the basis of the X-Requested-With header.
The Ruby on Rails web framework had a similar exemption.
Recently, engineers at Google made members of the Ruby on Rails
development team aware of a combination of browser plugins and
redirects which can allow an attacker to provide custom HTTP headers
on a request to any website. This can allow a forged request to appear
to be an AJAX request, thereby defeating CSRF protection which trusts
the same-origin nature of AJAX requests.
Michael Koziarski of the Rails team brought this to our attention, and
we were able to produce a proof-of-concept demonstrating the same
vulnerability in Django's CSRF handling.
To remedy this, Django will now apply full CSRF validation to all
requests, regardless of apparent AJAX origin. This is technically
backwards-incompatible, but the security risks have been judged to
outweigh the compatibility concerns in this case.
Additionally, Django will now accept the CSRF token in the custom HTTP
header X-CSRFTOKEN, as well as in the form submission itself, for ease
of use with popular JavaScript toolkits which allow insertion of
custom headers into all AJAX requests.
Please see the :ref:`CSRF docs for example jQuery code <csrf-ajax>`
that demonstrates this technique, ensuring that you are looking at the
documentation for your version of Django, as the exact code necessary
is different for some older versions of Django.
Restricted filters in admin interface Restricted filters in admin interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Django administrative interface, django.contrib.admin, supports Prior to Django 1.2.5, the Django administrative interface allowed
filtering of displayed lists of objects by fields on the corresponding filtering on any model field or relation -- not just those specified
models, including across database-level relationships. This is in ``list_filter`` -- via query string manipulation. Due to `security
implemented by passing lookup arguments in the querystring portion of issues`_ reported to us, however, query string lookup arguments in the
the URL, and options on the ModelAdmin class allow developers to admin must be for fields or relations specified in ``list_filter`` or
specify particular fields or relationships which will generate ``date_hierarchy``.
automatic links for filtering.
One historically-undocumented and -unofficially-supported feature has
been the ability for a user with sufficient knowledge of a model's
structure and the format of these lookup arguments to invent useful
new filters on the fly by manipulating the querystring.
However, it has been demonstrated that this can be abused to gain
access to information outside of an admin user's permissions; for
example, an attacker with access to the admin and sufficient knowledge
of model structure and relations could construct query strings which --
with repeated use of regular-expression lookups supported by the
Django database API -- expose sensitive information such as users'
password hashes.
To remedy this, django.contrib.admin will now validate that
querystring lookup arguments either specify only fields on the model
being viewed, or cross relations which have been explicitly
whitelisted by the application developer using the pre-existing
mechanism mentioned above. This is backwards-incompatible for any
users relying on the prior ability to insert arbitrary lookups.
FileField no longer deletes files FileField no longer deletes files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -448,10 +427,10 @@ list of profanities, preventing people from submitting comments that
contained one of those profanities. contained one of those profanities.
Unfortunately, the technique used to implement this profanities list Unfortunately, the technique used to implement this profanities list
was woefully naive, and prone to the `Scunthorpe problem`_. Fixing the was woefully naive, and prone to the `Scunthorpe problem`_. Improving
built in filter to fix this problem would require significant effort, the built-in filter to fix this problem would require significant
and since natural language processing isn't the normal domain of a web effort, and since natural language processing isn't the normal domain
framework, we have "fixed" the problem by making the list of of a web framework, we have "fixed" the problem by making the list of
prohibited words an empty list. prohibited words an empty list.
If you want to restore the old behavior, simply put a If you want to restore the old behavior, simply put a
@ -471,14 +450,19 @@ Localflavor changes
Django 1.3 introduces the following backwards-incompatible changes to Django 1.3 introduces the following backwards-incompatible changes to
local flavors: local flavors:
* Indonesia (id) -- The province "Nanggroe Aceh Darussalam (NAD)" * Indonesia (id) -- The province "Nanggroe Aceh Darussalam (NAD)" has
has been removed from the province list in favor of the new been removed from the province list in favor of the new official
official designation "Aceh (ACE)". designation "Aceh (ACE)".
* Canada (ca) -- The province "Newfoundland and Labrador" has * Canada (ca) -- The province "Newfoundland and Labrador" has had its
had its province code updated to "NL", rather than the province code updated to "NL", rather than the older "NF". In
older "NF". In addition, the Yukon Territory has had its addition, the Yukon Territory has had its province code corrected to
province code corrected to "YT", instead of "YK". "YT", instead of "YK".
* United States of America (us) -- The list of "states" used by
``USStateField`` has expanded to include Armed Forces postal
codes. This is backwards-incompatible if you were relying on
``USStateField`` not including them.
FormSet updates FormSet updates
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
@ -695,10 +679,13 @@ As a result of the introduction of class-based generic views, the
function-based generic views provided by Django have been deprecated. function-based generic views provided by Django have been deprecated.
The following modules and the views they contain have been deprecated: The following modules and the views they contain have been deprecated:
* :mod:`django.views.generic.create_update` * :mod:`django.views.generic.create_update`
* :mod:`django.views.generic.date_based`
* :mod:`django.views.generic.list_detail` * :mod:`django.views.generic.date_based`
* :mod:`django.views.generic.simple`
* :mod:`django.views.generic.list_detail`
* :mod:`django.views.generic.simple`
Test client response ``template`` attribute Test client response ``template`` attribute
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -796,17 +783,19 @@ statements manually.
GeoDjango GeoDjango
~~~~~~~~~ ~~~~~~~~~
* The function-based :setting:`TEST_RUNNER` previously used to execute * The function-based :setting:`TEST_RUNNER` previously used to execute
the GeoDjango test suite, :func:`django.contrib.gis.tests.run_gis_tests`, the GeoDjango test suite,
was deprecated for the class-bassed runner, :func:`django.contrib.gis.tests.run_gis_tests`, was deprecated for
:class:`django.contrib.gis.tests.GeoDjangoTestSuiteRunner`. the class-based runner,
:class:`django.contrib.gis.tests.GeoDjangoTestSuiteRunner`.
* Previously, calling :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` * Previously, calling
would silently do nothing when GDAL wasn't available. Now, :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` would
a :class:`~django.contrib.gis.geos.GEOSException` is properly raised silently do nothing when GDAL wasn't available. Now, a
to indicate possible faulty application code. A warning is now raised :class:`~django.contrib.gis.geos.GEOSException` is properly raised
if :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` is called when to indicate possible faulty application code. A warning is now
the SRID of the geometry is less than 0 or ``None``. raised if :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` is
called when the SRID of the geometry is less than 0 or ``None``.
``CZBirthNumberField.clean`` ``CZBirthNumberField.clean``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -837,27 +826,29 @@ directory containing project-level translations to the value of that setting.
Rationale for this decision: Rationale for this decision:
* The *project path* has always been a loosely defined concept (actually, the * The *project path* has always been a loosely defined concept
directory used for locating project-level translations is the directory (actually, the directory used for locating project-level
containing the settings module) and there has been a shift in other parts translations is the directory containing the settings module) and
of the framework to stop using it as a reference for location of assets at there has been a shift in other parts of the framework to stop using
runtime. it as a reference for location of assets at runtime.
* Detection of the ``locale`` subdirectory tends to fail when the deployment * Detection of the ``locale`` subdirectory tends to fail when the
scenario is more complex than the basic one. e.g. it fails when the settings deployment scenario is more complex than the basic one. e.g. it
module is a directory (ticket #10765). fails when the settings module is a directory (ticket #10765).
* There are potential strange development- and deployment-time problems like the * There are potential strange development- and deployment-time
fact that the ``project_dir/locale/`` subdir can generate spurious error problems like the fact that the ``project_dir/locale/`` subdir can
messages when the project directory is added to the Python path (``manage.py generate spurious error messages when the project directory is added
runserver`` does this) and then it clashes with the equally named standard to the Python path (``manage.py runserver`` does this) and then it
library module, this is a typical warning message:: clashes with the equally named standard library module, this is a
typical warning message::
/usr/lib/python2.6/gettext.py:49: ImportWarning: Not importing directory '/path/to/project/locale': missing __init__.py. /usr/lib/python2.6/gettext.py:49: ImportWarning: Not importing directory '/path/to/project/locale': missing __init__.py.
import locale, copy, os, re, struct, sys import locale, copy, os, re, struct, sys
* This location wasn't included in the translation building process for * This location wasn't included in the translation building process
JavaScript literals. This deprecation removes such inconsistency. for JavaScript literals. This deprecation removes such
inconsistency.
``PermWrapper`` moved to ``django.contrib.auth.context_processors`` ``PermWrapper`` moved to ``django.contrib.auth.context_processors``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~