diff --git a/docs/releases/1.0-alpha-1.txt b/docs/releases/1.0-alpha-1.txt deleted file mode 100644 index 0660f9e5f7..0000000000 --- a/docs/releases/1.0-alpha-1.txt +++ /dev/null @@ -1,161 +0,0 @@ -================================ -Django 1.0 alpha release notes -================================ - -Welcome to Django 1.0 alpha! - -This is the first in a series of preview/development releases leading -up to the eventual release of Django 1.0, currently scheduled to take -place in early September 2008. This release is primarily targeted at -developers who are interested in testing the Django codebase and -helping to identify and resolve bugs prior to the final 1.0 release. - -As such, this release is *not* intended for production use, and any -such use is strongly discouraged. - - -What's new in Django 1.0 alpha -============================== - -Django's development trunk has been the site of nearly constant -activity over the past year, with several major new features landing -since the 0.96 release. Some of the highlights include: - -Refactored admin application (newforms-admin) - The Django administrative interface (``django.contrib.admin``) has - been completely refactored; admin definitions are now completely - decoupled from model definitions (no more ``class Admin`` - declaration in models!), rewritten to use Django's new - form-handling library (introduced in the 0.96 release as - ``django.newforms``, and now available as simply ``django.forms``) - and redesigned with extensibility and customization in mind. Full - documentation for the admin application is available online in the - official Django documentation: - - * :doc:`admin reference ` - -Improved Unicode handling - Django's internals have been refactored to use Unicode throughout; - this drastically simplifies the task of dealing with - non-Western-European content and data in Django. Additionally, - utility functions have been provided to ease interoperability with - third-party libraries and systems which may or may not handle - Unicode gracefully. Details are available in Django's - Unicode-handling documentation: - - * :doc:`unicode reference ` - -An improved Django ORM - Django's object-relational mapper -- the component which provides - the mapping between Django model classes and your database, and - which mediates your database queries -- has been dramatically - improved by a massive refactoring. For most users of Django this - is backwards-compatible; the public-facing API for database - querying underwent a few minor changes, but most of the updates - took place in the ORM's internals. A guide to the changes, - including backwards-incompatible modifications and mentions of new - features opened up by this refactoring, is available on the Django - wiki: - - * https://code.djangoproject.com/wiki/QuerysetRefactorBranch - -Automatic escaping of template variables - To provide improved security against cross-site scripting (XSS) - vulnerabilities, Django's template system now automatically - escapes the output of variables. This behavior is configurable, - and allows both variables and larger template constructs to be - marked as safe (requiring no escaping) or unsafe (requiring - escaping). A full guide to this feature is in the documentation - for the :ttag:`autoescape` tag. - -There are many more new features, many bugfixes and many enhancements -to existing features from previous releases. The ``newforms`` library, -for example, has undergone massive improvements including several -useful add-ons in ``django.contrib`` which complement and build on -Django's form-handling capabilities, and Django's file-uploading -handlers have been refactored to allow finer-grained control over the -uploading process as well as streaming uploads of large files. - -Along with these improvements and additions, we've made a number of -backwards-incompatible changes to the framework, as features have been -fleshed out and APIs have been finalized for the 1.0 release. A -complete guide to these changes will be available as part of the final -Django 1.0 release, and a comprehensive list of backwards-incompatible -changes is also available on the Django wiki for those who want to -begin developing and testing their upgrade process: - -* https://code.djangoproject.com/wiki/BackwardsIncompatibleChanges - - -The Django 1.0 roadmap -====================== - -One of the primary goals of this alpha release is to focus attention -on the remaining features to be implemented for Django 1.0, and on the -bugs that need to be resolved before the final release. Following -this release, we'll be conducting a series of sprints building up to a -series of beta releases and a release-candidate stage, followed soon -after by Django 1.0. The timeline is projected to be: - -* August 1, 2008: Sprint (based in Washington, DC, and online). - -* August 5, 2008: Django 1.0 beta 1 release. This will also constitute - the feature freeze for 1.0. Any feature to be included in 1.0 must - be completed and in trunk by this time. - -* August 8, 2008: Sprint (based in Lawrence, KS, and online). - -* August 12, 2008: Django 1.0 beta 2 release. - -* August 15, 2008: Sprint (based in Austin, TX, and online). - -* August 19, 2008: Django 1.0 release candidate 1. - -* August 22, 2008: Sprint (based in Portland, OR, and online). - -* August 26, 2008: Django 1.0 release candidate 2. - -* September 2, 2008: Django 1.0 final release. The official Django 1.0 - release party will take place during the first-ever DjangoCon, to be - held in Mountain View, CA, September 6-7. - -Of course, like any estimated timeline, this is subject to change as -requirements dictate. The latest information will always be available -on the Django project wiki: - -* https://code.djangoproject.com/wiki/VersionOneRoadmap - - -What you can do to help -======================= - -In order to provide a high-quality 1.0 release, we need your -help. Although this alpha release is, again, *not* intended for -production use, you can help the Django team by trying out the alpha -codebase in a safe test environment and reporting any bugs or issues -you encounter. The Django ticket tracker is the central place to -search for open issues: - -* https://code.djangoproject.com/timeline - -Please open new tickets if no existing ticket corresponds to a problem -you're running into. - -Additionally, discussion of Django development, including progress -toward the 1.0 release, takes place daily on the django-developers -mailing list: - -* http://groups.google.com/group/django-developers - -...and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If -you're interested in helping out with Django's development, feel free -to join the discussions there. - -Django's online documentation also includes pointers on how to -contribute to Django: - -* :doc:`contributing to Django ` - -Contributions on any level -- developing code, writing -documentation or simply triaging tickets and helping to test proposed -bugfixes -- are always welcome and appreciated. diff --git a/docs/releases/1.0-alpha-2.txt b/docs/releases/1.0-alpha-2.txt deleted file mode 100644 index 786cfc56ad..0000000000 --- a/docs/releases/1.0-alpha-2.txt +++ /dev/null @@ -1,135 +0,0 @@ -================================ -Django 1.0 alpha 2 release notes -================================ - -Welcome to Django 1.0 alpha 2! - -This is the second in a series of preview/development releases leading -up to the eventual release of Django 1.0, currently scheduled to take -place in early September 2008. This releases is primarily targeted at -developers who are interested in testing the Django codebase and -helping to identify and resolve bugs prior to the final 1.0 release. - -As such, this release is *not* intended for production use, and any -such use is strongly discouraged. - - -What's new in Django 1.0 alpha 2 -================================ - -Django's development trunk has been the site of nearly constant activity over -the past year, with several major new features landing since the 0.96 release. -For features which were new as of Django 1.0 alpha 1, see :doc:`the 1.0 alpha 1 -release notes `. Since the 1.0 alpha 1 release several new -features have landed, including: - -``django.contrib.gis`` (`GeoDjango`_) - A project over a year in the making, this adds world-class GIS - (`Geographic Information Systems`_) support to Django, in the form - of a ``contrib`` application. Its documentation is currently - being maintained externally, and will be merged into the main - Django documentation prior to the final 1.0 release. Huge thanks - go to Justin Bronn, Jeremy Dunck, Brett Hoerner and Travis Pinney - for their efforts in creating and completing this feature. - -Pluggable file storage - Django's built-in ``FileField`` and ``ImageField`` now can take advantage of - pluggable file-storage backends, allowing extensive customization of where - and how uploaded files get stored by Django. For details, see :doc:`the - files documentation `; big thanks go to Marty Alchin for - putting in the hard work to get this completed. - -Jython compatibility - Thanks to a lot of work from Leo Soto during a Google Summer of - Code project, Django's codebase has been refactored to remove - incompatibilities with `Jython`_, an implementation of Python - written in Java, which runs Python code on the Java Virtual - Machine. Django is now compatible with the forthcoming Jython 2.5 - release. - -There are many other new features and improvements in this release, including -two major performance boosts: strings marked for translation using -:doc:`Django's internationalization system ` now consume far less -memory, and Django's internal dispatcher -- which is invoked frequently during -request/response processing and when working with Django's object-relational -mapper -- is now significantly faster. - -.. _GeoDjango: http://geodjango.org/ -.. _Geographic Information Systems: http://en.wikipedia.org/wiki/Geographic_information_system -.. _Jython: http://www.jython.org/ - - -The Django 1.0 roadmap -====================== - -One of the primary goals of this alpha release is to focus attention -on the remaining features to be implemented for Django 1.0, and on the -bugs that need to be resolved before the final release. Following this -release, we'll be conducting a series of development sprints building -up to the beta and release-candidate stages, followed soon after by -Django 1.0. The timeline is projected to be: - -* **August 14, 2008: Django 1.0 beta release.** Past this point Django - will be in a "feature freeze" for the 1.0 release; after Django 1.0 - beta, the development focus will be solely on bug fixes and - stabilization. - -* August 15, 2008: Sprint (based in Austin, Texas, USA, and online). - -* August 17, 2008: Sprint (based in Tel Aviv, Israel, and online). - -* **August 21, 2008: Django 1.0 release candidate 1.** At this point, - all strings marked for translation within Django's codebase will be - frozen, to provide contributors time to check and finalize all of - Django's bundled translation files prior to the final 1.0 release. - -* August 22, 2008: Sprint (based in Portland, Oregon, USA, and online). - -* **August 26, 2008: Django 1.0 release candidate 2.** - -* August 30, 2008: Sprint (based in London, England, UK, and online). - -* **September 2, 2008: Django 1.0 final release.** The official Django - 1.0 release party will take place during the first-ever DjangoCon, - to be held in Mountain View, California, USA, September 6-7. - -Of course, like any estimated timeline, this is subject to change as -requirements dictate. The latest information will always be available -on the Django project wiki: - -* https://code.djangoproject.com/wiki/VersionOneRoadmap - - -What you can do to help -======================= - -In order to provide a high-quality 1.0 release, we need your -help. Although this alpha release is, again, *not* intended for -production use, you can help the Django team by trying out the alpha -codebase in a safe test environment and reporting any bugs or issues -you encounter. The Django ticket tracker is the central place to -search for open issues: - -* https://code.djangoproject.com/timeline - -Please open new tickets if no existing ticket corresponds to a problem -you're running into. - -Additionally, discussion of Django development, including progress -toward the 1.0 release, takes place daily on the django-developers -mailing list: - -* http://groups.google.com/group/django-developers - -...and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If -you're interested in helping out with Django's development, feel free -to join the discussions there. - -Django's online documentation also includes pointers on how to -contribute to Django: - -* :doc:`contributing to Django ` - -Contributions on any level -- developing code, writing -documentation or simply triaging tickets and helping to test proposed -bugfixes -- are always welcome and appreciated. diff --git a/docs/releases/1.0-beta-2.txt b/docs/releases/1.0-beta-2.txt deleted file mode 100644 index 7bd3f396da..0000000000 --- a/docs/releases/1.0-beta-2.txt +++ /dev/null @@ -1,115 +0,0 @@ -=============================== -Django 1.0 beta 2 release notes -=============================== - -Welcome to Django 1.0 beta 2! - -This is the fourth in a series of preview/development releases leading -up to the eventual release of Django 1.0, currently scheduled to take -place in early September 2008. This releases is primarily targeted at -developers who are interested in testing the Django codebase and -helping to identify and resolve bugs prior to the final 1.0 release. - -As such, this release is *not* intended for production use, and any -such use is discouraged. - -What's new in Django 1.0 beta 2 -=============================== - -Django's development trunk has been the site of nearly constant -activity over the past year, with several major new features landing -since the 0.96 release. For features which were new as of Django 1.0 -alpha 1, see :doc:`the 1.0 alpha 1 release notes -`. For features which were new as of Django 1.0 -alpha 2, see :doc:`the 1.0 alpha 2 release notes -`. For features which were new as of Django 1.0 -beta 1, see :doc:`the 1.0 beta 1 release notes `. - -This beta release includes two major features: - -Refactored ``django.contrib.comments`` - As part of a Google Summer of Code project, Thejaswi Puthraya - carried out a major rewrite and refactoring of Django's bundled - comment system, greatly increasing its flexibility and customizability. - -Refactored documentation - Django's bundled and online documentation has also been - significantly refactored; the new documentation system uses - `Sphinx`_ to build the docs and handle such niceties as topical - indexes, reference documentation and cross-references within the - docs. You can check out the new documentation `online`_ or, if you - have Sphinx installed, build the HTML yourself from the - documentation files bundled with Django. - -.. _Sphinx: http://sphinx-doc.org/ -.. _online: https://docs.djangoproject.com/ - -Along with these new features, the Django team has also been hard at -work polishing Django's codebase for the final 1.0 release; this beta -release contains a large number of smaller improvements and bugfixes -from the ongoing push to 1.0. - -Also, as part of its ongoing deprecation process, Django's old -form-handling system has been removed; this means ``django.oldforms`` -no longer exists, and its various API hooks (such as automatic -manipulators) are no longer present in Django. This system has been -completely replaced by :doc:`the new form-handling system -` in ``django.forms``. - - -The Django 1.0 roadmap -====================== - -One of the primary goals of this beta release is to focus attention on -the remaining features to be implemented for Django 1.0, and on the -bugs that need to be resolved before the final release. As of this -beta release, Django is in its final "feature freeze" for 1.0; feature -requests will be deferred to later releases, and the development -effort will be focused solely on bugfixing and stability. Django is -also now in a "string freeze"; translatable strings (labels, error -messages, etc.) in Django's codebase will not be changed prior to the -release, in order to allow our translators to produce the final 1.0 -version of Django's translation files. - -Following this release, we'll be conducting a final development sprint -on August 30, 2008, based in London and coordinated online; the goal -of this sprint will be to squash as many bugs as possible in -anticipation of the final 1.0 release, which is currently targeted for -**September 2, 2008**. The official Django 1.0 release party will take -place during the first-ever DjangoCon, to be held in Mountain View, -California, USA, September 6-7. - - -What you can do to help -======================= - -In order to provide a high-quality 1.0 release, we need your -help. Although this beta release is, again, *not* intended for -production use, you can help the Django team by trying out the beta -codebase in a safe test environment and reporting any bugs or issues -you encounter. The Django ticket tracker is the central place to -search for open issues: - -* https://code.djangoproject.com/timeline - -Please open new tickets if no existing ticket corresponds to a problem -you're running into. - -Additionally, discussion of Django development, including progress -toward the 1.0 release, takes place daily on the django-developers -mailing list: - -* http://groups.google.com/group/django-developers - -...and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If -you're interested in helping out with Django's development, feel free -to join the discussions there. - -Django's online documentation also includes pointers on how to -contribute to Django: - -* :doc:`contributing to Django ` - -Contributions on any level -- developing code, writing -documentation or simply triaging tickets and helping to test proposed -bugfixes -- are always welcome and appreciated. diff --git a/docs/releases/1.0-beta.txt b/docs/releases/1.0-beta.txt deleted file mode 100644 index d2377f16ab..0000000000 --- a/docs/releases/1.0-beta.txt +++ /dev/null @@ -1,153 +0,0 @@ -=============================== -Django 1.0 beta 1 release notes -=============================== - -Welcome to Django 1.0 beta 1! - -This is the third in a series of preview/development releases leading -up to the eventual release of Django 1.0, currently scheduled to take -place in early September 2008. This releases is primarily targeted at -developers who are interested in testing the Django codebase and -helping to identify and resolve bugs prior to the final 1.0 release. - -As such, this release is *not* intended for production use, and any -such use is discouraged. - -What's new in Django 1.0 beta 1 -=============================== - -Django's development trunk has been the site of nearly constant activity over -the past year, with several major new features landing since the 0.96 release. -For features which were new as of Django 1.0 alpha 1, see :doc:`the 1.0 alpha 1 -release notes `. For features which were new as of Django -1.0 alpha 2, see :doc:`the 1.0 alpha 2 release notes `. - -This beta release does not contain any major new features, but does -include several smaller updates and improvements to Django: - -Generic relations in forms and admin - Classes are now included in ``django.contrib.contenttypes`` which - can be used to support generic relations in both the admin - interface and in end-user forms. See :ref:`the documentation for - generic relations ` for details. - -Improved flexibility in the admin - Following up on the refactoring of Django's administrative - interface (``django.contrib.admin``), introduced in Django 1.0 - alpha 1, two new hooks have been added to allow customized pre- - and post-save handling of model instances in the admin. Full - details are in :doc:`the admin documentation `. - -``INSERT``/``UPDATE`` distinction - Although Django's default behavior of having a model's ``save()`` - method automatically determine whether to perform an ``INSERT`` or - an ``UPDATE`` at the SQL level is suitable for the majority of - cases, there are occasional situations where forcing one or the - other is useful. As a result, models can now support an additional - parameter to ``save()`` which can force a specific - operation. Consult the database API documentation for details - and important notes about appropriate use of this parameter. - -Split ``CacheMiddleware`` - Django's ``CacheMiddleware`` has been split into three classes: - ``CacheMiddleware`` itself still exists and retains all of its - previous functionality, but it is now built from two separate - middleware classes which handle the two parts of caching (inserting - into and reading from the cache) separately, offering additional - flexibility for situations where combining these functions into a - single middleware posed problems. Full details, including updated - notes on appropriate use, are in - :doc:`the caching documentation `. - -Removal of deprecated features - A number of features and methods which had previously been marked - as deprecated, and which were scheduled for removal prior to the - 1.0 release, are no longer present in Django. These include - imports of the form library from ``django.newforms`` (now located - simply at ``django.forms``), the ``form_for_model`` and - ``form_for_instance`` helper functions (which have been replaced - by ``ModelForm``) and a number of deprecated features which were - replaced by the dispatcher, file-uploading and file-storage - refactorings introduced in the Django 1.0 alpha releases. A full - list of these and all other backwards-incompatible changes is - available on `the Django wiki`_. - -A number of other improvements and bugfixes have also been included: -some tricky cases involving case-sensitivity in differing MySQL -collations have been resolved, Windows packaging and installation has -been improved and the method by which Django generates unique session -identifiers has been made much more robust. - -.. _the documentation for generic relations: ../contenttypes/#generic-relations -.. _the Django wiki: https://code.djangoproject.com/wiki/BackwardsIncompatibleChanges#Removedseveralmoredeprecatedfeaturesfor1.0 - - -The Django 1.0 roadmap -====================== - -One of the primary goals of this beta release is to focus attention on -the remaining features to be implemented for Django 1.0, and on the -bugs that need to be resolved before the final release. Following this -release, we'll be conducting a series of development sprints building -up to the release-candidate stage, followed soon after by Django -1.0. The timeline is projected to be: - -* August 15, 2008: Sprint (based in Austin, Texas, USA, and online). - -* August 17, 2008: Sprint (based in Tel Aviv, Israel, and online). - -* **August 21, 2008: Django 1.0 release candidate 1.** At this point, - all strings marked for translation within Django's codebase will be - frozen, to provide contributors time to check and finalize all of - Django's bundled translation files prior to the final 1.0 release. - -* August 22, 2008: Sprint (based in Portland, Oregon, USA, and online). - -* **August 26, 2008: Django 1.0 release candidate 2.** - -* August 30, 2008: Sprint (based in London, England, UK, and online). - -* **September 2, 2008: Django 1.0 final release.** The official Django - 1.0 release party will take place during the first-ever DjangoCon, - to be held in Mountain View, California, USA, September 6-7. - -Of course, like any estimated timeline, this is subject to change as -requirements dictate. The latest information will always be available -on the Django project wiki: - -* https://code.djangoproject.com/wiki/VersionOneRoadmap - - -What you can do to help -======================= - -In order to provide a high-quality 1.0 release, we need your -help. Although this beta release is, again, *not* intended for -production use, you can help the Django team by trying out the beta -codebase in a safe test environment and reporting any bugs or issues -you encounter. The Django ticket tracker is the central place to -search for open issues: - -* https://code.djangoproject.com/timeline - -Please open new tickets if no existing ticket corresponds to a problem -you're running into. - -Additionally, discussion of Django development, including progress -toward the 1.0 release, takes place daily on the django-developers -mailing list: - -* http://groups.google.com/group/django-developers - -...and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If -you're interested in helping out with Django's development, feel free -to join the discussions there. - -Django's online documentation also includes pointers on how to -contribute to Django: - -* :doc:`contributing to Django ` - -Contributions on any level -- developing code, writing -documentation or simply triaging tickets and helping to test proposed -bugfixes -- are always welcome and appreciated. diff --git a/docs/releases/1.1-alpha-1.txt b/docs/releases/1.1-alpha-1.txt deleted file mode 100644 index e49b22c4aa..0000000000 --- a/docs/releases/1.1-alpha-1.txt +++ /dev/null @@ -1,165 +0,0 @@ -================================ -Django 1.1 alpha 1 release notes -================================ - -February 23, 2009 - -Welcome to Django 1.1 alpha 1! - -This is the first in a series of preview/development releases leading up to the -eventual release of Django 1.1, currently scheduled to take place in April 2009. -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.1 release. - -As such, this release is *not* intended for production use, and any such use is -discouraged. - -What's new in Django 1.1 alpha 1 -================================ - -ORM improvements ----------------- - -Two major enhancements have been added to Django's object-relational mapper -(ORM): - -Aggregate support -~~~~~~~~~~~~~~~~~ - -.. currentmodule:: django.db.models - -It's now possible to run SQL aggregate queries (i.e. ``COUNT()``, ``MAX()``, -``MIN()``, etc.) from within Django's ORM. You can choose to either return the -results of the aggregate directly, or else annotate the objects in a -:class:`~django.db.models.query.QuerySet` with the results of the aggregate -query. - -This feature is available as new -:meth:`~django.db.models.query.QuerySet.aggregate` and -:meth:`~django.db.models.query.QuerySet.annotate` methods, and is covered in -detail in :doc:`the ORM aggregation documentation `. - -Query expressions -~~~~~~~~~~~~~~~~~ - -Queries can now refer to a another field on the query and can traverse -relationships to refer to fields on related models. This is implemented in the -new :class:`F` object; for full details, including examples, consult the -:class:`F expressions documentation `. - -Performance improvements ------------------------- - -.. currentmodule:: django.test - -Tests written using Django's :doc:`testing framework ` -now run dramatically faster (as much as 10 times faster in many cases). - -This was accomplished through the introduction of transaction-based tests: when -using :class:`django.test.TestCase`, your tests will now be run in a transaction -which is rolled back when finished, instead of by flushing and re-populating the -database. This results in an immense speedup for most types of unit tests. See -the documentation for :class:`TestCase` and :class:`TransactionTestCase` for a -full description, and some important notes on database support. - -Other improvements ------------------- - -Other new features and changes introduced since Django 1.0 include: - -* The :doc:`CSRF protection middleware ` has been split into - two classes -- ``CsrfViewMiddleware`` checks incoming requests, and - ``CsrfResponseMiddleware`` processes outgoing responses. The combined - ``CsrfMiddleware`` class (which does both) remains for - backwards-compatibility, but using the split classes is now recommended in - order to allow fine-grained control of when and where the CSRF processing - takes place. - -* :func:`~django.core.urlresolvers.reverse` and code which uses it (e.g., the - ``{% url %}`` template tag) now works with URLs in Django's administrative - site, provided that the admin URLs are set up via ``include(admin.site.urls)`` - (sending admin requests to the ``admin.site.root`` view still works, but URLs - in the admin will not be "reversible" when configured this way). - -* The ``include()`` function in Django URLconf modules can now accept sequences - of URL patterns (generated by ``patterns()``) in addition to module names. - -* Instances of Django forms (see :doc:`the forms overview `) - now have two additional methods, ``hidden_fields()`` and ``visible_fields()``, - which return the list of hidden -- i.e., ```` -- and - visible fields on the form, respectively. - -* The ``redirect_to`` generic view - now accepts an additional keyword argument - ``permanent``. If ``permanent`` is ``True``, the view will emit an HTTP - permanent redirect (status code 301). If ``False``, the view will emit an HTTP - temporary redirect (status code 302). - -* A new database lookup type -- ``week_day`` -- has been added for ``DateField`` - and ``DateTimeField``. This type of lookup accepts a number between 1 (Sunday) - and 7 (Saturday), and returns objects where the field value matches that day - of the week. See :ref:`the full list of lookup types ` for - details. - -* The ``{% for %}`` tag in Django's template language now accepts an optional - ``{% empty %}`` clause, to be displayed when ``{% for %}`` is asked to loop - over an empty sequence. See :doc:`the list of built-in template tags - ` for examples of this. - -The Django 1.1 roadmap -====================== - -Before Django 1.1 goes final, several other preview/development releases will be -made available. The current schedule consists of at least the following: - -* Week of *March 20, 2009:* Django 1.1 beta 1, at which point Django 1.1 will - be in "feature freeze": no new features will be implemented for 1.1 - past that point, and all new feature work will be deferred to - Django 1.2. - -* Week of *April 2, 2009:* Django 1.1 release candidate. At this point all - strings marked for translation must freeze to allow translations to - be submitted in advance of the final release. - -* Week of *April 13, 2009:* Django 1.1 final. - -If deemed necessary, additional alpha, beta or release candidate packages will -be issued prior to the final 1.1 release. - -What you can do to help -======================= - -In order to provide a high-quality 1.1 release, we need your help. Although this -alpha release is, again, *not* intended for production use, you can help the -Django team by trying out the alpha codebase in a safe test environment and -reporting any bugs or issues you encounter. The Django ticket tracker is the -central place to search for open issues: - -* https://code.djangoproject.com/timeline - -Please open new tickets if no existing ticket corresponds to a problem you're -running into. - -Additionally, discussion of Django development, including progress toward the -1.1 release, takes place daily on the django-developers mailing list: - -* http://groups.google.com/group/django-developers - -... and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If you're -interested in helping out with Django's development, feel free to join the -discussions there. - -Django's online documentation also includes pointers on how to contribute to -Django: - -* :doc:`How to contribute to Django ` - -Contributions on any level -- developing code, writing documentation or simply -triaging tickets and helping to test proposed bugfixes -- are always welcome and -appreciated. - -Development sprints for Django 1.1 will also be taking place at PyCon US 2009, -on the dedicated sprint days (March 30 through April 2), and anyone who wants to -help out is welcome to join in, either in person at PyCon or virtually in the -IRC channel or on the mailing list. diff --git a/docs/releases/1.1-beta-1.txt b/docs/releases/1.1-beta-1.txt deleted file mode 100644 index 6d45b9dfc9..0000000000 --- a/docs/releases/1.1-beta-1.txt +++ /dev/null @@ -1,208 +0,0 @@ -=============================== -Django 1.1 beta 1 release notes -=============================== - -March 23, 2009 - -Welcome to Django 1.1 beta 1! - -This is the second in a series of preview/development releases leading up to -the eventual release of Django 1.1, currently scheduled to take place in April -2009. 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.1 release. - -As such, this release is *not* intended for production use, and any such use -is discouraged. - -What's new in Django 1.1 beta 1 -=============================== - -.. seealso:: - - The :doc:`1.1 alpha release notes `, which has a - list of everything new between Django 1.0 and Django 1.1 alpha. - -Model improvements ------------------- - -.. currentmodule:: django.db.models - -A number of features have been added to Django's model layer: - -"Unmanaged" models -~~~~~~~~~~~~~~~~~~ - -You can now control whether or not Django creates database tables for a model -using the :attr:`~Options.managed` model option. This defaults to ``True``, -meaning that Django will create the appropriate database tables in -:djadmin:`syncdb` and remove them as part of ``reset`` command. That -is, Django *manages* the database table's lifecycle. - -If you set this to ``False``, however, no database table creating or deletion -will be automatically performed for this model. This is useful if the model -represents an existing table or a database view that has been created by some -other means. - -For more details, see the documentation for the :attr:`~Options.managed` -option. - -Proxy models -~~~~~~~~~~~~ - -You can now create :ref:`proxy models `: subclasses of existing -models that only add Python behavior and aren't represented by a new table. -That is, the new model is a *proxy* for some underlying model, which stores -all the real data. - -All the details can be found in the :ref:`proxy models documentation -`. This feature is similar on the surface to unmanaged models, -so the documentation has an explanation of :ref:`how proxy models differ from -unmanaged models `. - -Deferred fields -~~~~~~~~~~~~~~~ - -In some complex situations, your models might contain fields which could -contain a lot of data (for example, large text fields), or require expensive -processing to convert them to Python objects. If you know you don't need those -particular fields, you can now tell Django not to retrieve them from the -database. - -You'll do this with the new queryset methods -:meth:`~django.db.models.query.QuerySet.defer` and -:meth:`~django.db.models.query.QuerySet.only`. - -New admin features ------------------- - -Since 1.1 alpha, a couple of new features have been added to Django's admin -application: - -Editable fields on the change list -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can now make fields editable on the admin list views via the new -:ref:`list_editable ` admin option. These fields will show -up as form widgets on the list pages, and can be edited and saved in bulk. - -Admin "actions" -~~~~~~~~~~~~~~~ - -You can now define :doc:`admin actions ` that can perform -some action to a group of models in bulk. Users will be able to select objects on -the change list page and then apply these bulk actions to all selected objects. - -Django ships with one pre-defined admin action to delete a group of objects in -one fell swoop. - -Testing improvements --------------------- - -.. currentmodule:: django.test - -A couple of small but very useful improvements have been made to the -:doc:`testing framework `: - -* The test :class:`Client` now can automatically follow redirects with the - ``follow`` argument to :meth:`Client.get` and :meth:`Client.post`. This - makes testing views that issue redirects simpler. - -* It's now easier to get at the template context in the response returned - the test client: you'll simply access the context as - ``request.context[key]``. The old way, which treats ``request.context`` - as a list of contexts, one for each rendered template, is still - available if you need it. - -Conditional view processing ---------------------------- - -Django now has much better support for :doc:`conditional view processing -` using the standard ``ETag`` and -``Last-Modified`` HTTP headers. This means you can now easily short-circuit -view processing by testing less-expensive conditions. For many views this can -lead to a serious improvement in speed and reduction in bandwidth. - -Other improvements ------------------- - -Finally, a grab-bag of other neat features made their way into this beta -release, including: - -* The :djadmin:`dumpdata` management command now accepts individual - model names as arguments, allowing you to export the data just from - particular models. - -* There's a new :tfilter:`safeseq` template filter which works just like - :tfilter:`safe` for lists, marking each item in the list as safe. - -* :doc:`Cache backends ` now support ``incr()`` and - ``decr()`` commands to increment and decrement the value of a cache key. - On cache backends that support atomic increment/decrement -- most - notably, the memcached backend -- these operations will be atomic, and - quite fast. - -* Django now can :doc:`easily delegate authentication to the Web server - ` via a new authentication backend that supports - the standard ``REMOTE_USER`` environment variable used for this purpose. - -* There's a new :func:`django.shortcuts.redirect` function that makes it - easier to issue redirects given an object, a view name, or a URL. - -* The ``postgresql_psycopg2`` backend now supports :ref:`native PostgreSQL - autocommit `. This is an advanced, PostgreSQL-specific - feature, that can make certain read-heavy applications a good deal - faster. - -The Django 1.1 roadmap -====================== - -Before Django 1.1 goes final, at least one other preview/development release -will be made available. The current schedule consists of at least the -following: - -* Week of *April 2, 2009:* Django 1.1 release candidate. At this point all - strings marked for translation must freeze to allow translations to - be submitted in advance of the final release. - -* Week of *April 13, 2009:* Django 1.1 final. - -If deemed necessary, additional beta or release candidate packages will be -issued prior to the final 1.1 release. - -What you can do to help -======================= - -In order to provide a high-quality 1.1 release, we need your help. Although this -beta release is, again, *not* intended for production use, you can help the -Django team by trying out the beta codebase in a safe test environment and -reporting any bugs or issues you encounter. The Django ticket tracker is the -central place to search for open issues: - -* https://code.djangoproject.com/timeline - -Please open new tickets if no existing ticket corresponds to a problem you're -running into. - -Additionally, discussion of Django development, including progress toward the -1.1 release, takes place daily on the django-developers mailing list: - -* http://groups.google.com/group/django-developers - -... and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If you're -interested in helping out with Django's development, feel free to join the -discussions there. - -Django's online documentation also includes pointers on how to contribute to -Django: - -* :doc:`How to contribute to Django ` - -Contributions on any level -- developing code, writing documentation or simply -triaging tickets and helping to test proposed bugfixes -- are always welcome and -appreciated. - -Development sprints for Django 1.1 will also be taking place at PyCon US 2009, -on the dedicated sprint days (March 30 through April 2), and anyone who wants to -help out is welcome to join in, either in person at PyCon or virtually in the -IRC channel or on the mailing list. diff --git a/docs/releases/1.1-rc-1.txt b/docs/releases/1.1-rc-1.txt deleted file mode 100644 index 56b7d89be9..0000000000 --- a/docs/releases/1.1-rc-1.txt +++ /dev/null @@ -1,109 +0,0 @@ -============================= -Django 1.1 RC 1 release notes -============================= - - -July 21, 2009 - -Welcome to the first Django 1.1 release candidate! - -This is the third -- and likely last -- in a series of -preview/development releases leading up to the eventual release of -Django 1.1, currently scheduled to take place approximately one week -after this release candidate. This release is targeted primarily at -developers who are interested in trying out new features and testing -the Django codebase to help identify and resolve any critical bugs -prior to the final 1.1 release. - -As such, this release is not yet intended for production use, and any -such use is discouraged. - - -What's new in Django 1.1 RC 1 -============================= - -The Django codebase has -- with one exception -- been in feature -freeze since the first 1.1 beta release, and so this release candidate -contains only one new feature (see below); work leading up to this -release candidate has instead been focused on bugfixing, particularly -on the new features introduced prior to the 1.1 beta. - -For an overview of those features, consult :doc:`the Django 1.1 beta -release notes `. - - -URL namespaces --------------- - -The 1.1 beta release introduced the ability to use reverse URL -resolution with Django's admin application, which exposed a set of -:ref:`named URLs `. Unfortunately, achieving -consistent and correct reverse resolution for admin URLs proved -extremely difficult, and so one additional feature was added to Django -to resolve this issue: URL namespaces. - -In short, this feature allows the same group of URLs, from the same -application, to be included in a Django URLConf multiple times, with -varying (and potentially nested) named prefixes which will be used -when performing reverse resolution. For full details, see :ref:`the -documentation on defining URL namespaces -`. - -Due to the changes needed to support this feature, the URL pattern -names used when reversing admin URLs have changed since the 1.1 beta -release; if you were developing applications which took advantage of -this new feature, you will need to update your code to reflect the new -names (for most purposes, changing ``admin_`` to ``admin:`` in names -to be reversed will suffice). For a full list of URL pattern names -used by the admin and information on how namespaces are applied to -them, consult the documentation on :ref:`reversing admin URLs -`. - - -The Django 1.1 roadmap -====================== - -As of this release candidate, Django 1.1 is in both feature freeze and -"string freeze" -- all strings marked for translation in the Django -codebase will retain their current form in the final Django 1.1 -release. Only critical release-blocking bugs will receive attention -between now and the final 1.1 release. - -If no such bugs are discovered, Django 1.1 will be released -approximately one week after this release candidate, on or about July -28, 2009. - - -What you can do to help -======================= - -In order to provide a high-quality 1.1 release, we need your -help. Although this release candidate is, again, *not* intended for -production use, you can help the Django team by trying out this -release candidate in a safe testing environment and reporting any bugs -or issues you encounter. The Django ticket tracker is the central -place to search for open issues: - -* https://code.djangoproject.com/timeline - -Please open a new ticket only if no existing ticket corresponds to a -problem you're running into. - -Additionally, discussion of Django development, including progress -toward the 1.1 release, takes place daily on the django-developers -mailing list: - -* http://groups.google.com/group/django-developers - -... and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If you're -interested in helping out with Django's development, feel free to join the -discussions there. - -Django's online documentation also includes pointers on how to contribute to -Django: - -* :doc:`How to contribute to Django ` - -Contributions on any level -- developing code, writing documentation or simply -triaging tickets and helping to test proposed bugfixes -- are always welcome and -appreciated. diff --git a/docs/releases/1.2-alpha-1.txt b/docs/releases/1.2-alpha-1.txt deleted file mode 100644 index 0d08c979ce..0000000000 --- a/docs/releases/1.2-alpha-1.txt +++ /dev/null @@ -1,588 +0,0 @@ -================================ -Django 1.2 alpha 1 release notes -================================ - -January 5, 2010 - -Welcome to Django 1.2 alpha 1! - -This is the first in a series of preview/development releases leading up to the -eventual release of Django 1.2, currently scheduled to take place in March 2010. -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.2 release. - -As such, this release is *not* intended for production use, and any such use is -discouraged. - - -Backwards-incompatible changes in 1.2 -===================================== - -CSRF Protection ---------------- - -There have been large changes to the way that CSRF protection works, detailed in -:doc:`the CSRF documentation `. The following are the major -changes that developers must be aware of: - -* ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` have been deprecated, and - **will be removed completely in Django 1.4**, in favor of a template tag that - should be inserted into forms. - -* All contrib apps use a ``csrf_protect`` decorator to protect the view. This - requires the use of the ``csrf_token`` template tag in the template, so if you - have used custom templates for contrib views, you MUST READ THE UPGRADE - INSTRUCTIONS to fix those templates. - - .. admonition:: Documentation removed - - The upgrade notes have been removed in current Django docs. Please refer - to the docs for Django 1.3 or older to find these instructions. - -* ``CsrfViewMiddleware`` is included in :setting:`MIDDLEWARE_CLASSES` by - default. This turns on CSRF protection by default, so that views that accept - POST requests need to be written to work with the middleware. Instructions - on how to do this are found in the CSRF docs. - -* CSRF-related code has moved from ``contrib`` to ``core`` (with - backwards compatible imports in the old locations, which are - deprecated). - -:ttag:`if` tag changes ----------------------- - -Due to new features in the :ttag:`if` template tag, it no longer accepts 'and', -'or' and 'not' as valid **variable** names. Previously that worked in some -cases even though these strings were normally treated as keywords. Now, the -keyword status is always enforced, and template code like ``{% if not %}`` or -``{% if and %}`` will throw a TemplateSyntaxError. - -``LazyObject`` --------------- - -``LazyObject`` is an undocumented utility class used for lazily wrapping other -objects of unknown type. In Django 1.1 and earlier, it handled introspection in -a non-standard way, depending on wrapped objects implementing a public method -``get_all_members()``. Since this could easily lead to name clashes, it has been -changed to use the standard method, involving ``__members__`` and ``__dir__()``. -If you used ``LazyObject`` in your own code, and implemented the -``get_all_members()`` method for wrapped objects, you need to make the following -changes: - -* If your class does not have special requirements for introspection (i.e. you - have not implemented ``__getattr__()`` or other methods that allow for - attributes not discoverable by normal mechanisms), you can simply remove the - ``get_all_members()`` method. The default implementation on ``LazyObject`` - will do the right thing. - -* If you have more complex requirements for introspection, first rename the - ``get_all_members()`` method to ``__dir__()``. This is the standard method, - from Python 2.6 onwards, for supporting introspection. If you are require - support for Python < 2.6, add the following code to the class:: - - __members__ = property(lambda self: self.__dir__()) - -``__dict__`` on Model instances -------------------------------- - -Historically, the ``__dict__`` attribute of a model instance has only contained -attributes corresponding to the fields on a model. - -In order to support multiple database configurations, Django 1.2 has -added a ``_state`` attribute to object instances. This attribute will -appear in ``__dict__`` for a model instance. If your code relies on -iterating over __dict__ to obtain a list of fields, you must now -filter the ``_state`` attribute of out ``__dict__``. - -``get_db_prep_*()`` methods on Field ------------------------------------- - -Prior to v1.2, a custom field had the option of defining several -functions to support conversion of Python values into -database-compatible values. A custom field might look something like:: - - class CustomModelField(models.Field): - # ... - - def get_db_prep_save(self, value): - # ... - - def get_db_prep_value(self, value): - # ... - - def get_db_prep_lookup(self, lookup_type, value): - # ... - -In 1.2, these three methods have undergone a change in prototype, and -two extra methods have been introduced:: - - class CustomModelField(models.Field): - # ... - - def get_prep_value(self, value): - # ... - - def get_prep_lookup(self, lookup_type, value): - # ... - - def get_db_prep_save(self, value, connection): - # ... - - def get_db_prep_value(self, value, connection, prepared=False): - # ... - - def get_db_prep_lookup(self, lookup_type, value, connection, prepared=False): - # ... - -These changes are required to support multiple databases: -``get_db_prep_*`` can no longer make any assumptions regarding the -database for which it is preparing. The ``connection`` argument now -provides the preparation methods with the specific connection for -which the value is being prepared. - -The two new methods exist to differentiate general data preparation -requirements, and requirements that are database-specific. The -``prepared`` argument is used to indicate to the database preparation -methods whether generic value preparation has been performed. If -an unprepared (i.e., ``prepared=False``) value is provided to the -``get_db_prep_*()`` calls, they should invoke the corresponding -``get_prep_*()`` calls to perform generic data preparation. - -Conversion functions has been provided which will transparently -convert functions adhering to the old prototype into functions -compatible with the new prototype. However, this conversion function -will be removed in Django 1.4, so you should upgrade your Field -definitions to use the new prototype. - -If your ``get_db_prep_*()`` methods made no use of the database -connection, you should be able to upgrade by renaming -``get_db_prep_value()`` to ``get_prep_value()`` and -``get_db_prep_lookup()`` to ``get_prep_lookup()`. If you require -database specific conversions, then you will need to provide an -implementation ``get_db_prep_*`` that uses the ``connection`` -argument to resolve database-specific values. - -Stateful template tags ----------------------- - -Template tags that store rendering state on the node itself may experience -problems if they are used with the new :ref:`cached -template loader`. - -All of the built-in Django template tags are safe to use with the cached -loader, but if you're using custom template tags that come from third -party packages, or that you wrote yourself, you should ensure that the -``Node`` implementation for each tag is thread-safe. For more -information, see -:ref:`template tag thread safety considerations`. - -Test runner exit status code ----------------------------- - -The exit status code of the test runners (``tests/runtests.py`` and ``python -manage.py test``) no longer represents the number of failed tests, since a -failure of 256 or more tests resulted in a wrong exit status code. The exit -status code for the test runner is now 0 for success (no failing tests) and 1 -for any number of test failures. If needed, the number of test failures can be -found at the end of the test runner's output. - -Features deprecated in 1.2 -========================== - -CSRF response rewriting middleware ----------------------------------- - -``CsrfResponseMiddleware``, the middleware that automatically inserted CSRF -tokens into POST forms in outgoing pages, has been deprecated in favor of a -template tag method (see above), and will be removed completely in Django -1.4. ``CsrfMiddleware``, which includes the functionality of -``CsrfResponseMiddleware`` and ``CsrfViewMiddleware`` has likewise been -deprecated. - -Also, the CSRF module has moved from contrib to core, and the old -imports are deprecated, as described in the upgrading notes. - -.. admonition:: Documentation removed - - The upgrade notes have been removed in current Django docs. Please refer - to the docs for Django 1.3 or older to find these instructions. - -``SMTPConnection`` ------------------- - -The ``SMTPConnection`` class has been deprecated in favor of a generic -Email backend API. Old code that explicitly instantiated an instance -of an SMTPConnection:: - - from django.core.mail import SMTPConnection - connection = SMTPConnection() - messages = get_notification_email() - connection.send_messages(messages) - -should now call :meth:`~django.core.mail.get_connection()` to -instantiate a generic email connection:: - - from django.core.mail import get_connection - connection = get_connection() - messages = get_notification_email() - connection.send_messages(messages) - -Depending on the value of the :setting:`EMAIL_BACKEND` setting, this -may not return an SMTP connection. If you explicitly require an SMTP -connection with which to send email, you can explicitly request an -SMTP connection:: - - from django.core.mail import get_connection - connection = get_connection('django.core.mail.backends.smtp.EmailBackend') - messages = get_notification_email() - connection.send_messages(messages) - -If your call to construct an instance of ``SMTPConnection`` required -additional arguments, those arguments can be passed to the -:meth:`~django.core.mail.get_connection()` call:: - - connection = get_connection('django.core.mail.backends.smtp.EmailBackend', hostname='localhost', port=1234) - -Specifying databases --------------------- - -Prior to Django 1.1, Django used a number of settings to control access to a -single database. Django 1.2 introduces support for multiple databases, and as -a result, the way you define database settings has changed. - -**Any existing Django settings file will continue to work as expected -until Django 1.4.** Old-style database settings will be automatically -translated to the new-style format. - -In the old-style (pre 1.2) format, there were a number of -``DATABASE_`` settings at the top level of your settings file. For -example:: - - DATABASE_NAME = 'test_db' - DATABASE_ENGINE = 'postgresql_psycopg2' - DATABASE_USER = 'myusername' - DATABASE_PASSWORD = 's3krit' - -These settings are now contained inside a dictionary named -:setting:`DATABASES`. Each item in the dictionary corresponds to a -single database connection, with the name ``'default'`` describing the -default database connection. The setting names have also been -shortened to reflect the fact that they are stored in a dictionary. -The sample settings given previously would now be stored using:: - - DATABASES = { - 'default': { - 'NAME': 'test_db', - 'ENGINE': 'django.db.backends.postgresql_psycopg2', - 'USER': 'myusername', - 'PASSWORD': 's3krit', - } - } - -This affects the following settings: - -========================================= ========================== - Old setting New Setting -========================================= ========================== -`DATABASE_ENGINE` :setting:`ENGINE ` -`DATABASE_HOST` :setting:`HOST` -`DATABASE_NAME` :setting:`NAME` -`DATABASE_OPTIONS` :setting:`OPTIONS` -`DATABASE_PASSWORD` :setting:`PASSWORD` -`DATABASE_PORT` :setting:`PORT` -`DATABASE_USER` :setting:`USER` -`TEST_DATABASE_CHARSET` :setting:`TEST_CHARSET` -`TEST_DATABASE_COLLATION` :setting:`TEST_COLLATION` -`TEST_DATABASE_NAME` :setting:`TEST_NAME` -========================================= ========================== - -These changes are also required if you have manually created a database -connection using ``DatabaseWrapper()`` from your database backend of choice. - -In addition to the change in structure, Django 1.2 removes the special -handling for the built-in database backends. All database backends -must now be specified by a fully qualified module name (i.e., -``django.db.backends.postgresql_psycopg2``, rather than just -``postgresql_psycopg2``). - -User Messages API ------------------ - -The API for storing messages in the user ``Message`` model (via -``user.message_set.create``) is now deprecated and will be removed in Django -1.4 according to the standard :doc:`release process `. - -To upgrade your code, you need to replace any instances of:: - - user.message_set.create('a message') - -with the following:: - - from django.contrib import messages - messages.add_message(request, messages.INFO, 'a message') - -Additionally, if you make use of the method, you need to replace the -following:: - - for message in user.get_and_delete_messages(): - ... - -with:: - - from django.contrib import messages - for message in messages.get_messages(request): - ... - -For more information, see the full -:doc:`messages documentation `. You should begin to -update your code to use the new API immediately. - -Date format helper functions ----------------------------- - -``django.utils.translation.get_date_formats()`` and -``django.utils.translation.get_partial_date_formats()`` have been deprecated -in favor of the appropriate calls to ``django.utils.formats.get_format()`` -which is locale aware when :setting:`USE_L10N` is set to ``True``, and falls -back to default settings if set to ``False``. - -To get the different date formats, instead of writing:: - - from django.utils.translation import get_date_formats - date_format, datetime_format, time_format = get_date_formats() - -use:: - - from django.utils import formats - - date_format = formats.get_format('DATE_FORMAT') - datetime_format = formats.get_format('DATETIME_FORMAT') - time_format = formats.get_format('TIME_FORMAT') - -or, when directly formatting a date value:: - - from django.utils import formats - value_formatted = formats.date_format(value, 'DATETIME_FORMAT') - -The same applies to the globals found in ``django.forms.fields``: - -* ``DEFAULT_DATE_INPUT_FORMATS`` -* ``DEFAULT_TIME_INPUT_FORMATS`` -* ``DEFAULT_DATETIME_INPUT_FORMATS`` - -Use ``django.utils.formats.get_format()`` to get the appropriate formats. - - -What's new in Django 1.2 alpha 1 -================================ - -The following new features are present as of this alpha release; this -release also marks the end of major feature development for the 1.2 -release cycle. Some minor features will continue development until the -1.2 beta release, however. - - -CSRF support ------------- - -Django now has much improved protection against :doc:`Cross-Site -Request Forgery (CSRF) attacks`. This type of attack -occurs when a malicious Web site contains a link, a form button or -some javascript that is intended to perform some action on your Web -site, using the credentials of a logged-in user who visits the -malicious site in their browser. A related type of attack, 'login -CSRF', where an attacking site tricks a user's browser into logging -into a site with someone else's credentials, is also covered. - -Email Backends --------------- - -You can now :ref:`configure the way that Django sends email -`. Instead of using SMTP to send all email, you -can now choose a configurable email backend to send messages. If your -hosting provider uses a sandbox or some other non-SMTP technique for -sending mail, you can now construct an email backend that will allow -Django's standard :doc:`mail sending methods` to use -those facilities. - -This also makes it easier to debug mail sending - Django ships with -backend implementations that allow you to send email to a -:ref:`file`, to the -:ref:`console`, or to -:ref:`memory` - you can even configure all -email to be :ref:`thrown away`. - -Messages Framework ------------------- - -Django now includes a robust and configurable :doc:`messages framework -` with built-in support for cookie- and session-based -messaging, for both anonymous and authenticated clients. The messages framework -replaces the deprecated user message API and allows you to temporarily store -messages in one request and retrieve them for display in a subsequent request -(usually the next one). - -Support for multiple databases ------------------------------- - -Django 1.2 adds the ability to use :doc:`more than one database -` in your Django project. Queries can be -issued at a specific database with the ``using()`` method on -querysets; individual objects can be saved to a specific database -by providing a ``using`` argument when you save the instance. - -'Smart' if tag --------------- - -The :ttag:`if` tag has been upgraded to be much more powerful. First, support -for comparison operators has been added. No longer will you have to type: - -.. code-block:: html+django - - {% ifnotequal a b %} - ... - {% endifnotequal %} - -...as you can now do: - -.. code-block:: html+django - - {% if a != b %} - ... - {% endif %} - -The operators supported are ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=`` and -``in``, all of which work like the Python operators, in addition to ``and``, -``or`` and ``not`` which were already supported. - -Also, filters may now be used in the ``if`` expression. For example: - -.. code-block:: html+django - -
{{ message }}
- -Template caching ----------------- - -In previous versions of Django, every time you rendered a template it -would be reloaded from disk. In Django 1.2, you can use a :ref:`cached -template loader ` to load templates once, then use -the cached result for every subsequent render. This can lead to a -significant performance improvement if your templates are broken into -lots of smaller subtemplates (using the ``{% extends %}`` or ``{% -include %}`` tags). - -As a side effect, it is now much easier to support non-Django template -languages. For more details, see the :ref:`notes on supporting -non-Django template languages`. - -Natural keys in fixtures ------------------------- - -Fixtures can refer to remote objects using -:ref:`topics-serialization-natural-keys`. This lookup scheme is an -alternative to the normal primary-key based object references in a -fixture, improving readability, and resolving problems referring to -objects whose primary key value may not be predictable or known. - -``BigIntegerField`` -------------------- - -Models can now use a 64 bit :class:`~django.db.models.BigIntegerField` type. - -Fast Failure for Tests ----------------------- - -The :djadmin:`test` subcommand of ``django-admin.py``, and the ``runtests.py`` -script used to run Django's own test suite, support a new ``--failfast`` option. -When specified, this option causes the test runner to exit after encountering -a failure instead of continuing with the test run. In addition, the handling -of ``Ctrl-C`` during a test run has been improved to trigger a graceful exit -from the test run that reports details of the tests run before the interruption. - -Improved localization ---------------------- - -Django's :doc:`internationalization framework ` has been -expanded by locale aware formatting and form processing. That means, if -enabled, dates and numbers on templates will be displayed using the format -specified for the current locale. Django will also use localized formats -when parsing data in forms. -See :ref:`Format localization ` for more details. - -Added ``readonly_fields`` to ``ModelAdmin`` -------------------------------------------- - -:attr:`django.contrib.admin.ModelAdmin.readonly_fields` has been added to -enable non-editable fields in add/change pages for models and inlines. Field -and calculated values can be displayed alongside editable fields. - -Customizable syntax highlighting --------------------------------- - -You can now use the ``DJANGO_COLORS`` environment variable to modify -or disable the colors used by ``django-admin.py`` to provide -:ref:`syntax highlighting `. - - -The Django 1.2 roadmap -====================== - -Before the final Django 1.2 release, several other preview/development -releases will be made available. The current schedule consists of at -least the following: - -* Week of **January 26, 2010**: First Django 1.2 beta release. Final - feature freeze for Django 1.2. - -* Week of **March 2, 2010**: First Django 1.2 release - candidate. String freeze for translations. - -* Week of **March 9, 2010**: Django 1.2 final release. - -If necessary, additional alpha, beta or release-candidate packages -will be issued prior to the final 1.2 release. Django 1.2 will be -released approximately one week after the final release candidate. - - -What you can do to help -======================= - -In order to provide a high-quality 1.2 release, we need your help. Although this -alpha release is, again, *not* intended for production use, you can help the -Django team by trying out the alpha codebase in a safe test environment and -reporting any bugs or issues you encounter. The Django ticket tracker is the -central place to search for open issues: - -* https://code.djangoproject.com/timeline - -Please open new tickets if no existing ticket corresponds to a problem you're -running into. - -Additionally, discussion of Django development, including progress toward the -1.2 release, takes place daily on the django-developers mailing list: - -* http://groups.google.com/group/django-developers - -... and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If you're -interested in helping out with Django's development, feel free to join the -discussions there. - -Django's online documentation also includes pointers on how to contribute to -Django: - -* :doc:`How to contribute to Django ` - -Contributions on any level -- developing code, writing documentation or simply -triaging tickets and helping to test proposed bugfixes -- are always welcome and -appreciated. - -Development sprints for Django 1.2 will also be taking place at PyCon -US 2010, on the dedicated sprint days (February 22 through 25), and -anyone who wants to help out is welcome to join in, either in person -at PyCon or virtually in the IRC channel or on the mailing list. diff --git a/docs/releases/1.2-beta-1.txt b/docs/releases/1.2-beta-1.txt deleted file mode 100644 index abb0f3bbb9..0000000000 --- a/docs/releases/1.2-beta-1.txt +++ /dev/null @@ -1,173 +0,0 @@ -=============================== -Django 1.2 beta 1 release notes -=============================== - -February 5, 2010 - -Welcome to Django 1.2 beta 1! - -This is the second in a series of preview/development releases leading -up to the eventual release of Django 1.2, currently scheduled to take -place in March 2010. 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.2 -release. - -As such, this release is *not* intended for production use, and any -such use is discouraged. - -This document covers changes since the Django 1.2 alpha release; the -:doc:`1.2 alpha release notes ` cover new and -updated features in Django between 1.1 and 1.2 alpha. - - -Deprecations and other changes in 1.2 beta -========================================== - -This beta release deprecates two portions of public API, and -introduces a potentially backwards-incompatible change to -another. Under :doc:`our API stability policy `, -deprecation proceeds over multiple release cycles: initially, the -deprecated API will raise ``PendingDeprecationWarning``, followed by -raising ``DeprecationWarning`` in the next release, and finally -removal of the deprecated API in the release after that. APIs -beginning the deprecation process in Django 1.2 will be removed in the -Django 1.4 release. - - -Unit test runners ------------------ - -Django 1.2 changes the test runner tools to use a class-based -approach. Old style function-based test runners will still work, but -should be updated to use the new :ref:`class-based runners -`. - - -Syndication feeds ------------------ - -The ``django.contrib.syndication.feeds.Feed`` class is being -replaced by the :class:`django.contrib.syndication.views.Feed` class. -The old ``feeds.Feed`` class is deprecated. The new class has an -almost identical API, but allows instances to be used as views. - -Also, in accordance with `RSS best practices`_, RSS feeds will now -include an ``atom:link`` element. You may need to update your tests to -take this into account. - -For more information, see the full :doc:`syndication framework -documentation `. - -.. _RSS best practices: http://www.rssboard.org/rss-profile - - -Cookie encoding ---------------- - -Due to cookie-handling bugs in Internet Explorer, Safari, and possibly -other browsers, Django's encoding of cookie values was changed so that -the characters comma (',') and semi-colon (';') are treated as -non-safe characters, and are therefore encoded as ``\054`` and -``\073`` respectively. This could produce backwards incompatibilities -if you are relying on the ability to set these characters directly in -cookie values. - - -What's new in 1.2 beta -====================== - -This 1.2 beta release marks the final feature freeze for Django 1.2; -while most feature development was completed for 1.2 alpha (which -constituted a freeze on major features), a few other new features were -added afterward and so are new as of 1.2 beta. - - -Object-level permissions ------------------------- - -A foundation for specifying permissions at the per-object level was -added in Django 1.2 alpha but not documented with the alpha release. - -The default authentication backends shipped with Django do not -currently make use of this, but third-party authentication backends -are free to do so. See the :doc:`authentication docs ` -for more information. - - -Permissions for anonymous users -------------------------------- - -If you provide a custom authentication backend with the attribute -``supports_anonymous_user`` set to ``True``, the ``AnonymousUser`` -class will check the backend for permissions, just as the normal -``User`` does. This is intended to help centralize permission -handling; apps can always delegate the question of whether something -is allowed or not to the authorization/authentication system. See the -:doc:`authentication docs ` for more details. - - -``select_related()`` improvements ---------------------------------- - -The ``select_related()`` method of ``QuerySet`` now accepts the -``related_name`` of a reverse one-to-one relation in the list of -fields to select. One-to-one relations will not, however, be traversed -by a depth-based ``select_related()`` call. - - -The Django 1.2 roadmap -====================== - -Before the final Django 1.2 release, at least one additional -preview/development releases will be made available. The current -schedule consists of at least the following: - -* Week of **March 2, 2010**: First Django 1.2 release - candidate. String freeze for translations. - -* Week of **March 9, 2010**: Django 1.2 final release. - -If necessary, additional beta or release-candidate packages will be -issued prior to the final 1.2 release. Django 1.2 will be released -approximately one week after the final release candidate. - - -What you can do to help -======================= - -In order to provide a high-quality 1.2 release, we need your -help. Although this beta release is, again, *not* intended for -production use, you can help the Django team by trying out the beta -codebase in a safe test environment and reporting any bugs or issues -you encounter. The Django ticket tracker is the central place to -search for open issues: - -* https://code.djangoproject.com/timeline - -Please open new tickets if no existing ticket corresponds to a problem -you're running into. - -Additionally, discussion of Django development, including progress -toward the 1.2 release, takes place daily on the django-developers -mailing list: - -* http://groups.google.com/group/django-developers - -... and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If you're -interested in helping out with Django's development, feel free to join the -discussions there. - -Django's online documentation also includes pointers on how to -contribute to Django: - -* :doc:`How to contribute to Django ` - -Contributions on any level -- developing code, writing documentation -or simply triaging tickets and helping to test proposed bugfixes -- -are always welcome and appreciated. - -Development sprints for Django 1.2 will also be taking place at PyCon -US 2010, on the dedicated sprint days (February 22 through 25), and -anyone who wants to help out is welcome to join in, either in person -at PyCon or virtually in the IRC channel or on the mailing list. diff --git a/docs/releases/1.2-rc-1.txt b/docs/releases/1.2-rc-1.txt deleted file mode 100644 index 78046d8b57..0000000000 --- a/docs/releases/1.2-rc-1.txt +++ /dev/null @@ -1,101 +0,0 @@ -============================= -Django 1.2 RC 1 release notes -============================= - - -May 5, 2010 - -Welcome to the first Django 1.2 release candidate! - -This is the third -- and likely last -- in a series of -preview/development releases leading up to the eventual release of -Django 1.2. This release is targeted primarily at developers who are -interested in trying out new features and testing the Django codebase -to help identify and resolve any critical bugs prior to the final 1.2 -release. - -As such, this release is not yet intended for production use, and any -such use is discouraged. - -Django has been feature frozen since the 1.2 beta release, so this -release candidate contains no new features, only bugfixes; for a -summary of features new to Django 1.2, consult the :doc:`1.2 alpha -` and :doc:`1.2 beta ` -release notes. - - -Python compatibility -==================== - -While not a new feature, it's important to note that Django 1.2 -introduces the first shift in our Python compatibility policy since -Django's initial public debut. Previous Django releases were tested -and supported on 2.x Python versions from 2.3 up; Django 1.2, however, -drops official support for Python 2.3. As such, the minimum Python -version required for Django is now 2.4, and Django is tested and -supported on Python 2.4, 2.5 and 2.6, and will be supported on the -as-yet-unreleased Python 2.7. - -This change should affect only a small number of Django users, as most -operating-system vendors today are shipping Python 2.4 or newer as -their default version. If you're still using Python 2.3, however, -you'll need to stick to Django 1.1 until you can upgrade; per -:doc:`our support policy `, Django 1.1 will -continue to receive security support until the release of Django 1.3. - -A roadmap for Django's overall 2.x Python support, and eventual -transition to Python 3.x, is currently being developed, and will be -announced prior to the release of Django 1.3. - - -The Django 1.2 roadmap -====================== - -As of this release candidate, Django 1.2 is in both feature freeze and -"string freeze" -- all strings marked for translation in the Django -codebase will retain their current form in the final Django 1.2 -release. Only critical release-blocking bugs, documentation and -updated translation files will receive attention between now and the -final 1.2 release. Note that Django's localization infrastructure has -been expanded for 1.2, and translation packages should now include a -``formats.py`` file containing data for localized formatting of -numbers and dates. - -If no critical bugs are discovered, Django 1.2 will be released -approximately one week after this release candidate, on or about May -12, 2010. - - -What you can do to help -======================= - -In order to provide a high-quality 1.2 release, we need your -help. Although this release candidate is, again, *not* intended for -production use, you can help the Django team by trying out this -release candidate in a safe testing environment and reporting any bugs -or issues you encounter. The Django ticket tracker is the central -place to search for open issues: - -* https://code.djangoproject.com/timeline - -Please open a new ticket only if no existing ticket corresponds to a -problem you're running into. - -Additionally, discussion of Django development, including progress -toward the 1.2 release, takes place daily on the django-developers -mailing list: - -* http://groups.google.com/group/django-developers - -... and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If you're -interested in helping out with Django's development, feel free to join the -discussions there. - -Django's online documentation also includes pointers on how to contribute to -Django: - -* :doc:`How to contribute to Django ` - -Contributions on any level -- developing code, writing documentation or simply -triaging tickets and helping to test proposed bugfixes -- are always welcome and -appreciated. diff --git a/docs/releases/1.3-alpha-1.txt b/docs/releases/1.3-alpha-1.txt deleted file mode 100644 index f2c44830e9..0000000000 --- a/docs/releases/1.3-alpha-1.txt +++ /dev/null @@ -1,396 +0,0 @@ -================================ -Django 1.3 alpha 1 release notes -================================ - -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 contains a 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-alpha-1_ - -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 common views of data without -having to write too much code. - -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 Class-based Generic Views -` for more details. There is also a document to -help you `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. - -Extended static files handling -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.3 ships with a new contrib app ``'django.contrib.staticfiles'`` -to help developers handle the static media files (images, CSS, Javascript, -etc.) that are needed to render a complete web page. - -In previous versions of Django, it was common to place static assets -in :setting:`MEDIA_ROOT` along with user-uploaded files, and serve -them both at :setting:`MEDIA_URL`. Part of the purpose of introducing -the ``staticfiles`` app is to make it easier to keep static files -separate from user-uploaded files. Static assets should now go in -``static/`` subdirectories of your apps or in other static assets -directories listed in :setting:`STATICFILES_DIRS`, and will be served -at :setting:`STATIC_URL`. - -See the :doc:`reference documentation of the app ` -for more details or learn how to :doc:`manage static files -`. - -``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 its 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 library, 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 transaction management functions as -`context managers`_. For example:: - - with transaction.autocommit(): - # ... - -.. _context managers: http://docs.python.org/glossary.html#term-context-manager - -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 via - ``django.contrib.sites.models.get_current_site()``. - -* A :class:`~django.test.RequestFactory` for mocking - requests in tests. - -* A new test assertion -- - :meth:`~django.test.TransactionTestCase.assertNumQueries` -- making it - easier to test the database activity associated with a view. - - -.. _backwards-incompatible-changes-1.3-alpha-1: - -Backwards-incompatible changes in 1.3 alpha 1 -============================================= - -PasswordInput default rendering behavior -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :class:`~django.forms.PasswordInput` form widget, intended for use -with form fields which represent passwords, accepts a boolean keyword -argument ``render_value`` indicating whether to send its data back to -the browser when displaying a submitted form with errors. Prior to -Django 1.3, this argument defaulted to ``True``, meaning that the -submitted password would be sent back to the browser as part of the -form. Developers who wished to add a bit of additional security by -excluding that value from the redisplayed form could instantiate a -:class:`~django.forms.PasswordInput` passing ``render_value=False`` . - -Due to the sensitive nature of passwords, however, Django 1.3 takes -this step automatically; the default value of ``render_value`` is now -``False``, and developers who want the password value returned to the -browser on a submission with errors (the previous behavior) must now -explicitly indicate this. For example:: - - 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 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: https://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)". - - -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 :mod:`warnings` -module, or by running Python with a ``-Wd`` or ``-Wall`` flag. - -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, you are strongly -encouraged to 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: - -* ``django.views.generic.create_update`` -* ``django.views.generic.date_based`` -* ``django.views.generic.list_detail`` -* ``django.views.generic.simple`` - -Test client response ``template`` attribute -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django's :ref:`test client ` returns -:class:`~django.test.Response` objects annotated with extra testing -information. In Django versions prior to 1.3, this included a ``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 ``template`` attribute is deprecated in favor of a new -:attr:`~django.test.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 ``django.test.simple.DjangoTestRunner`` (including fail-fast -and Ctrl-C test termination) have been made redundant. In view of this -redundancy, ``DjangoTestRunner`` has been turned into an empty placeholder -class, and will be removed entirely in Django 1.5. - -The Django 1.3 roadmap -====================== - -Before the final Django 1.3 release, several other preview/development -releases will be made available. The current schedule consists of at -least the following: - -* Week of **November 29, 2010**: First Django 1.3 beta release. Final - feature freeze for Django 1.3. - -* Week of **January 10, 2011**: First Django 1.3 release - candidate. String freeze for translations. - -* Week of **January 17, 2011**: Django 1.3 final release. - -If necessary, additional alpha, beta or release-candidate packages -will be issued prior to the final 1.3 release. Django 1.3 will be -released approximately one week after the final release candidate. - - -What you can do to help -======================= - -In order to provide a high-quality 1.3 release, we need your help. Although this -alpha release is, again, *not* intended for production use, you can help the -Django team by trying out the alpha codebase in a safe test environment and -reporting any bugs or issues you encounter. The Django ticket tracker is the -central place to search for open issues: - -* https://code.djangoproject.com/timeline - -Please open new tickets if no existing ticket corresponds to a problem you're -running into. - -Additionally, discussion of Django development, including progress toward the -1.3 release, takes place daily on the django-developers mailing list: - -* http://groups.google.com/group/django-developers - -... and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If you're -interested in helping out with Django's development, feel free to join the -discussions there. - -Django's online documentation also includes pointers on how to contribute to -Django: - -* :doc:`How to contribute to Django ` - -Contributions on any level -- developing code, writing documentation or simply -triaging tickets and helping to test proposed bugfixes -- are always welcome and -appreciated. - -Several development sprints will also be taking place before the 1.3 -release; these will typically be announced in advance on the -django-developers mailing list, and anyone who wants to help is -welcome to join in. diff --git a/docs/releases/1.3-beta-1.txt b/docs/releases/1.3-beta-1.txt deleted file mode 100644 index 9ae5657ea3..0000000000 --- a/docs/releases/1.3-beta-1.txt +++ /dev/null @@ -1,231 +0,0 @@ -================================ -Django 1.3 beta 1 release notes -================================ - -Welcome to Django 1.3 beta 1! - -This is the second 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. - -What's new in Django 1.3 beta 1 -=============================== - -Further tweaks to the staticfiles app -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.3 ships with a new contrib app :mod:`django.contrib.staticfiles` -to help developers handle the static media files (images, CSS, JavaScript, -etc.) that are needed to render a complete web page. - -The :mod:`~django.contrib.staticfiles` app ships with the ability to -automatically serve static files during development (if the :setting:`DEBUG` -setting is ``True``) when using the :djadmin:`runserver` management command. -Based on feedback from the community this release adds two new options to the -:djadmin:`runserver` command to modify this behavior: - -* ``--nostatic``: prevents the :djadmin:`runserver` command from serving - files completely. - -* ``--insecure``: enables serving of static files even if running with - :setting:`DEBUG` set to False. (This is **not** recommended!) - -See the :doc:`staticfiles reference documentation ` -for more details, or learn :doc:`how to manage static files -`. - -Translation comments -~~~~~~~~~~~~~~~~~~~~ - -If you would like to give translators hints about a translatable string, you -can add a comment prefixed with the ``Translators`` keyword on the line -preceding the string, e.g.:: - - def my_view(request): - # Translators: This message appears on the home page only - output = ugettext("Welcome to my site.") - -The comment will appear in the resulting .po file and should also be -displayed by most translation tools. - -For more information, see :ref:`translator-comments`. - -Permissions for inactive users -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you provide a custom auth backend with ``supports_inactive_user`` set to -``True``, an inactive user model will check the backend for permissions. -This is useful for further centralizing the permission handling. See the -:doc:`authentication docs ` for more details. - -Backwards-incompatible changes in 1.3 alpha 2 -============================================= - -Change to admin lookup filters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Django admin has long had an undocumented "feature" allowing savvy -users to manipulate the query string of changelist pages to filter the -list of objects displayed. However, this also creates a security -issue, as a staff user with sufficient knowledge of model structure -could use this "feature" to gain access to information not normally accessible. - -As a result, changelist filtering now explicitly validates all lookup -arguments in the query string, and permits only fields which are -directly on the model, or relations explicitly permitted by the -``ModelAdmin`` definition. If you were relying on this undocumented -feature, you will need to update your ``ModelAdmin`` definitions to -whitelist the relations you choose to expose for filtering. - -Introduction of STATIC_URL and STATIC_ROOT settings -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The newly introduced :mod:`~django.contrib.staticfiles` app -- which extends -Django's abilities to handle static files for apps and projects -- required the -addition of two new settings to refer to those files in templates and code, -especially in contrast to the :setting:`MEDIA_URL` and :setting:`MEDIA_ROOT` -settings that refer to user-uploaded files. - -Prior to 1.3 alpha 2 these settings were called ``STATICFILES_URL`` and -``STATICFILES_ROOT`` to follow the naming scheme for app-centric settings. -Based on feedback from the community it became apparent that those settings -created confusion, especially given the fact that handling static files is also -desired outside the use of the optional :mod:`~django.contrib.staticfiles` app. - -As a result, we took the following steps to rectify the issue: - -* Two new global settings were added that will be used by, **but are not - limited to**, the :doc:`staticfiles` app: - -* :setting:`STATIC_ROOT` (formally ``STATICFILES_ROOT``) - -* :setting:`STATIC_URL` (formally ``STATICFILES_URL``) - -* The ``django.contrib.staticfiles.templatetags.staticfiles.get_staticfiles_prefix`` - template tag was moved to Django's core (``django.templatetags.static``) and - renamed to :ttag:`get_static_prefix`. - -* The ``django.contrib.staticfiles.context_processors.staticfiles`` - context processor was moved to Django's core - (``django.core.context_processors.static``) and renamed to - :func:`~django.core.context_processors.static`. - -* :ref:`form-asset-paths` now uses :setting:`STATIC_URL` as the prefix - **if the value is not None**, and falls back to the previously used - :setting:`MEDIA_URL` setting otherwise. - -Changes to the login methods of the admin -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In previous version the admin app defined login methods in multiple locations -and ignored the almost identical implementation in the already used auth app. -A side effect of this duplication was the missing adoption of the changes made -in r12634_ to support a broader set of characters for usernames. - -This release refactors the admin's login mechanism to use a subclass of the -:class:`~django.contrib.auth.forms.AuthenticationForm` instead of a manual -form validation. The previously undocumented method -``'django.contrib.admin.sites.AdminSite.display_login_form'`` has been removed -in favor of a new :attr:`~django.contrib.admin.AdminSite.login_form` -attribute. - -.. _r12634: https://code.djangoproject.com/changeset/12634 - -Changes to ``USStateField`` -=========================== - -The ``django.contrib.localflavor`` application contains collections -of code relevant to specific countries or cultures. One such is -``USStateField``, which provides a field for storing the two-letter postal -abbreviation of a U.S. state. This field has consistently caused problems, -however, because it is often used to store the state portion of a U.S postal -address, but not all "states" recognized by the U.S Postal Service are -actually states of the U.S. or even U.S. territory. Several -compromises over the list of choices resulted in some users feeling -the field supported too many locations, while others felt it supported -too few. - -In Django 1.3 we're taking a new approach to this problem, implemented -as a pair of changes: - -* The choice list for ``USStateField`` has changed. Previously, it - consisted of the 50 U.S. states, the District of Columbia and - U.S. overseas territories. As of Django 1.3 it includes all previous - choices, plus the U.S. Armed Forces postal codes. - -* A new model field, - ``django.contrib.localflavor.us.models.USPostalCodeField``, has - been added which draws its choices from a list of all postal - abbreviations recognized by the U.S Postal Service. This includes - all abbreviations recognized by ``USStateField``, plus three - independent nations -- the Federated States of Micronesia, the - Republic of the Marshall Islands and the Republic of Palau -- which - are serviced under treaty by the U.S. postal system. A new form - widget, ``django.contrib.localflavor.us.forms.USPSSelect``, is - also available and provides the same set of choices. - -Additionally, several finer-grained choice tuples are provided which -allow mixing and matching of subsets of the U.S. states and -territories, and other locations serviced by the U.S. postal -system. Consult the ``django.contrib.localflavor`` documentation -for more details. - -The change to ``USStateField`` is technically backwards-incompatible for -users who expect this field to exclude Armed Forces locations. If you -need to support U.S. mailing addresses without Armed Forces locations, -see the list of choice tuples available in the localflavor -documentation. - -The Django 1.3 roadmap -====================== - -Before the final Django 1.3 release, several other preview/development -releases will be made available. The current schedule consists of at -least the following: - -* Week of **January 24, 2011**: First Django 1.3 release - candidate. String freeze for translations. - -* Week of **January 31, 2011**: Django 1.3 final release. - -If necessary, additional beta or release-candidate packages -will be issued prior to the final 1.3 release. Django 1.3 will be -released approximately one week after the final release candidate. - - -What you can do to help -======================= - -In order to provide a high-quality 1.3 release, we need your help. Although this -beta release is, again, *not* intended for production use, you can help the -Django team by trying out the beta codebase in a safe test environment and -reporting any bugs or issues you encounter. The Django ticket tracker is the -central place to search for open issues: - -* https://code.djangoproject.com/timeline - -Please open new tickets if no existing ticket corresponds to a problem you're -running into. - -Additionally, discussion of Django development, including progress toward the -1.3 release, takes place daily on the django-developers mailing list: - -* http://groups.google.com/group/django-developers - -... and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If you're -interested in helping out with Django's development, feel free to join the -discussions there. - -Django's online documentation also includes pointers on how to contribute to -Django: - -* :doc:`How to contribute to Django ` - -Contributions on any level -- developing code, writing documentation or simply -triaging tickets and helping to test proposed bugfixes -- are always welcome and -appreciated. diff --git a/docs/releases/1.4-alpha-1.txt b/docs/releases/1.4-alpha-1.txt deleted file mode 100644 index 8a330bf1d9..0000000000 --- a/docs/releases/1.4-alpha-1.txt +++ /dev/null @@ -1,1119 +0,0 @@ -============================== -Django 1.4 alpha release notes -============================== - -December 22, 2011. - -Welcome to Django 1.4 alpha! - -This is the first in a series of preview/development releases leading up to -the eventual release of Django 1.4, scheduled for March 2012. 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.4 release. - -As such, this release is *not* intended for production use, and any such use -is discouraged. - -Django 1.4 alpha includes various `new features`_ and some minor `backwards -incompatible changes`_. There are also some features that have been dropped, -which are detailed in :doc:`our deprecation plan `, -and we've `begun the deprecation process for some features`_. - -.. _new features: `What's new in Django 1.4`_ -.. _backwards incompatible changes: `Backwards incompatible changes in 1.4`_ -.. _begun the deprecation process for some features: `Features deprecated in 1.4`_ - -Python compatibility -==================== - -While not a new feature, it's important to note that Django 1.4 introduces the -second shift in our Python compatibility policy since Django's initial public -debut. Django 1.2 dropped support for Python 2.3; now Django 1.4 drops support -for Python 2.4. As such, the minimum Python version required for Django is now -2.5, and Django is tested and supported on Python 2.5, 2.6 and 2.7. - -This change should affect only a small number of Django users, as most -operating-system vendors today are shipping Python 2.5 or newer as their default -version. If you're still using Python 2.4, however, you'll need to stick to -Django 1.3 until you can upgrade; per :doc:`our support policy -`, Django 1.3 will continue to receive security -support until the release of Django 1.5. - -Django does not support Python 3.x at this time. A document outlining our full -timeline for deprecating Python 2.x and moving to Python 3.x will be published -before the release of Django 1.4. - -What's new in Django 1.4 -======================== - -Support for in-browser testing frameworks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 supports integration with in-browser testing frameworks like -Selenium_. The new :class:`django.test.LiveServerTestCase` base class lets you -test the interactions between your site's front and back ends more -comprehensively. See the -:class:`documentation` for more details and -concrete examples. - -.. _Selenium: http://seleniumhq.org/ - -``SELECT FOR UPDATE`` support -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 now includes a :meth:`QuerySet.select_for_update() -` method which generates a -``SELECT ... FOR UPDATE`` SQL query. This will lock rows until the end of the -transaction, meaning that other transactions cannot modify or delete rows -matched by a ``FOR UPDATE`` query. - -For more details, see the documentation for -:meth:`~django.db.models.query.QuerySet.select_for_update`. - -``Model.objects.bulk_create`` in the ORM -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This method allows for more efficient creation of multiple objects in the ORM. -It can provide significant performance increases if you have many objects. -Django makes use of this internally, meaning some operations (such as database -setup for test suites) have seen a performance benefit as a result. - -See the :meth:`~django.db.models.query.QuerySet.bulk_create` docs for more -information. - -``QuerySet.prefetch_related`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Similar to :meth:`~django.db.models.query.QuerySet.select_related` but with a -different strategy and broader scope, -:meth:`~django.db.models.query.QuerySet.prefetch_related` has been added to -:class:`~django.db.models.query.QuerySet`. This method returns a new -``QuerySet`` that will prefetch each of the specified related lookups in a -single batch as soon as the query begins to be evaluated. Unlike -``select_related``, it does the joins in Python, not in the database, and -supports many-to-many relationships, ``GenericForeignKey`` and more. This -allows you to fix a very common performance problem in which your code ends up -doing O(n) database queries (or worse) if objects on your primary ``QuerySet`` -each have many related objects that you also need. - -Improved password hashing -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django's auth system (``django.contrib.auth``) stores passwords using a one-way -algorithm. Django 1.3 uses the SHA1_ algorithm, but increasing processor speeds -and theoretical attacks have revealed that SHA1 isn't as secure as we'd like. -Thus, Django 1.4 introduces a new password storage system: by default Django now -uses the PBKDF2_ algorithm (as recommended by NIST_). You can also easily choose -a different algorithm (including the popular bcrypt_ algorithm). For more -details, see :ref:`auth_password_storage`. - -.. _sha1: http://en.wikipedia.org/wiki/SHA1 -.. _pbkdf2: http://en.wikipedia.org/wiki/PBKDF2 -.. _nist: http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf -.. _bcrypt: http://en.wikipedia.org/wiki/Bcrypt - - -HTML5 Doctype -~~~~~~~~~~~~~ - -We've switched the admin and other bundled templates to use the HTML5 -doctype. While Django will be careful to maintain compatibility with older -browsers, this change means that you can use any HTML5 features you need in -admin pages without having to lose HTML validity or override the provided -templates to change the doctype. - -List filters in admin interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Prior to Django 1.4, the :mod:`~django.contrib.admin` app allowed you to specify -change list filters by specifying a field lookup, but didn't allow you to create -custom filters. This has been rectified with a simple API (previously used -internally and known as "FilterSpec"). For more details, see the documentation -for :attr:`~django.contrib.admin.ModelAdmin.list_filter`. - -Multiple sort in admin interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The admin change list now supports sorting on multiple columns. It respects all -elements of the :attr:`~django.contrib.admin.ModelAdmin.ordering` attribute, and -sorting on multiple columns by clicking on headers is designed to mimic the -behavior of desktop GUIs. The -:meth:`~django.contrib.admin.ModelAdmin.get_ordering` method for specifying the -ordering dynamically (e.g. depending on the request) has also been added. - -New ``ModelAdmin`` methods -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A new :meth:`~django.contrib.admin.ModelAdmin.save_related` method was added to -:mod:`~django.contrib.admin.ModelAdmin` to ease customization of how -related objects are saved in the admin. - -Two other new methods, -:meth:`~django.contrib.admin.ModelAdmin.get_list_display` and -:meth:`~django.contrib.admin.ModelAdmin.get_list_display_links` -were added to :class:`~django.contrib.admin.ModelAdmin` to enable the dynamic -customization of fields and links displayed on the admin change list. - -Admin inlines respect user permissions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Admin inlines will now only allow those actions for which the user has -permission. For ``ManyToMany`` relationships with an auto-created intermediate -model (which does not have its own permissions), the change permission for the -related model determines if the user has the permission to add, change or -delete relationships. - -Tools for cryptographic signing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 adds both a low-level API for signing values and a high-level API -for setting and reading signed cookies, one of the most common uses of -signing in Web applications. - -See the :doc:`cryptographic signing ` docs for more -information. - -Cookie-based session backend -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 introduces a new cookie-based backend for the session framework -which uses the tools for :doc:`cryptographic signing ` to -store the session data in the client's browser. - -See the :ref:`cookie-based session backend ` docs for -more information. - -New form wizard -~~~~~~~~~~~~~~~ - -The previous ``FormWizard`` from the formtools contrib app has been -replaced with a new implementation based on the class-based views -introduced in Django 1.3. It features a pluggable storage API and doesn't -require the wizard to pass around hidden fields for every previous step. - -Django 1.4 ships with a session-based storage backend and a cookie-based -storage backend. The latter uses the tools for -:doc:`cryptographic signing ` also introduced in -Django 1.4 to store the wizard's state in the user's cookies. - -See the :doc:`form wizard ` docs for -more information. - -``reverse_lazy`` -~~~~~~~~~~~~~~~~ - -A lazily evaluated version of :func:`django.core.urlresolvers.reverse` was -added to allow using URL reversals before the project's URLConf gets loaded. - -Translating URL patterns -~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 gained the ability to look for a language prefix in the URL pattern -when using the new :func:`~django.conf.urls.i18n.i18n_patterns` helper function. -Additionally, it's now possible to define translatable URL patterns using -:func:`~django.utils.translation.ugettext_lazy`. See -:ref:`url-internationalization` for more information about the language prefix -and how to internationalize URL patterns. - -Contextual translation support for ``{% trans %}`` and ``{% blocktrans %}`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :ref:`contextual translation` support introduced in -Django 1.3 via the ``pgettext`` function has been extended to the -:ttag:`trans` and :ttag:`blocktrans` template tags using the new ``context`` -keyword. - -Customizable ``SingleObjectMixin`` URLConf kwargs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Two new attributes, -:attr:`pk_url_kwarg` -and -:attr:`slug_url_kwarg`, -have been added to :class:`~django.views.generic.detail.SingleObjectMixin` to -enable the customization of URLConf keyword arguments used for single -object generic views. - -Assignment template tags -~~~~~~~~~~~~~~~~~~~~~~~~ - -A new :ref:`assignment_tag` helper -function was added to ``template.Library`` to ease the creation of template -tags that store data in a specified context variable. - -``*args`` and ``**kwargs`` support for template tag helper functions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :ref:`simple_tag`, -:ref:`inclusion_tag ` and -newly introduced -:ref:`assignment_tag` template -helper functions may now accept any number of positional or keyword arguments. -For example:: - - @register.simple_tag - def my_tag(a, b, *args, **kwargs): - warning = kwargs['warning'] - profile = kwargs['profile'] - ... - return ... - -Then in the template any number of arguments may be passed to the template tag. -For example: - -.. code-block:: html+django - - {% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %} - -No wrapping of exceptions in ``TEMPLATE_DEBUG`` mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In previous versions of Django, whenever the :setting:`TEMPLATE_DEBUG` setting -was ``True``, any exception raised during template rendering (even exceptions -unrelated to template syntax) were wrapped in ``TemplateSyntaxError`` and -re-raised. This was done in order to provide detailed template source location -information in the debug 500 page. - -In Django 1.4, exceptions are no longer wrapped. Instead, the original -exception is annotated with the source information. This means that catching -exceptions from template rendering is now consistent regardless of the value of -:setting:`TEMPLATE_DEBUG`, and there's no need to catch and unwrap -``TemplateSyntaxError`` in order to catch other errors. - -``truncatechars`` template filter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Added a filter which truncates a string to be no longer than the specified -number of characters. Truncated strings end with a translatable ellipsis -sequence ("..."). See the documentation for :tfilter:`truncatechars` for -more details. - -``static`` template tag -~~~~~~~~~~~~~~~~~~~~~~~ - -The :mod:`staticfiles` contrib app has a new -:ttag:`static` template tag to refer to files saved with -the :setting:`STATICFILES_STORAGE` storage backend. It uses the storage -backend's ``url`` method and therefore supports advanced features such as -:ref:`serving files from a cloud service`. - -``CachedStaticFilesStorage`` storage backend -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In addition to the `static template tag`_, the -:mod:`staticfiles` contrib app now has a -:class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` backend -which caches the files it saves (when running the :djadmin:`collectstatic` -management command) by appending the MD5 hash of the file's content to the -filename. For example, the file ``css/styles.css`` would also be saved as -``css/styles.55e7cbb9ba48.css`` - -See the :class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` -docs for more information. - -Simple clickjacking protection -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -We've added a middleware to provide easy protection against `clickjacking -`_ using the ``X-Frame-Options`` -header. It's not enabled by default for backwards compatibility reasons, but -you'll almost certainly want to :doc:`enable it ` to help -plug that security hole for browsers that support the header. - -CSRF improvements -~~~~~~~~~~~~~~~~~ - -We've made various improvements to our CSRF features, including the -:func:`~django.views.decorators.csrf.ensure_csrf_cookie` decorator which can -help with AJAX heavy sites, protection for PUT and DELETE requests, and the -:setting:`CSRF_COOKIE_SECURE` and :setting:`CSRF_COOKIE_PATH` settings which can -improve the security and usefulness of the CSRF protection. See the :doc:`CSRF -docs ` for more information. - -Error report filtering -~~~~~~~~~~~~~~~~~~~~~~ - -We added two function decorators, -:func:`~django.views.decorators.debug.sensitive_variables` and -:func:`~django.views.decorators.debug.sensitive_post_parameters`, to allow -designating the local variables and POST parameters that may contain sensitive -information and should be filtered out of error reports. - -All POST parameters are now systematically filtered out of error reports for -certain views (``login``, ``password_reset_confirm``, ``password_change``, and -``add_view`` in :mod:`django.contrib.auth.views`, as well as -``user_change_password`` in the admin app) to prevent the leaking of sensitive -information such as user passwords. - -You may override or customize the default filtering by writing a :ref:`custom -filter`. For more information see the docs on -:ref:`Filtering error reports`. - -Extended IPv6 support -~~~~~~~~~~~~~~~~~~~~~ - -The previously added support for IPv6 addresses when using the runserver -management command in Django 1.3 has now been further extended by adding -a :class:`~django.db.models.GenericIPAddressField` model field, -a :class:`~django.forms.GenericIPAddressField` form field and -the validators :data:`~django.core.validators.validate_ipv46_address` and -:data:`~django.core.validators.validate_ipv6_address` - -Updated default project layout and ``manage.py`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 ships with an updated default project layout and ``manage.py`` file -for the :djadmin:`startproject` management command. These fix some issues with -the previous ``manage.py`` handling of Python import paths that caused double -imports, trouble moving from development to deployment, and other -difficult-to-debug path issues. - -The previous ``manage.py`` called functions that are now deprecated, and thus -projects upgrading to Django 1.4 should update their ``manage.py``. (The -old-style ``manage.py`` will continue to work as before until Django 1.6; in -1.5 it will raise ``DeprecationWarning``). - -The new recommended ``manage.py`` file should look like this:: - - #!/usr/bin/env python - import os, sys - - if __name__ == "__main__": - os.environ.setdefault("DJANGO_SETTINGS_MODULE", "{{ project_name }}.settings") - - from django.core.management import execute_from_command_line - - execute_from_command_line(sys.argv) - -``{{ project_name }}`` should be replaced with the Python package name of the -actual project. - -If settings, URLconfs, and apps within the project are imported or referenced -using the project name prefix (e.g. ``myproject.settings``, ``ROOT_URLCONF = -"myproject.urls"``, etc), the new ``manage.py`` will need to be moved one -directory up, so it is outside the project package rather than adjacent to -``settings.py`` and ``urls.py``. - -For instance, with the following layout:: - - manage.py - mysite/ - __init__.py - settings.py - urls.py - myapp/ - __init__.py - models.py - -You could import ``mysite.settings``, ``mysite.urls``, and ``mysite.myapp``, -but not ``settings``, ``urls``, or ``myapp`` as top-level modules. - -Anything imported as a top-level module can be placed adjacent to the new -``manage.py``. For instance, to decouple "myapp" from the project module and -import it as just ``myapp``, place it outside the ``mysite/`` directory:: - - manage.py - myapp/ - __init__.py - models.py - mysite/ - __init__.py - settings.py - urls.py - -If the same code is imported inconsistently (some places with the project -prefix, some places without it), the imports will need to be cleaned up when -switching to the new ``manage.py``. - -Improved WSGI support -~~~~~~~~~~~~~~~~~~~~~ - -The :djadmin:`startproject` management command now adds a :file:`wsgi.py` -module to the initial project layout, containing a simple WSGI application that -can be used for :doc:`deploying with WSGI app -servers`. - -The :djadmin:`built-in development server` now supports using an -externally-defined WSGI callable, so as to make it possible to run runserver -with the same WSGI configuration that is used for deployment. A new -:setting:`WSGI_APPLICATION` setting is available to configure which WSGI -callable :djadmin:`runserver` uses. - -(The :djadmin:`runfcgi` management command also internally wraps the WSGI -callable configured via :setting:`WSGI_APPLICATION`.) - -Custom project and app templates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :djadmin:`startapp` and :djadmin:`startproject` management commands -got a ``--template`` option for specifying a path or URL to a custom app or -project template. - -For example, Django will use the ``/path/to/my_project_template`` directory -when running the following command:: - - django-admin.py startproject --template=/path/to/my_project_template myproject - -You can also now provide a destination directory as the second -argument to both :djadmin:`startapp` and :djadmin:`startproject`:: - - django-admin.py startapp myapp /path/to/new/app - django-admin.py startproject myproject /path/to/new/project - -For more information, see the :djadmin:`startapp` and :djadmin:`startproject` -documentation. - -Support for time zones -~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 adds :ref:`support for time zones `. When it's enabled, -Django stores date and time information in UTC in the database, uses time -zone-aware datetime objects internally, and translates them to the end user's -time zone in templates and forms. - -Reasons for using this feature include: - -- Customizing date and time display for users around the world. -- Storing datetimes in UTC for database portability and interoperability. - (This argument doesn't apply to PostgreSQL, because it already stores - timestamps with time zone information in Django 1.3.) -- Avoiding data corruption problems around DST transitions. - -Time zone support is enabled by default in new projects created with -:djadmin:`startproject`. If you want to use this feature in an existing -project, there is a :ref:`migration guide `. - -Minor features -~~~~~~~~~~~~~~ - -Django 1.4 also includes several smaller improvements worth noting: - -* A more usable stacktrace in the technical 500 page: frames in the - stack trace which reference Django's code are dimmed out, while - frames in user code are slightly emphasized. This change makes it - easier to scan a stacktrace for issues in user code. - -* :doc:`Tablespace support ` in PostgreSQL. - -* Customizable names for :meth:`~django.template.Library.simple_tag`. - -* In the documentation, a helpful :doc:`security overview ` - page. - -* The ``django.contrib.auth.models.check_password`` function has been moved - to the ``django.contrib.auth.utils`` module. Importing it from the old - location will still work, but you should update your imports. - -* The :djadmin:`collectstatic` management command gained a ``--clear`` option - to delete all files at the destination before copying or linking the static - files. - -* It is now possible to load fixtures containing forward references when using - MySQL with the InnoDB database engine. - -* A new 403 response handler has been added as - ``'django.views.defaults.permission_denied'``. You can set your own handler by - setting the value of :data:`django.conf.urls.handler403`. See the - documentation about :ref:`the 403 (HTTP Forbidden) view` - for more information. - -* The :ttag:`trans` template tag now takes an optional ``as`` argument to - be able to retrieve a translation string without displaying it but setting - a template context variable instead. - -* The :ttag:`if` template tag now supports ``{% elif %}`` clauses. - -* A new plain text version of the HTTP 500 status code internal error page - served when :setting:`DEBUG` is ``True`` is now sent to the client when - Django detects that the request has originated in JavaScript code - (:meth:`~django.http.HttpRequest.is_ajax` is used for this). - - Similarly to its HTML counterpart, it contains a collection of different - pieces of information about the state of the web application. - - This should make it easier to read when debugging interaction with - client-side Javascript code. - -* Added the :djadminopt:`--no-location` option to the :djadmin:`makemessages` - command. - -* Changed the ``locmem`` cache backend to use - ``pickle.HIGHEST_PROTOCOL`` for better compatibility with the other - cache backends. - -* Added support in the ORM for generating ``SELECT`` queries containing - ``DISTINCT ON``. - - The ``distinct()`` ``QuerySet`` method now accepts an optional list of model - field names. If specified, then the ``DISTINCT`` statement is limited to these - fields. This is only supported in PostgreSQL. - - For more details, see the documentation for - :meth:`~django.db.models.query.QuerySet.distinct`. - -Backwards incompatible changes in 1.4 -===================================== - -django.contrib.admin -~~~~~~~~~~~~~~~~~~~~ - -The included administration app ``django.contrib.admin`` has for a long time -shipped with a default set of static files such as JavaScript, images and -stylesheets. Django 1.3 added a new contrib app ``django.contrib.staticfiles`` -to handle such files in a generic way and defined conventions for static -files included in apps. - -Starting in Django 1.4 the admin's static files also follow this -convention to make it easier to deploy the included files. In previous -versions of Django, it was also common to define an ``ADMIN_MEDIA_PREFIX`` -setting to point to the URL where the admin's static files are served by a -web server. This setting has now been deprecated and replaced by the more -general setting :setting:`STATIC_URL`. Django will now expect to find the -admin static files under the URL ``/admin/``. - -If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g. -``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT` -are configured and your web server serves the files correctly. The development -server continues to serve the admin files just like before. Don't hesitate to -consult the :doc:`static files howto ` for further -details. - -In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g. -``http://media.example.com/admin/``) make sure to also set your -:setting:`STATIC_URL` setting to the correct URL, for example -``http://media.example.com/``. - -.. warning:: - - If you're implicitly relying on the path of the admin static files on - your server's file system when you deploy your site, you have to update - that path. The files were moved from :file:`django/contrib/admin/media/` - to :file:`django/contrib/admin/static/admin/`. - -Supported browsers for the admin -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django hasn't had a clear policy on which browsers are supported for using the -admin app. Django's new policy formalizes existing practices: `YUI's A-grade`_ -browsers should provide a fully-functional admin experience, with the notable -exception of IE6, which is no longer supported. - -Released over ten years ago, IE6 imposes many limitations on modern web -development. The practical implications of this policy are that contributors -are free to improve the admin without consideration for these limitations. - -This new policy **has no impact** on development outside of the admin. Users of -Django are free to develop webapps compatible with any range of browsers. - -.. _YUI's A-grade: http://yuilibrary.com/yui/docs/tutorials/gbs/ - -Removed admin icons -~~~~~~~~~~~~~~~~~~~ - -As part of an effort to improve the performance and usability of the admin's -changelist sorting interface and of the admin's :attr:`horizontal -` and :attr:`vertical -` "filter" widgets, some icon -files were removed and grouped into two sprite files. - -Specifically: ``selector-add.gif``, ``selector-addall.gif``, -``selector-remove.gif``, ``selector-removeall.gif``, -``selector_stacked-add.gif`` and ``selector_stacked-remove.gif`` were -combined into ``selector-icons.gif``; and ``arrow-up.gif`` and -``arrow-down.gif`` were combined into ``sorting-icons.gif``. - -If you used those icons to customize the admin then you will want to replace -them with your own icons or retrieve them from a previous release. - -CSS class names in admin forms -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To avoid conflicts with other common CSS class names (e.g. "button"), a prefix -"field-" has been added to all CSS class names automatically generated from the -form field names in the main admin forms, stacked inline forms and tabular -inline cells. You will need to take that prefix into account in your custom -style sheets or javascript files if you previously used plain field names as -selectors for custom styles or javascript transformations. - -Compatibility with old signed data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.3 changed the cryptographic signing mechanisms used in a number of -places in Django. While Django 1.3 kept fallbacks that would accept hashes -produced by the previous methods, these fallbacks are removed in Django 1.4. - -So, if you upgrade to Django 1.4 directly from 1.2 or earlier, you may -lose/invalidate certain pieces of data that have been cryptographically signed -using an old method. To avoid this, use Django 1.3 first for a period of time -to allow the signed data to expire naturally. The affected parts are detailed -below, with 1) the consequences of ignoring this advice and 2) the amount of -time you need to run Django 1.3 for the data to expire or become irrelevant. - -* ``contrib.sessions`` data integrity check - - * consequences: the user will be logged out, and session data will be lost. - - * time period: defined by :setting:`SESSION_COOKIE_AGE`. - -* ``contrib.auth`` password reset hash - - * consequences: password reset links from before the upgrade will not work. - - * time period: defined by :setting:`PASSWORD_RESET_TIMEOUT_DAYS`. - -Form-related hashes — these are much shorter lifetime, and are relevant only for -the short window where a user might fill in a form generated by the pre-upgrade -Django instance, and try to submit it to the upgraded Django instance: - -* ``contrib.comments`` form security hash - - * consequences: the user will see a validation error "Security hash failed". - - * time period: the amount of time you expect users to take filling out comment - forms. - -* ``FormWizard`` security hash - - * consequences: the user will see an error about the form having expired, - and will be sent back to the first page of the wizard, losing the data - they have entered so far. - - * time period: the amount of time you expect users to take filling out the - affected forms. - -* CSRF check - - * Note: This is actually a Django 1.1 fallback, not Django 1.2, - and applies only if you are upgrading from 1.1. - - * consequences: the user will see a 403 error with any CSRF protected POST - form. - - * time period: the amount of time you expect user to take filling out - such forms. - -django.contrib.flatpages -~~~~~~~~~~~~~~~~~~~~~~~~ - -Starting in the 1.4 release the -:class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` only -adds a trailing slash and redirects if the resulting URL refers to an existing -flatpage. For example, requesting ``/notaflatpageoravalidurl`` in a previous -version would redirect to ``/notaflatpageoravalidurl/``, which would -subsequently raise a 404. Requesting ``/notaflatpageoravalidurl`` now will -immediately raise a 404. Additionally redirects returned by flatpages are now -permanent (301 status code) to match the behavior of the -:class:`~django.middleware.common.CommonMiddleware`. - -Serialization of :class:`~datetime.datetime` and :class:`~datetime.time` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As a consequence of time zone support, and according to the ECMA-262 -specification, some changes were made to the JSON serializer: - -- It includes the time zone for aware datetime objects. It raises an exception - for aware time objects. -- It includes milliseconds for datetime and time objects. There is still - some precision loss, because Python stores microseconds (6 digits) and JSON - only supports milliseconds (3 digits). However, it's better than discarding - microseconds entirely. - -The XML serializer was also changed to use the ISO8601 format for datetimes. -The letter ``T`` is used to separate the date part from the time part, instead -of a space. Time zone information is included in the ``[+-]HH:MM`` format. - -The serializers will dump datetimes in fixtures with these new formats. They -can still load fixtures that use the old format. - -``supports_timezone`` changed to ``False`` for SQLite -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The database feature ``supports_timezone`` used to be ``True`` for SQLite. -Indeed, if you saved an aware datetime object, SQLite stored a string that -included an UTC offset. However, this offset was ignored when loading the value -back from the database, which could corrupt the data. - -In the context of time zone support, this flag was changed to ``False``, and -datetimes are now stored without time zone information in SQLite. When -:setting:`USE_TZ` is ``False``, if you attempt to save an aware datetime -object, Django raises an exception. - -Database connection's thread-locality -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``DatabaseWrapper`` objects (i.e. the connection objects referenced by -``django.db.connection`` and ``django.db.connections["some_alias"]``) used to -be thread-local. They are now global objects in order to be potentially shared -between multiple threads. While the individual connection objects are now -global, the ``django.db.connections`` dictionary referencing those objects is -still thread-local. Therefore if you just use the ORM or -``DatabaseWrapper.cursor()`` then the behavior is still the same as before. -Note, however, that ``django.db.connection`` does not directly reference the -default ``DatabaseWrapper`` object anymore and is now a proxy to access that -object's attributes. If you need to access the actual ``DatabaseWrapper`` -object, use ``django.db.connections[DEFAULT_DB_ALIAS]`` instead. - -As part of this change, all underlying SQLite connections are now enabled for -potential thread-sharing (by passing the ``check_same_thread=False`` attribute -to pysqlite). ``DatabaseWrapper`` however preserves the previous behavior by -disabling thread-sharing by default, so this does not affect any existing -code that purely relies on the ORM or on ``DatabaseWrapper.cursor()``. - -Finally, while it is now possible to pass connections between threads, Django -does not make any effort to synchronize access to the underlying backend. -Concurrency behavior is defined by the underlying backend implementation. -Check their documentation for details. - -`COMMENTS_BANNED_USERS_GROUP` setting -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django's comments app has historically -supported excluding the comments of a special user group, but we've never -documented the feature properly and didn't enforce the exclusion in other parts -of the app such as the template tags. To fix this problem, we removed the code -from the feed class. - -If you rely on the feature and want to restore the old behavior, simply use -a custom comment model manager to exclude the user group, like this:: - - from django.conf import settings - from django.contrib.comments.managers import CommentManager - - class BanningCommentManager(CommentManager): - def get_query_set(self): - qs = super(BanningCommentManager, self).get_query_set() - if getattr(settings, 'COMMENTS_BANNED_USERS_GROUP', None): - where = ['user_id NOT IN (SELECT user_id FROM auth_user_groups WHERE group_id = %s)'] - params = [settings.COMMENTS_BANNED_USERS_GROUP] - qs = qs.extra(where=where, params=params) - return qs - -Save this model manager in your custom comment app (e.g. in -``my_comments_app/managers.py``) and add it your custom comment app model:: - - from django.db import models - from django.contrib.comments.models import Comment - - from my_comments_app.managers import BanningCommentManager - - class CommentWithTitle(Comment): - title = models.CharField(max_length=300) - - objects = BanningCommentManager() - -`IGNORABLE_404_STARTS` and `IGNORABLE_404_ENDS` settings -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Until Django 1.3, it was possible to exclude some URLs from Django's -:doc:`404 error reporting` by adding prefixes to -``IGNORABLE_404_STARTS`` and suffixes to ``IGNORABLE_404_ENDS``. - -In Django 1.4, these two settings are superseded by -:setting:`IGNORABLE_404_URLS`, which is a list of compiled regular -expressions. Django won't send an email for 404 errors on URLs that match any -of them. - -Furthermore, the previous settings had some rather arbitrary default values:: - - IGNORABLE_404_STARTS = ('/cgi-bin/', '/_vti_bin', '/_vti_inf') - IGNORABLE_404_ENDS = ('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', - 'favicon.ico', '.php') - -It's not Django's role to decide if your website has a legacy ``/cgi-bin/`` -section or a ``favicon.ico``. As a consequence, the default values of -:setting:`IGNORABLE_404_URLS`, ``IGNORABLE_404_STARTS``, and -``IGNORABLE_404_ENDS`` are all now empty. - -If you have customized ``IGNORABLE_404_STARTS`` or ``IGNORABLE_404_ENDS``, or -if you want to keep the old default value, you should add the following lines -in your settings file:: - - import re - IGNORABLE_404_URLS = ( - # for each in IGNORABLE_404_STARTS - re.compile(r'^'), - # for each in IGNORABLE_404_ENDS - re.compile(r'$'), - ) - -Don't forget to escape characters that have a special meaning in a regular -expression. - -CSRF protection extended to PUT and DELETE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Previously, Django's :doc:`CSRF protection ` provided -protection against only POST requests. Since use of PUT and DELETE methods in -AJAX applications is becoming more common, we now protect all methods not -defined as safe by :rfc:`2616` i.e. we exempt GET, HEAD, OPTIONS and TRACE, and -enforce protection on everything else. - -If you are using PUT or DELETE methods in AJAX applications, please see the -:ref:`instructions about using AJAX and CSRF `. - -``django.core.template_loaders`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This was an alias to ``django.template.loader`` since 2005, it has been removed -without emitting a warning due to the length of the deprecation. If your code -still referenced this please use ``django.template.loader`` instead. - -``django.db.models.fields.URLField.verify_exists`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This functionality has been removed due to intractable performance and -security issues. Any existing usage of ``verify_exists`` should be -removed. - -``django.core.files.storage.Storage.open`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``open`` method of the base Storage class took an obscure parameter -``mixin`` which allowed you to dynamically change the base classes of the -returned file object. This has been removed. In the rare case you relied on the -``mixin`` parameter, you can easily achieve the same by overriding the ``open`` -method, e.g.:: - - from django.core.files import File - from django.core.files.storage import FileSystemStorage - - class Spam(File): - """ - Spam, spam, spam, spam and spam. - """ - def ham(self): - return 'eggs' - - class SpamStorage(FileSystemStorage): - """ - A custom file storage backend. - """ - def open(self, name, mode='rb'): - return Spam(open(self.path(name), mode)) - -YAML deserializer now uses ``yaml.safe_load`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``yaml.load`` is able to construct any Python object, which may trigger -arbitrary code execution if you process a YAML document that comes from an -untrusted source. This feature isn't necessary for Django's YAML deserializer, -whose primary use is to load fixtures consisting of simple objects. Even though -fixtures are trusted data, for additional security, the YAML deserializer now -uses ``yaml.safe_load``. - -Features deprecated in 1.4 -========================== - -Old styles of calling ``cache_page`` decorator -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some legacy ways of calling :func:`~django.views.decorators.cache.cache_page` -have been deprecated, please see the docs for the correct way to use this -decorator. - -Support for PostgreSQL versions older than 8.2 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.3 dropped support for PostgreSQL versions older than 8.0 and the -relevant documents suggested to use a recent version because of performance -reasons but more importantly because end of the upstream support periods for -releases 8.0 and 8.1 was near (November 2010). - -Django 1.4 takes that policy further and sets 8.2 as the minimum PostgreSQL -version it officially supports. - -Request exceptions are now always logged -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When :doc:`logging support ` was added to Django in 1.3, the -admin error email support was moved into the -:class:`django.utils.log.AdminEmailHandler`, attached to the -``'django.request'`` logger. In order to maintain the established behavior of -error emails, the ``'django.request'`` logger was called only when -:setting:`DEBUG` was ``False``. - -To increase the flexibility of error logging for requests, the -``'django.request'`` logger is now called regardless of the value of -:setting:`DEBUG`, and the default settings file for new projects now includes a -separate filter attached to :class:`django.utils.log.AdminEmailHandler` to -prevent admin error emails in ``DEBUG`` mode:: - - 'filters': { - 'require_debug_false': { - '()': 'django.utils.log.RequireDebugFalse' - } - }, - 'handlers': { - 'mail_admins': { - 'level': 'ERROR', - 'filters': ['require_debug_false'], - 'class': 'django.utils.log.AdminEmailHandler' - } - }, - -If your project was created prior to this change, your :setting:`LOGGING` -setting will not include this new filter. In order to maintain -backwards-compatibility, Django will detect that your ``'mail_admins'`` handler -configuration includes no ``'filters'`` section, and will automatically add -this filter for you and issue a pending-deprecation warning. This will become a -deprecation warning in Django 1.5, and in Django 1.6 the -backwards-compatibility shim will be removed entirely. - -The existence of any ``'filters'`` key under the ``'mail_admins'`` handler will -disable this backward-compatibility shim and deprecation warning. - -``django.conf.urls.defaults`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Until Django 1.3 the functions :func:`~django.conf.urls.include`, -:func:`~django.conf.urls.patterns` and :func:`~django.conf.urls.url` plus -:data:`~django.conf.urls.handler404`, :data:`~django.conf.urls.handler500` -were located in a ``django.conf.urls.defaults`` module. - -Starting with Django 1.4 they are now available in :mod:`django.conf.urls`. - -``django.contrib.databrowse`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Databrowse has not seen active development for some time, and this does not show -any sign of changing. There had been a suggestion for a `GSOC project`_ to -integrate the functionality of databrowse into the admin, but no progress was -made. While Databrowse has been deprecated, an enhancement of -``django.contrib.admin`` providing a similar feature set is still possible. - -.. _GSOC project: https://code.djangoproject.com/wiki/SummerOfCode2011#Integratedatabrowseintotheadmin - -The code that powers Databrowse is licensed under the same terms as Django -itself, and so is available to be adopted by an individual or group as -a third-party project. - -``django.core.management.setup_environ`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This function temporarily modified ``sys.path`` in order to make the parent -"project" directory importable under the old flat :djadmin:`startproject` -layout. This function is now deprecated, as its path workarounds are no longer -needed with the new ``manage.py`` and default project layout. - -This function was never documented or part of the public API, but was widely -recommended for use in setting up a "Django environment" for a user script. -These uses should be replaced by setting the ``DJANGO_SETTINGS_MODULE`` -environment variable or using :func:`django.conf.settings.configure`. - -``django.core.management.execute_manager`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This function was previously used by ``manage.py`` to execute a management -command. It is identical to -``django.core.management.execute_from_command_line``, except that it first -calls ``setup_environ``, which is now deprecated. As such, ``execute_manager`` -is also deprecated; ``execute_from_command_line`` can be used instead. Neither -of these functions is documented as part of the public API, but a deprecation -path is needed due to use in existing ``manage.py`` files. - -``is_safe`` and ``needs_autoescape`` attributes of template filters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Two flags, ``is_safe`` and ``needs_autoescape``, define how each template filter -interacts with Django's auto-escaping behavior. They used to be attributes of -the filter function:: - - @register.filter - def noop(value): - return value - noop.is_safe = True - -However, this technique caused some problems in combination with decorators, -especially :func:`@stringfilter `. -Now, the flags are keyword arguments of :meth:`@register.filter -`:: - - @register.filter(is_safe=True) - def noop(value): - return value - -See :ref:`filters and auto-escaping ` for more information. - -Session cookies now have the ``httponly`` flag by default -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Session cookies now include the ``httponly`` attribute by default to -help reduce the impact of potential XSS attacks. For strict backwards -compatibility, use ``SESSION_COOKIE_HTTPONLY = False`` in your settings file. - -Wildcard expansion of application names in `INSTALLED_APPS` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Until Django 1.3, :setting:`INSTALLED_APPS` accepted wildcards in application -names, like ``django.contrib.*``. The expansion was performed by a -filesystem-based implementation of ``from import *``. Unfortunately, -`this can't be done reliably`_. - -This behavior was never documented. Since it is unpythonic and not obviously -useful, it was removed in Django 1.4. If you relied on it, you must edit your -settings file to list all your applications explicitly. - -.. _this can't be done reliably: http://docs.python.org/tutorial/modules.html#importing-from-a-package - -``HttpRequest.raw_post_data`` renamed to ``HttpRequest.body`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This attribute was confusingly named ``HttpRequest.raw_post_data``, but it -actually provided the body of the HTTP request. It's been renamed to -``HttpRequest.body``, and ``HttpRequest.raw_post_data`` has been deprecated. - -The Django 1.4 roadmap -====================== - -Before the final Django 1.4 release, several other preview/development releases -will be made available. The current schedule consists of at least the following: - -* Week of **January 30, 2012**: First Django 1.4 beta release; final - feature freeze for Django 1.4. - -* Week of **February 27, 2012**: First Django 1.4 release - candidate; string freeze for translations. - -* Week of **March 5, 2012**: Django 1.4 final release. - -If necessary, additional alpha, beta or release-candidate packages -will be issued prior to the final 1.4 release. Django 1.4 will be -released approximately one week after the final release candidate. - -What you can do to help -======================= - -In order to provide a high-quality 1.4 release, we need your help. Although this -alpha release is, again, *not* intended for production use, you can help the -Django team by trying out the alpha codebase in a safe test environment and -reporting any bugs or issues you encounter. The Django ticket tracker is the -central place to search for open issues: - -* https://code.djangoproject.com/timeline - -Please open new tickets if no existing ticket corresponds to a problem you're -running into. - -Additionally, discussion of Django development, including progress toward the -1.3 release, takes place daily on the django-developers mailing list: - -* http://groups.google.com/group/django-developers - -... and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If you're -interested in helping out with Django's development, feel free to join the -discussions there. - -Django's online documentation also includes pointers on how to contribute to -Django: - -* :doc:`How to contribute to Django ` - -Contributions on any level -- developing code, writing documentation or simply -triaging tickets and helping to test proposed bugfixes -- are always welcome and -appreciated. - -Several development sprints will also be taking place before the 1.4 -release; these will typically be announced in advance on the -django-developers mailing list, and anyone who wants to help is -welcome to join in. diff --git a/docs/releases/1.4-beta-1.txt b/docs/releases/1.4-beta-1.txt deleted file mode 100644 index c57f5bee09..0000000000 --- a/docs/releases/1.4-beta-1.txt +++ /dev/null @@ -1,1191 +0,0 @@ -============================== -Django 1.4 beta release notes -============================== - -February 15, 2012. - -Welcome to Django 1.4 beta! - -This is the second in a series of preview/development releases leading -up to the eventual release of Django 1.4, scheduled for March -2012. 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.4 release. - -As such, this release is *not* intended for production use, and any such use -is discouraged. - -Django 1.4 beta includes various `new features`_ and some minor `backwards -incompatible changes`_. There are also some features that have been dropped, -which are detailed in :doc:`our deprecation plan `, -and we've `begun the deprecation process for some features`_. - -.. _new features: `What's new in Django 1.4`_ -.. _backwards incompatible changes: `Backwards incompatible changes in 1.4`_ -.. _begun the deprecation process for some features: `Features deprecated in 1.4`_ - - -Version numbering -================= - -Internally, Django's version number is represented by the tuple -``django.VERSION``. This is used to generate human-readable version -number strings; as of Django 1.4 beta 1, the algorithm for generating -these strings has been changed to match the recommendations of :pep:`386`. -This only affects the human-readable strings identifying Django alphas, -betas and release candidates, and should not affect end users in any way. - -For example purposes, the old algorithm would give Django 1.4 beta 1 a -version string of the form "1.4 beta 1". The new algorithm generates -the version string "1.4b1". - - -Python compatibility -==================== - -While not a new feature, it's important to note that Django 1.4 introduces the -second shift in our Python compatibility policy since Django's initial public -debut. Django 1.2 dropped support for Python 2.3; now Django 1.4 drops support -for Python 2.4. As such, the minimum Python version required for Django is now -2.5, and Django is tested and supported on Python 2.5, 2.6 and 2.7. - -This change should affect only a small number of Django users, as most -operating-system vendors today are shipping Python 2.5 or newer as their default -version. If you're still using Python 2.4, however, you'll need to stick to -Django 1.3 until you can upgrade; per :doc:`our support policy -`, Django 1.3 will continue to receive security -support until the release of Django 1.5. - -Django does not support Python 3.x at this time. A document outlining our full -timeline for deprecating Python 2.x and moving to Python 3.x will be published -before the release of Django 1.4. - -What's new in Django 1.4 -======================== - -Support for in-browser testing frameworks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 supports integration with in-browser testing frameworks like -Selenium_. The new :class:`django.test.LiveServerTestCase` base class lets you -test the interactions between your site's front and back ends more -comprehensively. See the -:class:`documentation` for more details and -concrete examples. - -.. _Selenium: http://seleniumhq.org/ - -``SELECT FOR UPDATE`` support -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 now includes a :meth:`QuerySet.select_for_update() -` method which generates a -``SELECT ... FOR UPDATE`` SQL query. This will lock rows until the end of the -transaction, meaning that other transactions cannot modify or delete rows -matched by a ``FOR UPDATE`` query. - -For more details, see the documentation for -:meth:`~django.db.models.query.QuerySet.select_for_update`. - -``Model.objects.bulk_create`` in the ORM -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This method allows for more efficient creation of multiple objects in the ORM. -It can provide significant performance increases if you have many objects. -Django makes use of this internally, meaning some operations (such as database -setup for test suites) have seen a performance benefit as a result. - -See the :meth:`~django.db.models.query.QuerySet.bulk_create` docs for more -information. - -``QuerySet.prefetch_related`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Similar to :meth:`~django.db.models.query.QuerySet.select_related` but with a -different strategy and broader scope, -:meth:`~django.db.models.query.QuerySet.prefetch_related` has been added to -:class:`~django.db.models.query.QuerySet`. This method returns a new -``QuerySet`` that will prefetch each of the specified related lookups in a -single batch as soon as the query begins to be evaluated. Unlike -``select_related``, it does the joins in Python, not in the database, and -supports many-to-many relationships, ``GenericForeignKey`` and more. This -allows you to fix a very common performance problem in which your code ends up -doing O(n) database queries (or worse) if objects on your primary ``QuerySet`` -each have many related objects that you also need. - -Improved password hashing -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django's auth system (``django.contrib.auth``) stores passwords using a one-way -algorithm. Django 1.3 uses the SHA1_ algorithm, but increasing processor speeds -and theoretical attacks have revealed that SHA1 isn't as secure as we'd like. -Thus, Django 1.4 introduces a new password storage system: by default Django now -uses the PBKDF2_ algorithm (as recommended by NIST_). You can also easily choose -a different algorithm (including the popular bcrypt_ algorithm). For more -details, see :ref:`auth_password_storage`. - -.. _sha1: http://en.wikipedia.org/wiki/SHA1 -.. _pbkdf2: http://en.wikipedia.org/wiki/PBKDF2 -.. _nist: http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf -.. _bcrypt: http://en.wikipedia.org/wiki/Bcrypt - -.. warning:: - - Django 1.4 alpha contained a bug that corrupted PBKDF2 hashes. To - determine which accounts are affected, run :djadmin:`manage.py shell - ` and paste this snippet:: - - from base64 import b64decode - from django.contrib.auth.models import User - hash_len = {'pbkdf2_sha1': 20, 'pbkdf2_sha256': 32} - for user in User.objects.filter(password__startswith='pbkdf2_'): - algo, _, _, hash = user.password.split('$') - if len(b64decode(hash)) != hash_len[algo]: - print user - - These users should reset their passwords. - -HTML5 Doctype -~~~~~~~~~~~~~ - -We've switched the admin and other bundled templates to use the HTML5 -doctype. While Django will be careful to maintain compatibility with older -browsers, this change means that you can use any HTML5 features you need in -admin pages without having to lose HTML validity or override the provided -templates to change the doctype. - -List filters in admin interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Prior to Django 1.4, the :mod:`~django.contrib.admin` app allowed you to specify -change list filters by specifying a field lookup, but didn't allow you to create -custom filters. This has been rectified with a simple API (previously used -internally and known as "FilterSpec"). For more details, see the documentation -for :attr:`~django.contrib.admin.ModelAdmin.list_filter`. - -Multiple sort in admin interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The admin change list now supports sorting on multiple columns. It respects all -elements of the :attr:`~django.contrib.admin.ModelAdmin.ordering` attribute, and -sorting on multiple columns by clicking on headers is designed to mimic the -behavior of desktop GUIs. The -:meth:`~django.contrib.admin.ModelAdmin.get_ordering` method for specifying the -ordering dynamically (e.g. depending on the request) has also been added. - -New ``ModelAdmin`` methods -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A new :meth:`~django.contrib.admin.ModelAdmin.save_related` method was added to -:mod:`~django.contrib.admin.ModelAdmin` to ease customization of how -related objects are saved in the admin. - -Two other new methods, -:meth:`~django.contrib.admin.ModelAdmin.get_list_display` and -:meth:`~django.contrib.admin.ModelAdmin.get_list_display_links` -were added to :class:`~django.contrib.admin.ModelAdmin` to enable the dynamic -customization of fields and links displayed on the admin change list. - -Admin inlines respect user permissions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Admin inlines will now only allow those actions for which the user has -permission. For ``ManyToMany`` relationships with an auto-created intermediate -model (which does not have its own permissions), the change permission for the -related model determines if the user has the permission to add, change or -delete relationships. - -Tools for cryptographic signing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 adds both a low-level API for signing values and a high-level API -for setting and reading signed cookies, one of the most common uses of -signing in Web applications. - -See the :doc:`cryptographic signing ` docs for more -information. - -Cookie-based session backend -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 introduces a new cookie-based backend for the session framework -which uses the tools for :doc:`cryptographic signing ` to -store the session data in the client's browser. - -.. warning:: - - Session data is signed and validated by the server, but is not - encrypted. This means that a user can view any data stored in the - session, but cannot change it. Please read the documentation for - further clarification before using this backend. - -See the :ref:`cookie-based session backend ` docs for -more information. - -New form wizard -~~~~~~~~~~~~~~~ - -The previous ``FormWizard`` from the formtools contrib app has been -replaced with a new implementation based on the class-based views -introduced in Django 1.3. It features a pluggable storage API and doesn't -require the wizard to pass around hidden fields for every previous step. - -Django 1.4 ships with a session-based storage backend and a cookie-based -storage backend. The latter uses the tools for -:doc:`cryptographic signing ` also introduced in -Django 1.4 to store the wizard's state in the user's cookies. - -See the :doc:`form wizard ` docs for -more information. - -``reverse_lazy`` -~~~~~~~~~~~~~~~~ - -A lazily evaluated version of :func:`django.core.urlresolvers.reverse` was -added to allow using URL reversals before the project's URLConf gets loaded. - -Translating URL patterns -~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 gained the ability to look for a language prefix in the URL pattern -when using the new :func:`~django.conf.urls.i18n.i18n_patterns` helper function. -Additionally, it's now possible to define translatable URL patterns using -:func:`~django.utils.translation.ugettext_lazy`. See -:ref:`url-internationalization` for more information about the language prefix -and how to internationalize URL patterns. - -Contextual translation support for ``{% trans %}`` and ``{% blocktrans %}`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :ref:`contextual translation` support introduced in -Django 1.3 via the ``pgettext`` function has been extended to the -:ttag:`trans` and :ttag:`blocktrans` template tags using the new ``context`` -keyword. - -Customizable ``SingleObjectMixin`` URLConf kwargs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Two new attributes, -:attr:`pk_url_kwarg` -and -:attr:`slug_url_kwarg`, -have been added to :class:`~django.views.generic.detail.SingleObjectMixin` to -enable the customization of URLConf keyword arguments used for single -object generic views. - -Assignment template tags -~~~~~~~~~~~~~~~~~~~~~~~~ - -A new :ref:`assignment_tag` helper -function was added to ``template.Library`` to ease the creation of template -tags that store data in a specified context variable. - -``*args`` and ``**kwargs`` support for template tag helper functions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :ref:`simple_tag`, -:ref:`inclusion_tag ` and -newly introduced -:ref:`assignment_tag` template -helper functions may now accept any number of positional or keyword arguments. -For example:: - - @register.simple_tag - def my_tag(a, b, *args, **kwargs): - warning = kwargs['warning'] - profile = kwargs['profile'] - ... - return ... - -Then in the template any number of arguments may be passed to the template tag. -For example: - -.. code-block:: html+django - - {% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %} - -No wrapping of exceptions in ``TEMPLATE_DEBUG`` mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In previous versions of Django, whenever the :setting:`TEMPLATE_DEBUG` setting -was ``True``, any exception raised during template rendering (even exceptions -unrelated to template syntax) were wrapped in ``TemplateSyntaxError`` and -re-raised. This was done in order to provide detailed template source location -information in the debug 500 page. - -In Django 1.4, exceptions are no longer wrapped. Instead, the original -exception is annotated with the source information. This means that catching -exceptions from template rendering is now consistent regardless of the value of -:setting:`TEMPLATE_DEBUG`, and there's no need to catch and unwrap -``TemplateSyntaxError`` in order to catch other errors. - -``truncatechars`` template filter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Added a filter which truncates a string to be no longer than the specified -number of characters. Truncated strings end with a translatable ellipsis -sequence ("..."). See the documentation for :tfilter:`truncatechars` for -more details. - -``static`` template tag -~~~~~~~~~~~~~~~~~~~~~~~ - -The :mod:`staticfiles` contrib app has a new -:ttag:`static` template tag to refer to files saved with -the :setting:`STATICFILES_STORAGE` storage backend. It uses the storage -backend's ``url`` method and therefore supports advanced features such as -:ref:`serving files from a cloud service`. - -``CachedStaticFilesStorage`` storage backend -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In addition to the `static template tag`_, the -:mod:`staticfiles` contrib app now has a -:class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` backend -which caches the files it saves (when running the :djadmin:`collectstatic` -management command) by appending the MD5 hash of the file's content to the -filename. For example, the file ``css/styles.css`` would also be saved as -``css/styles.55e7cbb9ba48.css`` - -See the :class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` -docs for more information. - -Simple clickjacking protection -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -We've added a middleware to provide easy protection against `clickjacking -`_ using the ``X-Frame-Options`` -header. It's not enabled by default for backwards compatibility reasons, but -you'll almost certainly want to :doc:`enable it ` to help -plug that security hole for browsers that support the header. - -CSRF improvements -~~~~~~~~~~~~~~~~~ - -We've made various improvements to our CSRF features, including the -:func:`~django.views.decorators.csrf.ensure_csrf_cookie` decorator which can -help with AJAX heavy sites, protection for PUT and DELETE requests, and the -:setting:`CSRF_COOKIE_SECURE` and :setting:`CSRF_COOKIE_PATH` settings which can -improve the security and usefulness of the CSRF protection. See the :doc:`CSRF -docs ` for more information. - -Error report filtering -~~~~~~~~~~~~~~~~~~~~~~ - -We added two function decorators, -:func:`~django.views.decorators.debug.sensitive_variables` and -:func:`~django.views.decorators.debug.sensitive_post_parameters`, to allow -designating the local variables and POST parameters that may contain sensitive -information and should be filtered out of error reports. - -All POST parameters are now systematically filtered out of error reports for -certain views (``login``, ``password_reset_confirm``, ``password_change``, and -``add_view`` in :mod:`django.contrib.auth.views`, as well as -``user_change_password`` in the admin app) to prevent the leaking of sensitive -information such as user passwords. - -You may override or customize the default filtering by writing a :ref:`custom -filter`. For more information see the docs on -:ref:`Filtering error reports`. - -Extended IPv6 support -~~~~~~~~~~~~~~~~~~~~~ - -The previously added support for IPv6 addresses when using the runserver -management command in Django 1.3 has now been further extended by adding -a :class:`~django.db.models.GenericIPAddressField` model field, -a :class:`~django.forms.GenericIPAddressField` form field and -the validators :data:`~django.core.validators.validate_ipv46_address` and -:data:`~django.core.validators.validate_ipv6_address` - -Updated default project layout and ``manage.py`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 ships with an updated default project layout and ``manage.py`` file -for the :djadmin:`startproject` management command. These fix some issues with -the previous ``manage.py`` handling of Python import paths that caused double -imports, trouble moving from development to deployment, and other -difficult-to-debug path issues. - -The previous ``manage.py`` called functions that are now deprecated, and thus -projects upgrading to Django 1.4 should update their ``manage.py``. (The -old-style ``manage.py`` will continue to work as before until Django 1.6; in -1.5 it will raise ``DeprecationWarning``). - -The new recommended ``manage.py`` file should look like this:: - - #!/usr/bin/env python - import os, sys - - if __name__ == "__main__": - os.environ.setdefault("DJANGO_SETTINGS_MODULE", "{{ project_name }}.settings") - - from django.core.management import execute_from_command_line - - execute_from_command_line(sys.argv) - -``{{ project_name }}`` should be replaced with the Python package name of the -actual project. - -If settings, URLconfs, and apps within the project are imported or referenced -using the project name prefix (e.g. ``myproject.settings``, ``ROOT_URLCONF = -"myproject.urls"``, etc), the new ``manage.py`` will need to be moved one -directory up, so it is outside the project package rather than adjacent to -``settings.py`` and ``urls.py``. - -For instance, with the following layout:: - - manage.py - mysite/ - __init__.py - settings.py - urls.py - myapp/ - __init__.py - models.py - -You could import ``mysite.settings``, ``mysite.urls``, and ``mysite.myapp``, -but not ``settings``, ``urls``, or ``myapp`` as top-level modules. - -Anything imported as a top-level module can be placed adjacent to the new -``manage.py``. For instance, to decouple "myapp" from the project module and -import it as just ``myapp``, place it outside the ``mysite/`` directory:: - - manage.py - myapp/ - __init__.py - models.py - mysite/ - __init__.py - settings.py - urls.py - -If the same code is imported inconsistently (some places with the project -prefix, some places without it), the imports will need to be cleaned up when -switching to the new ``manage.py``. - -Improved WSGI support -~~~~~~~~~~~~~~~~~~~~~ - -The :djadmin:`startproject` management command now adds a :file:`wsgi.py` -module to the initial project layout, containing a simple WSGI application that -can be used for :doc:`deploying with WSGI app -servers`. - -The :djadmin:`built-in development server` now supports using an -externally-defined WSGI callable, so as to make it possible to run runserver -with the same WSGI configuration that is used for deployment. A new -:setting:`WSGI_APPLICATION` setting is available to configure which WSGI -callable :djadmin:`runserver` uses. - -(The :djadmin:`runfcgi` management command also internally wraps the WSGI -callable configured via :setting:`WSGI_APPLICATION`.) - -Custom project and app templates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :djadmin:`startapp` and :djadmin:`startproject` management commands -got a ``--template`` option for specifying a path or URL to a custom app or -project template. - -For example, Django will use the ``/path/to/my_project_template`` directory -when running the following command:: - - django-admin.py startproject --template=/path/to/my_project_template myproject - -You can also now provide a destination directory as the second -argument to both :djadmin:`startapp` and :djadmin:`startproject`:: - - django-admin.py startapp myapp /path/to/new/app - django-admin.py startproject myproject /path/to/new/project - -For more information, see the :djadmin:`startapp` and :djadmin:`startproject` -documentation. - -Support for time zones -~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 adds :ref:`support for time zones `. When it's enabled, -Django stores date and time information in UTC in the database, uses time -zone-aware datetime objects internally, and translates them to the end user's -time zone in templates and forms. - -Reasons for using this feature include: - -- Customizing date and time display for users around the world. -- Storing datetimes in UTC for database portability and interoperability. - (This argument doesn't apply to PostgreSQL, because it already stores - timestamps with time zone information in Django 1.3.) -- Avoiding data corruption problems around DST transitions. - -Time zone support is enabled by default in new projects created with -:djadmin:`startproject`. If you want to use this feature in an existing -project, there is a :ref:`migration guide `. - -Two new date format strings -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Two new :tfilter:`date` formats were added for use in template filters, -template tags and :ref:`format-localization`: - -- ``e`` -- the name of the timezone of the given datetime object -- ``o`` -- the ISO 8601 year number - -Please make sure to update your :ref:`custom format files -` if they contain either ``e`` or ``o`` in a format -string. For example a Spanish localization format previously only escaped the -``d`` format character:: - - DATE_FORMAT = r'j \de F \de Y' - -But now it needs to also escape ``e`` and ``o``:: - - DATE_FORMAT = r'j \d\e F \d\e Y' - -For more information, see the :tfilter:`date` documentation. - -Minor features -~~~~~~~~~~~~~~ - -Django 1.4 also includes several smaller improvements worth noting: - -* A more usable stacktrace in the technical 500 page: frames in the - stack trace which reference Django's code are dimmed out, while - frames in user code are slightly emphasized. This change makes it - easier to scan a stacktrace for issues in user code. - -* :doc:`Tablespace support ` in PostgreSQL. - -* Customizable names for :meth:`~django.template.Library.simple_tag`. - -* In the documentation, a helpful :doc:`security overview ` - page. - -* The ``django.contrib.auth.models.check_password`` function has been moved - to the ``django.contrib.auth.utils`` module. Importing it from the old - location will still work, but you should update your imports. - -* The :djadmin:`collectstatic` management command gained a ``--clear`` option - to delete all files at the destination before copying or linking the static - files. - -* It is now possible to load fixtures containing forward references when using - MySQL with the InnoDB database engine. - -* A new 403 response handler has been added as - ``'django.views.defaults.permission_denied'``. You can set your own handler by - setting the value of :data:`django.conf.urls.handler403`. See the - documentation about :ref:`the 403 (HTTP Forbidden) view` - for more information. - -* The :ttag:`trans` template tag now takes an optional ``as`` argument to - be able to retrieve a translation string without displaying it but setting - a template context variable instead. - -* The :ttag:`if` template tag now supports ``{% elif %}`` clauses. - -* A new plain text version of the HTTP 500 status code internal error page - served when :setting:`DEBUG` is ``True`` is now sent to the client when - Django detects that the request has originated in JavaScript code - (:meth:`~django.http.HttpRequest.is_ajax` is used for this). - - Similarly to its HTML counterpart, it contains a collection of different - pieces of information about the state of the web application. - - This should make it easier to read when debugging interaction with - client-side Javascript code. - -* Added the :djadminopt:`--no-location` option to the :djadmin:`makemessages` - command. - -* Changed the ``locmem`` cache backend to use - ``pickle.HIGHEST_PROTOCOL`` for better compatibility with the other - cache backends. - -* Added support in the ORM for generating ``SELECT`` queries containing - ``DISTINCT ON``. - - The ``distinct()`` ``QuerySet`` method now accepts an optional list of model - field names. If specified, then the ``DISTINCT`` statement is limited to these - fields. This is only supported in PostgreSQL. - - For more details, see the documentation for - :meth:`~django.db.models.query.QuerySet.distinct`. - -* New phrases added to ``HIDDEN_SETTINGS`` regex in `django/views/debug.py`_. - - ``'API'``, ``'TOKEN'``, ``'KEY'`` were added, ``'PASSWORD'`` was changed to - ``'PASS'``. - -.. _django/views/debug.py: https://code.djangoproject.com/browser/django/trunk/django/views/debug.py - - -Backwards incompatible changes in 1.4 -===================================== - -django.contrib.admin -~~~~~~~~~~~~~~~~~~~~ - -The included administration app ``django.contrib.admin`` has for a long time -shipped with a default set of static files such as JavaScript, images and -stylesheets. Django 1.3 added a new contrib app ``django.contrib.staticfiles`` -to handle such files in a generic way and defined conventions for static -files included in apps. - -Starting in Django 1.4 the admin's static files also follow this -convention to make it easier to deploy the included files. In previous -versions of Django, it was also common to define an ``ADMIN_MEDIA_PREFIX`` -setting to point to the URL where the admin's static files are served by a -web server. This setting has now been deprecated and replaced by the more -general setting :setting:`STATIC_URL`. Django will now expect to find the -admin static files under the URL ``/admin/``. - -If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g. -``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT` -are configured and your web server serves the files correctly. The development -server continues to serve the admin files just like before. Don't hesitate to -consult the :doc:`static files howto ` for further -details. - -In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g. -``http://media.example.com/admin/``) make sure to also set your -:setting:`STATIC_URL` setting to the correct URL, for example -``http://media.example.com/``. - -.. warning:: - - If you're implicitly relying on the path of the admin static files on - your server's file system when you deploy your site, you have to update - that path. The files were moved from :file:`django/contrib/admin/media/` - to :file:`django/contrib/admin/static/admin/`. - -Supported browsers for the admin -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django hasn't had a clear policy on which browsers are supported for using the -admin app. Django's new policy formalizes existing practices: `YUI's A-grade`_ -browsers should provide a fully-functional admin experience, with the notable -exception of IE6, which is no longer supported. - -Released over ten years ago, IE6 imposes many limitations on modern web -development. The practical implications of this policy are that contributors -are free to improve the admin without consideration for these limitations. - -This new policy **has no impact** on development outside of the admin. Users of -Django are free to develop webapps compatible with any range of browsers. - -.. _YUI's A-grade: http://yuilibrary.com/yui/docs/tutorials/gbs/ - -Removed admin icons -~~~~~~~~~~~~~~~~~~~ - -As part of an effort to improve the performance and usability of the admin's -changelist sorting interface and of the admin's :attr:`horizontal -` and :attr:`vertical -` "filter" widgets, some icon -files were removed and grouped into two sprite files. - -Specifically: ``selector-add.gif``, ``selector-addall.gif``, -``selector-remove.gif``, ``selector-removeall.gif``, -``selector_stacked-add.gif`` and ``selector_stacked-remove.gif`` were -combined into ``selector-icons.gif``; and ``arrow-up.gif`` and -``arrow-down.gif`` were combined into ``sorting-icons.gif``. - -If you used those icons to customize the admin then you will want to replace -them with your own icons or retrieve them from a previous release. - -CSS class names in admin forms -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To avoid conflicts with other common CSS class names (e.g. "button"), a prefix -"field-" has been added to all CSS class names automatically generated from the -form field names in the main admin forms, stacked inline forms and tabular -inline cells. You will need to take that prefix into account in your custom -style sheets or javascript files if you previously used plain field names as -selectors for custom styles or javascript transformations. - -Compatibility with old signed data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.3 changed the cryptographic signing mechanisms used in a number of -places in Django. While Django 1.3 kept fallbacks that would accept hashes -produced by the previous methods, these fallbacks are removed in Django 1.4. - -So, if you upgrade to Django 1.4 directly from 1.2 or earlier, you may -lose/invalidate certain pieces of data that have been cryptographically signed -using an old method. To avoid this, use Django 1.3 first for a period of time -to allow the signed data to expire naturally. The affected parts are detailed -below, with 1) the consequences of ignoring this advice and 2) the amount of -time you need to run Django 1.3 for the data to expire or become irrelevant. - -* ``contrib.sessions`` data integrity check - - * consequences: the user will be logged out, and session data will be lost. - - * time period: defined by :setting:`SESSION_COOKIE_AGE`. - -* ``contrib.auth`` password reset hash - - * consequences: password reset links from before the upgrade will not work. - - * time period: defined by :setting:`PASSWORD_RESET_TIMEOUT_DAYS`. - -Form-related hashes — these are much shorter lifetime, and are relevant only for -the short window where a user might fill in a form generated by the pre-upgrade -Django instance, and try to submit it to the upgraded Django instance: - -* ``contrib.comments`` form security hash - - * consequences: the user will see a validation error "Security hash failed". - - * time period: the amount of time you expect users to take filling out comment - forms. - -* ``FormWizard`` security hash - - * consequences: the user will see an error about the form having expired, - and will be sent back to the first page of the wizard, losing the data - they have entered so far. - - * time period: the amount of time you expect users to take filling out the - affected forms. - -* CSRF check - - * Note: This is actually a Django 1.1 fallback, not Django 1.2, - and applies only if you are upgrading from 1.1. - - * consequences: the user will see a 403 error with any CSRF protected POST - form. - - * time period: the amount of time you expect user to take filling out - such forms. - -django.contrib.flatpages -~~~~~~~~~~~~~~~~~~~~~~~~ - -Starting in the 1.4 release the -:class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` only -adds a trailing slash and redirects if the resulting URL refers to an existing -flatpage. For example, requesting ``/notaflatpageoravalidurl`` in a previous -version would redirect to ``/notaflatpageoravalidurl/``, which would -subsequently raise a 404. Requesting ``/notaflatpageoravalidurl`` now will -immediately raise a 404. Additionally redirects returned by flatpages are now -permanent (301 status code) to match the behavior of the -:class:`~django.middleware.common.CommonMiddleware`. - -Serialization of :class:`~datetime.datetime` and :class:`~datetime.time` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As a consequence of time zone support, and according to the ECMA-262 -specification, some changes were made to the JSON serializer: - -- It includes the time zone for aware datetime objects. It raises an exception - for aware time objects. -- It includes milliseconds for datetime and time objects. There is still - some precision loss, because Python stores microseconds (6 digits) and JSON - only supports milliseconds (3 digits). However, it's better than discarding - microseconds entirely. - -The XML serializer was also changed to use the ISO8601 format for datetimes. -The letter ``T`` is used to separate the date part from the time part, instead -of a space. Time zone information is included in the ``[+-]HH:MM`` format. - -The serializers will dump datetimes in fixtures with these new formats. They -can still load fixtures that use the old format. - -``supports_timezone`` changed to ``False`` for SQLite -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The database feature ``supports_timezone`` used to be ``True`` for SQLite. -Indeed, if you saved an aware datetime object, SQLite stored a string that -included an UTC offset. However, this offset was ignored when loading the value -back from the database, which could corrupt the data. - -In the context of time zone support, this flag was changed to ``False``, and -datetimes are now stored without time zone information in SQLite. When -:setting:`USE_TZ` is ``False``, if you attempt to save an aware datetime -object, Django raises an exception. - -Database connection's thread-locality -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``DatabaseWrapper`` objects (i.e. the connection objects referenced by -``django.db.connection`` and ``django.db.connections["some_alias"]``) used to -be thread-local. They are now global objects in order to be potentially shared -between multiple threads. While the individual connection objects are now -global, the ``django.db.connections`` dictionary referencing those objects is -still thread-local. Therefore if you just use the ORM or -``DatabaseWrapper.cursor()`` then the behavior is still the same as before. -Note, however, that ``django.db.connection`` does not directly reference the -default ``DatabaseWrapper`` object anymore and is now a proxy to access that -object's attributes. If you need to access the actual ``DatabaseWrapper`` -object, use ``django.db.connections[DEFAULT_DB_ALIAS]`` instead. - -As part of this change, all underlying SQLite connections are now enabled for -potential thread-sharing (by passing the ``check_same_thread=False`` attribute -to pysqlite). ``DatabaseWrapper`` however preserves the previous behavior by -disabling thread-sharing by default, so this does not affect any existing -code that purely relies on the ORM or on ``DatabaseWrapper.cursor()``. - -Finally, while it is now possible to pass connections between threads, Django -does not make any effort to synchronize access to the underlying backend. -Concurrency behavior is defined by the underlying backend implementation. -Check their documentation for details. - -`COMMENTS_BANNED_USERS_GROUP` setting -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django's comments app has historically -supported excluding the comments of a special user group, but we've never -documented the feature properly and didn't enforce the exclusion in other parts -of the app such as the template tags. To fix this problem, we removed the code -from the feed class. - -If you rely on the feature and want to restore the old behavior, simply use -a custom comment model manager to exclude the user group, like this:: - - from django.conf import settings - from django.contrib.comments.managers import CommentManager - - class BanningCommentManager(CommentManager): - def get_query_set(self): - qs = super(BanningCommentManager, self).get_query_set() - if getattr(settings, 'COMMENTS_BANNED_USERS_GROUP', None): - where = ['user_id NOT IN (SELECT user_id FROM auth_user_groups WHERE group_id = %s)'] - params = [settings.COMMENTS_BANNED_USERS_GROUP] - qs = qs.extra(where=where, params=params) - return qs - -Save this model manager in your custom comment app (e.g. in -``my_comments_app/managers.py``) and add it your custom comment app model:: - - from django.db import models - from django.contrib.comments.models import Comment - - from my_comments_app.managers import BanningCommentManager - - class CommentWithTitle(Comment): - title = models.CharField(max_length=300) - - objects = BanningCommentManager() - -`IGNORABLE_404_STARTS` and `IGNORABLE_404_ENDS` settings -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Until Django 1.3, it was possible to exclude some URLs from Django's -:doc:`404 error reporting` by adding prefixes to -``IGNORABLE_404_STARTS`` and suffixes to ``IGNORABLE_404_ENDS``. - -In Django 1.4, these two settings are superseded by -:setting:`IGNORABLE_404_URLS`, which is a list of compiled regular -expressions. Django won't send an email for 404 errors on URLs that match any -of them. - -Furthermore, the previous settings had some rather arbitrary default values:: - - IGNORABLE_404_STARTS = ('/cgi-bin/', '/_vti_bin', '/_vti_inf') - IGNORABLE_404_ENDS = ('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', - 'favicon.ico', '.php') - -It's not Django's role to decide if your website has a legacy ``/cgi-bin/`` -section or a ``favicon.ico``. As a consequence, the default values of -:setting:`IGNORABLE_404_URLS`, ``IGNORABLE_404_STARTS``, and -``IGNORABLE_404_ENDS`` are all now empty. - -If you have customized ``IGNORABLE_404_STARTS`` or ``IGNORABLE_404_ENDS``, or -if you want to keep the old default value, you should add the following lines -in your settings file:: - - import re - IGNORABLE_404_URLS = ( - # for each in IGNORABLE_404_STARTS - re.compile(r'^'), - # for each in IGNORABLE_404_ENDS - re.compile(r'$'), - ) - -Don't forget to escape characters that have a special meaning in a regular -expression. - -CSRF protection extended to PUT and DELETE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Previously, Django's :doc:`CSRF protection ` provided -protection against only POST requests. Since use of PUT and DELETE methods in -AJAX applications is becoming more common, we now protect all methods not -defined as safe by :rfc:`2616` i.e. we exempt GET, HEAD, OPTIONS and TRACE, and -enforce protection on everything else. - -If you are using PUT or DELETE methods in AJAX applications, please see the -:ref:`instructions about using AJAX and CSRF `. - -``django.core.template_loaders`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This was an alias to ``django.template.loader`` since 2005, it has been removed -without emitting a warning due to the length of the deprecation. If your code -still referenced this please use ``django.template.loader`` instead. - -``django.db.models.fields.URLField.verify_exists`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This functionality has been removed due to intractable performance and -security issues. Any existing usage of ``verify_exists`` should be -removed. - -``django.core.files.storage.Storage.open`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``open`` method of the base Storage class took an obscure parameter -``mixin`` which allowed you to dynamically change the base classes of the -returned file object. This has been removed. In the rare case you relied on the -``mixin`` parameter, you can easily achieve the same by overriding the ``open`` -method, e.g.:: - - from django.core.files import File - from django.core.files.storage import FileSystemStorage - - class Spam(File): - """ - Spam, spam, spam, spam and spam. - """ - def ham(self): - return 'eggs' - - class SpamStorage(FileSystemStorage): - """ - A custom file storage backend. - """ - def open(self, name, mode='rb'): - return Spam(open(self.path(name), mode)) - -YAML deserializer now uses ``yaml.safe_load`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``yaml.load`` is able to construct any Python object, which may trigger -arbitrary code execution if you process a YAML document that comes from an -untrusted source. This feature isn't necessary for Django's YAML deserializer, -whose primary use is to load fixtures consisting of simple objects. Even though -fixtures are trusted data, for additional security, the YAML deserializer now -uses ``yaml.safe_load``. - -Features deprecated in 1.4 -========================== - -Old styles of calling ``cache_page`` decorator -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some legacy ways of calling :func:`~django.views.decorators.cache.cache_page` -have been deprecated, please see the docs for the correct way to use this -decorator. - -Support for PostgreSQL versions older than 8.2 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.3 dropped support for PostgreSQL versions older than 8.0 and the -relevant documents suggested to use a recent version because of performance -reasons but more importantly because end of the upstream support periods for -releases 8.0 and 8.1 was near (November 2010). - -Django 1.4 takes that policy further and sets 8.2 as the minimum PostgreSQL -version it officially supports. - -Request exceptions are now always logged -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When :doc:`logging support ` was added to Django in 1.3, the -admin error email support was moved into the -:class:`django.utils.log.AdminEmailHandler`, attached to the -``'django.request'`` logger. In order to maintain the established behavior of -error emails, the ``'django.request'`` logger was called only when -:setting:`DEBUG` was ``False``. - -To increase the flexibility of error logging for requests, the -``'django.request'`` logger is now called regardless of the value of -:setting:`DEBUG`, and the default settings file for new projects now includes a -separate filter attached to :class:`django.utils.log.AdminEmailHandler` to -prevent admin error emails in ``DEBUG`` mode:: - - 'filters': { - 'require_debug_false': { - '()': 'django.utils.log.RequireDebugFalse' - } - }, - 'handlers': { - 'mail_admins': { - 'level': 'ERROR', - 'filters': ['require_debug_false'], - 'class': 'django.utils.log.AdminEmailHandler' - } - }, - -If your project was created prior to this change, your :setting:`LOGGING` -setting will not include this new filter. In order to maintain -backwards-compatibility, Django will detect that your ``'mail_admins'`` handler -configuration includes no ``'filters'`` section, and will automatically add -this filter for you and issue a pending-deprecation warning. This will become a -deprecation warning in Django 1.5, and in Django 1.6 the -backwards-compatibility shim will be removed entirely. - -The existence of any ``'filters'`` key under the ``'mail_admins'`` handler will -disable this backward-compatibility shim and deprecation warning. - -``django.conf.urls.defaults`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Until Django 1.3 the functions :func:`~django.conf.urls.include`, -:func:`~django.conf.urls.patterns` and :func:`~django.conf.urls.url` plus -:data:`~django.conf.urls.handler404`, :data:`~django.conf.urls.handler500` -were located in a ``django.conf.urls.defaults`` module. - -Starting with Django 1.4 they are now available in :mod:`django.conf.urls`. - -``django.contrib.databrowse`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Databrowse has not seen active development for some time, and this does not show -any sign of changing. There had been a suggestion for a `GSOC project`_ to -integrate the functionality of databrowse into the admin, but no progress was -made. While Databrowse has been deprecated, an enhancement of -``django.contrib.admin`` providing a similar feature set is still possible. - -.. _GSOC project: https://code.djangoproject.com/wiki/SummerOfCode2011#Integratedatabrowseintotheadmin - -The code that powers Databrowse is licensed under the same terms as Django -itself, and so is available to be adopted by an individual or group as -a third-party project. - -``django.core.management.setup_environ`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This function temporarily modified ``sys.path`` in order to make the parent -"project" directory importable under the old flat :djadmin:`startproject` -layout. This function is now deprecated, as its path workarounds are no longer -needed with the new ``manage.py`` and default project layout. - -This function was never documented or part of the public API, but was widely -recommended for use in setting up a "Django environment" for a user script. -These uses should be replaced by setting the ``DJANGO_SETTINGS_MODULE`` -environment variable or using :func:`django.conf.settings.configure`. - -``django.core.management.execute_manager`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This function was previously used by ``manage.py`` to execute a management -command. It is identical to -``django.core.management.execute_from_command_line``, except that it first -calls ``setup_environ``, which is now deprecated. As such, ``execute_manager`` -is also deprecated; ``execute_from_command_line`` can be used instead. Neither -of these functions is documented as part of the public API, but a deprecation -path is needed due to use in existing ``manage.py`` files. - -``is_safe`` and ``needs_autoescape`` attributes of template filters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Two flags, ``is_safe`` and ``needs_autoescape``, define how each template filter -interacts with Django's auto-escaping behavior. They used to be attributes of -the filter function:: - - @register.filter - def noop(value): - return value - noop.is_safe = True - -However, this technique caused some problems in combination with decorators, -especially :func:`@stringfilter `. -Now, the flags are keyword arguments of :meth:`@register.filter -`:: - - @register.filter(is_safe=True) - def noop(value): - return value - -See :ref:`filters and auto-escaping ` for more information. - -Session cookies now have the ``httponly`` flag by default -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Session cookies now include the ``httponly`` attribute by default to -help reduce the impact of potential XSS attacks. As a consequence of -this change, session cookie data, including sessionid, is no longer -accessible from Javascript in many browsers. For strict backwards -compatibility, use ``SESSION_COOKIE_HTTPONLY = False`` in your -settings file. - -Wildcard expansion of application names in `INSTALLED_APPS` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Until Django 1.3, :setting:`INSTALLED_APPS` accepted wildcards in application -names, like ``django.contrib.*``. The expansion was performed by a -filesystem-based implementation of ``from import *``. Unfortunately, -`this can't be done reliably`_. - -This behavior was never documented. Since it is unpythonic and not obviously -useful, it was removed in Django 1.4. If you relied on it, you must edit your -settings file to list all your applications explicitly. - -.. _this can't be done reliably: http://docs.python.org/tutorial/modules.html#importing-from-a-package - -``HttpRequest.raw_post_data`` renamed to ``HttpRequest.body`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This attribute was confusingly named ``HttpRequest.raw_post_data``, but it -actually provided the body of the HTTP request. It's been renamed to -``HttpRequest.body``, and ``HttpRequest.raw_post_data`` has been deprecated. - - -The Django 1.4 roadmap -====================== - -Before the final Django 1.4 release, several other preview/development releases -will be made available. The current schedule consists of at least the following: - -* Week of **January 13, 2012**: First Django 1.4 beta release; final - feature freeze for Django 1.4. - -* Week of **February 27, 2012**: First Django 1.4 release - candidate; string freeze for translations. - -* Week of **March 5, 2012**: Django 1.4 final release. - -If necessary, additional alpha, beta or release-candidate packages -will be issued prior to the final 1.4 release. Django 1.4 will be -released approximately one week after the final release candidate. - -What you can do to help -======================= - -In order to provide a high-quality 1.4 release, we need your help. Although this -beta release is, again, *not* intended for production use, you can help the -Django team by trying out the beta codebase in a safe test environment and -reporting any bugs or issues you encounter. The Django ticket tracker is the -central place to search for open issues: - -* https://code.djangoproject.com/timeline - -Please open new tickets if no existing ticket corresponds to a problem you're -running into. - -Additionally, discussion of Django development, including progress toward the -1.4 release, takes place daily on the django-developers mailing list: - -* http://groups.google.com/group/django-developers - -... and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If you're -interested in helping out with Django's development, feel free to join the -discussions there. - -Django's online documentation also includes pointers on how to contribute to -Django: - -* :doc:`How to contribute to Django ` - -Contributions on any level -- developing code, writing documentation or simply -triaging tickets and helping to test proposed bugfixes -- are always welcome and -appreciated. - -Several development sprints will also be taking place before the 1.4 -release; these will typically be announced in advance on the -django-developers mailing list, and anyone who wants to help is -welcome to join in. diff --git a/docs/releases/1.5-alpha-1.txt b/docs/releases/1.5-alpha-1.txt deleted file mode 100644 index 06a0c2728d..0000000000 --- a/docs/releases/1.5-alpha-1.txt +++ /dev/null @@ -1,634 +0,0 @@ -============================== -Django 1.5 alpha release notes -============================== - -October 25, 2012. - -Welcome to Django 1.5 alpha! - -This is the first in a series of preview/development releases leading up to the -eventual release of Django 1.5, scheduled for December 2012. 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.5 release. - -As such, this release is *not* intended for production use, and any such use -is discouraged. - -In particular, we need the community's help to test Django 1.5's new `Python 3 -support`_ -- not just to report bugs on Python 3, but also regressions on Python -2. While Django is very conservative with regards to backwards compatibility, -mistakes are always possible, and it's likely that the Python 3 refactoring work -introduced some regressions. - -Django 1.5 alpha includes various `new features`_ and some minor `backwards -incompatible changes`_. There are also some features that have been dropped, -which are detailed in :doc:`our deprecation plan `, -and we've `begun the deprecation process for some features`_. - -.. _`new features`: `What's new in Django 1.5`_ -.. _`backwards incompatible changes`: `Backwards incompatible changes in 1.5`_ -.. _`begun the deprecation process for some features`: `Features deprecated in 1.5`_ - -Overview -======== - -The biggest new feature in Django 1.5 is the `configurable User model`_. Before -Django 1.5, applications that wanted to use Django's auth framework -(:mod:`django.contrib.auth`) were forced to use Django's definition of a "user". -In Django 1.5, you can now swap out the ``User`` model for one that you write -yourself. This could be a simple extension to the existing ``User`` model -- for -example, you could add a Twitter or Facebook ID field -- or you could completely -replace the ``User`` with one totally customized for your site. - -Django 1.5 is also the first release with `Python 3 support`_! We're labeling -this support "experimental" because we don't yet consider it production-ready, -but everything's in place for you to start porting your apps to Python 3. -Our next release, Django 1.6, will support Python 3 without reservations. - -Other notable new features in Django 1.5 include: - -* `Support for saving a subset of model's fields`_ - - :meth:`Model.save() ` now accepts an - ``update_fields`` argument, letting you specify which fields are - written back to the database when you call ``save()``. This can help - in high-concurrency operations, and can improve performance. - -* Better `support for streaming responses <#explicit-streaming-responses>`_ via - the new :class:`~django.http.StreamingHttpResponse` response class. - -* `GeoDjango`_ now supports PostGIS 2.0. - -* ... and more; `see below <#what-s-new-in-django-1-5>`_. - -Wherever possible we try to introduce new features in a backwards-compatible -manner per :doc:`our API stability policy ` policy. -However, as with previous releases, Django 1.5 ships with some minor -`backwards incompatible changes`_; people upgrading from previous versions -of Django should read that list carefully. - -One deprecated feature worth noting is the shift to "new-style" :ttag:`url` tag. -Prior to Django 1.3, syntax like ``{% url myview %}`` was interpreted -incorrectly (Django considered ``"myview"`` to be a literal name of a view, not -a template variable named ``myview``). Django 1.3 and above introduced the -``{% load url from future %}`` syntax to bring in the corrected behavior where -``myview`` was seen as a variable. - -The upshot of this is that if you are not using ``{% load url from future %}`` -in your templates, you'll need to change tags like ``{% url myview %}`` to -``{% url "myview" %}``. If you *were* using ``{% load url from future %}`` you -can simply remove that line under Django 1.5 - -Python compatibility -==================== - -Django 1.5 requires Python 2.6.5 or above, though we **highly recommended** -Python 2.7.3 or above. Support for Python 2.5 and below has been dropped. - -This change should affect only a small number of Django users, as most -operating-system vendors today are shipping Python 2.6 or newer as their default -version. If you're still using Python 2.5, however, you'll need to stick to -Django 1.4 until you can upgrade your Python version. Per :doc:`our support -policy `, Django 1.4 will continue to receive -security support until the release of Django 1.6. - -Django 1.5 does not run on a Jython final release, because Jython's latest -release doesn't currently support Python 2.6. However, Jython currently does -offer an alpha release featuring 2.7 support, and Django 1.5 supports that alpha -release. - -Python 3 support -~~~~~~~~~~~~~~~~ - -Django 1.5 introduces support for Python 3 - specifically, Python -3.2 and above. This comes in the form of a **single** codebase; you don't -need to install a different version of Django on Python 3. This means that -you can write application targeted for just Python 2, just Python 3, or single -applications that support both platforms. - -However, we're labeling this support "experimental" for now: although it's -received extensive testing via our automated test suite, it's received very -little real-world testing. We've done our best to eliminate bugs, but we can't -be sure we covered all possible uses of Django. Further, Django's more than a -web framework; it's an ecosystem of pluggable components. At this point, very -few third-party applications have been ported to Python 3, so it's unlikely -that a real-world application will have all its dependencies satisfied under -Python 3. - -Thus, we're recommending that Django 1.5 not be used in production under Python -3. Instead, use this opportunity to begin :doc:`porting applications to Python 3 -`. If you're an author of a pluggable component, we encourage you -to start porting now. - -We plan to offer first-class, production-ready support for Python 3 in our next -release, Django 1.6. - -What's new in Django 1.5 -======================== - -Configurable User model -~~~~~~~~~~~~~~~~~~~~~~~ - -In Django 1.5, you can now use your own model as the store for user-related -data. If your project needs a username with more than 30 characters, or if -you want to store usernames in a format other than first name/last name, or -you want to put custom profile information onto your User object, you can -now do so. - -If you have a third-party reusable application that references the User model, -you may need to make some changes to the way you reference User instances. You -should also document any specific features of the User model that your -application relies upon. - -See the :ref:`documentation on custom User models ` for -more details. - -Support for saving a subset of model's fields -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The method :meth:`Model.save() ` has a new -keyword argument ``update_fields``. By using this argument it is possible to -save only a select list of model's fields. This can be useful for performance -reasons or when trying to avoid overwriting concurrent changes. - -Deferred instances (those loaded by .only() or .defer()) will automatically -save just the loaded fields. If any field is set manually after load, that -field will also get updated on save. - -See the :meth:`Model.save() ` documentation for -more details. - -Caching of related model instances -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When traversing relations, the ORM will avoid re-fetching objects that were -previously loaded. For example, with the tutorial's models:: - - >>> first_poll = Poll.objects.all()[0] - >>> first_choice = first_poll.choice_set.all()[0] - >>> first_choice.poll is first_poll - True - -In Django 1.5, the third line no longer triggers a new SQL query to fetch -``first_choice.poll``; it was set by the second line. - -For one-to-one relationships, both sides can be cached. For many-to-one -relationships, only the single side of the relationship can be cached. This -is particularly helpful in combination with ``prefetch_related``. - -Explicit support for streaming responses -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before Django 1.5, it was possible to create a streaming response by passing -an iterator to :class:`~django.http.HttpResponse`. But this was unreliable: -any middleware that accessed the :attr:`~django.http.HttpResponse.content` -attribute would consume the iterator prematurely. - -You can now explicitly generate a streaming response with the new -:class:`~django.http.StreamingHttpResponse` class. This class exposes a -:class:`~django.http.StreamingHttpResponse.streaming_content` attribute which -is an iterator. - -Since :class:`~django.http.StreamingHttpResponse` does not have a ``content`` -attribute, middleware that needs access to the response content must test for -streaming responses and behave accordingly. See :ref:`response-middleware` for -more information. - -``{% verbatim %}`` template tag -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To make it easier to deal with javascript templates which collide with Django's -syntax, you can now use the :ttag:`verbatim` block tag to avoid parsing the -tag's content. - -Retrieval of ``ContentType`` instances associated with proxy models -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The methods :meth:`ContentTypeManager.get_for_model() ` -and :meth:`ContentTypeManager.get_for_models() ` -have a new keyword argument – respectively ``for_concrete_model`` and ``for_concrete_models``. -By passing ``False`` using this argument it is now possible to retrieve the -:class:`ContentType ` -associated with proxy models. - -New ``view`` variable in class-based views context -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In all :doc:`generic class-based views ` -(or any class-based view inheriting from ``ContextMixin``), the context dictionary -contains a ``view`` variable that points to the ``View`` instance. - -GeoDjango -~~~~~~~~~ - -* :class:`~django.contrib.gis.geos.LineString` and - :class:`~django.contrib.gis.geos.MultiLineString` GEOS objects now support the - :meth:`~django.contrib.gis.geos.GEOSGeometry.interpolate()` and - :meth:`~django.contrib.gis.geos.GEOSGeometry.project()` methods - (so-called linear referencing). - -* The ``wkb`` and ``hex`` properties of - :class:`~django.contrib.gis.geos.GEOSGeometry` objects preserve the Z - dimension. - -* Support for PostGIS 2.0 has been added and support for GDAL < 1.5 has been - dropped. - -Minor features -~~~~~~~~~~~~~~ - -Django 1.5 also includes several smaller improvements worth noting: - -* The template engine now interprets ``True``, ``False`` and ``None`` as the - corresponding Python objects. - -* :mod:`django.utils.timezone` provides a helper for converting aware - datetimes between time zones. See :func:`~django.utils.timezone.localtime`. - -* The generic views support OPTIONS requests. - -* Management commands do not raise ``SystemExit`` any more when called by code - from :ref:`call_command `. Any exception raised by the command - (mostly :ref:`CommandError `) is propagated. - -* The dumpdata management command outputs one row at a time, preventing - out-of-memory errors when dumping large datasets. - -* In the localflavor for Canada, "pq" was added to the acceptable codes for - Quebec. It's an old abbreviation. - -* The :ref:`receiver ` decorator is now able to - connect to more than one signal by supplying a list of signals. - -* In the admin, you can now filter users by groups which they are members of. - -* :meth:`QuerySet.bulk_create() - ` now has a batch_size - argument. By default the batch_size is unlimited except for SQLite where - single batch is limited so that 999 parameters per query isn't exceeded. - -* The :setting:`LOGIN_URL` and :setting:`LOGIN_REDIRECT_URL` settings now also - accept view function names and - :ref:`named URL patterns `. This allows you to reduce - configuration duplication. More information can be found in the - :func:`~django.contrib.auth.decorators.login_required` documentation. - -* Django now provides a mod_wsgi :doc:`auth handler - `. - -* The :meth:`QuerySet.delete() ` - and :meth:`Model.delete() ` can now take - fast-path in some cases. The fast-path allows for less queries and less - objects fetched into memory. See :meth:`QuerySet.delete() - ` for details. - -* An instance of :class:`~django.core.urlresolvers.ResolverMatch` is stored on - the request as ``resolver_match``. - -* By default, all logging messages reaching the ``django`` logger when - :setting:`DEBUG` is ``True`` are sent to the console (unless you redefine the - logger in your :setting:`LOGGING` setting). - -* When using :class:`~django.template.RequestContext`, it is now possible to - look up permissions by using ``{% if 'someapp.someperm' in perms %}`` - in templates. - -* It's not required any more to have ``404.html`` and ``500.html`` templates in - the root templates directory. Django will output some basic error messages for - both situations when those templates are not found. Of course, it's still - recommended as good practice to provide those templates in order to present - pretty error pages to the user. - -* :mod:`django.contrib.auth` provides a new signal that is emitted - whenever a user fails to login successfully. See - :data:`~django.contrib.auth.signals.user_login_failed` - -* The loaddata management command now supports an - :djadminopt:`--ignorenonexistent` option to ignore data for fields that no - longer exist. - -* :meth:`~django.test.SimpleTestCase.assertXMLEqual` and - :meth:`~django.test.SimpleTestCase.assertXMLNotEqual` new assertions allow - you to test equality for XML content at a semantic level, without caring for - syntax differences (spaces, attribute order, etc.). - -Backwards incompatible changes in 1.5 -===================================== - -.. warning:: - - In addition to the changes outlined in this section, be sure to review the - :doc:`deprecation plan ` for any features that - have been removed. If you haven't updated your code within the - deprecation timeline for a given feature, its removal may appear as a - backwards incompatible change. - -Context in year archive class-based views -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For consistency with the other date-based generic views, -:class:`~django.views.generic.dates.YearArchiveView` now passes ``year`` in -the context as a :class:`datetime.date` rather than a string. If you are -using ``{{ year }}`` in your templates, you must replace it with ``{{ -year|date:"Y" }}``. - -``next_year`` and ``previous_year`` were also added in the context. They are -calculated according to ``allow_empty`` and ``allow_future``. - -Context in year and month archive class-based views -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:class:`~django.views.generic.dates.YearArchiveView` and -:class:`~django.views.generic.dates.MonthArchiveView` were documented to -provide a ``date_list`` sorted in ascending order in the context, like their -function-based predecessors, but it actually was in descending order. In 1.5, -the documented order was restored. You may want to add (or remove) the -``reversed`` keyword when you're iterating on ``date_list`` in a template:: - - {% for date in date_list reversed %} - -:class:`~django.views.generic.dates.ArchiveIndexView` still provides a -``date_list`` in descending order. - -Context in TemplateView -~~~~~~~~~~~~~~~~~~~~~~~ - -For consistency with the design of the other generic views, -:class:`~django.views.generic.base.TemplateView` no longer passes a ``params`` -dictionary into the context, instead passing the variables from the URLconf -directly into the context. - -Non-form data in HTTP requests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:attr:`request.POST ` will no longer include data -posted via HTTP requests with non form-specific content-types in the header. -In prior versions, data posted with content-types other than -``multipart/form-data`` or ``application/x-www-form-urlencoded`` would still -end up represented in the :attr:`request.POST ` -attribute. Developers wishing to access the raw POST data for these cases, -should use the :attr:`request.body ` attribute -instead. - -OPTIONS, PUT and DELETE requests in the test client -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Unlike GET and POST, these HTTP methods aren't implemented by web browsers. -Rather, they're used in APIs, which transfer data in various formats such as -JSON or XML. Since such requests may contain arbitrary data, Django doesn't -attempt to decode their body. - -However, the test client used to build a query string for OPTIONS and DELETE -requests like for GET, and a request body for PUT requests like for POST. This -encoding was arbitrary and inconsistent with Django's behavior when it -receives the requests, so it was removed in Django 1.5. - -If you were using the ``data`` parameter in an OPTIONS or a DELETE request, -you must convert it to a query string and append it to the ``path`` parameter. - -If you were using the ``data`` parameter in a PUT request without a -``content_type``, you must encode your data before passing it to the test -client and set the ``content_type`` argument. - -System version of :mod:`simplejson` no longer used -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As explained below, Django 1.5 deprecates -``django.utils.simplejson`` in favor of Python 2.6's built-in :mod:`json` -module. In theory, this change is harmless. Unfortunately, because of -incompatibilities between versions of :mod:`simplejson`, it may trigger errors -in some circumstances. - -JSON-related features in Django 1.4 always used ``django.utils.simplejson``. -This module was actually: - -- A system version of :mod:`simplejson`, if one was available (ie. ``import - simplejson`` works), if it was more recent than Django's built-in copy or it - had the C speedups, or -- The :mod:`json` module from the standard library, if it was available (ie. - Python 2.6 or greater), or -- A built-in copy of version 2.0.7 of :mod:`simplejson`. - -In Django 1.5, those features use Python's :mod:`json` module, which is based -on version 2.0.9 of :mod:`simplejson`. - -There are no known incompatibilities between Django's copy of version 2.0.7 and -Python's copy of version 2.0.9. However, there are some incompatibilities -between other versions of :mod:`simplejson`: - -- While the :mod:`simplejson` API is documented as always returning unicode - strings, the optional C implementation can return a byte string. This was - fixed in Python 2.7. -- :class:`simplejson.JSONEncoder` gained a ``namedtuple_as_object`` keyword - argument in version 2.2. - -More information on these incompatibilities is available in `ticket #18023`_. - -The net result is that, if you have installed :mod:`simplejson` and your code -uses Django's serialization internals directly -- for instance -``django.core.serializers.json.DjangoJSONEncoder``, the switch from -:mod:`simplejson` to :mod:`json` could break your code. (In general, changes to -internals aren't documented; we're making an exception here.) - -At this point, the maintainers of Django believe that using :mod:`json` from -the standard library offers the strongest guarantee of backwards-compatibility. -They recommend to use it from now on. - -.. _ticket #18023: https://code.djangoproject.com/ticket/18023#comment:10 - -String types of hasher method parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you have written a :ref:`custom password hasher `, -your ``encode()``, ``verify()`` or ``safe_summary()`` methods should accept -Unicode parameters (``password``, ``salt`` or ``encoded``). If any of the -hashing methods need byte strings, you can use the -:func:`~django.utils.encoding.force_bytes` utility to encode the strings. - -Validation of previous_page_number and next_page_number -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When using :doc:`object pagination `, -the ``previous_page_number()`` and ``next_page_number()`` methods of the -:class:`~django.core.paginator.Page` object did not check if the returned -number was inside the existing page range. -It does check it now and raises an :exc:`~django.core.paginator.InvalidPage` -exception when the number is either too low or too high. - -Behavior of autocommit database option on PostgreSQL changed -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -PostgreSQL's autocommit option didn't work as advertised previously. It did -work for single transaction block, but after the first block was left the -autocommit behavior was never restored. This bug is now fixed in 1.5. While -this is only a bug fix, it is worth checking your applications behavior if -you are using PostgreSQL together with the autocommit option. - -Session not saved on 500 responses -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django's session middleware will skip saving the session data if the -response's status code is 500. - -Email checks on failed admin login -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Prior to Django 1.5, if you attempted to log into the admin interface and -mistakenly used your email address instead of your username, the admin -interface would provide a warning advising that your email address was -not your username. In Django 1.5, the introduction of -:ref:`custom User models ` has required the removal of this -warning. This doesn't change the login behavior of the admin site; it only -affects the warning message that is displayed under one particular mode of -login failure. - -Changes in tests execution -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some changes have been introduced in the execution of tests that might be -backward-incompatible for some testing setups: - -Database flushing in ``django.test.TransactionTestCase`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Previously, the test database was truncated *before* each test run in a -:class:`~django.test.TransactionTestCase`. - -In order to be able to run unit tests in any order and to make sure they are -always isolated from each other, :class:`~django.test.TransactionTestCase` will -now reset the database *after* each test run instead. - -No more implicit DB sequences reset -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:class:`~django.test.TransactionTestCase` tests used to reset primary key -sequences automatically together with the database flushing actions described -above. - -This has been changed so no sequences are implicitly reset. This can cause -:class:`~django.test.TransactionTestCase` tests that depend on hard-coded -primary key values to break. - -The new :attr:`~django.test.TransactionTestCase.reset_sequences` attribute can -be used to force the old behavior for :class:`~django.test.TransactionTestCase` -that might need it. - -Ordering of tests -^^^^^^^^^^^^^^^^^ - -In order to make sure all ``TestCase`` code starts with a clean database, -tests are now executed in the following order: - -* First, all unittests (including :class:`unittest.TestCase`, - :class:`~django.test.SimpleTestCase`, :class:`~django.test.TestCase` and - :class:`~django.test.TransactionTestCase`) are run with no particular ordering - guaranteed nor enforced among them. - -* Then any other tests (e.g. doctests) that may alter the database without - restoring it to its original state are run. - -This should not cause any problems unless you have existing doctests which -assume a :class:`~django.test.TransactionTestCase` executed earlier left some -database state behind or unit tests that rely on some form of state being -preserved after the execution of other tests. Such tests are already very -fragile, and must now be changed to be able to run independently. - -`cleaned_data` dictionary kept for invalid forms -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :attr:`~django.forms.Form.cleaned_data` dictionary is now always present -after form validation. When the form doesn't validate, it contains only the -fields that passed validation. You should test the success of the validation -with the :meth:`~django.forms.Form.is_valid()` method and not with the -presence or absence of the :attr:`~django.forms.Form.cleaned_data` attribute -on the form. - -Miscellaneous -~~~~~~~~~~~~~ - -* :class:`django.forms.ModelMultipleChoiceField` now returns an empty - ``QuerySet`` as the empty value instead of an empty list. - -* :func:`~django.utils.http.int_to_base36` properly raises a - :exc:`TypeError` instead of :exc:`ValueError` for non-integer inputs. - -* The ``slugify`` template filter is now available as a standard python - function at :func:`django.utils.text.slugify`. Similarly, ``remove_tags`` is - available at :func:`django.utils.html.remove_tags`. - -* Uploaded files are no longer created as executable by default. If you need - them to be executable change :setting:`FILE_UPLOAD_PERMISSIONS` to your - needs. The new default value is ``0o666`` (octal) and the current umask value - is first masked out. - -* The :class:`F expressions ` supported bitwise operators - by ``&`` and ``|``. These operators are now available using ``.bitand()`` and - ``.bitor()`` instead. The removal of ``&`` and ``|`` was done to be - consistent with :ref:`Q() expressions ` and - ``QuerySet`` combining where the operators are used as boolean AND and OR - operators. - -* The :ttag:`csrf_token` template tag is no longer enclosed in a div. If you need - HTML validation against pre-HTML5 Strict DTDs, you should add a div around it - in your pages. - -Features deprecated in 1.5 -========================== - -``AUTH_PROFILE_MODULE`` setting -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -With the introduction of :ref:`custom User models `, there is -no longer any need for a built-in mechanism to store user profile data. - -You can still define user profiles models that have a one-to-one relation with -the User model - in fact, for many applications needing to associate data with -a User account, this will be an appropriate design pattern to follow. However, -the ``AUTH_PROFILE_MODULE`` setting, and the -``django.contrib.auth.models.User.get_profile()`` method for accessing -the user profile model, should not be used any longer. - -Streaming behavior of :class:`~django.http.HttpResponse` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.5 deprecates the ability to stream a response by passing an iterator -to :class:`~django.http.HttpResponse`. If you rely on this behavior, switch to -:class:`~django.http.StreamingHttpResponse`. See above for more details. - -In Django 1.7 and above, the iterator will be consumed immediately by -:class:`~django.http.HttpResponse`. - -``django.utils.simplejson`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Since Django 1.5 drops support for Python 2.5, we can now rely on the -:mod:`json` module being available in Python's standard library, so we've -removed our own copy of :mod:`simplejson`. You should now import :mod:`json` -instead of ``django.utils.simplejson``. - -Unfortunately, this change might have unwanted side-effects, because of -incompatibilities between versions of :mod:`simplejson` -- see the backwards- -incompatible changes section. If you rely on features added to :mod:`simplejson` -after it became Python's :mod:`json`, you should import :mod:`simplejson` -explicitly. - -``django.utils.encoding.StrAndUnicode`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``django.utils.encoding.StrAndUnicode`` mix-in has been deprecated. -Define a ``__str__`` method and apply the -:func:`~django.utils.encoding.python_2_unicode_compatible` decorator instead. - -``django.utils.itercompat.product`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``django.utils.itercompat.product`` function has been deprecated. Use -the built-in :func:`itertools.product` instead. - -``django.utils.markup`` -~~~~~~~~~~~~~~~~~~~~~~~ - -The markup contrib module has been deprecated and will follow an accelerated -deprecation schedule. Direct use of python markup libraries or 3rd party tag -libraries is preferred to Django maintaining this functionality in the -framework. diff --git a/docs/releases/1.5-beta-1.txt b/docs/releases/1.5-beta-1.txt deleted file mode 100644 index 74f564c360..0000000000 --- a/docs/releases/1.5-beta-1.txt +++ /dev/null @@ -1,706 +0,0 @@ -============================= -Django 1.5 beta release notes -============================= - -November 27, 2012. - -Welcome to Django 1.5 beta! - -This is the second in a series of preview/development releases leading -up to the eventual release of Django 1.5, scheduled for December -2012. 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.5 release. - -As such, this release is *not* intended for production use, and any such use -is discouraged. - -These release notes cover the `new features`_, as well -as some `backwards incompatible changes`_ you'll want to be aware of -when upgrading from Django 1.4 or older versions. We've also dropped some -features, which are detailed in :doc:`our deprecation plan -`, and we've `begun the deprecation process for some -features`_. - -.. _`new features`: `What's new in Django 1.5`_ -.. _`backwards incompatible changes`: `Backwards incompatible changes in 1.5`_ -.. _`begun the deprecation process for some features`: `Features deprecated in 1.5`_ - -Overview -======== - -The biggest new feature in Django 1.5 is the `configurable User model`_. Before -Django 1.5, applications that wanted to use Django's auth framework -(:mod:`django.contrib.auth`) were forced to use Django's definition of a "user". -In Django 1.5, you can now swap out the ``User`` model for one that you write -yourself. This could be a simple extension to the existing ``User`` model -- for -example, you could add a Twitter or Facebook ID field -- or you could completely -replace the ``User`` with one totally customized for your site. - -Django 1.5 is also the first release with `Python 3 support`_! We're labeling -this support "experimental" because we don't yet consider it production-ready, -but everything's in place for you to start porting your apps to Python 3. -Our next release, Django 1.6, will support Python 3 without reservations. - -Other notable new features in Django 1.5 include: - -* `Support for saving a subset of model's fields`_ - - :meth:`Model.save() ` now accepts an - ``update_fields`` argument, letting you specify which fields are - written back to the database when you call ``save()``. This can help - in high-concurrency operations, and can improve performance. - -* Better `support for streaming responses <#explicit-streaming-responses-beta-1>`_ via - the new :class:`~django.http.StreamingHttpResponse` response class. - -* `GeoDjango`_ now supports PostGIS 2.0. - -* ... and more; `see below <#what-s-new-in-django-1-5>`_. - -Wherever possible we try to introduce new features in a backwards-compatible -manner per :doc:`our API stability policy `. -However, as with previous releases, Django 1.5 ships with some minor -`backwards incompatible changes`_; people upgrading from previous versions -of Django should read that list carefully. - -One deprecated feature worth noting is the shift to "new-style" :ttag:`url` tag. -Prior to Django 1.3, syntax like ``{% url myview %}`` was interpreted -incorrectly (Django considered ``"myview"`` to be a literal name of a view, not -a template variable named ``myview``). Django 1.3 and above introduced the -``{% load url from future %}`` syntax to bring in the corrected behavior where -``myview`` was seen as a variable. - -The upshot of this is that if you are not using ``{% load url from future %}`` -in your templates, you'll need to change tags like ``{% url myview %}`` to -``{% url "myview" %}``. If you *were* using ``{% load url from future %}`` you -can simply remove that line under Django 1.5 - -Python compatibility -==================== - -Django 1.5 requires Python 2.6.5 or above, though we **highly recommend** -Python 2.7.3 or above. Support for Python 2.5 and below has been dropped. - -This change should affect only a small number of Django users, as most -operating-system vendors today are shipping Python 2.6 or newer as their default -version. If you're still using Python 2.5, however, you'll need to stick to -Django 1.4 until you can upgrade your Python version. Per :doc:`our support -policy `, Django 1.4 will continue to receive -security support until the release of Django 1.6. - -Django 1.5 does not run on a Jython final release, because Jython's latest -release doesn't currently support Python 2.6. However, Jython currently does -offer an alpha release featuring 2.7 support, and Django 1.5 supports that alpha -release. - -Python 3 support -~~~~~~~~~~~~~~~~ - -Django 1.5 introduces support for Python 3 - specifically, Python -3.2 and above. This comes in the form of a **single** codebase; you don't -need to install a different version of Django on Python 3. This means that -you can write applications targeted for just Python 2, just Python 3, or single -applications that support both platforms. - -However, we're labeling this support "experimental" for now: although it's -received extensive testing via our automated test suite, it's received very -little real-world testing. We've done our best to eliminate bugs, but we can't -be sure we covered all possible uses of Django. Further, Django's more than a -web framework; it's an ecosystem of pluggable components. At this point, very -few third-party applications have been ported to Python 3, so it's unlikely -that a real-world application will have all its dependencies satisfied under -Python 3. - -Thus, we're recommending that Django 1.5 not be used in production under Python -3. Instead, use this opportunity to begin :doc:`porting applications to Python 3 -`. If you're an author of a pluggable component, we encourage you -to start porting now. - -We plan to offer first-class, production-ready support for Python 3 in our next -release, Django 1.6. - -What's new in Django 1.5 -======================== - -Configurable User model -~~~~~~~~~~~~~~~~~~~~~~~ - -In Django 1.5, you can now use your own model as the store for user-related -data. If your project needs a username with more than 30 characters, or if -you want to store user's names in a format other than first name/last name, -or you want to put custom profile information onto your User object, you can -now do so. - -If you have a third-party reusable application that references the User model, -you may need to make some changes to the way you reference User instances. You -should also document any specific features of the User model that your -application relies upon. - -See the :ref:`documentation on custom User models ` for -more details. - -Support for saving a subset of model's fields -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The method :meth:`Model.save() ` has a new -keyword argument ``update_fields``. By using this argument it is possible to -save only a select list of model's fields. This can be useful for performance -reasons or when trying to avoid overwriting concurrent changes. - -Deferred instances (those loaded by .only() or .defer()) will automatically -save just the loaded fields. If any field is set manually after load, that -field will also get updated on save. - -See the :meth:`Model.save() ` documentation for -more details. - -Caching of related model instances -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When traversing relations, the ORM will avoid re-fetching objects that were -previously loaded. For example, with the tutorial's models:: - - >>> first_poll = Poll.objects.all()[0] - >>> first_choice = first_poll.choice_set.all()[0] - >>> first_choice.poll is first_poll - True - -In Django 1.5, the third line no longer triggers a new SQL query to fetch -``first_choice.poll``; it was set by the second line. - -For one-to-one relationships, both sides can be cached. For many-to-one -relationships, only the single side of the relationship can be cached. This -is particularly helpful in combination with ``prefetch_related``. - -.. _explicit-streaming-responses-beta-1: - -Explicit support for streaming responses -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before Django 1.5, it was possible to create a streaming response by passing -an iterator to :class:`~django.http.HttpResponse`. But this was unreliable: -any middleware that accessed the :attr:`~django.http.HttpResponse.content` -attribute would consume the iterator prematurely. - -You can now explicitly generate a streaming response with the new -:class:`~django.http.StreamingHttpResponse` class. This class exposes a -:class:`~django.http.StreamingHttpResponse.streaming_content` attribute which -is an iterator. - -Since :class:`~django.http.StreamingHttpResponse` does not have a ``content`` -attribute, middleware that needs access to the response content must test for -streaming responses and behave accordingly. See :ref:`response-middleware` for -more information. - -``{% verbatim %}`` template tag -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To make it easier to deal with javascript templates which collide with Django's -syntax, you can now use the :ttag:`verbatim` block tag to avoid parsing the -tag's content. - -Retrieval of ``ContentType`` instances associated with proxy models -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The methods :meth:`ContentTypeManager.get_for_model() ` -and :meth:`ContentTypeManager.get_for_models() ` -have a new keyword argument – respectively ``for_concrete_model`` and ``for_concrete_models``. -By passing ``False`` using this argument it is now possible to retrieve the -:class:`ContentType ` -associated with proxy models. - -New ``view`` variable in class-based views context -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In all :doc:`generic class-based views ` -(or any class-based view inheriting from ``ContextMixin``), the context dictionary -contains a ``view`` variable that points to the ``View`` instance. - -GeoDjango -~~~~~~~~~ - -* :class:`~django.contrib.gis.geos.LineString` and - :class:`~django.contrib.gis.geos.MultiLineString` GEOS objects now support the - :meth:`~django.contrib.gis.geos.GEOSGeometry.interpolate()` and - :meth:`~django.contrib.gis.geos.GEOSGeometry.project()` methods - (so-called linear referencing). - -* The ``wkb`` and ``hex`` properties of - :class:`~django.contrib.gis.geos.GEOSGeometry` objects preserve the Z - dimension. - -* Support for PostGIS 2.0 has been added and support for GDAL < 1.5 has been - dropped. - -Minor features -~~~~~~~~~~~~~~ - -Django 1.5 also includes several smaller improvements worth noting: - -* The template engine now interprets ``True``, ``False`` and ``None`` as the - corresponding Python objects. - -* :mod:`django.utils.timezone` provides a helper for converting aware - datetimes between time zones. See :func:`~django.utils.timezone.localtime`. - -* The generic views support OPTIONS requests. - -* Management commands do not raise ``SystemExit`` any more when called by code - from :ref:`call_command `. Any exception raised by the command - (mostly :ref:`CommandError `) is propagated. - -* The dumpdata management command outputs one row at a time, preventing - out-of-memory errors when dumping large datasets. - -* In the localflavor for Canada, "pq" was added to the acceptable codes for - Quebec. It's an old abbreviation. - -* The :ref:`receiver ` decorator is now able to - connect to more than one signal by supplying a list of signals. - -* In the admin, you can now filter users by groups which they are members of. - -* :meth:`QuerySet.bulk_create() - ` now has a batch_size - argument. By default the batch_size is unlimited except for SQLite where - single batch is limited so that 999 parameters per query isn't exceeded. - -* The :setting:`LOGIN_URL` and :setting:`LOGIN_REDIRECT_URL` settings now also - accept view function names and - :ref:`named URL patterns `. This allows you to reduce - configuration duplication. More information can be found in the - :func:`~django.contrib.auth.decorators.login_required` documentation. - -* Django now provides a mod_wsgi :doc:`auth handler - `. - -* The :meth:`QuerySet.delete() ` - and :meth:`Model.delete() ` can now take - fast-path in some cases. The fast-path allows for less queries and less - objects fetched into memory. See :meth:`QuerySet.delete() - ` for details. - -* An instance of :class:`~django.core.urlresolvers.ResolverMatch` is stored on - the request as ``resolver_match``. - -* By default, all logging messages reaching the ``django`` logger when - :setting:`DEBUG` is ``True`` are sent to the console (unless you redefine the - logger in your :setting:`LOGGING` setting). - -* When using :class:`~django.template.RequestContext`, it is now possible to - look up permissions by using ``{% if 'someapp.someperm' in perms %}`` - in templates. - -* It's not required any more to have ``404.html`` and ``500.html`` templates in - the root templates directory. Django will output some basic error messages for - both situations when those templates are not found. Of course, it's still - recommended as good practice to provide those templates in order to present - pretty error pages to the user. - -* :mod:`django.contrib.auth` provides a new signal that is emitted - whenever a user fails to login successfully. See - :data:`~django.contrib.auth.signals.user_login_failed` - -* The loaddata management command now supports an - :djadminopt:`--ignorenonexistent` option to ignore data for fields that no - longer exist. - -* :meth:`~django.test.SimpleTestCase.assertXMLEqual` and - :meth:`~django.test.SimpleTestCase.assertXMLNotEqual` new assertions allow - you to test equality for XML content at a semantic level, without caring for - syntax differences (spaces, attribute order, etc.). - -* RemoteUserMiddleware now forces logout when the REMOTE_USER header - disappears during the same browser session. - -* The :ref:`cache-based session backend ` can store - session data in a non-default cache. - -* Multi-column indexes can now be created on models. Read the - :attr:`~django.db.models.Options.index_together` documentation for more - information. - -* During Django's logging configuration verbose Deprecation warnings are - enabled and warnings are captured into the logging system. Logged warnings - are routed through the ``console`` logging handler, which by default requires - :setting:`DEBUG` to be True for output to be generated. The result is that - DeprecationWarnings should be printed to the console in development - environments the way they have been in Python versions < 2.7. - -* The API for :meth:`django.contrib.admin.ModelAdmin.message_user` method has - been modified to accept additional arguments adding capabilities similar to - :func:`django.contrib.messages.add_message`. This is useful for generating - error messages from admin actions. - -* The admin's list filters can now be customized per-request thanks to the new - :meth:`django.contrib.admin.ModelAdmin.get_list_filter` method. - -Backwards incompatible changes in 1.5 -===================================== - -.. warning:: - - In addition to the changes outlined in this section, be sure to review the - :doc:`deprecation plan ` for any features that - have been removed. If you haven't updated your code within the - deprecation timeline for a given feature, its removal may appear as a - backwards incompatible change. - -Context in year archive class-based views -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For consistency with the other date-based generic views, -:class:`~django.views.generic.dates.YearArchiveView` now passes ``year`` in -the context as a :class:`datetime.date` rather than a string. If you are -using ``{{ year }}`` in your templates, you must replace it with ``{{ -year|date:"Y" }}``. - -``next_year`` and ``previous_year`` were also added in the context. They are -calculated according to ``allow_empty`` and ``allow_future``. - -Context in year and month archive class-based views -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:class:`~django.views.generic.dates.YearArchiveView` and -:class:`~django.views.generic.dates.MonthArchiveView` were documented to -provide a ``date_list`` sorted in ascending order in the context, like their -function-based predecessors, but it actually was in descending order. In 1.5, -the documented order was restored. You may want to add (or remove) the -``reversed`` keyword when you're iterating on ``date_list`` in a template:: - - {% for date in date_list reversed %} - -:class:`~django.views.generic.dates.ArchiveIndexView` still provides a -``date_list`` in descending order. - -Context in TemplateView -~~~~~~~~~~~~~~~~~~~~~~~ - -For consistency with the design of the other generic views, -:class:`~django.views.generic.base.TemplateView` no longer passes a ``params`` -dictionary into the context, instead passing the variables from the URLconf -directly into the context. - -Non-form data in HTTP requests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:attr:`request.POST ` will no longer include data -posted via HTTP requests with non form-specific content-types in the header. -In prior versions, data posted with content-types other than -``multipart/form-data`` or ``application/x-www-form-urlencoded`` would still -end up represented in the :attr:`request.POST ` -attribute. Developers wishing to access the raw POST data for these cases, -should use the :attr:`request.body ` attribute -instead. - -OPTIONS, PUT and DELETE requests in the test client -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Unlike GET and POST, these HTTP methods aren't implemented by web browsers. -Rather, they're used in APIs, which transfer data in various formats such as -JSON or XML. Since such requests may contain arbitrary data, Django doesn't -attempt to decode their body. - -However, the test client used to build a query string for OPTIONS and DELETE -requests like for GET, and a request body for PUT requests like for POST. This -encoding was arbitrary and inconsistent with Django's behavior when it -receives the requests, so it was removed in Django 1.5. - -If you were using the ``data`` parameter in an OPTIONS or a DELETE request, -you must convert it to a query string and append it to the ``path`` parameter. - -If you were using the ``data`` parameter in a PUT request without a -``content_type``, you must encode your data before passing it to the test -client and set the ``content_type`` argument. - -.. _simplejson-incompatibilities-beta-1: - -System version of :mod:`simplejson` no longer used -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:ref:`As explained below `, Django 1.5 deprecates -``django.utils.simplejson`` in favor of Python 2.6's built-in :mod:`json` -module. In theory, this change is harmless. Unfortunately, because of -incompatibilities between versions of :mod:`simplejson`, it may trigger errors -in some circumstances. - -JSON-related features in Django 1.4 always used ``django.utils.simplejson``. -This module was actually: - -- A system version of :mod:`simplejson`, if one was available (ie. ``import - simplejson`` works), if it was more recent than Django's built-in copy or it - had the C speedups, or -- The :mod:`json` module from the standard library, if it was available (ie. - Python 2.6 or greater), or -- A built-in copy of version 2.0.7 of :mod:`simplejson`. - -In Django 1.5, those features use Python's :mod:`json` module, which is based -on version 2.0.9 of :mod:`simplejson`. - -There are no known incompatibilities between Django's copy of version 2.0.7 and -Python's copy of version 2.0.9. However, there are some incompatibilities -between other versions of :mod:`simplejson`: - -- While the :mod:`simplejson` API is documented as always returning unicode - strings, the optional C implementation can return a byte string. This was - fixed in Python 2.7. -- :class:`simplejson.JSONEncoder` gained a ``namedtuple_as_object`` keyword - argument in version 2.2. - -More information on these incompatibilities is available in `ticket #18023`_. - -The net result is that, if you have installed :mod:`simplejson` and your code -uses Django's serialization internals directly -- for instance -``django.core.serializers.json.DjangoJSONEncoder``, the switch from -:mod:`simplejson` to :mod:`json` could break your code. (In general, changes to -internals aren't documented; we're making an exception here.) - -At this point, the maintainers of Django believe that using :mod:`json` from -the standard library offers the strongest guarantee of backwards-compatibility. -They recommend to use it from now on. - -.. _ticket #18023: https://code.djangoproject.com/ticket/18023#comment:10 - -String types of hasher method parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you have written a :ref:`custom password hasher `, -your ``encode()``, ``verify()`` or ``safe_summary()`` methods should accept -Unicode parameters (``password``, ``salt`` or ``encoded``). If any of the -hashing methods need byte strings, you can use the -:func:`~django.utils.encoding.force_bytes` utility to encode the strings. - -Validation of previous_page_number and next_page_number -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When using :doc:`object pagination `, -the ``previous_page_number()`` and ``next_page_number()`` methods of the -:class:`~django.core.paginator.Page` object did not check if the returned -number was inside the existing page range. -It does check it now and raises an :exc:`~django.core.paginator.InvalidPage` -exception when the number is either too low or too high. - -Behavior of autocommit database option on PostgreSQL changed -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -PostgreSQL's autocommit option didn't work as advertised previously. It did -work for single transaction block, but after the first block was left the -autocommit behavior was never restored. This bug is now fixed in 1.5. While -this is only a bug fix, it is worth checking your applications behavior if -you are using PostgreSQL together with the autocommit option. - -Session not saved on 500 responses -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django's session middleware will skip saving the session data if the -response's status code is 500. - -Email checks on failed admin login -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Prior to Django 1.5, if you attempted to log into the admin interface and -mistakenly used your email address instead of your username, the admin -interface would provide a warning advising that your email address was -not your username. In Django 1.5, the introduction of -:ref:`custom User models ` has required the removal of this -warning. This doesn't change the login behavior of the admin site; it only -affects the warning message that is displayed under one particular mode of -login failure. - -Changes in tests execution -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some changes have been introduced in the execution of tests that might be -backward-incompatible for some testing setups: - -Database flushing in ``django.test.TransactionTestCase`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Previously, the test database was truncated *before* each test run in a -:class:`~django.test.TransactionTestCase`. - -In order to be able to run unit tests in any order and to make sure they are -always isolated from each other, :class:`~django.test.TransactionTestCase` will -now reset the database *after* each test run instead. - -No more implicit DB sequences reset -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:class:`~django.test.TransactionTestCase` tests used to reset primary key -sequences automatically together with the database flushing actions described -above. - -This has been changed so no sequences are implicitly reset. This can cause -:class:`~django.test.TransactionTestCase` tests that depend on hard-coded -primary key values to break. - -The new :attr:`~django.test.TransactionTestCase.reset_sequences` attribute can -be used to force the old behavior for :class:`~django.test.TransactionTestCase` -that might need it. - -Ordering of tests -^^^^^^^^^^^^^^^^^ - -In order to make sure all ``TestCase`` code starts with a clean database, -tests are now executed in the following order: - -* First, all unittests (including :class:`unittest.TestCase`, - :class:`~django.test.SimpleTestCase`, :class:`~django.test.TestCase` and - :class:`~django.test.TransactionTestCase`) are run with no particular ordering - guaranteed nor enforced among them. - -* Then any other tests (e.g. doctests) that may alter the database without - restoring it to its original state are run. - -This should not cause any problems unless you have existing doctests which -assume a :class:`~django.test.TransactionTestCase` executed earlier left some -database state behind or unit tests that rely on some form of state being -preserved after the execution of other tests. Such tests are already very -fragile, and must now be changed to be able to run independently. - -`cleaned_data` dictionary kept for invalid forms -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :attr:`~django.forms.Form.cleaned_data` dictionary is now always present -after form validation. When the form doesn't validate, it contains only the -fields that passed validation. You should test the success of the validation -with the :meth:`~django.forms.Form.is_valid()` method and not with the -presence or absence of the :attr:`~django.forms.Form.cleaned_data` attribute -on the form. - -Behavior of :djadmin:`syncdb` with multiple databases -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:djadmin:`syncdb` now queries the database routers to determine if content -types (when :mod:`~django.contrib.contenttypes` is enabled) and permissions -(when :mod:`~django.contrib.auth` is enabled) should be created in the target -database. Previously, it created them in the default database, even when -another database was specified with the :djadminopt:`--database` option. - -If you use :djadmin:`syncdb` on multiple databases, you should ensure that -your routers allow synchronizing content types and permissions to only one of -them. See the docs on the :ref:`behavior of contrib apps with multiple -databases ` for more information. - -Miscellaneous -~~~~~~~~~~~~~ - -* :class:`django.forms.ModelMultipleChoiceField` now returns an empty - ``QuerySet`` as the empty value instead of an empty list. - -* :func:`~django.utils.http.int_to_base36` properly raises a - :exc:`TypeError` instead of :exc:`ValueError` for non-integer inputs. - -* The ``slugify`` template filter is now available as a standard python - function at :func:`django.utils.text.slugify`. Similarly, ``remove_tags`` is - available at :func:`django.utils.html.remove_tags`. - -* Uploaded files are no longer created as executable by default. If you need - them to be executable change :setting:`FILE_UPLOAD_PERMISSIONS` to your - needs. The new default value is ``0o666`` (octal) and the current umask value - is first masked out. - -* The :class:`F expressions ` supported bitwise operators by - ``&`` and ``|``. These operators are now available using ``.bitand()`` and - ``.bitor()`` instead. The removal of ``&`` and ``|`` was done to be - consistent with :ref:`Q() expressions ` and - ``QuerySet`` combining where the operators are used as boolean AND and OR - operators. - -* In a ``filter()`` call, when :class:`F expressions ` - contained lookups spanning multi-valued relations, they didn't always reuse - the same relations as other lookups along the same chain. This was changed, - and now F() expressions will always use the same relations as other lookups - within the same ``filter()`` call. - -* The :ttag:`csrf_token` template tag is no longer enclosed in a div. If you need - HTML validation against pre-HTML5 Strict DTDs, you should add a div around it - in your pages. - -* The template tags library ``adminmedia``, which only contained the - deprecated template tag ``{% admin_media_prefix %}``, was removed. - Attempting to load it with ``{% load adminmedia %}`` will fail. If your - templates still contain that line you must remove it. - -Features deprecated in 1.5 -========================== - -.. _simplejson-deprecation-beta-1: - -``AUTH_PROFILE_MODULE`` -~~~~~~~~~~~~~~~~~~~~~~~ - -With the introduction of :ref:`custom User models `, there is -no longer any need for a built-in mechanism to store user profile data. - -You can still define user profiles models that have a one-to-one relation with -the User model - in fact, for many applications needing to associate data with -a User account, this will be an appropriate design pattern to follow. However, -the ``AUTH_PROFILE_MODULE`` setting, and the -``django.contrib.auth.models.User.get_profile()`` method for accessing -the user profile model, should not be used any longer. - -Streaming behavior of :class:`~django.http.HttpResponse` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.5 deprecates the ability to stream a response by passing an iterator -to :class:`~django.http.HttpResponse`. If you rely on this behavior, switch to -:class:`~django.http.StreamingHttpResponse`. See -:ref:`explicit-streaming-responses-beta-1` above. - -In Django 1.7 and above, the iterator will be consumed immediately by -:class:`~django.http.HttpResponse`. - -``django.utils.simplejson`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Since Django 1.5 drops support for Python 2.5, we can now rely on the -:mod:`json` module being available in Python's standard library, so we've -removed our own copy of :mod:`simplejson`. You should now import :mod:`json` -instead of ``django.utils.simplejson``. - -Unfortunately, this change might have unwanted side-effects, because of -incompatibilities between versions of :mod:`simplejson` -- see the -:ref:`backwards-incompatible changes ` section. -If you rely on features added to :mod:`simplejson` after it became Python's -:mod:`json`, you should import :mod:`simplejson` explicitly. - -``django.utils.encoding.StrAndUnicode`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``django.utils.encoding.StrAndUnicode`` mix-in has been deprecated. -Define a ``__str__`` method and apply the -:func:`~django.utils.encoding.python_2_unicode_compatible` decorator instead. - -``django.utils.itercompat.product`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``django.utils.itercompat.product`` function has been deprecated. Use -the built-in :func:`itertools.product` instead. - -``django.utils.markup`` -~~~~~~~~~~~~~~~~~~~~~~~ - -The markup contrib module has been deprecated and will follow an accelerated -deprecation schedule. Direct use of python markup libraries or 3rd party tag -libraries is preferred to Django maintaining this functionality in the -framework. - -``cleanup`` management command -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``cleanup`` management command has been deprecated and replaced by -:djadmin:`clearsessions`. - -``daily_cleanup.py`` script -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The undocumented ``daily_cleanup.py`` script has been deprecated. Use the -:djadmin:`clearsessions` management command instead. - -``depth`` keyword argument in ``select_related`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``depth`` keyword argument in -:meth:`~django.db.models.query.QuerySet.select_related` has been deprecated. -You should use field names instead. diff --git a/docs/releases/index.txt b/docs/releases/index.txt index 06c94a5dc6..59c08c04be 100644 --- a/docs/releases/index.txt +++ b/docs/releases/index.txt @@ -156,30 +156,7 @@ added to all affected release series. Additionally, :doc:`an archive of disclosed security issues ` is maintained. -Development releases -==================== - -These notes are retained for historical purposes. If you are upgrading -between formal Django releases, you don't need to worry about these -notes. - .. toctree:: - :maxdepth: 1 + :hidden: security - 1.5-beta-1 - 1.5-alpha-1 - 1.4-beta-1 - 1.4-alpha-1 - 1.3-beta-1 - 1.3-alpha-1 - 1.2-rc-1 - 1.2-beta-1 - 1.2-alpha-1 - 1.1-rc-1 - 1.1-beta-1 - 1.1-alpha-1 - 1.0-beta-2 - 1.0-beta - 1.0-alpha-2 - 1.0-alpha-1