← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/python-django/oneiric-201108291626

« back to all changes in this revision

Viewing changes to docs/releases/1.2.txt

  • Committer: Bazaar Package Importer
  • Author(s): Jamie Strandboge
  • Date: 2010-10-12 11:34:35 UTC
  • mfrom: (1.1.12 upstream) (29.1.1 maverick-security)
  • Revision ID: james.westby@ubuntu.com-20101012113435-yy57c8tx6g9anf3e
Tags: 1.2.3-1ubuntu0.1
* SECURITY UPDATE: XSS in CSRF protections. New upstream release
  - CVE-2010-3082
* debian/patches/01_disable_url_verify_regression_tests.diff:
  - updated to disable another test that fails without internet connection
  - patch based on work by Kai Kasurinen and Krzysztof Klimonda
* debian/control: don't Build-Depends on locales-all, which doesn't exist
  in maverick

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/releases/1.2.txt
1
 
.. _releases-1.2:
2
 
 
3
1
========================
4
2
Django 1.2 release notes
5
3
========================
21
19
Django 1.2 introduces several large, important new features, including:
22
20
 
23
21
    * Support for `multiple database connections`_ in a single Django instance.
24
 
    
 
22
 
25
23
    * `Model validation`_ inspired by Django's form validation.
26
 
    
 
24
 
27
25
    * Vastly `improved protection against Cross-Site Request Forgery`_ (CSRF).
28
 
    
 
26
 
29
27
    * A new `user "messages" framework`_ with support for cookie- and session-based
30
28
      message for both anonymous and authenticated users.
31
29
 
49
47
 
50
48
.. seealso::
51
49
 
52
 
    `Django Advent`_ covered the release of Django 1.2 with a series of 
 
50
    `Django Advent`_ covered the release of Django 1.2 with a series of
53
51
    articles and tutorials that cover some of the new features in depth.
54
 
        
 
52
 
55
53
.. _django advent: http://djangoadvent.com/
56
54
 
57
55
Wherever possible these features have been introduced in a backwards-compatible
58
 
manner per :ref:`our API stability policy <misc-api-stability>` policy.
 
56
manner per :doc:`our API stability policy </misc/api-stability>` policy.
59
57
 
60
58
However, a handful of features *have* changed in ways that, for some users, will be
61
59
backwards-incompatible. The big changes are:
66
64
    * The new CSRF protection framework is not backwards-compatible with
67
65
      the old system. Users of the old system will not be affected until
68
66
      the old system is removed in Django 1.4.
69
 
      
 
67
 
70
68
      However, upgrading to the new CSRF protection framework requires a few
71
69
      important backwards-incompatible changes, detailed in `CSRF Protection`_,
72
70
      below.
74
72
    * Authors of custom :class:`~django.db.models.Field` subclasses should be
75
73
      aware that a number of methods have had a change in prototype, detailed
76
74
      under `get_db_prep_*() methods on Field`_, below.
77
 
      
 
75
 
78
76
    * The internals of template tags have changed somewhat; authors of custom
79
77
      template tags that need to store state (e.g. custom control flow tags)
80
78
      should ensure that their code follows the new rules for `stateful template
81
79
      tags`_
82
 
    
 
80
 
83
81
    * The :func:`~django.contrib.auth.decorators.user_passes_test`,
84
82
      :func:`~django.contrib.auth.decorators.login_required`, and
85
83
      :func:`~django.contrib.auth.decorators.permission_required`, decorators
110
108
operating-system vendors today are shipping Python 2.4 or newer as
111
109
their default version. If you're still using Python 2.3, however,
112
110
you'll need to stick to Django 1.1 until you can upgrade; per
113
 
:ref:`our support policy <internals-release-process>`, Django 1.1 will
 
111
:doc:`our support policy </internals/release-process>`, Django 1.1 will
114
112
continue to receive security support until the release of Django 1.3.
115
113
 
116
114
A roadmap for Django's overall 2.x Python support, and eventual
123
121
Support for multiple databases
124
122
------------------------------
125
123
 
126
 
Django 1.2 adds the ability to use :ref:`more than one database
127
 
<topics-db-multi-db>` in your Django project. Queries can be issued at a
 
124
Django 1.2 adds the ability to use :doc:`more than one database
 
125
</topics/db/multi-db>` in your Django project. Queries can be issued at a
128
126
specific database with the `using()` method on ``QuerySet`` objects. Individual
129
127
objects can be saved to a specific database by providing a ``using`` argument
130
128
when you call ``save()``.
134
132
 
135
133
Model instances now have support for :ref:`validating their own data
136
134
<validating-objects>`, and both model and form fields now accept configurable
137
 
lists of :ref:`validators <ref-validators>` specifying reusable, encapsulated
 
135
lists of :doc:`validators </ref/validators>` specifying reusable, encapsulated
138
136
validation behavior. Note, however, that validation must still be performed
139
137
explicitly. Simply invoking a model instance's ``save()`` method will not
140
138
perform any validation of the instance's data.
142
140
Improved CSRF protection
143
141
------------------------
144
142
 
145
 
Django now has much improved protection against :ref:`Cross-Site Request Forgery
146
 
(CSRF) attacks<ref-contrib-csrf>`. This type of attack occurs when a malicious
 
143
Django now has much improved protection against :doc:`Cross-Site Request Forgery
 
144
(CSRF) attacks</ref/contrib/csrf>`. This type of attack occurs when a malicious
147
145
Web site contains a link, a form button or some JavaScript that is intended to
148
146
perform some action on your Web site, using the credentials of a logged-in user
149
147
who visits the malicious site in their browser. A related type of attack, "login
153
151
Messages framework
154
152
------------------
155
153
 
156
 
Django now includes a robust and configurable :ref:`messages framework
157
 
<ref-contrib-messages>` with built-in support for cookie- and session-based
 
154
Django now includes a robust and configurable :doc:`messages framework
 
155
</ref/contrib/messages>` with built-in support for cookie- and session-based
158
156
messaging, for both anonymous and authenticated clients. The messages framework
159
157
replaces the deprecated user message API and allows you to temporarily store
160
158
messages in one request and retrieve them for display in a subsequent request
166
164
A foundation for specifying permissions at the per-object level has been added.
167
165
Although there is no implementation of this in core, a custom authentication
168
166
backend can provide this implementation and it will be used by
169
 
:class:`django.contrib.auth.models.User`. See the :ref:`authentication docs
170
 
<topics-auth>` for more information.
 
167
:class:`django.contrib.auth.models.User`. See the :doc:`authentication docs
 
168
</topics/auth>` for more information.
171
169
 
172
170
Permissions for anonymous users
173
171
-------------------------------
176
174
``True``, AnonymousUser will check the backend for permissions, just like
177
175
User already did.  This is useful for centralizing permission handling - apps
178
176
can always delegate the question of whether something is allowed or not to
179
 
the authorization/authentication backend. See the :ref:`authentication
180
 
docs <topics-auth>` for more details.
 
177
the authorization/authentication backend. See the :doc:`authentication
 
178
docs </topics/auth>` for more details.
181
179
 
182
180
Relaxed requirements for usernames
183
181
----------------------------------
194
192
can now choose a configurable e-mail backend to send messages. If your
195
193
hosting provider uses a sandbox or some other non-SMTP technique for
196
194
sending mail, you can now construct an e-mail backend that will allow
197
 
Django's standard :ref:`mail sending methods<topics-email>` to use
 
195
Django's standard :doc:`mail sending methods</topics/email>` to use
198
196
those facilities.
199
197
 
200
198
This also makes it easier to debug mail sending. Django ships with
286
284
Improved localization
287
285
---------------------
288
286
 
289
 
Django's :ref:`internationalization framework <topics-i18n>` has been expanded
 
287
Django's :doc:`internationalization framework </topics/i18n/index>` has been expanded
290
288
with locale-aware formatting and form processing. That means, if enabled, dates
291
289
and numbers on templates will be displayed using the format specified for the
292
290
current locale. Django will also use localized formats when parsing data in
309
307
Syndication feeds as views
310
308
--------------------------
311
309
 
312
 
:ref:`Syndication feeds <ref-contrib-syndication>` can now be used directly as
313
 
views in your :ref:`URLconf <topics-http-urls>`. This means that you can
 
310
:doc:`Syndication feeds </ref/contrib/syndication>` can now be used directly as
 
311
views in your :doc:`URLconf </topics/http/urls>`. This means that you can
314
312
maintain complete control over the URL structure of your feeds. Like any other
315
313
view, feeds views are passed a ``request`` object, so you can do anything you
316
314
would normally do with a view, like user based access control, or making a feed
319
317
GeoDjango
320
318
---------
321
319
 
322
 
The most significant new feature for :ref:`GeoDjango <ref-contrib-gis>`
 
320
The most significant new feature for :doc:`GeoDjango </ref/contrib/gis/index>`
323
321
in 1.2 is support for multiple spatial databases.  As a result,
324
322
the following :ref:`spatial database backends <spatial-backends>`
325
323
are now included:
357
355
the features returned when iterating over a
358
356
:class:`~django.contrib.gis.gdal.Layer`.
359
357
 
360
 
Finally, :ref:`GeoDjango's documentation <ref-contrib-gis>` is now
 
358
Finally, :doc:`GeoDjango's documentation </ref/contrib/gis/index>` is now
361
359
included with Django's and is no longer
362
360
hosted separately at `geodjango.org <http://geodjango.org/>`_.
363
361
 
391
389
=====================================
392
390
 
393
391
Wherever possible the new features above have been introduced in a
394
 
backwards-compatible manner per :ref:`our API stability policy
395
 
<misc-api-stability>` policy. This means that practically all existing
 
392
backwards-compatible manner per :doc:`our API stability policy
 
393
</misc/api-stability>` policy. This means that practically all existing
396
394
code which worked with Django 1.1 will continue to work with Django
397
395
1.2; such code will, however, begin issuing warnings (see below for
398
396
details).
405
403
---------------
406
404
 
407
405
We've made large changes to the way CSRF protection works, detailed in
408
 
:ref:`the CSRF documentaton <ref-contrib-csrf>`. Here are the major changes you
 
406
:doc:`the CSRF documentaton </ref/contrib/csrf>`. Here are the major changes you
409
407
should be aware of:
410
408
 
411
409
 * ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` have been deprecated and
435
433
 
436
434
    class CustomModelField(models.Field):
437
435
        # ...
 
436
        def db_type(self):
 
437
            # ...
438
438
 
439
439
        def get_db_prep_save(self, value):
440
440
            # ...
451
451
    class CustomModelField(models.Field):
452
452
        # ...
453
453
 
 
454
        def db_type(self, connection):
 
455
            # ...
 
456
 
454
457
        def get_prep_value(self, value):
455
458
            # ...
456
459
 
467
470
            # ...
468
471
 
469
472
These changes are required to support multiple databases --
470
 
``get_db_prep_*`` can no longer make any assumptions regarding the
471
 
database for which it is preparing. The ``connection`` argument now
472
 
provides the preparation methods with the specific connection for
473
 
which the value is being prepared.
 
473
``db_type`` and ``get_db_prep_*`` can no longer make any assumptions
 
474
regarding the database for which it is preparing. The ``connection``
 
475
argument now provides the preparation methods with the specific
 
476
connection for which the value is being prepared.
474
477
 
475
478
The two new methods exist to differentiate general data-preparation
476
479
requirements from requirements that are database-specific. The
603
606
--------------
604
607
 
605
608
``LazyObject`` is an undocumented-but-often-used utility class used for lazily
606
 
wrapping other objects of unknown type. 
 
609
wrapping other objects of unknown type.
607
610
 
608
611
In Django 1.1 and earlier, it handled introspection in a non-standard way,
609
612
depending on wrapped objects implementing a public method named
610
613
``get_all_members()``. Since this could easily lead to name clashes, it has been
611
614
changed to use the standard Python introspection method, involving
612
 
``__members__`` and ``__dir__()``. 
 
615
``__members__`` and ``__dir__()``.
613
616
 
614
617
If you used ``LazyObject`` in your own code
615
618
and implemented the ``get_all_members()`` method for wrapped objects, you'll need
737
740
 
738
741
.. seealso::
739
742
 
740
 
    For more details, see the documentation :ref:`Django's release process
741
 
    <internals-release-process>` and our :ref:`deprecation timeline
742
 
    <internals-deprecation>`.`
 
743
    For more details, see the documentation :doc:`Django's release process
 
744
    </internals/release-process>` and our :doc:`deprecation timeline
 
745
    </internals/deprecation>`.`
743
746
 
744
747
.. _specifying-databases:
745
748
 
872
875
 
873
876
The API for storing messages in the user ``Message`` model (via
874
877
``user.message_set.create``) is now deprecated and will be removed in Django
875
 
1.4 according to the standard :ref:`release process <internals-release-process>`.
 
878
1.4 according to the standard :doc:`release process </internals/release-process>`.
876
879
 
877
880
To upgrade your code, you need to replace any instances of this::
878
881
 
896
899
        ...
897
900
 
898
901
For more information, see the full
899
 
:ref:`messages documentation <ref-contrib-messages>`. You should begin to
 
902
:doc:`messages documentation </ref/contrib/messages>`. You should begin to
900
903
update your code to use the new API immediately.
901
904
 
902
905
Date format helper functions
960
963
 
961
964
The new class has an almost identical API, but allows instances to be
962
965
used as views. For example, consider the use of the old framework in
963
 
the following :ref:`URLconf <topics-http-urls>`::
 
966
the following :doc:`URLconf </topics/http/urls>`::
964
967
 
965
968
    from django.conf.urls.defaults import *
966
969
    from myproject.feeds import LatestEntries, LatestEntriesByCategory
1029
1032
an ``atom:link`` element. You may need to update your tests to take
1030
1033
this into account.
1031
1034
 
1032
 
For more information, see the full :ref:`syndication framework
1033
 
documentation <ref-contrib-syndication>`.
 
1035
For more information, see the full :doc:`syndication framework
 
1036
documentation </ref/contrib/syndication>`.
1034
1037
 
1035
1038
.. _RSS best practices: http://www.rssboard.org/rss-profile
1036
1039