PageRenderTime 98ms CodeModel.GetById 91ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/releases/1.1.txt

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