/docs/releases/1.3.txt
Plain Text | 904 lines | 683 code | 221 blank | 0 comment | 0 complexity | c16900e5ebb95e27937f5c38c1ece8c5 MD5 | raw file
1======================== 2Django 1.3 release notes 3======================== 4 5*March 23, 2011* 6 7Welcome to Django 1.3! 8 9Nearly a year in the making, Django 1.3 includes quite a few `new 10features`_ and plenty of bug fixes and improvements to existing 11features. These release notes cover the new features in 1.3, as well 12as some `backwards-incompatible changes`_ you'll want to be aware of 13when upgrading from Django 1.2 or older versions. 14 15Overview 16======== 17 18Django 1.3's focus has mostly been on resolving smaller, long-standing 19feature requests, but that hasn't prevented a few fairly significant 20new features from landing, including: 21 22* A framework for writing `class-based views`_. 23 24* Built-in support for `using Python's logging facilities`_. 25 26* Contrib support for `easy handling of static files`_. 27 28* Django's testing framework now supports (and ships with a copy of) 29 `the unittest2 library`_. 30 31There's plenty more, of course; see the coverage of `new features`_ 32below for a full rundown and details. 33 34Wherever possible, of course, new features are introduced in a 35backwards-compatible manner per :doc:`our API stability policy 36</misc/api-stability>` policy. As a result of this policy, Django 1.3 37`begins the deprecation process for some features`_. 38 39Some changes, unfortunately, are genuinely backwards-incompatible; in 40most cases these are due to security issues or bugs which simply 41couldn't be fixed any other way. Django 1.3 includes a few of these, 42and descriptions of them -- along with the (minor) modifications 43you'll need to make to handle them -- are documented in the list of 44`backwards-incompatible changes`_ below. 45 46.. _new features: `What's new in Django 1.3`_ 47.. _backwards-incompatible changes: backwards-incompatible-changes-1.3_ 48.. _using Python's logging facilities: `Logging`_ 49.. _easy handling of static files: `Extended static files handling`_ 50.. _the unittest2 library: `unittest2 support`_ 51.. _begins the deprecation process for some features: `deprecated-features-1.3`_ 52 53Python compatibility 54==================== 55 56The release of Django 1.2 was notable for having the first shift in 57Django's Python compatibility policy; prior to Django 1.2, Django 58supported any 2.x version of Python from 2.3 up. As of Django 1.2, the 59minimum requirement was raised to Python 2.4. 60 61Django 1.3 continues to support Python 2.4, but will be the final 62Django release series to do so; beginning with Django 1.4, the minimum 63supported Python version will be 2.5. A document outlining our full 64timeline for deprecating Python 2.x and moving to Python 3.x will be 65published shortly after the release of Django 1.3. 66 67What's new in Django 1.3 68======================== 69 70Class-based views 71~~~~~~~~~~~~~~~~~ 72 73Django 1.3 adds a framework that allows you to use a class as a view. 74This means you can compose a view out of a collection of methods that 75can be subclassed and overridden to provide common views of data without 76having to write too much code. 77 78Analogs of all the old function-based generic views have been 79provided, along with a completely generic view base class that can be 80used as the basis for reusable applications that can be easily 81extended. 82 83See :doc:`the documentation on class-based generic views</topics/class-based-views>` 84for more details. There is also a document to help you :doc:`convert 85your function-based generic views to class-based 86views</topics/generic-views-migration>`. 87 88Logging 89~~~~~~~ 90 91Django 1.3 adds framework-level support for Python's ``logging`` 92module. This means you can now easily configure and control logging 93as part of your Django project. A number of logging handlers and 94logging calls have been added to Django's own code as well -- most 95notably, the error emails sent on a HTTP 500 server error are now 96handled as a logging activity. See :doc:`the documentation on Django's 97logging interface </topics/logging>` for more details. 98 99Extended static files handling 100~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 101 102Django 1.3 ships with a new contrib app -- 103``django.contrib.staticfiles`` -- to help developers handle the static 104media files (images, CSS, Javascript, etc.) that are needed to render 105a complete web page. 106 107In previous versions of Django, it was common to place static assets 108in :setting:`MEDIA_ROOT` along with user-uploaded files, and serve 109them both at :setting:`MEDIA_URL`. Part of the purpose of introducing 110the ``staticfiles`` app is to make it easier to keep static files 111separate from user-uploaded files. Static assets should now go in 112``static/`` subdirectories of your apps or in other static assets 113directories listed in :setting:`STATICFILES_DIRS`, and will be served 114at :setting:`STATIC_URL`. 115 116See the :doc:`reference documentation of the app </ref/contrib/staticfiles>` 117for more details or learn how to :doc:`manage static files 118</howto/static-files>`. 119 120unittest2 support 121~~~~~~~~~~~~~~~~~ 122 123Python 2.7 introduced some major changes to the ``unittest`` library, 124adding some extremely useful features. To ensure that every Django 125project can benefit from these new features, Django ships with a copy 126of unittest2_, a copy of the Python 2.7 unittest library, backported 127for Python 2.4 compatibility. 128 129To access this library, Django provides the ``django.utils.unittest`` 130module alias. If you are using Python 2.7, or you have installed 131``unittest2`` locally, Django will map the alias to the installed 132version of the unittest library. Otherwise, Django will use its own 133bundled version of unittest2. 134 135To take advantage of this alias, simply use:: 136 137 from django.utils import unittest 138 139wherever you would have historically used:: 140 141 import unittest 142 143If you want to continue to use the base unittest library, you can -- 144you just won't get any of the nice new unittest2 features. 145 146.. _unittest2: http://pypi.python.org/pypi/unittest2 147 148Transaction context managers 149~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 150 151Users of Python 2.5 and above may now use :ref:`transaction management functions 152<transaction-management-functions>` as `context managers`_. For example:: 153 154 with transaction.autocommit(): 155 # ... 156 157.. _context managers: http://docs.python.org/glossary.html#term-context-manager 158 159For more information, see :ref:`transaction-management-functions`. 160 161Configurable delete-cascade 162~~~~~~~~~~~~~~~~~~~~~~~~~~~ 163 164:class:`~django.db.models.ForeignKey` and 165:class:`~django.db.models.OneToOneField` now accept an 166:attr:`~django.db.models.ForeignKey.on_delete` argument to customize behavior 167when the referenced object is deleted. Previously, deletes were always 168cascaded; available alternatives now include set null, set default, set to any 169value, protect, or do nothing. 170 171For more information, see the :attr:`~django.db.models.ForeignKey.on_delete` 172documentation. 173 174Contextual markers and comments for translatable strings 175~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 176 177For translation strings with ambiguous meaning, you can now 178use the ``pgettext`` function to specify the context of the string. 179 180And if you just want to add some information for translators, you 181can also add special translator comments in the source. 182 183For more information, see :ref:`contextual-markers` and 184:ref:`translator-comments`. 185 186Improvements to built-in template tags 187~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 188 189A number of improvements have been made to Django's built-in template tags: 190 191 * The :ttag:`include` tag now accepts a ``with`` option, allowing 192 you to specify context variables to the included template 193 194 * The :ttag:`include` tag now accepts an ``only`` option, allowing 195 you to exclude the current context from the included context 196 197 * The :ttag:`with` tag now allows you to define multiple context 198 variables in a single :ttag:`with` block. 199 200 * The :ttag:`load` tag now accepts a ``from`` argument, allowing 201 you to load a single tag or filter from a library. 202 203TemplateResponse 204~~~~~~~~~~~~~~~~ 205 206It can sometimes be beneficial to allow decorators or middleware to 207modify a response *after* it has been constructed by the view. For 208example, you may want to change the template that is used, or put 209additional data into the context. 210 211However, you can't (easily) modify the content of a basic 212:class:`~django.http.HttpResponse` after it has been constructed. To 213overcome this limitation, Django 1.3 adds a new 214:class:`~django.template.response.TemplateResponse` class. Unlike basic 215:class:`~django.http.HttpResponse` objects, 216:class:`~django.template.response.TemplateResponse` objects retain the details 217of the template and context that was provided by the view to compute 218the response. The final output of the response is not computed until 219it is needed, later in the response process. 220 221For more details, see the :doc:`documentation </ref/template-response>` 222on the :class:`~django.template.response.TemplateResponse` class. 223 224Caching changes 225~~~~~~~~~~~~~~~ 226 227Django 1.3 sees the introduction of several improvements to the 228Django's caching infrastructure. 229 230Firstly, Django now supports multiple named caches. In the same way 231that Django 1.2 introduced support for multiple database connections, 232Django 1.3 allows you to use the new :setting:`CACHES` setting to 233define multiple named cache connections. 234 235Secondly, :ref:`versioning <cache_versioning>`, :ref:`site-wide 236prefixing <cache_key_prefixing>` and :ref:`transformation 237<cache_key_transformation>` have been added to the cache API. 238 239Thirdly, :ref:`cache key creation <using-vary-headers>` has been 240updated to take the request query string into account on ``GET`` 241requests. 242 243Finally, support for pylibmc_ has been added to the memcached cache 244backend. 245 246For more details, see the :doc:`documentation on 247caching in Django</topics/cache>`. 248 249.. _pylibmc: http://sendapatch.se/projects/pylibmc/ 250 251Permissions for inactive users 252~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 253 254If you provide a custom auth backend with ``supports_inactive_user`` 255set to ``True``, an inactive ``User`` instance will check the backend 256for permissions. This is useful for further centralizing the 257permission handling. See the :doc:`authentication docs </topics/auth>` 258for more details. 259 260GeoDjango 261~~~~~~~~~ 262 263The GeoDjango test suite is now included when 264:ref:`running the Django test suite <running-unit-tests>` with ``runtests.py`` 265when using :ref:`spatial database backends <spatial-backends>`. 266 267:setting:`MEDIA_URL` and :setting:`STATIC_URL` must end in a slash 268~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 269 270Previously, the :setting:`MEDIA_URL` setting only required a trailing slash if 271it contained a suffix beyond the domain name. 272 273A trailing slash is now *required* for :setting:`MEDIA_URL` and the new 274:setting:`STATIC_URL` setting as long as it is not blank. This ensures there is 275a consistent way to combine paths in templates. 276 277Project settings which provide either of both settings without a trailing 278slash will now raise a ``PendingDeprecationWarning``. 279 280In Django 1.4 this same condition will raise ``DeprecationWarning``, 281and in Django 1.5 will raise an ``ImproperlyConfigured`` exception. 282 283Everything else 284~~~~~~~~~~~~~~~ 285 286Django :doc:`1.1 <1.1>` and :doc:`1.2 <1.2>` added 287lots of big ticket items to Django, like multiple-database support, 288model validation, and a session-based messages framework. However, 289this focus on big features came at the cost of lots of smaller 290features. 291 292To compensate for this, the focus of the Django 1.3 development 293process has been on adding lots of smaller, long standing feature 294requests. These include: 295 296* Improved tools for accessing and manipulating the current 297 :class:`~django.contrib.sites.models.Site` object in 298 :doc:`the sites framework </ref/contrib/sites>`. 299 300* A :class:`~django.test.client.RequestFactory` for mocking requests 301 in tests. 302 303* A new test assertion -- 304 :meth:`~django.test.TestCase.assertNumQueries` -- making it 305 easier to test the database activity associated with a view. 306 307* Support for lookups spanning relations in admin's 308 :attr:`~django.contrib.admin.ModelAdmin.list_filter`. 309 310* Support for HTTPOnly_ cookies. 311 312* :meth:`~django.core.mail.mail_admins()` and 313 :meth:`~django.core.mail.mail_managers()` now support easily attaching 314 HTML content to messages. 315 316* :class:`~django.core.mail.EmailMessage` now supports CC's. 317 318* Error emails now include more of the detail and formatting of the 319 debug server error page. 320 321* :meth:`~django.template.Library.simple_tag` now accepts a 322 ``takes_context`` argument, making it easier to write simple 323 template tags that require access to template context. 324 325* A new :meth:`~django.shortcuts.render()` shortcut -- an alternative 326 to :meth:`~django.shortcuts.render_to_response()` providing a 327 :class:`~django.template.RequestContext` by default. 328 329* Support for combining :ref:`F() expressions <query-expressions>` 330 with timedelta values when retrieving or updating database values. 331 332.. _HTTPOnly: http://www.owasp.org/index.php/HTTPOnly 333 334.. _backwards-incompatible-changes-1.3: 335 336Backwards-incompatible changes in 1.3 337===================================== 338 339CSRF validation now applies to AJAX requests 340~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 341 342Prior to Django 1.2.5, Django's CSRF-prevention system exempted AJAX 343requests from CSRF verification; due to `security issues`_ reported to 344us, however, *all* requests are now subjected to CSRF 345verification. Consult :doc:`the Django CSRF documentation 346</ref/contrib/csrf>` for details on how to handle CSRF verification in 347AJAX requests. 348 349.. _security issues: http://www.djangoproject.com/weblog/2011/feb/08/security/ 350 351Restricted filters in admin interface 352~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 353 354Prior to Django 1.2.5, the Django administrative interface allowed 355filtering on any model field or relation -- not just those specified 356in ``list_filter`` -- via query string manipulation. Due to `security 357issues`_ reported to us, however, query string lookup arguments in the 358admin must be for fields or relations specified in ``list_filter`` or 359``date_hierarchy``. 360 361Deleting a model doesn't delete associated files 362~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 363 364In earlier Django versions, when a model instance containing a 365:class:`~django.db.models.FileField` was deleted, 366:class:`~django.db.models.FileField` took it upon itself to also delete the 367file from the backend storage. This opened the door to several data-loss 368scenarios, including rolled-back transactions and fields on different models 369referencing the same file. In Django 1.3, when a model is deleted the 370:class:`~django.db.models.FileField`'s 371:func:`~django.db.models.FileField.delete` method won't be called. If you 372need cleanup of orphaned files, you'll need to handle it yourself (for 373instance, with a custom management command that can be run manually or 374scheduled to run periodically via e.g. cron). 375 376PasswordInput default rendering behavior 377~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 378 379The :class:`~django.forms.PasswordInput` form widget, intended for use 380with form fields which represent passwords, accepts a boolean keyword 381argument ``render_value`` indicating whether to send its data back to 382the browser when displaying a submitted form with errors. Prior to 383Django 1.3, this argument defaulted to ``True``, meaning that the 384submitted password would be sent back to the browser as part of the 385form. Developers who wished to add a bit of additional security by 386excluding that value from the redisplayed form could instantiate a 387:class:`~django.forms.PasswordInput` passing ``render_value=False`` . 388 389Due to the sensitive nature of passwords, however, Django 1.3 takes 390this step automatically; the default value of ``render_value`` is now 391``False``, and developers who want the password value returned to the 392browser on a submission with errors (the previous behavior) must now 393explicitly indicate this. For example:: 394 395 class LoginForm(forms.Form): 396 username = forms.CharField(max_length=100) 397 password = forms.CharField(widget=forms.PasswordInput(render_value=True)) 398 399Clearable default widget for FileField 400~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 401 402Django 1.3 now includes a :class:`~django.forms.ClearableFileInput` form widget 403in addition to :class:`~django.forms.FileInput`. ``ClearableFileInput`` renders 404with a checkbox to clear the field's value (if the field has a value and is not 405required); ``FileInput`` provided no means for clearing an existing file from 406a ``FileField``. 407 408``ClearableFileInput`` is now the default widget for a ``FileField``, so 409existing forms including ``FileField`` without assigning a custom widget will 410need to account for the possible extra checkbox in the rendered form output. 411 412To return to the previous rendering (without the ability to clear the 413``FileField``), use the ``FileInput`` widget in place of 414``ClearableFileInput``. For instance, in a ``ModelForm`` for a hypothetical 415``Document`` model with a ``FileField`` named ``document``:: 416 417 from django import forms 418 from myapp.models import Document 419 420 class DocumentForm(forms.ModelForm): 421 class Meta: 422 model = Document 423 widgets = {'document': forms.FileInput} 424 425New index on database session table 426~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 427 428Prior to Django 1.3, the database table used by the database backend 429for the :doc:`sessions </topics/http/sessions>` app had no index on 430the ``expire_date`` column. As a result, date-based queries on the 431session table -- such as the query that is needed to purge old 432sessions -- would be very slow if there were lots of sessions. 433 434If you have an existing project that is using the database session 435backend, you don't have to do anything to accommodate this change. 436However, you may get a significant performance boost if you manually 437add the new index to the session table. The SQL that will add the 438index can be found by running the :djadmin:`sqlindexes` admin 439command:: 440 441 python manage.py sqlindexes sessions 442 443No more naughty words 444~~~~~~~~~~~~~~~~~~~~~ 445 446Django has historically provided (and enforced) a list of profanities. 447The :doc:`comments app </ref/contrib/comments/index>` has enforced this 448list of profanities, preventing people from submitting comments that 449contained one of those profanities. 450 451Unfortunately, the technique used to implement this profanities list 452was woefully naive, and prone to the `Scunthorpe problem`_. Improving 453the built-in filter to fix this problem would require significant 454effort, and since natural language processing isn't the normal domain 455of a web framework, we have "fixed" the problem by making the list of 456prohibited words an empty list. 457 458If you want to restore the old behavior, simply put a 459:setting:`PROFANITIES_LIST` setting in your settings file that includes the 460words that you want to prohibit (see the `commit that implemented this 461change`_ if you want to see the list of words that was historically 462prohibited). However, if avoiding profanities is important to you, you 463would be well advised to seek out a better, less naive approach to the 464problem. 465 466.. _Scunthorpe problem: http://en.wikipedia.org/wiki/Scunthorpe_problem 467.. _commit that implemented this change: http://code.djangoproject.com/changeset/13996 468 469Localflavor changes 470~~~~~~~~~~~~~~~~~~~ 471 472Django 1.3 introduces the following backwards-incompatible changes to 473local flavors: 474 475* Canada (ca) -- The province "Newfoundland and Labrador" has had its 476 province code updated to "NL", rather than the older "NF". In 477 addition, the Yukon Territory has had its province code corrected to 478 "YT", instead of "YK". 479 480* Indonesia (id) -- The province "Nanggroe Aceh Darussalam (NAD)" has 481 been removed from the province list in favor of the new official 482 designation "Aceh (ACE)". 483 484* United States of America (us) -- The list of "states" used by 485 ``USStateField`` has expanded to include Armed Forces postal 486 codes. This is backwards-incompatible if you were relying on 487 ``USStateField`` not including them. 488 489FormSet updates 490~~~~~~~~~~~~~~~ 491 492In Django 1.3 ``FormSet`` creation behavior is modified slightly. Historically 493the class didn't make a distinction between not being passed data and being 494passed empty dictionary. This was inconsistent with behavior in other parts of 495the framework. Starting with 1.3 if you pass in empty dictionary the 496``FormSet`` will raise a ``ValidationError``. 497 498For example with a ``FormSet``:: 499 500 >>> class ArticleForm(Form): 501 ... title = CharField() 502 ... pub_date = DateField() 503 >>> ArticleFormSet = formset_factory(ArticleForm) 504 505the following code will raise a ``ValidationError``:: 506 507 >>> ArticleFormSet({}) 508 Traceback (most recent call last): 509 ... 510 ValidationError: [u'ManagementForm data is missing or has been tampered with'] 511 512if you need to instantiate an empty ``FormSet``, don't pass in the data or use 513``None``:: 514 515 >>> formset = ArticleFormSet() 516 >>> formset = ArticleFormSet(data=None) 517 518Callables in templates 519~~~~~~~~~~~~~~~~~~~~~~ 520 521Previously, a callable in a template would only be called automatically as part 522of the variable resolution process if it was retrieved via attribute 523lookup. This was an inconsistency that could result in confusing and unhelpful 524behavior:: 525 526 >>> Template("{{ user.get_full_name }}").render(Context({'user': user})) 527 u'Joe Bloggs' 528 >>> Template("{{ full_name }}").render(Context({'full_name': user.get_full_name})) 529 u'<bound method User.get_full_name of <... 530 531This has been resolved in Django 1.3 - the result in both cases will be ``u'Joe 532Bloggs'``. Although the previous behavior was not useful for a template language 533designed for web designers, and was never deliberately supported, it is possible 534that some templates may be broken by this change. 535 536Use of custom SQL to load initial data in tests 537~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 538 539Django provides a custom SQL hooks as a way to inject hand-crafted SQL 540into the database synchronization process. One of the possible uses 541for this custom SQL is to insert data into your database. If your 542custom SQL contains ``INSERT`` statements, those insertions will be 543performed every time your database is synchronized. This includes the 544synchronization of any test databases that are created when you run a 545test suite. 546 547However, in the process of testing the Django 1.3, it was discovered 548that this feature has never completely worked as advertised. When 549using database backends that don't support transactions, or when using 550a TransactionTestCase, data that has been inserted using custom SQL 551will not be visible during the testing process. 552 553Unfortunately, there was no way to rectify this problem without 554introducing a backwards incompatibility. Rather than leave 555SQL-inserted initial data in an uncertain state, Django now enforces 556the policy that data inserted by custom SQL will *not* be visible 557during testing. 558 559This change only affects the testing process. You can still use custom 560SQL to load data into your production database as part of the syncdb 561process. If you require data to exist during test conditions, you 562should either insert it using :ref:`test fixtures 563<topics-testing-fixtures>`, or using the ``setUp()`` method of your 564test case. 565 566Changed priority of translation loading 567~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 568 569Work has been done to simplify, rationalize and properly document the algorithm 570used by Django at runtime to build translations from the different translations 571found on disk, namely: 572 573For translatable literals found in Python code and templates (``'django'`` 574gettext domain): 575 576 * Priorities of translations included with applications listed in the 577 :setting:`INSTALLED_APPS` setting were changed. To provide a behavior 578 consistent with other parts of Django that also use such setting (templates, 579 etc.) now, when building the translation that will be made available, the 580 apps listed first have higher precedence than the ones listed later. 581 582 * Now it is possible to override the translations shipped with applications by 583 using the :setting:`LOCALE_PATHS` setting whose translations have now higher 584 precedence than the translations of :setting:`INSTALLED_APPS` applications. 585 The relative priority among the values listed in this setting has also been 586 modified so the paths listed first have higher precedence than the 587 ones listed later. 588 589 * The ``locale`` subdirectory of the directory containing the settings, that 590 usually coincides with and is know as the *project directory* is being 591 deprecated in this release as a source of translations. (the precedence of 592 these translations is intermediate between applications and :setting:`LOCALE_PATHS` 593 translations). See the `corresponding deprecated features section`_ 594 of this document. 595 596For translatable literals found in Javascript code (``'djangojs'`` gettext 597domain): 598 599 * Similarly to the ``'django'`` domain translations: Overriding of 600 translations shipped with applications by using the :setting:`LOCALE_PATHS` 601 setting is now possible for this domain too. These translations have higher 602 precedence than the translations of Python packages passed to the 603 :ref:`javascript_catalog view <javascript_catalog-view>`. Paths listed first 604 have higher precedence than the ones listed later. 605 606 * Translations under the ``locale`` subdirectory of the *project directory* 607 have never been taken in account for JavaScript translations and remain in 608 the same situation considering the deprecation of such location. 609 610.. _corresponding deprecated features section: loading_of_project_level_translations_ 611 612Transaction management 613~~~~~~~~~~~~~~~~~~~~~~ 614 615When using managed transactions -- that is, anything but the default 616autocommit mode -- it is important when a transaction is marked as 617"dirty". Dirty transactions are committed by the 618:func:`~django.db.transaction.commit_on_success` decorator or the 619:class:`~django.middleware.transaction.TransactionMiddleware`, and 620:func:`~django.db.transaction.commit_manually` forces them to be 621closed explicitly; clean transactions "get a pass", which means they 622are usually rolled back at the end of a request when the connection is 623closed. 624 625Until Django 1.3, transactions were only marked dirty when Django was 626aware of a modifying operation performed in them; that is, either some 627model was saved, some bulk update or delete was performed, or the user 628explicitly called ``transaction.set_dirty()``. In Django 1.3, a 629transaction is marked dirty when *any* database operation is 630performed. 631 632As a result of this change, you no longer need to set a transaction 633dirty explicitly when you execute raw SQL or use a data-modifying 634``SELECT``. However, you *do* need to explicitly close any read-only 635transactions that are being managed using 636:func:`~django.db.transaction.commit_manually`. For example:: 637 638 @transaction.commit_manually 639 def my_view(request, name): 640 obj = get_object_or_404(MyObject, name__iexact=name) 641 return render_to_response('template', {'object':obj}) 642 643Prior to Django 1.3, this would work without error. However, under 644Django 1.3, this will raise a 645:class:`~django.db.transaction.TransactionManagementError` because 646the read operation that retrieves the ``MyObject`` instance leaves the 647transaction in a dirty state. 648 649No password reset for inactive users 650~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 651 652Prior to Django 1.3, inactive users were able to request a password reset email 653and reset their password. In Django 1.3 inactive users will receive the same 654message as a nonexistent account. 655 656.. _deprecated-features-1.3: 657 658Features deprecated in 1.3 659========================== 660 661Django 1.3 deprecates some features from earlier releases. 662These features are still supported, but will be gradually phased out 663over the next few release cycles. 664 665Code taking advantage of any of the features below will raise a 666``PendingDeprecationWarning`` in Django 1.3. This warning will be 667silent by default, but may be turned on using Python's `warnings 668module`_, or by running Python with a ``-Wd`` or `-Wall` flag. 669 670.. _warnings module: http://docs.python.org/library/warnings.html 671 672In Django 1.4, these warnings will become a ``DeprecationWarning``, 673which is *not* silent. In Django 1.5 support for these features will 674be removed entirely. 675 676.. seealso:: 677 678 For more details, see the documentation :doc:`Django's release process 679 </internals/release-process>` and our :doc:`deprecation timeline 680 </internals/deprecation>`. 681 682``mod_python`` support 683~~~~~~~~~~~~~~~~~~~~~~ 684 685The ``mod_python`` library has not had a release since 2007 or a commit since 6862008. The Apache Foundation board voted to remove ``mod_python`` from the set 687of active projects in its version control repositories, and its lead developer 688has shifted all of his efforts toward the lighter, slimmer, more stable, and 689more flexible ``mod_wsgi`` backend. 690 691If you are currently using the ``mod_python`` request handler, you 692should redeploy your Django projects using another request handler. 693:doc:`mod_wsgi </howto/deployment/modwsgi>` is the request handler 694recommended by the Django project, but :doc:`FastCGI 695</howto/deployment/fastcgi>` is also supported. Support for 696``mod_python`` deployment will be removed in Django 1.5. 697 698Function-based generic views 699~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 700 701As a result of the introduction of class-based generic views, the 702function-based generic views provided by Django have been deprecated. 703The following modules and the views they contain have been deprecated: 704 705* :mod:`django.views.generic.create_update` 706 707* :mod:`django.views.generic.date_based` 708 709* :mod:`django.views.generic.list_detail` 710 711* :mod:`django.views.generic.simple` 712 713Test client response ``template`` attribute 714~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 715 716Django's :ref:`test client <test-client>` returns 717:class:`~django.test.client.Response` objects annotated with extra testing 718information. In Django versions prior to 1.3, this included a 719:attr:`~django.test.client.Response.template` attribute containing information 720about templates rendered in generating the response: either None, a single 721:class:`~django.template.Template` object, or a list of 722:class:`~django.template.Template` objects. This inconsistency in return values 723(sometimes a list, sometimes not) made the attribute difficult to work with. 724 725In Django 1.3 the :attr:`~django.test.client.Response.template` attribute is 726deprecated in favor of a new :attr:`~django.test.client.Response.templates` 727attribute, which is always a list, even if it has only a single element or no 728elements. 729 730``DjangoTestRunner`` 731~~~~~~~~~~~~~~~~~~~~ 732 733As a result of the introduction of support for unittest2, the features 734of :class:`django.test.simple.DjangoTestRunner` (including fail-fast 735and Ctrl-C test termination) have been made redundant. In view of this 736redundancy, :class:`~django.test.simple.DjangoTestRunner` has been 737turned into an empty placeholder class, and will be removed entirely 738in Django 1.5. 739 740Changes to :ttag:`url` and :ttag:`ssi` 741~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 742 743Most template tags will allow you to pass in either constants or 744variables as arguments -- for example:: 745 746 {% extends "base.html" %} 747 748allows you to specify a base template as a constant, but if you have a 749context variable ``templ`` that contains the value ``base.html``:: 750 751 {% extends templ %} 752 753is also legal. 754 755However, due to an accident of history, the :ttag:`url` and 756:ttag:`ssi` are different. These tags use the second, quoteless 757syntax, but interpret the argument as a constant. This means it isn't 758possible to use a context variable as the target of a :ttag:`url` and 759:ttag:`ssi` tag. 760 761Django 1.3 marks the start of the process to correct this historical 762accident. Django 1.3 adds a new template library -- ``future`` -- that 763provides alternate implementations of the :ttag:`url` and :ttag:`ssi` 764template tags. This ``future`` library implement behavior that makes 765the handling of the first argument consistent with the handling of all 766other variables. So, an existing template that contains:: 767 768 {% url sample %} 769 770should be replaced with:: 771 772 {% load url from future %} 773 {% url 'sample' %} 774 775The tags implementing the old behavior have been deprecated, and in 776Django 1.5, the old behavior will be replaced with the new behavior. 777To ensure compatibility with future versions of Django, existing 778templates should be modified to use the new ``future`` libraries and 779syntax. 780 781Changes to the login methods of the admin 782~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 783 784In previous version the admin app defined login methods in multiple locations 785and ignored the almost identical implementation in the already used auth app. 786A side effect of this duplication was the missing adoption of the changes made 787in r12634_ to support a broader set of characters for usernames. 788 789This release refactors the admin's login mechanism to use a subclass of the 790:class:`~django.contrib.auth.forms.AuthenticationForm` instead of a manual 791form validation. The previously undocumented method 792``'django.contrib.admin.sites.AdminSite.display_login_form'`` has been removed 793in favor of a new :attr:`~django.contrib.admin.AdminSite.login_form` 794attribute. 795 796.. _r12634: http://code.djangoproject.com/changeset/12634 797 798``reset`` and ``sqlreset`` management commands 799~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 800 801Those commands have been deprecated. The ``flush`` and ``sqlflush`` commands 802can be used to delete everything. You can also use ALTER TABLE or DROP TABLE 803statements manually. 804 805 806GeoDjango 807~~~~~~~~~ 808 809* The function-based :setting:`TEST_RUNNER` previously used to execute 810 the GeoDjango test suite, 811 :func:`django.contrib.gis.tests.run_gis_tests`, was deprecated for 812 the class-based runner, 813 :class:`django.contrib.gis.tests.GeoDjangoTestSuiteRunner`. 814 815* Previously, calling 816 :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` would 817 silently do nothing when GDAL wasn't available. Now, a 818 :class:`~django.contrib.gis.geos.GEOSException` is properly raised 819 to indicate possible faulty application code. A warning is now 820 raised if :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` is 821 called when the SRID of the geometry is less than 0 or ``None``. 822 823``CZBirthNumberField.clean`` 824~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 825 826Previously this field's ``clean()`` method accepted a second, gender, argument 827which allowed stronger validation checks to be made, however since this 828argument could never actually be passed from the Django form machinery it is 829now pending deprecation. 830 831``CompatCookie`` 832~~~~~~~~~~~~~~~~ 833 834Previously, ``django.http`` exposed an undocumented ``CompatCookie`` class, 835which was a bug-fix wrapper around the standard library ``SimpleCookie``. As the 836fixes are moving upstream, this is now deprecated - you should use ``from 837django.http import SimpleCookie`` instead. 838 839.. _loading_of_project_level_translations: 840 841Loading of *project-level* translations 842~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 843 844This release of Django starts the deprecation process for inclusion of 845translations located under the so-called *project path* in the translation 846building process performed at runtime. The :setting:`LOCALE_PATHS` setting can 847be used for the same task by adding the filesystem path to a ``locale`` 848directory containing project-level translations to the value of that setting. 849 850Rationale for this decision: 851 852* The *project path* has always been a loosely defined concept 853 (actually, the directory used for locating project-level 854 translations is the directory containing the settings module) and 855 there has been a shift in other parts of the framework to stop using 856 it as a reference for location of assets at runtime. 857 858* Detection of the ``locale`` subdirectory tends to fail when the 859 deployment scenario is more complex than the basic one. e.g. it 860 fails when the settings module is a directory (ticket #10765). 861 862* There are potential strange development- and deployment-time 863 problems like the fact that the ``project_dir/locale/`` subdir can 864 generate spurious error messages when the project directory is added 865 to the Python path (``manage.py runserver`` does this) and then it 866 clashes with the equally named standard library module, this is a 867 typical warning message:: 868 869 /usr/lib/python2.6/gettext.py:49: ImportWarning: Not importing directory '/path/to/project/locale': missing __init__.py. 870 import locale, copy, os, re, struct, sys 871 872* This location wasn't included in the translation building process 873 for JavaScript literals. This deprecation removes such 874 inconsistency. 875 876``PermWrapper`` moved to ``django.contrib.auth.context_processors`` 877~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 878 879In Django 1.2, we began the process of changing the location of the 880``auth`` context processor from ``django.core.context_processors`` to 881``django.contrib.auth.context_processors``. However, the 882``PermWrapper`` support class was mistakenly omitted from that 883migration. In Django 1.3, the ``PermWrapper`` class has also been 884moved to ``django.contrib.auth.context_processors``, along with the 885``PermLookupDict`` support class. The new classes are functionally 886identical to their old versions; only the module location has changed. 887 888Removal of ``XMLField`` 889~~~~~~~~~~~~~~~~~~~~~~~ 890 891When Django was first released, Django included an 892:class:`~django.db.models.XMLField` that performed automatic XML validation 893for any field input. However, this validation function hasn't been 894performed since the introduction of ``newforms``, prior to the 1.0 release. 895As a result, ``XMLField`` as currently implemented is functionally 896indistinguishable from a simple :class:`~django.db.models.TextField`. 897 898For this reason, Django 1.3 has fast-tracked the deprecation of 899``XMLField`` -- instead of a two-release deprecation, ``XMLField`` 900will be removed entirely in Django 1.4. 901 902It's easy to update your code to accommodate this change -- just 903replace all uses of ``XMLField`` with ``TextField``, and remove the 904``schema_path`` keyword argument (if it is specified).