PageRenderTime 40ms CodeModel.GetById 19ms RepoModel.GetById 0ms app.codeStats 0ms

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