Debian Codegraph @

docs/releases/1.1.txt

raw
1 ========================
2 Django 1.1 release notes
3 ========================
4
5 July 29, 2009
6
7 Welcome to Django 1.1!
8
9 Django 1.1 includes a number of nifty :ref:`new features <whats-new-1.1>`, lots
10 of bug fixes, and an easy upgrade path from Django 1.0.
11
12 .. _backwards-incompatible-changes-1.1:
13
14 Backwards-incompatible changes in 1.1
15 =====================================
16
17 Django has a policy of :doc:`API stability </misc/api-stability>`. This means
18 that, in general, code you develop against Django 1.0 should continue to work
19 against 1.1 unchanged. However, we do sometimes make backwards-incompatible
20 changes if they're necessary to resolve bugs, and there are a handful of such
21 (minor) changes between Django 1.0 and Django 1.1.
22
23 Before upgrading to Django 1.1 you should double-check that the following
24 changes don't impact you, and upgrade your code if they do.
25
26 Changes to constraint names
27 ---------------------------
28
29 Django 1.1 modifies the method used to generate database constraint names so
30 that names are consistent regardless of machine word size. This change is
31 backwards incompatible for some users.
32
33 If you are using a 32-bit platform, you're off the hook; you'll observe no
34 differences as a result of this change.
35
36 However, **users on 64-bit platforms may experience some problems** using the
37 ``reset`` management command. Prior to this change, 64-bit platforms
38 would generate a 64-bit, 16 character digest in the constraint name; for
39 example:
40
41 .. code-block:: sql
42
43 ALTER TABLE myapp_sometable ADD CONSTRAINT object_id_refs_id_5e8f10c132091d1e FOREIGN KEY ...
44
45 Following this change, all platforms, regardless of word size, will generate a
46 32-bit, 8 character digest in the constraint name; for example:
47
48 .. code-block:: sql
49
50 ALTER TABLE myapp_sometable ADD CONSTRAINT object_id_refs_id_32091d1e FOREIGN KEY ...
51
52 As a result of this change, you will not be able to use the ``reset``
53 management command on any table made by a 64-bit machine. This is because the
54 new generated name will not match the historically generated name; as a
55 result, the SQL constructed by the reset command will be invalid.
56
57 If you need to reset an application that was created with 64-bit constraints,
58 you will need to manually drop the old constraint prior to invoking
59 ``reset``.
60
61 Test cases are now run in a transaction
62 ---------------------------------------
63
64 Django 1.1 runs tests inside a transaction, allowing better test performance
65 (see `test performance improvements`_ for details).
66
67 This change is slightly backwards incompatible if existing tests need to test
68 transactional behavior, if they rely on invalid assumptions about the test
69 environment, or if they require a specific test case ordering.
70
71 For these cases, :class:`~django.test.TransactionTestCase` can be used instead.
72 This is a just a quick fix to get around test case errors revealed by the new
73 rollback approach; in the long-term tests should be rewritten to correct the
74 test case.
75
76 .. _removed-setremoteaddrfromforwardedfor-middleware:
77
78 Removed ``SetRemoteAddrFromForwardedFor`` middleware
79 ----------------------------------------------------
80
81 For convenience, Django 1.0 included an optional middleware class --
82 ``django.middleware.http.SetRemoteAddrFromForwardedFor`` -- which updated the
83 value of ``REMOTE_ADDR`` based on the HTTP ``X-Forwarded-For`` header commonly
84 set by some proxy configurations.
85
86 It has been demonstrated that this mechanism cannot be made reliable enough for
87 general-purpose use, and that (despite documentation to the contrary) its
88 inclusion in Django may lead application developers to assume that the value of
89 ``REMOTE_ADDR`` is "safe" or in some way reliable as a source of authentication.
90
91 While not directly a security issue, we've decided to remove this middleware
92 with the Django 1.1 release. It has been replaced with a class that does nothing
93 other than raise a ``DeprecationWarning``.
94
95 If you've been relying on this middleware, the easiest upgrade path is:
96
97 * Examine `the code as it existed before it was removed`__.
98
99 * Verify that it works correctly with your upstream proxy, modifying
100 it to support your particular proxy (if necessary).
101
102 * Introduce your modified version of ``SetRemoteAddrFromForwardedFor`` as a
103 piece of middleware in your own project.
104
105 __ https://github.com/django/django/blob/91f18400cc0fb37659e2dbaab5484ff2081f1f30/django/middleware/http.py#L33
106
107 Names of uploaded files are available later
108 -------------------------------------------
109
110 .. currentmodule:: django.db.models
111
112 In Django 1.0, files uploaded and stored in a model's :class:`FileField` were
113 saved to disk before the model was saved to the database. This meant that the
114 actual file name assigned to the file was available before saving. For example,
115 it was available in a model's pre-save signal handler.
116
117 In Django 1.1 the file is saved as part of saving the model in the database, so
118 the actual file name used on disk cannot be relied on until *after* the model
119 has been saved.
120
121 Changes to how model formsets are saved
122 ---------------------------------------
123
124 In Django 1.1, :class:`~django.forms.models.BaseModelFormSet` now calls
125 ``ModelForm.save()``.
126
127 This is backwards-incompatible if you were modifying ``self.initial`` in a model
128 formset's ``__init__``, or if you relied on the internal ``_total_form_count``
129 or ``_initial_form_count`` attributes of BaseFormSet. Those attributes are now
130 public methods.
131
132 Fixed the ``join`` filter's escaping behavior
133 ---------------------------------------------
134
135 The :tfilter:`join` filter no longer escapes the literal value that is
136 passed in for the connector.
137
138 This is backwards incompatible for the special situation of the literal string
139 containing one of the five special HTML characters. Thus, if you were writing
140 ``{{ foo|join:"&" }}``, you now have to write ``{{ foo|join:"&amp;" }}``.
141
142 The previous behavior was a bug and contrary to what was documented
143 and expected.
144
145 Permanent redirects and the ``redirect_to()`` generic view
146 ----------------------------------------------------------
147
148 Django 1.1 adds a ``permanent`` argument to the
149 ``django.views.generic.simple.redirect_to()`` view. This is technically
150 backwards-incompatible if you were using the ``redirect_to`` view with a
151 format-string key called 'permanent', which is highly unlikely.
152
153 .. _deprecated-features-1.1:
154
155 Features deprecated in 1.1
156 ==========================
157
158 One feature has been marked as deprecated in Django 1.1:
159
160 * You should no longer use ``AdminSite.root()`` to register that admin
161 views. That is, if your URLconf contains the line::
162
163 (r"^admin/(.*)", admin.site.root),
164
165 You should change it to read::
166
167 (r"^admin/", include(admin.site.urls)),
168
169 You should begin to remove use of this feature from your code immediately.
170
171 ``AdminSite.root`` will raise a ``PendingDeprecationWarning`` if used in
172 Django 1.1. This warning is hidden by default. In Django 1.2, this warning will
173 be upgraded to a ``DeprecationWarning``, which will be displayed loudly. Django
174 1.3 will remove ``AdminSite.root()`` entirely.
175
176 For more details on our deprecation policies and strategy, see
177 :doc:`/internals/release-process`.
178
179 .. _whats-new-1.1:
180
181 What's new in Django 1.1
182 ========================
183
184 Quite a bit: since Django 1.0, we've made 1,290 code commits, fixed 1,206 bugs,
185 and added roughly 10,000 lines of documentation.
186
187 The major new features in Django 1.1 are:
188
189 ORM improvements
190 ----------------
191
192 .. currentmodule:: django.db.models
193
194 Two major enhancements have been added to Django's object-relational mapper
195 (ORM): aggregate support, and query expressions.
196
197 Aggregate support
198 ~~~~~~~~~~~~~~~~~
199
200 It's now possible to run SQL aggregate queries (i.e. ``COUNT()``, ``MAX()``,
201 ``MIN()``, etc.) from within Django's ORM. You can choose to either return the
202 results of the aggregate directly, or else annotate the objects in a
203 :class:`~django.db.models.query.QuerySet` with the results of the aggregate
204 query.
205
206 This feature is available as new
207 :meth:`~django.db.models.query.QuerySet.aggregate` and
208 :meth:`~django.db.models.query.QuerySet.annotate` methods, and is covered in
209 detail in :doc:`the ORM aggregation documentation </topics/db/aggregation>`.
210
211 Query expressions
212 ~~~~~~~~~~~~~~~~~
213
214 Queries can now refer to another field on the query and can traverse
215 relationships to refer to fields on related models. This is implemented in the
216 new :class:`~django.db.models.F` object; for full details, including examples,
217 consult the :class:`F expressions documentation <django.db.models.F>`.
218
219 Model improvements
220 ------------------
221
222 A number of features have been added to Django's model layer:
223
224 "Unmanaged" models
225 ~~~~~~~~~~~~~~~~~~
226
227 You can now control whether or not Django manages the life-cycle of the database
228 tables for a model using the :attr:`~Options.managed` model option. This
229 defaults to ``True``, meaning that Django will create the appropriate database
230 tables in ``syncdb`` and remove them as part of the ``reset``
231 command. That is, Django *manages* the database table's lifecycle.
232
233 If you set this to ``False``, however, no database table creating or deletion
234 will be automatically performed for this model. This is useful if the model
235 represents an existing table or a database view that has been created by some
236 other means.
237
238 For more details, see the documentation for the :attr:`~Options.managed`
239 option.
240
241 Proxy models
242 ~~~~~~~~~~~~
243
244 You can now create :ref:`proxy models <proxy-models>`: subclasses of existing
245 models that only add Python-level (rather than database-level) behavior and
246 aren't represented by a new table. That is, the new model is a *proxy* for some
247 underlying model, which stores all the real data.
248
249 All the details can be found in the :ref:`proxy models documentation
250 <proxy-models>`. This feature is similar on the surface to unmanaged models,
251 so the documentation has an explanation of :ref:`how proxy models differ from
252 unmanaged models <proxy-vs-unmanaged-models>`.
253
254 Deferred fields
255 ~~~~~~~~~~~~~~~
256
257 In some complex situations, your models might contain fields which could
258 contain a lot of data (for example, large text fields), or require expensive
259 processing to convert them to Python objects. If you know you don't need those
260 particular fields, you can now tell Django not to retrieve them from the
261 database.
262
263 You'll do this with the new queryset methods
264 :meth:`~django.db.models.query.QuerySet.defer` and
265 :meth:`~django.db.models.query.QuerySet.only`.
266
267 Testing improvements
268 --------------------
269
270 A few notable improvements have been made to the :doc:`testing framework
271 </topics/testing/index>`.
272
273 Test performance improvements
274 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
275
276 .. currentmodule:: django.test
277
278 Tests written using Django's :doc:`testing framework </topics/testing/index>` now run
279 dramatically faster (as much as 10 times faster in many cases).
280
281 This was accomplished through the introduction of transaction-based tests: when
282 using :class:`django.test.TestCase`, your tests will now be run in a transaction
283 which is rolled back when finished, instead of by flushing and re-populating the
284 database. This results in an immense speedup for most types of unit tests. See
285 the documentation for :class:`TestCase` and :class:`TransactionTestCase` for a
286 full description, and some important notes on database support.
287
288 Test client improvements
289 ------------------------
290
291 A couple of small -- but highly useful -- improvements have been made to the
292 test client:
293
294 * The test :class:`Client` now can automatically follow redirects with the
295 ``follow`` argument to :meth:`Client.get` and :meth:`Client.post`. This
296 makes testing views that issue redirects simpler.
297
298 * It's now easier to get at the template context in the response returned
299 the test client: you'll simply access the context as
300 ``request.context[key]``. The old way, which treats ``request.context`` as
301 a list of contexts, one for each rendered template in the inheritance
302 chain, is still available if you need it.
303
304 New admin features
305 ------------------
306
307 Django 1.1 adds a couple of nifty new features to Django's admin interface:
308
309 Editable fields on the change list
310 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
311
312 You can now make fields editable on the admin list views via the new
313 :ref:`list_editable <admin-list-editable>` admin option. These fields will show
314 up as form widgets on the list pages, and can be edited and saved in bulk.
315
316 Admin "actions"
317 ~~~~~~~~~~~~~~~
318
319 You can now define :doc:`admin actions </ref/contrib/admin/actions>` that can
320 perform some action to a group of models in bulk. Users will be able to select
321 objects on the change list page and then apply these bulk actions to all
322 selected objects.
323
324 Django ships with one pre-defined admin action to delete a group of objects in
325 one fell swoop.
326
327 Conditional view processing
328 ---------------------------
329
330 Django now has much better support for :doc:`conditional view processing
331 </topics/conditional-view-processing>` using the standard ``ETag`` and
332 ``Last-Modified`` HTTP headers. This means you can now easily short-circuit
333 view processing by testing less-expensive conditions. For many views this can
334 lead to a serious improvement in speed and reduction in bandwidth.
335
336 URL namespaces
337 --------------
338
339 Django 1.1 improves :ref:`named URL patterns <naming-url-patterns>` with the
340 introduction of URL "namespaces."
341
342 In short, this feature allows the same group of URLs, from the same application,
343 to be included in a Django URLConf multiple times, with varying (and potentially
344 nested) named prefixes which will be used when performing reverse resolution. In
345 other words, reusable applications like Django's admin interface may be
346 registered multiple times without URL conflicts.
347
348 For full details, see :ref:`the documentation on defining URL namespaces
349 <topics-http-defining-url-namespaces>`.
350
351 GeoDjango
352 ---------
353
354 In Django 1.1, :doc:`GeoDjango </ref/contrib/gis/index>` (i.e.
355 ``django.contrib.gis``) has several new features:
356
357 * Support for SpatiaLite_ -- a spatial database for SQLite -- as a spatial
358 backend.
359
360 * Geographic aggregates (``Collect``, ``Extent``, ``MakeLine``, ``Union``)
361 and ``F`` expressions.
362
363 * New ``GeoQuerySet`` methods: ``collect``, ``geojson``, and
364 ``snap_to_grid``.
365
366 * A new list interface methods for ``GEOSGeometry`` objects.
367
368 For more details, see the GeoDjango documentation.
369
370 .. _spatialite: https://www.gaia-gis.it/gaia-sins/
371
372 Other improvements
373 ------------------
374
375 Other new features and changes introduced since Django 1.0 include:
376
377 * The :doc:`CSRF protection middleware </ref/csrf>` has been split into
378 two classes -- ``CsrfViewMiddleware`` checks incoming requests, and
379 ``CsrfResponseMiddleware`` processes outgoing responses. The combined
380 ``CsrfMiddleware`` class (which does both) remains for
381 backwards-compatibility, but using the split classes is now recommended in
382 order to allow fine-grained control of when and where the CSRF processing
383 takes place.
384
385 * ``reverse()`` and code which uses it (e.g., the ``{% url %}`` template tag)
386 now works with URLs in Django's administrative site, provided that the admin
387 URLs are set up via ``include(admin.site.urls)`` (sending admin requests to
388 the ``admin.site.root`` view still works, but URLs in the admin will not be
389 "reversible" when configured this way).
390
391 * The ``include()`` function in Django URLconf modules can now accept sequences
392 of URL patterns (generated by ``patterns()``) in addition to module names.
393
394 * Instances of Django forms (see :doc:`the forms overview </topics/forms/index>`)
395 now have two additional methods, ``hidden_fields()`` and ``visible_fields()``,
396 which return the list of hidden -- i.e., ``<input type="hidden">`` -- and
397 visible fields on the form, respectively.
398
399 * The ``redirect_to`` generic view
400 now accepts an additional keyword argument
401 ``permanent``. If ``permanent`` is ``True``, the view will emit an HTTP
402 permanent redirect (status code 301). If ``False``, the view will emit an HTTP
403 temporary redirect (status code 302).
404
405 * A new database lookup type -- ``week_day`` -- has been added for ``DateField``
406 and ``DateTimeField``. This type of lookup accepts a number between 1 (Sunday)
407 and 7 (Saturday), and returns objects where the field value matches that day
408 of the week. See :ref:`the full list of lookup types <field-lookups>` for
409 details.
410
411 * The ``{% for %}`` tag in Django's template language now accepts an optional
412 ``{% empty %}`` clause, to be displayed when ``{% for %}`` is asked to loop
413 over an empty sequence. See :doc:`the list of built-in template tags
414 </ref/templates/builtins>` for examples of this.
415
416 * The :djadmin:`dumpdata` management command now accepts individual
417 model names as arguments, allowing you to export the data just from
418 particular models.
419
420 * There's a new :tfilter:`safeseq` template filter which works just like
421 :tfilter:`safe` for lists, marking each item in the list as safe.
422
423 * :doc:`Cache backends </topics/cache>` now support ``incr()`` and
424 ``decr()`` commands to increment and decrement the value of a cache key.
425 On cache backends that support atomic increment/decrement -- most
426 notably, the memcached backend -- these operations will be atomic, and
427 quite fast.
428
429 * Django now can :doc:`easily delegate authentication to the web server
430 </howto/auth-remote-user>` via a new authentication backend that supports
431 the standard ``REMOTE_USER`` environment variable used for this purpose.
432
433 * There's a new :func:`django.shortcuts.redirect` function that makes it
434 easier to issue redirects given an object, a view name, or a URL.
435
436 * The ``postgresql_psycopg2`` backend now supports :ref:`native PostgreSQL
437 autocommit <postgresql-notes>`. This is an advanced, PostgreSQL-specific
438 feature, that can make certain read-heavy applications a good deal
439 faster.
440
441 What's next?
442 ============
443
444 We'll take a short break, and then work on Django 1.2 will begin -- no rest for
445 the weary! If you'd like to help, discussion of Django development, including
446 progress toward the 1.2 release, takes place daily on the |django-developers|
447 mailing list and in the ``#django-dev`` IRC channel on ``irc.libera.chat``.
448 Feel free to join the discussions!
449
450 Django's online documentation also includes pointers on how to contribute to
451 Django:
452
453 * :doc:`How to contribute to Django </internals/contributing/index>`
454
455 Contributions on any level -- developing code, writing documentation or simply
456 triaging tickets and helping to test proposed bugfixes -- are always welcome and
457 appreciated.
458
459 And that's the way it is.