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

/docs/releases/1.3-alpha-1.txt

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