diff --git a/docs/releases/1.3-alpha-1.txt b/docs/releases/1.3-alpha-1.txt new file mode 100644 index 00000000000..c233734a2b0 --- /dev/null +++ b/docs/releases/1.3-alpha-1.txt @@ -0,0 +1,333 @@ +================================ +Django 1.3 alpha 1 release notes +================================ + +This page documents release notes for the as-yet-unreleased Django +1.3. As such, it's tentative and subject to change. It provides +up-to-date information for those who are following trunk. + +November 11, 2010 + +Welcome to Django 1.3 alpha 1! + +This is the first in a series of preview/development releases leading +up to the eventual release of Django 1.3. This release is primarily +targeted at developers who are interested in trying out new features +and testing the Django codebase to help identify and resolve bugs +prior to the final 1.3 release. + +As such, this release is *not* intended for production use, and any such use is +discouraged. + +As of this alpha release, Django 1.3 containsa number of nifty `new +features`_, lots of bug fixes, some minor `backwards incompatible +changes`_ and an easy upgrade path from Django 1.2. + +.. _new features: `What's new in Django 1.3 alpha 1`_ + +.. _backwards incompatible changes: backwards-incompatible-changes-1.3_ + +What's new in Django 1.3 alpha 1 +================================ + +Class-based views +~~~~~~~~~~~~~~~~~ + +Django 1.3 adds a framework that allows you to use a class as a view. +This means you can compose a view out of a collection of methods that +can be subclassed and overridden to provide + +Analogs of all the old function-based generic views have been +provided, along with a completely generic view base class that can be +used as the basis for reusable applications that can be easily +extended. + +See :doc:`the documentation on Generic Views` +for more details. There is also a document to help you :doc:`convert +your function-based generic views to class-based +views`. + +Logging +~~~~~~~ + +Django 1.3 adds framework-level support for Python's logging module. +This means you can now easily configure and control logging as part of +your Django project. A number of logging handlers and logging calls +have been added to Django's own code as well -- most notably, the +error emails sent on a HTTP 500 server error are now handled as a +logging activity. See :doc:`the documentation on Django's logging +interface ` for more details. + +``unittest2`` support +~~~~~~~~~~~~~~~~~~~~~ + +Python 2.7 introduced some major changes to the unittest library, +adding some extremely useful features. To ensure that every Django +project can benefit from these new features, Django ships with a +copy of unittest2_, a copy of the Python 2.7 unittest library, +backported for Python 2.4 compatibility. + +To access this library, Django provides the +``django.utils.unittest`` module alias. If you are using Python +2.7, or you have installed unittest2 locally, Django will map the +alias to the installed version of the unittest library. Otherwise, +Django will use it's own bundled version of unittest2. + +To use this alias, simply use:: + + from django.utils import unittest + +wherever you would have historically used:: + + import unittest + +If you want to continue to use the base unittest libary, you can -- +you just won't get any of the nice new unittest2 features. + +.. _unittest2: http://pypi.python.org/pypi/unittest2 + +Transaction context managers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Users of Python 2.5 and above may now use :ref:`transaction management functions +` as `context managers`_. For example:: + + with transaction.autocommit(): + # ... + +.. _context managers: http://docs.python.org/glossary.html#term-context-manager + +For more information, see :ref:`transaction-management-functions`. + +Configurable delete-cascade +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:class:`~django.db.models.ForeignKey` and +:class:`~django.db.models.OneToOneField` now accept an +:attr:`~django.db.models.ForeignKey.on_delete` argument to customize behavior +when the referenced object is deleted. Previously, deletes were always +cascaded; available alternatives now include set null, set default, set to any +value, protect, or do nothing. + +For more information, see the :attr:`~django.db.models.ForeignKey.on_delete` +documentation. + +Contextual markers in translatable strings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For translation strings with ambiguous meaning, you can now +use the ``pgettext`` function to specify the context of the string. + +For more information, see :ref:`contextual-markers` + +Everything else +~~~~~~~~~~~~~~~ + +Django :doc:`1.1 <1.1>` and :doc:`1.2 <1.2>` added +lots of big ticket items to Django, like multiple-database support, +model validation, and a session-based messages framework. However, +this focus on big features came at the cost of lots of smaller +features. + +To compensate for this, the focus of the Django 1.3 development +process has been on adding lots of smaller, long standing feature +requests. These include: + + * Improved tools for accessing and manipulating the current Site. + + * A :class:`~django.test.client.RequestFactory` for mocking + requests in tests. + + * A new test assertion -- + :meth:`~django.test.client.Client.assertNumQueries` -- making it + easier to test the database activity associated with a view. + + +.. _backwards-incompatible-changes-1.3: + +Backwards-incompatible changes in 1.3 alpha 1 +============================================= + +PasswordInput default rendering behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Prior to Django 1.3, a :class:`~django.forms.PasswordInput` would render +data values like any other form. If a form submission raised an error, +the password that was submitted would be reflected to the client as form +data populating the form for resubmission. + +This had the potential to leak passwords, as any failed password +attempt would cause the password that was typed to be sent back to the +client. + +In Django 1.3, the default behavior of +:class:`~django.forms.PasswordInput` is to suppress the display of +password values. This change doesn't alter the way form data is +validated or handled. It only affects the user experience with +passwords on a form when they make an error submitting form data (such +as on unsuccessful logins, or when completing a registration form). + +If you want restore the pre-Django 1.3 behavior, you need to pass in a +custom widget to your form that sets the ``render_value`` argument:: + + class LoginForm(forms.Form): + username = forms.CharField(max_length=100) + password = forms.CharField(widget=forms.PasswordInput(render_value=True)) + +Clearable default widget for FileField +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Django 1.3 now includes a ``ClearableFileInput`` form widget in addition to +``FileInput``. ``ClearableFileInput`` renders with a checkbox to clear the +field's value (if the field has a value and is not required); ``FileInput`` +provided no means for clearing an existing file from a ``FileField``. + +``ClearableFileInput`` is now the default widget for a ``FileField``, so +existing forms including ``FileField`` without assigning a custom widget will +need to account for the possible extra checkbox in the rendered form output. + +To return to the previous rendering (without the ability to clear the +``FileField``), use the ``FileInput`` widget in place of +``ClearableFileInput``. For instance, in a ``ModelForm`` for a hypothetical +``Document`` model with a ``FileField`` named ``document``:: + + from django import forms + from myapp.models import Document + + class DocumentForm(forms.ModelForm): + class Meta: + model = Document + widgets = {'document': forms.FileInput} + +New index on database session table +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Prior to Django 1.3, the database table used by the database backend +for the :doc:`sessions ` app had no index on +the ``expire_date`` column. As a result, date-based queries on the +session table -- such as the query that is needed to purge old +sessions -- would be very slow if there were lots of sessions. + +If you have an existing project that is using the database session +backend, you don't have to do anything to accommodate this change. +However, you may get a significant performance boost if you manually +add the new index to the session table. The SQL that will add the +index can be found by running the :djadmin:`sqlindexes` admin +command:: + + python manage.py sqlindexes sessions + +No more naughty words +~~~~~~~~~~~~~~~~~~~~~ + +Django has historically provided (and enforced) a list of profanities. +The :doc:`comments app ` has enforced this +list of profanities, preventing people from submitting comments that +contained one of those profanities. + +Unfortunately, the technique used to implement this profanities list +was woefully naive, and prone to the `Scunthorpe problem`_. Fixing the +built in filter to fix this problem would require significant effort, +and since natural language processing isn't the normal domain of a web +framework, we have "fixed" the problem by making the list of +prohibited words an empty list. + +If you want to restore the old behavior, simply put a +``PROFANITIES_LIST`` setting in your settings file that includes the +words that you want to prohibit (see the `commit that implemented this +change`_ if you want to see the list of words that was historically +prohibited). However, if avoiding profanities is important to you, you +would be well advised to seek out a better, less naive approach to the +problem. + +.. _Scunthorpe problem: http://en.wikipedia.org/wiki/Scunthorpe_problem +.. _commit that implemented this change: http://code.djangoproject.com/changeset/13996 + +Localflavor changes +~~~~~~~~~~~~~~~~~~~ + +Django 1.3 introduces the following backwards-incompatible changes to +local flavors: + + * Indonesia (id) -- The province "Nanggroe Aceh Darussalam (NAD)" + has been removed from the province list in favor of the new + official designation "Aceh (ACE)". + + +.. _deprecated-features-1.3: + +Features deprecated in 1.3 +========================== + +Django 1.3 deprecates some features from earlier releases. +These features are still supported, but will be gradually phased out +over the next few release cycles. + +Code taking advantage of any of the features below will raise a +``PendingDeprecationWarning`` in Django 1.3. This warning will be +silent by default, but may be turned on using Python's `warnings +module`_, or by running Python with a ``-Wd`` or `-Wall` flag. + +.. _warnings module: http://docs.python.org/library/warnings.html + +In Django 1.4, these warnings will become a ``DeprecationWarning``, +which is *not* silent. In Django 1.5 support for these features will +be removed entirely. + +.. seealso:: + + For more details, see the documentation :doc:`Django's release process + ` and our :doc:`deprecation timeline + `.` + +``mod_python`` support +~~~~~~~~~~~~~~~~~~~~~~ + +The ``mod_python`` library has not had a release since 2007 or a commit since +2008. The Apache Foundation board voted to remove ``mod_python`` from the set +of active projects in its version control repositories, and its lead developer +has shifted all of his efforts toward the lighter, slimmer, more stable, and +more flexible ``mod_wsgi`` backend. + +If you are currently using the ``mod_python`` request handler, it is strongly +encouraged you redeploy your Django instances using :doc:`mod_wsgi +`. + +Function-based generic views +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As a result of the introduction of class-based generic views, the +function-based generic views provided by Django have been deprecated. +The following modules and the views they contain have been deprecated: + + * :mod:`django.views.generic.create_update` + * :mod:`django.views.generic.date_based` + * :mod:`django.views.generic.list_detail` + * :mod:`django.views.generic.simple` + +Test client response ``template`` attribute +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Django's :ref:`test client ` returns +:class:`~django.test.client.Response` objects annotated with extra testing +information. In Django versions prior to 1.3, this included a +:attr:`~django.test.client.Response.template` attribute containing information +about templates rendered in generating the response: either None, a single +:class:`~django.template.Template` object, or a list of +:class:`~django.template.Template` objects. This inconsistency in return values +(sometimes a list, sometimes not) made the attribute difficult to work with. + +In Django 1.3 the :attr:`~django.test.client.Response.template` attribute is +deprecated in favor of a new :attr:`~django.test.client.Response.templates` +attribute, which is always a list, even if it has only a single element or no +elements. + +``DjangoTestRunner`` +~~~~~~~~~~~~~~~~~~~~ + +As a result of the introduction of support for unittest2, the features +of :class:`django.test.simple.DjangoTestRunner` (including fail-fast +and Ctrl-C test termination) have been made redundant. In view of this +redundancy, :class:`~django.test.simple.DjangoTestRunner` has been +turned into an empty placeholder class, and will be removed entirely +in Django 1.5.