PageRenderTime 32ms CodeModel.GetById 17ms RepoModel.GetById 0ms app.codeStats 1ms

Plain Text | 404 lines | 297 code | 107 blank | 0 comment | 0 complexity | 9cf2a01b82894809b1767532ecf15981 MD5 | raw file
Possible License(s): BSD-3-Clause
  1. ================================
  2. Django 1.3 alpha 1 release notes
  3. ================================
  4. November 11, 2010
  5. Welcome to Django 1.3 alpha 1!
  6. This is the first in a series of preview/development releases leading
  7. up to the eventual release of Django 1.3. This release is primarily
  8. targeted at developers who are interested in trying out new features
  9. and testing the Django codebase to help identify and resolve bugs
  10. prior to the final 1.3 release.
  11. As such, this release is *not* intended for production use, and any such use is
  12. discouraged.
  13. As of this alpha release, Django 1.3 contains a number of nifty `new
  14. features`_, lots of bug fixes, some minor `backwards incompatible
  15. changes`_ and an easy upgrade path from Django 1.2.
  16. .. _new features: `What's new in Django 1.3 alpha 1`_
  17. .. _backwards incompatible changes: backwards-incompatible-changes-1.3-alpha-1_
  18. What's new in Django 1.3 alpha 1
  19. ================================
  20. Class-based views
  21. ~~~~~~~~~~~~~~~~~
  22. Django 1.3 adds a framework that allows you to use a class as a view.
  23. This means you can compose a view out of a collection of methods that
  24. can be subclassed and overridden to provide common views of data without
  25. having to write too much code.
  26. Analogs of all the old function-based generic views have been provided,
  27. along with a completely generic view base class that can be used as
  28. the basis for reusable applications that can be easily extended.
  29. See :doc:`the documentation on Class-based Generic Views
  30. </topics/class-based-views>` for more details. There is also a document to
  31. help you :doc:`convert your function-based generic views to class-based
  32. views</topics/generic-views-migration>`.
  33. Logging
  34. ~~~~~~~
  35. Django 1.3 adds framework-level support for Python's logging module.
  36. This means you can now easily configure and control logging as part of
  37. your Django project. A number of logging handlers and logging calls
  38. have been added to Django's own code as well -- most notably, the
  39. error emails sent on a HTTP 500 server error are now handled as a
  40. logging activity. See :doc:`the documentation on Django's logging
  41. interface </topics/logging>` for more details.
  42. Extended static files handling
  43. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  44. Django 1.3 ships with a new contrib app ``'django.contrib.staticfiles'``
  45. to help developers handle the static media files (images, CSS, Javascript,
  46. etc.) that are needed to render a complete web page.
  47. In previous versions of Django, it was common to place static assets in
  48. :setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both at
  49. :setting:`MEDIA_URL`. Part of the purpose of introducing the ``staticfiles``
  50. app is to make it easier to keep static files separate from user-uploaded
  51. files. For this reason, you will probably want to make your
  52. :setting:`MEDIA_ROOT` and :setting:`MEDIA_URL` different from your
  53. :setting:`STATICFILES_ROOT` and :setting:`STATICFILES_URL`. You will need to
  54. arrange for serving of files in :setting:`MEDIA_ROOT` yourself;
  55. ``staticfiles`` does not deal with user-uploaded media at all.
  56. See the :doc:`reference documentation of the app </ref/contrib/staticfiles>`
  57. for more details or learn how to :doc:`manage static files
  58. </howto/static-files>`.
  59. ``unittest2`` support
  60. ~~~~~~~~~~~~~~~~~~~~~
  61. Python 2.7 introduced some major changes to the unittest library,
  62. adding some extremely useful features. To ensure that every Django
  63. project can benefit from these new features, Django ships with a
  64. copy of unittest2_, a copy of the Python 2.7 unittest library,
  65. backported for Python 2.4 compatibility.
  66. To access this library, Django provides the
  67. ``django.utils.unittest`` module alias. If you are using Python
  68. 2.7, or you have installed unittest2 locally, Django will map the
  69. alias to the installed version of the unittest library. Otherwise,
  70. Django will use it's own bundled version of unittest2.
  71. To use this alias, simply use::
  72. from django.utils import unittest
  73. wherever you would have historically used::
  74. import unittest
  75. If you want to continue to use the base unittest libary, you can --
  76. you just won't get any of the nice new unittest2 features.
  77. .. _unittest2:
  78. Transaction context managers
  79. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  80. Users of Python 2.5 and above may now use :ref:`transaction management functions
  81. <transaction-management-functions>` as `context managers`_. For example::
  82. with transaction.autocommit():
  83. # ...
  84. .. _context managers:
  85. For more information, see :ref:`transaction-management-functions`.
  86. Configurable delete-cascade
  87. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  88. :class:`~django.db.models.ForeignKey` and
  89. :class:`~django.db.models.OneToOneField` now accept an
  90. :attr:`~django.db.models.ForeignKey.on_delete` argument to customize behavior
  91. when the referenced object is deleted. Previously, deletes were always
  92. cascaded; available alternatives now include set null, set default, set to any
  93. value, protect, or do nothing.
  94. For more information, see the :attr:`~django.db.models.ForeignKey.on_delete`
  95. documentation.
  96. Contextual markers in translatable strings
  97. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  98. For translation strings with ambiguous meaning, you can now
  99. use the ``pgettext`` function to specify the context of the string.
  100. For more information, see :ref:`contextual-markers`
  101. Everything else
  102. ~~~~~~~~~~~~~~~
  103. Django :doc:`1.1 <1.1>` and :doc:`1.2 <1.2>` added
  104. lots of big ticket items to Django, like multiple-database support,
  105. model validation, and a session-based messages framework. However,
  106. this focus on big features came at the cost of lots of smaller
  107. features.
  108. To compensate for this, the focus of the Django 1.3 development
  109. process has been on adding lots of smaller, long standing feature
  110. requests. These include:
  111. * Improved tools for accessing and manipulating the current Site via
  112. :func:`django.contrib.sites.models.get_current_site`.
  113. * A :class:`~django.test.client.RequestFactory` for mocking
  114. requests in tests.
  115. * A new test assertion --
  116. :meth:`~django.test.client.Client.assertNumQueries` -- making it
  117. easier to test the database activity associated with a view.
  118. .. _backwards-incompatible-changes-1.3-alpha-1:
  119. Backwards-incompatible changes in 1.3 alpha 1
  120. =============================================
  121. PasswordInput default rendering behavior
  122. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  123. The :class:`~django.forms.PasswordInput` form widget, intended for use
  124. with form fields which represent passwords, accepts a boolean keyword
  125. argument ``render_value`` indicating whether to send its data back to
  126. the browser when displaying a submitted form with errors. Prior to
  127. Django 1.3, this argument defaulted to ``True``, meaning that the
  128. submitted password would be sent back to the browser as part of the
  129. form. Developers who wished to add a bit of additional security by
  130. excluding that value from the redisplayed form could instantiate a
  131. :class:`~django.forms.PasswordInput` passing ``render_value=False`` .
  132. Due to the sensitive nature of passwords, however, Django 1.3 takes
  133. this step automatically; the default value of ``render_value`` is now
  134. ``False``, and developers who want the password value returned to the
  135. browser on a submission with errors (the previous behavior) must now
  136. explicitly indicate this. For example::
  137. class LoginForm(forms.Form):
  138. username = forms.CharField(max_length=100)
  139. password = forms.CharField(widget=forms.PasswordInput(render_value=True))
  140. Clearable default widget for FileField
  141. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  142. Django 1.3 now includes a ``ClearableFileInput`` form widget in addition to
  143. ``FileInput``. ``ClearableFileInput`` renders with a checkbox to clear the
  144. field's value (if the field has a value and is not required); ``FileInput``
  145. provided no means for clearing an existing file from a ``FileField``.
  146. ``ClearableFileInput`` is now the default widget for a ``FileField``, so
  147. existing forms including ``FileField`` without assigning a custom widget will
  148. need to account for the possible extra checkbox in the rendered form output.
  149. To return to the previous rendering (without the ability to clear the
  150. ``FileField``), use the ``FileInput`` widget in place of
  151. ``ClearableFileInput``. For instance, in a ``ModelForm`` for a hypothetical
  152. ``Document`` model with a ``FileField`` named ``document``::
  153. from django import forms
  154. from myapp.models import Document
  155. class DocumentForm(forms.ModelForm):
  156. class Meta:
  157. model = Document
  158. widgets = {'document': forms.FileInput}
  159. New index on database session table
  160. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  161. Prior to Django 1.3, the database table used by the database backend
  162. for the :doc:`sessions </topics/http/sessions>` app had no index on
  163. the ``expire_date`` column. As a result, date-based queries on the
  164. session table -- such as the query that is needed to purge old
  165. sessions -- would be very slow if there were lots of sessions.
  166. If you have an existing project that is using the database session
  167. backend, you don't have to do anything to accommodate this change.
  168. However, you may get a significant performance boost if you manually
  169. add the new index to the session table. The SQL that will add the
  170. index can be found by running the :djadmin:`sqlindexes` admin
  171. command::
  172. python sqlindexes sessions
  173. No more naughty words
  174. ~~~~~~~~~~~~~~~~~~~~~
  175. Django has historically provided (and enforced) a list of profanities.
  176. The :doc:`comments app </ref/contrib/comments/index>` has enforced this
  177. list of profanities, preventing people from submitting comments that
  178. contained one of those profanities.
  179. Unfortunately, the technique used to implement this profanities list
  180. was woefully naive, and prone to the `Scunthorpe problem`_. Fixing the
  181. built in filter to fix this problem would require significant effort,
  182. and since natural language processing isn't the normal domain of a web
  183. framework, we have "fixed" the problem by making the list of
  184. prohibited words an empty list.
  185. If you want to restore the old behavior, simply put a
  186. :setting:`PROFANITIES_LIST` setting in your settings file that includes the
  187. words that you want to prohibit (see the `commit that implemented this
  188. change`_ if you want to see the list of words that was historically
  189. prohibited). However, if avoiding profanities is important to you, you
  190. would be well advised to seek out a better, less naive approach to the
  191. problem.
  192. .. _Scunthorpe problem:
  193. .. _commit that implemented this change:
  194. Localflavor changes
  195. ~~~~~~~~~~~~~~~~~~~
  196. Django 1.3 introduces the following backwards-incompatible changes to
  197. local flavors:
  198. * Indonesia (id) -- The province "Nanggroe Aceh Darussalam (NAD)"
  199. has been removed from the province list in favor of the new
  200. official designation "Aceh (ACE)".
  201. Features deprecated in 1.3
  202. ==========================
  203. Django 1.3 deprecates some features from earlier releases.
  204. These features are still supported, but will be gradually phased out
  205. over the next few release cycles.
  206. Code taking advantage of any of the features below will raise a
  207. ``PendingDeprecationWarning`` in Django 1.3. This warning will be
  208. silent by default, but may be turned on using Python's `warnings
  209. module`_, or by running Python with a ``-Wd`` or `-Wall` flag.
  210. .. _warnings module:
  211. In Django 1.4, these warnings will become a ``DeprecationWarning``,
  212. which is *not* silent. In Django 1.5 support for these features will
  213. be removed entirely.
  214. .. seealso::
  215. For more details, see the documentation :doc:`Django's release process
  216. </internals/release-process>` and our :doc:`deprecation timeline
  217. </internals/deprecation>`.
  218. ``mod_python`` support
  219. ~~~~~~~~~~~~~~~~~~~~~~
  220. The ``mod_python`` library has not had a release since 2007 or a commit since
  221. 2008. The Apache Foundation board voted to remove ``mod_python`` from the set
  222. of active projects in its version control repositories, and its lead developer
  223. has shifted all of his efforts toward the lighter, slimmer, more stable, and
  224. more flexible ``mod_wsgi`` backend.
  225. If you are currently using the ``mod_python`` request handler, you are strongly
  226. encouraged to redeploy your Django instances using :doc:`mod_wsgi
  227. </howto/deployment/modwsgi>`.
  228. Function-based generic views
  229. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  230. As a result of the introduction of class-based generic views, the
  231. function-based generic views provided by Django have been deprecated.
  232. The following modules and the views they contain have been deprecated:
  233. * :mod:`django.views.generic.create_update`
  234. * :mod:`django.views.generic.date_based`
  235. * :mod:`django.views.generic.list_detail`
  236. * :mod:`django.views.generic.simple`
  237. Test client response ``template`` attribute
  238. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  239. Django's :ref:`test client <test-client>` returns
  240. :class:`~django.test.client.Response` objects annotated with extra testing
  241. information. In Django versions prior to 1.3, this included a
  242. :attr:`~django.test.client.Response.template` attribute containing information
  243. about templates rendered in generating the response: either None, a single
  244. :class:`~django.template.Template` object, or a list of
  245. :class:`~django.template.Template` objects. This inconsistency in return values
  246. (sometimes a list, sometimes not) made the attribute difficult to work with.
  247. In Django 1.3 the :attr:`~django.test.client.Response.template` attribute is
  248. deprecated in favor of a new :attr:`~django.test.client.Response.templates`
  249. attribute, which is always a list, even if it has only a single element or no
  250. elements.
  251. ``DjangoTestRunner``
  252. ~~~~~~~~~~~~~~~~~~~~
  253. As a result of the introduction of support for unittest2, the features
  254. of :class:`django.test.simple.DjangoTestRunner` (including fail-fast
  255. and Ctrl-C test termination) have been made redundant. In view of this
  256. redundancy, :class:`~django.test.simple.DjangoTestRunner` has been
  257. turned into an empty placeholder class, and will be removed entirely
  258. in Django 1.5.
  259. The Django 1.3 roadmap
  260. ======================
  261. Before the final Django 1.3 release, several other preview/development
  262. releases will be made available. The current schedule consists of at
  263. least the following:
  264. * Week of **November 29, 2010**: First Django 1.3 beta release. Final
  265. feature freeze for Django 1.3.
  266. * Week of **January 10, 2011**: First Django 1.3 release
  267. candidate. String freeze for translations.
  268. * Week of **January 17, 2011**: Django 1.3 final release.
  269. If necessary, additional alpha, beta or release-candidate packages
  270. will be issued prior to the final 1.3 release. Django 1.3 will be
  271. released approximately one week after the final release candidate.
  272. What you can do to help
  273. =======================
  274. In order to provide a high-quality 1.3 release, we need your help. Although this
  275. alpha release is, again, *not* intended for production use, you can help the
  276. Django team by trying out the alpha codebase in a safe test environment and
  277. reporting any bugs or issues you encounter. The Django ticket tracker is the
  278. central place to search for open issues:
  279. *
  280. Please open new tickets if no existing ticket corresponds to a problem you're
  281. running into.
  282. Additionally, discussion of Django development, including progress toward the
  283. 1.3 release, takes place daily on the django-developers mailing list:
  284. *
  285. ... and in the ``#django-dev`` IRC channel on ````. If you're
  286. interested in helping out with Django's development, feel free to join the
  287. discussions there.
  288. Django's online documentation also includes pointers on how to contribute to
  289. Django:
  290. * :doc:`How to contribute to Django </internals/contributing>`
  291. Contributions on any level -- developing code, writing documentation or simply
  292. triaging tickets and helping to test proposed bugfixes -- are always welcome and
  293. appreciated.
  294. Several development sprints will also be taking place before the 1.3
  295. release; these will typically be announced in advance on the
  296. django-developers mailing list, and anyone who wants to help is
  297. welcome to join in.