diff options
Diffstat (limited to 'parts/django/docs/releases')
22 files changed, 5232 insertions, 0 deletions
diff --git a/parts/django/docs/releases/0.95.txt b/parts/django/docs/releases/0.95.txt new file mode 100644 index 0000000..7409bff --- /dev/null +++ b/parts/django/docs/releases/0.95.txt @@ -0,0 +1,124 @@ +================================= +Django version 0.95 release notes +================================= + +Welcome to the Django 0.95 release. + +This represents a significant advance in Django development since the 0.91 +release in January 2006. The details of every change in this release would be +too extensive to list in full, but a summary is presented below. + +Suitability and API stability +============================= + +This release is intended to provide a stable reference point for developers +wanting to work on production-level applications that use Django. + +However, it's not the 1.0 release, and we'll be introducing further changes +before 1.0. For a clear look at which areas of the framework will change (and +which ones will *not* change) before 1.0, see the api-stability.txt file, which +lives in the docs/ directory of the distribution. + +You may have a need to use some of the features that are marked as +"subject to API change" in that document, but that's OK with us as long as it's +OK with you, and as long as you understand APIs may change in the future. + +Fortunately, most of Django's core APIs won't be changing before version 1.0. +There likely won't be as big of a change between 0.95 and 1.0 versions as there +was between 0.91 and 0.95. + +Changes and new features +======================== + +The major changes in this release (for developers currently using the 0.91 +release) are a result of merging the 'magic-removal' branch of development. +This branch removed a number of constraints in the way Django code had to be +written that were a consequence of decisions made in the early days of Django, +prior to its open-source release. It's now possible to write more natural, +Pythonic code that works as expected, and there's less "black magic" happening +behind the scenes. + +Aside from that, another main theme of this release is a dramatic increase in +usability. We've made countless improvements in error messages, documentation, +etc., to improve developers' quality of life. + +The new features and changes introduced in 0.95 include: + + * Django now uses a more consistent and natural filtering interface for + retrieving objects from the database. + + * User-defined models, functions and constants now appear in the module + namespace they were defined in. (Previously everything was magically + transferred to the django.models.* namespace.) + + * Some optional applications, such as the FlatPage, Sites and Redirects + apps, have been decoupled and moved into django.contrib. If you don't + want to use these applications, you no longer have to install their + database tables. + + * Django now has support for managing database transactions. + + * We've added the ability to write custom authentication and authorization + backends for authenticating users against alternate systems, such as + LDAP. + + * We've made it easier to add custom table-level functions to models, + through a new "Manager" API. + + * It's now possible to use Django without a database. This simply means + that the framework no longer requires you to have a working database set + up just to serve dynamic pages. In other words, you can just use + URLconfs/views on their own. Previously, the framework required that a + database be configured, regardless of whether you actually used it. + + * It's now more explicit and natural to override save() and delete() + methods on models, rather than needing to hook into the pre_save() and + post_save() method hooks. + + * Individual pieces of the framework now can be configured without + requiring the setting of an environment variable. This permits use of, + for example, the Django templating system inside other applications. + + * More and more parts of the framework have been internationalized, as + we've expanded internationalization (i18n) support. The Django + codebase, including code and templates, has now been translated, at least + in part, into 31 languages. From Arabic to Chinese to Hungarian to Welsh, + it is now possible to use Django's admin site in your native language. + +The number of changes required to port from 0.91-compatible code to the 0.95 +code base are significant in some cases. However, they are, for the most part, +reasonably routine and only need to be done once. A list of the necessary +changes is described in the `Removing The Magic`_ wiki page. There is also an +easy checklist_ for reference when undertaking the porting operation. + +.. _Removing The Magic: http://code.djangoproject.com/wiki/RemovingTheMagic +.. _checklist: http://code.djangoproject.com/wiki/MagicRemovalCheatSheet1 + +Problem reports and getting help +================================ + +Need help resolving a problem with Django? The documentation in the distribution +is also available online_ at the `Django Web site`_. The :doc:`FAQ </faq/index>` +document is especially recommended, as it contains a number of issues that come +up time and again. + +For more personalized help, the `django-users`_ mailing list is a very active +list, with more than 2,000 subscribers who can help you solve any sort of +Django problem. We recommend you search the archives first, though, because +many common questions appear with some regularity, and any particular problem +may already have been answered. + +Finally, for those who prefer the more immediate feedback offered by IRC, +there's a #django channel on irc.freenode.net that is regularly populated by +Django users and developers from around the world. Friendly people are usually +available at any hour of the day -- to help, or just to chat. + +.. _online: http://www.djangoproject.com/documentation/0.95/ +.. _Django Web site: http://www.djangoproject.com/ +.. _django-users: http://groups.google.com/group/django-users + +Thanks for using Django! + +The Django Team +July 2006 + diff --git a/parts/django/docs/releases/0.96.txt b/parts/django/docs/releases/0.96.txt new file mode 100644 index 0000000..1224360 --- /dev/null +++ b/parts/django/docs/releases/0.96.txt @@ -0,0 +1,264 @@ +================================= +Django version 0.96 release notes +================================= + +Welcome to Django 0.96! + +The primary goal for 0.96 is a cleanup and stabilization of the features +introduced in 0.95. There have been a few small `backwards-incompatible +changes`_ since 0.95, but the upgrade process should be fairly simple +and should not require major changes to existing applications. + +However, we're also releasing 0.96 now because we have a set of +backwards-incompatible changes scheduled for the near future. Once +completed, they will involve some code changes for application +developers, so we recommend that you stick with Django 0.96 until the +next official release; then you'll be able to upgrade in one step +instead of needing to make incremental changes to keep up with the +development version of Django. + +Backwards-incompatible changes +============================== + +The following changes may require you to update your code when you switch from +0.95 to 0.96: + +``MySQLdb`` version requirement +------------------------------- + +Due to a bug in older versions of the ``MySQLdb`` Python module (which +Django uses to connect to MySQL databases), Django's MySQL backend now +requires version 1.2.1p2 or higher of ``MySQLdb``, and will raise +exceptions if you attempt to use an older version. + +If you're currently unable to upgrade your copy of ``MySQLdb`` to meet +this requirement, a separate, backwards-compatible backend, called +"mysql_old", has been added to Django. To use this backend, change +the :setting:`DATABASE_ENGINE` setting in your Django settings file from +this:: + + DATABASE_ENGINE = "mysql" + +to this:: + + DATABASE_ENGINE = "mysql_old" + +However, we strongly encourage MySQL users to upgrade to a more recent +version of ``MySQLdb`` as soon as possible, The "mysql_old" backend is +provided only to ease this transition, and is considered deprecated; +aside from any necessary security fixes, it will not be actively +maintained, and it will be removed in a future release of Django. + +Also, note that some features, like the new :setting:`DATABASE_OPTIONS` +setting (see the `databases documentation`_ for details), are only +available on the "mysql" backend, and will not be made available for +"mysql_old". + +.. _databases documentation: http://www.djangoproject.com/documentation/0.96/databases/ + +Database constraint names changed +--------------------------------- + +The format of the constraint names Django generates for foreign key +references have changed slightly. These names are generally only used +when it is not possible to put the reference directly on the affected +column, so they are not always visible. + +The effect of this change is that running ``manage.py reset`` and +similar commands against an existing database may generate SQL with +the new form of constraint name, while the database itself contains +constraints named in the old form; this will cause the database server +to raise an error message about modifying non-existent constraints. + +If you need to work around this, there are two methods available: + + 1. Redirect the output of ``manage.py`` to a file, and edit the + generated SQL to use the correct constraint names before + executing it. + + 2. Examine the output of ``manage.py sqlall`` to see the new-style + constraint names, and use that as a guide to rename existing + constraints in your database. + +Name changes in ``manage.py`` +----------------------------- + +A few of the options to ``manage.py`` have changed with the addition of fixture +support: + + * There are new ``dumpdata`` and ``loaddata`` commands which, as + you might expect, will dump and load data to/from the + database. These commands can operate against any of Django's + supported serialization formats. + + * The ``sqlinitialdata`` command has been renamed to ``sqlcustom`` to + emphasize that ``loaddata`` should be used for data (and ``sqlcustom`` for + other custom SQL -- views, stored procedures, etc.). + + * The vestigial ``install`` command has been removed. Use ``syncdb``. + +Backslash escaping changed +-------------------------- + +The Django database API now escapes backslashes given as query parameters. If +you have any database API code that matches backslashes, and it was working before +(despite the lack of escaping), you'll have to change your code to "unescape" the +slashes one level. + +For example, this used to work:: + + # Find text containing a single backslash + MyModel.objects.filter(text__contains='\\\\') + +The above is now incorrect, and should be rewritten as:: + + # Find text containing a single backslash + MyModel.objects.filter(text__contains='\\') + +Removed ENABLE_PSYCO setting +---------------------------- + +The ``ENABLE_PSYCO`` setting no longer exists. If your settings file includes +``ENABLE_PSYCO`` it will have no effect; to use Psyco_, we recommend +writing a middleware class to activate it. + +.. _psyco: http://psyco.sourceforge.net/ + +What's new in 0.96? +=================== + +This revision represents over a thousand source commits and over four hundred +bug fixes, so we can't possibly catalog all the changes. Here, we describe the +most notable changes in this release. + +New forms library +----------------- + +``django.newforms`` is Django's new form-handling library. It's a +replacement for ``django.forms``, the old form/manipulator/validation +framework. Both APIs are available in 0.96, but over the next two +releases we plan to switch completely to the new forms system, and +deprecate and remove the old system. + +There are three elements to this transition: + + * We've copied the current ``django.forms`` to + ``django.oldforms``. This allows you to upgrade your code *now* + rather than waiting for the backwards-incompatible change and + rushing to fix your code after the fact. Just change your + import statements like this:: + + from django import forms # 0.95-style + from django import oldforms as forms # 0.96-style + + * The next official release of Django will move the current + ``django.newforms`` to ``django.forms``. This will be a + backwards-incompatible change, and anyone still using the old + version of ``django.forms`` at that time will need to change + their import statements as described above. + + * The next release after that will completely remove + ``django.oldforms``. + +Although the ``newforms`` library will continue to evolve, it's ready for use +for most common cases. We recommend that anyone new to form handling skip the +old forms system and start with the new. + +For more information about ``django.newforms``, read the `newforms +documentation`_. + +.. _newforms documentation: http://www.djangoproject.com/documentation/0.96/newforms/ + +URLconf improvements +-------------------- + +You can now use any callable as the callback in URLconfs (previously, only +strings that referred to callables were allowed). This allows a much more +natural use of URLconfs. For example, this URLconf:: + + from django.conf.urls.defaults import * + + urlpatterns = patterns('', + ('^myview/$', 'mysite.myapp.views.myview') + ) + +can now be rewritten as:: + + from django.conf.urls.defaults import * + from mysite.myapp.views import myview + + urlpatterns = patterns('', + ('^myview/$', myview) + ) + +One useful application of this can be seen when using decorators; this +change allows you to apply decorators to views *in your +URLconf*. Thus, you can make a generic view require login very +easily:: + + from django.conf.urls.defaults import * + from django.contrib.auth.decorators import login_required + from django.views.generic.list_detail import object_list + from mysite.myapp.models import MyModel + + info = { + "queryset" : MyModel.objects.all(), + } + + urlpatterns = patterns('', + ('^myview/$', login_required(object_list), info) + ) + +Note that both syntaxes (strings and callables) are valid, and will continue to +be valid for the foreseeable future. + +The test framework +------------------ + +Django now includes a test framework so you can start transmuting fear into +boredom (with apologies to Kent Beck). You can write tests based on doctest_ +or unittest_ and test your views with a simple test client. + +There is also new support for "fixtures" -- initial data, stored in any of the +supported `serialization formats`_, that will be loaded into your database at the +start of your tests. This makes testing with real data much easier. + +See `the testing documentation`_ for the full details. + +.. _doctest: http://docs.python.org/library/doctest.html +.. _unittest: http://docs.python.org/library/unittest.html +.. _the testing documentation: http://www.djangoproject.com/documentation/0.96/testing/ +.. _serialization formats: http://www.djangoproject.com/documentation/0.96/serialization/ + +Improvements to the admin interface +----------------------------------- + +A small change, but a very nice one: dedicated views for adding and +updating users have been added to the admin interface, so you no +longer need to worry about working with hashed passwords in the admin. + +Thanks +====== + +Since 0.95, a number of people have stepped forward and taken a major +new role in Django's development. We'd like to thank these people for +all their hard work: + + * Russell Keith-Magee and Malcolm Tredinnick for their major code + contributions. This release wouldn't have been possible without them. + + * Our new release manager, James Bennett, for his work in getting out + 0.95.1, 0.96, and (hopefully) future release. + + * Our ticket managers Chris Beaven (aka SmileyChris), Simon Greenhill, + Michael Radziej, and Gary Wilson. They agreed to take on the monumental + task of wrangling our tickets into nicely cataloged submission. Figuring + out what to work on is now about a million times easier; thanks again, + guys. + + * Everyone who submitted a bug report, patch or ticket comment. We can't + possibly thank everyone by name -- over 200 developers submitted patches + that went into 0.96 -- but everyone who's contributed to Django is listed + in AUTHORS_. + +.. _AUTHORS: http://code.djangoproject.com/browser/django/trunk/AUTHORS diff --git a/parts/django/docs/releases/1.0-alpha-1.txt b/parts/django/docs/releases/1.0-alpha-1.txt new file mode 100644 index 0000000..82846be --- /dev/null +++ b/parts/django/docs/releases/1.0-alpha-1.txt @@ -0,0 +1,161 @@ +================================ +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 </ref/contrib/admin/index>` + +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 </ref/unicode>` + +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: + + http://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 +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: + + http://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: + + http://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: + + http://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 </internals/contributing>` + +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/parts/django/docs/releases/1.0-alpha-2.txt b/parts/django/docs/releases/1.0-alpha-2.txt new file mode 100644 index 0000000..83e2e2e --- /dev/null +++ b/parts/django/docs/releases/1.0-alpha-2.txt @@ -0,0 +1,136 @@ +================================ +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 </releases/1.0-alpha-1>`. 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 </topics/files>`; 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 </topics/i18n/index>` 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 +.. _Its documentation: http://geodjango.org/docs/ +.. _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: + + http://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: + + http://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 </internals/contributing>` + +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/parts/django/docs/releases/1.0-beta-2.txt b/parts/django/docs/releases/1.0-beta-2.txt new file mode 100644 index 0000000..eabd6b7 --- /dev/null +++ b/parts/django/docs/releases/1.0-beta-2.txt @@ -0,0 +1,119 @@ +=============================== +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 +</releases/1.0-alpha-1>`. For features which were new as of Django 1.0 +alpha 2, see :doc:`the 1.0 alpha 2 release notes +</releases/1.0-alpha-2>`. For features which were new as of Django 1.0 +beta 1, see :doc:`the 1.0 beta 1 release notes </releases/1.0-beta>`. + +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. :doc:`Full documentation + </ref/contrib/comments/index>` is available, as well as :doc:`an + upgrade guide </ref/contrib/comments/upgrade>` if you were using + the previous incarnation of the comments application.. + +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.pocoo.org/ +.. _online: http://docs.djangoproject.com/en/dev/ + +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 +</topics/forms/index>` 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 bug-fixing 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: + + http://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 </internals/contributing>` + +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/parts/django/docs/releases/1.0-beta.txt b/parts/django/docs/releases/1.0-beta.txt new file mode 100644 index 0000000..9e07e6c --- /dev/null +++ b/parts/django/docs/releases/1.0-beta.txt @@ -0,0 +1,153 @@ +=============================== +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 </releases/1.0-alpha-1>`. For features which were new as of Django +1.0 alpha 2, see :doc:`the 1.0 alpha 2 release notes </releases/1.0-alpha-2>`. + +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 <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 </ref/contrib/admin/index>`. + +``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 </topics/cache>`. + +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: http://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: + + http://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: + + http://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 </internals/contributing>` + +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/parts/django/docs/releases/1.0-porting-guide.txt b/parts/django/docs/releases/1.0-porting-guide.txt new file mode 100644 index 0000000..e12b34e --- /dev/null +++ b/parts/django/docs/releases/1.0-porting-guide.txt @@ -0,0 +1,772 @@ +========================================= +Porting your apps from Django 0.96 to 1.0 +========================================= + +.. highlight:: python + +Django 1.0 breaks compatibility with 0.96 in some areas. + +This guide will help you port 0.96 projects and apps to 1.0. The first part of +this document includes the common changes needed to run with 1.0. If after going +through the first part your code still breaks, check the section `Less-common +Changes`_ for a list of a bunch of less-common compatibility issues. + +.. seealso:: + + The :doc:`1.0 release notes </releases/1.0>`. That document explains the new + features in 1.0 more deeply; the porting guide is more concerned with + helping you quickly update your code. + +Common changes +============== + +This section describes the changes between 0.96 and 1.0 that most users will +need to make. + +Use Unicode +----------- + +Change string literals (``'foo'``) into Unicode literals (``u'foo'``). Django +now uses Unicode strings throughout. In most places, raw strings will continue +to work, but updating to use Unicode literals will prevent some obscure +problems. + +See :doc:`/ref/unicode` for full details. + +Models +------ + +Common changes to your models file: + +Rename ``maxlength`` to ``max_length`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Rename your ``maxlength`` argument to ``max_length`` (this was changed to be +consistent with form fields): + +Replace ``__str__`` with ``__unicode__`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Replace your model's ``__str__`` function with a ``__unicode__`` method, and +make sure you `use Unicode`_ (``u'foo'``) in that method. + +Remove ``prepopulated_from`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Remove the ``prepopulated_from`` argument on model fields. It's no longer valid +and has been moved to the ``ModelAdmin`` class in ``admin.py``. See `the +admin`_, below, for more details about changes to the admin. + +Remove ``core`` +~~~~~~~~~~~~~~~ + +Remove the ``core`` argument from your model fields. It is no longer +necessary, since the equivalent functionality (part of :ref:`inline editing +<admin-inlines>`) is handled differently by the admin interface now. You don't +have to worry about inline editing until you get to `the admin`_ section, +below. For now, remove all references to ``core``. + +Replace ``class Admin:`` with ``admin.py`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Remove all your inner ``class Admin`` declarations from your models. They won't +break anything if you leave them, but they also won't do anything. To register +apps with the admin you'll move those declarations to an ``admin.py`` file; +see `the admin`_ below for more details. + +.. seealso:: + + A contributor to djangosnippets__ has written a script that'll `scan your + models.py and generate a corresponding admin.py`__. + + __ http://www.djangosnippets.org/ + __ http://www.djangosnippets.org/snippets/603/ + +Example +~~~~~~~ + +Below is an example ``models.py`` file with all the changes you'll need to make: + +Old (0.96) ``models.py``:: + + class Author(models.Model): + first_name = models.CharField(maxlength=30) + last_name = models.CharField(maxlength=30) + slug = models.CharField(maxlength=60, prepopulate_from=('first_name', 'last_name')) + + class Admin: + list_display = ['first_name', 'last_name'] + + def __str__(self): + return '%s %s' % (self.first_name, self.last_name) + +New (1.0) ``models.py``:: + + class Author(models.Model): + first_name = models.CharField(max_length=30) + last_name = models.CharField(max_length=30) + slug = models.CharField(max_length=60) + + def __unicode__(self): + return u'%s %s' % (self.first_name, self.last_name) + +New (1.0) ``admin.py``:: + + from django.contrib import admin + from models import Author + + class AuthorAdmin(admin.ModelAdmin): + list_display = ['first_name', 'last_name'] + prepopulated_fields = { + 'slug': ('first_name', 'last_name') + } + + admin.site.register(Author, AuthorAdmin) + +The Admin +--------- + +One of the biggest changes in 1.0 is the new admin. The Django administrative +interface (``django.contrib.admin``) has been completely refactored; admin +definitions are now completely decoupled from model definitions, the framework +has been rewritten to use Django's new form-handling library and redesigned with +extensibility and customization in mind. + +Practically, this means you'll need to rewrite all of your ``class Admin`` +declarations. You've already seen in `models`_ above how to replace your ``class +Admin`` with a ``admin.site.register()`` call in an ``admin.py`` file. Below are +some more details on how to rewrite that ``Admin`` declaration into the new +syntax. + +Use new inline syntax +~~~~~~~~~~~~~~~~~~~~~ + +The new ``edit_inline`` options have all been moved to ``admin.py``. Here's an +example: + +Old (0.96):: + + class Parent(models.Model): + ... + + class Child(models.Model): + parent = models.ForeignKey(Parent, edit_inline=models.STACKED, num_in_admin=3) + + +New (1.0):: + + class ChildInline(admin.StackedInline): + model = Child + extra = 3 + + class ParentAdmin(admin.ModelAdmin): + model = Parent + inlines = [ChildInline] + + admin.site.register(Parent, ParentAdmin) + +See :ref:`admin-inlines` for more details. + +Simplify ``fields``, or use ``fieldsets`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The old ``fields`` syntax was quite confusing, and has been simplified. The old +syntax still works, but you'll need to use ``fieldsets`` instead. + +Old (0.96):: + + class ModelOne(models.Model): + ... + + class Admin: + fields = ( + (None, {'fields': ('foo','bar')}), + ) + + class ModelTwo(models.Model): + ... + + class Admin: + fields = ( + ('group1', {'fields': ('foo','bar'), 'classes': 'collapse'}), + ('group2', {'fields': ('spam','eggs'), 'classes': 'collapse wide'}), + ) + + +New (1.0):: + + class ModelOneAdmin(admin.ModelAdmin): + fields = ('foo', 'bar') + + class ModelTwoAdmin(admin.ModelAdmin): + fieldsets = ( + ('group1', {'fields': ('foo','bar'), 'classes': 'collapse'}), + ('group2', {'fields': ('spam','eggs'), 'classes': 'collapse wide'}), + ) + + +.. seealso:: + + * More detailed information about the changes and the reasons behind them + can be found on the `NewformsAdminBranch wiki page`__ + + * The new admin comes with a ton of new features; you can read about them in + the :doc:`admin documentation </ref/contrib/admin/index>`. + + __ http://code.djangoproject.com/wiki/NewformsAdminBranch + +URLs +---- + +Update your root ``urls.py`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you're using the admin site, you need to update your root ``urls.py``. + +Old (0.96) ``urls.py``:: + + from django.conf.urls.defaults import * + + urlpatterns = patterns('', + (r'^admin/', include('django.contrib.admin.urls')), + + # ... the rest of your URLs here ... + ) + +New (1.0) ``urls.py``:: + + from django.conf.urls.defaults import * + + # The next two lines enable the admin and load each admin.py file: + from django.contrib import admin + admin.autodiscover() + + urlpatterns = patterns('', + (r'^admin/(.*)', admin.site.root), + + # ... the rest of your URLs here ... + ) + +Views +----- + +Use ``django.forms`` instead of ``newforms`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Replace ``django.newforms`` with ``django.forms`` -- Django 1.0 renamed the +``newforms`` module (introduced in 0.96) to plain old ``forms``. The +``oldforms`` module was also removed. + +If you're already using the ``newforms`` library, and you used our recommended +``import`` statement syntax, all you have to do is change your import +statements. + +Old:: + + from django import newforms as forms + +New:: + + from django import forms + +If you're using the old forms system (formerly known as ``django.forms`` and +``django.oldforms``), you'll have to rewrite your forms. A good place to start +is the :doc:`forms documentation </topics/forms/index>` + +Handle uploaded files using the new API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Replace use of uploaded files -- that is, entries in ``request.FILES`` -- as +simple dictionaries with the new :class:`~django.core.files.UploadedFile`. The +old dictionary syntax no longer works. + +Thus, in a view like:: + + def my_view(request): + f = request.FILES['file_field_name'] + ... + +...you'd need to make the following changes: + +===================== ===================== +Old (0.96) New (1.0) +===================== ===================== +``f['content']`` ``f.read()`` +``f['filename']`` ``f.name`` +``f['content-type']`` ``f.content_type`` +===================== ===================== + +Work with file fields using the new API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The internal implementation of :class:`django.db.models.FileField` have changed. +A visible result of this is that the way you access special attributes (URL, +filename, image size, etc) of these model fields has changed. You will need to +make the following changes, assuming your model's +:class:`~django.db.models.FileField` is called ``myfile``: + +=================================== ======================== +Old (0.96) New (1.0) +=================================== ======================== +``myfile.get_content_filename()`` ``myfile.content.path`` +``myfile.get_content_url()`` ``myfile.content.url`` +``myfile.get_content_size()`` ``myfile.content.size`` +``myfile.save_content_file()`` ``myfile.content.save()`` +``myfile.get_content_width()`` ``myfile.content.width`` +``myfile.get_content_height()`` ``myfile.content.height`` +=================================== ======================== + +Note that the ``width`` and ``height`` attributes only make sense for +:class:`~django.db.models.ImageField` fields. More details can be found in the +:doc:`model API </ref/models/fields>` documentation. + +Use ``Paginator`` instead of ``ObjectPaginator`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``ObjectPaginator`` in 0.96 has been removed and replaced with an improved +version, :class:`django.core.paginator.Paginator`. + +Templates +--------- + +Learn to love autoescaping +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, the template system now automatically HTML-escapes the output of +every variable. To learn more, see :ref:`automatic-html-escaping`. + +To disable auto-escaping for an individual variable, use the :tfilter:`safe` +filter: + +.. code-block:: html+django + + This will be escaped: {{ data }} + This will not be escaped: {{ data|safe }} + +To disable auto-escaping for an entire template, wrap the template (or just a +particular section of the template) in the :ttag:`autoescape` tag: + +.. code-block:: html+django + + {% autoescape off %} + ... unescaped template content here ... + {% endautoescape %} + +Less-common changes +=================== + +The following changes are smaller, more localized changes. They should only +affect more advanced users, but it's probably worth reading through the list and +checking your code for these things. + +Signals +------- + +* Add ``**kwargs`` to any registered signal handlers. + +* Connect, disconnect, and send signals via methods on the + :class:`~django.dispatch.Signal` object instead of through module methods in + ``django.dispatch.dispatcher``. + +* Remove any use of the ``Anonymous`` and ``Any`` sender options; they no longer + exist. You can still receive signals sent by any sender by using + ``sender=None`` + +* Make any custom signals you've declared into instances of + :class:`django.dispatch.Signal` instead of anonymous objects. + +Here's quick summary of the code changes you'll need to make: + +================================================= ====================================== +Old (0.96) New (1.0) +================================================= ====================================== +``def callback(sender)`` ``def callback(sender, **kwargs)`` +``sig = object()`` ``sig = django.dispatch.Signal()`` +``dispatcher.connect(callback, sig)`` ``sig.connect(callback)`` +``dispatcher.send(sig, sender)`` ``sig.send(sender)`` +``dispatcher.connect(callback, sig, sender=Any)`` ``sig.connect(callback, sender=None)`` +================================================= ====================================== + +Comments +-------- + +If you were using Django 0.96's ``django.contrib.comments`` app, you'll need to +upgrade to the new comments app introduced in 1.0. See +:doc:`/ref/contrib/comments/upgrade` for details. + +Template tags +------------- + +:ttag:`spaceless` tag +~~~~~~~~~~~~~~~~~~~~~ + +The spaceless template tag now removes *all* spaces between HTML tags, instead +of preserving a single space. + +Local flavors +------------- + +U.S. local flavor +~~~~~~~~~~~~~~~~~ + +``django.contrib.localflavor.usa`` has been renamed to +:mod:`django.contrib.localflavor.us`. This change was made to match the naming +scheme of other local flavors. To migrate your code, all you need to do is +change the imports. + +Sessions +-------- + +Getting a new session key +~~~~~~~~~~~~~~~~~~~~~~~~~ + +``SessionBase.get_new_session_key()`` has been renamed to +``_get_new_session_key()``. ``get_new_session_object()`` no longer exists. + +Fixtures +-------- + +Loading a row no longer calls ``save()`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Previously, loading a row automatically ran the model's ``save()`` method. This +is no longer the case, so any fields (for example: timestamps) that were +auto-populated by a ``save()`` now need explicit values in any fixture. + +Settings +-------- + +Better exceptions +~~~~~~~~~~~~~~~~~ + +The old :exc:`EnvironmentError` has split into an :exc:`ImportError` when +Django fails to find the settings module and a :exc:`RuntimeError` when you try +to reconfigure settings after having already used them + +``LOGIN_URL`` has moved +~~~~~~~~~~~~~~~~~~~~~~~ + +The ``LOGIN_URL`` constant moved from ``django.contrib.auth`` into the +``settings`` module. Instead of using ``from django.contrib.auth import +LOGIN_URL`` refer to :setting:`settings.LOGIN_URL <LOGIN_URL>`. + +:setting:`APPEND_SLASH` behavior has been updated +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In 0.96, if a URL didn't end in a slash or have a period in the final +component of its path, and ``APPEND_SLASH`` was True, Django would redirect +to the same URL, but with a slash appended to the end. Now, Django checks to +see whether the pattern without the trailing slash would be matched by +something in your URL patterns. If so, no redirection takes place, because it +is assumed you deliberately wanted to catch that pattern. + +For most people, this won't require any changes. Some people, though, have URL +patterns that look like this:: + + r'/some_prefix/(.*)$' + +Previously, those patterns would have been redirected to have a trailing +slash. If you always want a slash on such URLs, rewrite the pattern as:: + + r'/some_prefix/(.*/)$' + +Smaller model changes +--------------------- + +Different exception from ``get()`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Managers now return a :exc:`MultipleObjectsReturned` exception +instead of :exc:`AssertionError`: + +Old (0.96):: + + try: + Model.objects.get(...) + except AssertionError: + handle_the_error() + +New (1.0):: + + try: + Model.objects.get(...) + except Model.MultipleObjectsReturned: + handle_the_error() + +``LazyDate`` has been fired +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``LazyDate`` helper class no longer exists. + +Default field values and query arguments can both be callable objects, so +instances of ``LazyDate`` can be replaced with a reference to ``datetime.datetime.now``: + +Old (0.96):: + + class Article(models.Model): + title = models.CharField(maxlength=100) + published = models.DateField(default=LazyDate()) + +New (1.0):: + + import datetime + + class Article(models.Model): + title = models.CharField(max_length=100) + published = models.DateField(default=datetime.datetime.now) + +``DecimalField`` is new, and ``FloatField`` is now a proper float +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Old (0.96):: + + class MyModel(models.Model): + field_name = models.FloatField(max_digits=10, decimal_places=3) + ... + +New (1.0):: + + class MyModel(models.Model): + field_name = models.DecimalField(max_digits=10, decimal_places=3) + ... + +If you forget to make this change, you will see errors about ``FloatField`` +not taking a ``max_digits`` attribute in ``__init__``, because the new +``FloatField`` takes no precision-related arguments. + +If you're using MySQL or PostgreSQL, no further changes are needed. The +database column types for ``DecimalField`` are the same as for the old +``FloatField``. + +If you're using SQLite, you need to force the database to view the +appropriate columns as decimal types, rather than floats. To do this, you'll +need to reload your data. Do this after you have made the change to using +``DecimalField`` in your code and updated the Django code. + +.. warning:: + + **Back up your database first!** + + For SQLite, this means making a copy of the single file that stores the + database (the name of that file is the ``DATABASE_NAME`` in your settings.py + file). + +To upgrade each application to use a ``DecimalField``, you can do the +following, replacing ``<app>`` in the code below with each app's name: + +.. code-block:: bash + + $ ./manage.py dumpdata --format=xml <app> > data-dump.xml + $ ./manage.py reset <app> + $ ./manage.py loaddata data-dump.xml + +Notes: + + 1. It's important that you remember to use XML format in the first step of + this process. We are exploiting a feature of the XML data dumps that makes + porting floats to decimals with SQLite possible. + + 2. In the second step you will be asked to confirm that you are prepared to + lose the data for the application(s) in question. Say yes; we'll restore + this data in the third step, of course. + + 3. ``DecimalField`` is not used in any of the apps shipped with Django prior + to this change being made, so you do not need to worry about performing + this procedure for any of the standard Django models. + +If something goes wrong in the above process, just copy your backed up +database file over the original file and start again. + +Internationalization +-------------------- + +:func:`django.views.i18n.set_language` now requires a POST request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Previously, a GET request was used. The old behavior meant that state (the +locale used to display the site) could be changed by a GET request, which is +against the HTTP specification's recommendations. Code calling this view must +ensure that a POST request is now made, instead of a GET. This means you can +no longer use a link to access the view, but must use a form submission of +some kind (e.g. a button). + +``_()`` is no longer in builtins +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``_()`` (the callable object whose name is a single underscore) is no longer +monkeypatched into builtins -- that is, it's no longer available magically in +every module. + +If you were previously relying on ``_()`` always being present, you should now +explicitly import ``ugettext`` or ``ugettext_lazy``, if appropriate, and alias +it to ``_`` yourself:: + + from django.utils.translation import ugettext as _ + +HTTP request/response objects +----------------------------- + +Dictionary access to ``HttpRequest`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``HttpRequest`` objects no longer directly support dictionary-style +access; previously, both ``GET`` and ``POST`` data were directly +available on the ``HttpRequest`` object (e.g., you could check for a +piece of form data by using ``if 'some_form_key' in request`` or by +reading ``request['some_form_key']``. This is no longer supported; if +you need access to the combined ``GET`` and ``POST`` data, use +``request.REQUEST`` instead. + +It is strongly suggested, however, that you always explicitly look in +the appropriate dictionary for the type of request you expect to +receive (``request.GET`` or ``request.POST``); relying on the combined +``request.REQUEST`` dictionary can mask the origin of incoming data. + +Accessing ``HTTPResponse`` headers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``django.http.HttpResponse.headers`` has been renamed to ``_headers`` and +:class:`~django.http.HttpResponse` now supports containment checking directly. +So use ``if header in response:`` instead of ``if header in response.headers:``. + +Generic relations +----------------- + +Generic relations have been moved out of core +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The generic relation classes -- ``GenericForeignKey`` and ``GenericRelation`` +-- have moved into the :mod:`django.contrib.contenttypes` module. + +Testing +------- + +:meth:`django.test.Client.login` has changed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Old (0.96):: + + from django.test import Client + c = Client() + c.login('/path/to/login','myuser','mypassword') + +New (1.0):: + + # ... same as above, but then: + c.login(username='myuser', password='mypassword') + +Management commands +------------------- + +Running management commands from your code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:mod:`django.core.management` has been greatly refactored. + +Calls to management services in your code now need to use +``call_command``. For example, if you have some test code that calls flush and +load_data:: + + from django.core import management + management.flush(verbosity=0, interactive=False) + management.load_data(['test_data'], verbosity=0) + +...you'll need to change this code to read:: + + from django.core import management + management.call_command('flush', verbosity=0, interactive=False) + management.call_command('loaddata', 'test_data', verbosity=0) + +Subcommands must now precede options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``django-admin.py`` and ``manage.py`` now require subcommands to precede +options. So: + +.. code-block:: bash + + $ django-admin.py --settings=foo.bar runserver + +...no longer works and should be changed to: + +.. code-block:: bash + + $ django-admin.py runserver --settings=foo.bar + +Syndication +----------- + +``Feed.__init__`` has changed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``__init__()`` method of the syndication framework's ``Feed`` class now +takes an ``HttpRequest`` object as its second parameter, instead of the feed's +URL. This allows the syndication framework to work without requiring the sites +framework. This only affects code that subclasses ``Feed`` and overrides the +``__init__()`` method, and code that calls ``Feed.__init__()`` directly. + +Data structures +--------------- + +``SortedDictFromList`` is gone +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``django.newforms.forms.SortedDictFromList`` was removed. +:class:`django.utils.datastructures.SortedDict` can now be instantiated with +a sequence of tuples. + +To update your code: + + 1. Use :class:`django.utils.datastructures.SortedDict` wherever you were + using ``django.newforms.forms.SortedDictFromList``. + + 2. Because :meth:`django.utils.datastructures.SortedDict.copy` doesn't + return a deepcopy as ``SortedDictFromList.copy()`` did, you will need + to update your code if you were relying on a deepcopy. Do this by using + ``copy.deepcopy`` directly. + +Database backend functions +-------------------------- + +Database backend functions have been renamed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Almost *all* of the database backend-level functions have been renamed and/or +relocated. None of these were documented, but you'll need to change your code +if you're using any of these functions, all of which are in :mod:`django.db`: + +======================================= =================================================== +Old (0.96) New (1.0) +======================================= =================================================== +``backend.get_autoinc_sql`` ``connection.ops.autoinc_sql`` +``backend.get_date_extract_sql`` ``connection.ops.date_extract_sql`` +``backend.get_date_trunc_sql`` ``connection.ops.date_trunc_sql`` +``backend.get_datetime_cast_sql`` ``connection.ops.datetime_cast_sql`` +``backend.get_deferrable_sql`` ``connection.ops.deferrable_sql`` +``backend.get_drop_foreignkey_sql`` ``connection.ops.drop_foreignkey_sql`` +``backend.get_fulltext_search_sql`` ``connection.ops.fulltext_search_sql`` +``backend.get_last_insert_id`` ``connection.ops.last_insert_id`` +``backend.get_limit_offset_sql`` ``connection.ops.limit_offset_sql`` +``backend.get_max_name_length`` ``connection.ops.max_name_length`` +``backend.get_pk_default_value`` ``connection.ops.pk_default_value`` +``backend.get_random_function_sql`` ``connection.ops.random_function_sql`` +``backend.get_sql_flush`` ``connection.ops.sql_flush`` +``backend.get_sql_sequence_reset`` ``connection.ops.sequence_reset_sql`` +``backend.get_start_transaction_sql`` ``connection.ops.start_transaction_sql`` +``backend.get_tablespace_sql`` ``connection.ops.tablespace_sql`` +``backend.quote_name`` ``connection.ops.quote_name`` +``backend.get_query_set_class`` ``connection.ops.query_set_class`` +``backend.get_field_cast_sql`` ``connection.ops.field_cast_sql`` +``backend.get_drop_sequence`` ``connection.ops.drop_sequence_sql`` +``backend.OPERATOR_MAPPING`` ``connection.operators`` +``backend.allows_group_by_ordinal`` ``connection.features.allows_group_by_ordinal`` +``backend.allows_unique_and_pk`` ``connection.features.allows_unique_and_pk`` +``backend.autoindexes_primary_keys`` ``connection.features.autoindexes_primary_keys`` +``backend.needs_datetime_string_cast`` ``connection.features.needs_datetime_string_cast`` +``backend.needs_upper_for_iops`` ``connection.features.needs_upper_for_iops`` +``backend.supports_constraints`` ``connection.features.supports_constraints`` +``backend.supports_tablespaces`` ``connection.features.supports_tablespaces`` +``backend.uses_case_insensitive_names`` ``connection.features.uses_case_insensitive_names`` +``backend.uses_custom_queryset`` ``connection.features.uses_custom_queryset`` +======================================= =================================================== + diff --git a/parts/django/docs/releases/1.0.1.txt b/parts/django/docs/releases/1.0.1.txt new file mode 100644 index 0000000..780dc53 --- /dev/null +++ b/parts/django/docs/releases/1.0.1.txt @@ -0,0 +1,65 @@ +========================== +Django 1.0.1 release notes +========================== + +Welcome to Django 1.0.1! + +This is the first "bugfix" release in the Django 1.0 series, improving +the stability and performance of the Django 1.0 codebase. As such, +Django 1.0.1 contains no new features (and, pursuant to `our +compatibility policy`_, maintains backwards compatibility with Django +1.0), but does contain a number of fixes and other +improvements. Django 1.0.1 is a recommended upgrade for any +development or deployment currently using or targeting Django 1.0. + + +Fixes and improvements in Django 1.0.1 +====================================== + +Django 1.0.1 contains over two hundred fixes to the original Django +1.0 codebase; full details of every fix are available in `the +Subversion log of the 1.0.X branch`_, but here are some of the +highlights: + +* Several fixes in ``django.contrib.comments``, pertaining to RSS + feeds of comments, default ordering of comments and the XHTML and + internationalization of the default templates for comments. + +* Multiple fixes for Django's support of Oracle databases, including + pagination support for GIS QuerySets, more efficient slicing of + results and improved introspection of existing databases. + +* Several fixes for query support in the Django object-relational + mapper, including repeated setting and resetting of ordering and + fixes for working with ``INSERT``-only queries. + +* Multiple fixes for inline forms in formsets. + +* Multiple fixes for ``unique`` and ``unique_together`` model + constraints in automatically-generated forms. + +* Fixed support for custom callable ``upload_to`` declarations when + handling file uploads through automatically-generated forms. + +* Fixed support for sorting an admin change list based on a callable + attributes in ``list_display``. + +* A fix to the application of autoescaping for literal strings passed + to the ``join`` template filter. Previously, literal strings passed + to ``join`` were automatically escaped, contrary to `the documented + behavior for autoescaping and literal strings`_. Literal strings + passed to ``join`` are no longer automatically escaped, meaning you + must now manually escape them; this is an incompatibility if you + were relying on this bug, but not if you were relying on escaping + behaving as documented. + +* Improved and expanded translation files for many of the languages + Django supports by default. + +* And as always, a large number of improvements to Django's + documentation, including both corrections to existing documents and + expanded and new documentation. + +.. _our compatibility policy: http://docs.djangoproject.com/en/dev/misc/api-stability/ +.. _the Subversion log of the 1.0.X branch: http://code.djangoproject.com/log/django/branches/releases/1.0.X +.. _the documented behavior for autoescaping and literal strings: http://docs.djangoproject.com/en/dev/topics/templates/#string-literals-and-automatic-escaping diff --git a/parts/django/docs/releases/1.0.2.txt b/parts/django/docs/releases/1.0.2.txt new file mode 100644 index 0000000..b34522a --- /dev/null +++ b/parts/django/docs/releases/1.0.2.txt @@ -0,0 +1,51 @@ +========================== +Django 1.0.2 release notes +========================== + +Welcome to Django 1.0.2! + +This is the second "bugfix" release in the Django 1.0 series, +improving the stability and performance of the Django 1.0 codebase. As +such, Django 1.0.2 contains no new features (and, pursuant to +:doc:`our compatibility policy </misc/api-stability>`, maintains backwards compatibility with Django +1.0.0), but does contain a number of fixes and other +improvements. Django 1.0.2 is a recommended upgrade for any +development or deployment currently using or targeting Django 1.0. + + +Fixes and improvements in Django 1.0.2 +====================================== + +The primary reason behind this release is to remedy an issue in the +recently-released Django 1.0.1; the packaging scripts used for Django +1.0.1 omitted some directories from the final release package, +including one directory required by ``django.contrib.gis`` and part of +Django's unit-test suite. + +Django 1.0.2 contains updated packaging scripts, and the release +package contains the directories omitted from Django 1.0.1. As such, +this release contains all of the fixes and improvements from Django +1.0.1; see :doc:`the Django 1.0.1 release notes </releases/1.0.1>` for +details. + +Additionally, in the period since Django 1.0.1 was released: + +* Updated Hebrew and Danish translations have been added. + +* The default ``__repr__`` method of Django models has been made more + robust in the face of bad Unicode data coming from the + ``__unicode__`` method; rather than raise an exception in such + cases, ``repr()`` will now contain the string "[Bad Unicode data]" + in place of the invalid Unicode. + +* A bug involving the interaction of Django's ``SafeUnicode`` class + and the MySQL adapter has been resolved; ``SafeUnicode`` instances + (generated, for example, by template rendering) can now be assigned + to model attributes and saved to MySQL without requiring an explicit + intermediate cast to ``unicode``. + +* A bug affecting filtering on a nullable ``DateField`` in SQLite has + been resolved. + +* Several updates and improvements have been made to Django's + documentation. diff --git a/parts/django/docs/releases/1.0.txt b/parts/django/docs/releases/1.0.txt new file mode 100644 index 0000000..a2b6083 --- /dev/null +++ b/parts/django/docs/releases/1.0.txt @@ -0,0 +1,246 @@ +======================== +Django 1.0 release notes +======================== + +Welcome to Django 1.0! + +We've been looking forward to this moment for over three years, and it's finally +here. Django 1.0 represents a the largest milestone in Django's development to +date: a Web framework that a group of perfectionists can truly be proud of. + +Django 1.0 represents over three years of community development as an Open +Source project. Django's received contributions from hundreds of developers, +been translated into fifty languages, and today is used by developers on every +continent and in every kind of job. + +An interesting historical note: when Django was first released in July 2005, the +initial released version of Django came from an internal repository at revision +number 8825. Django 1.0 represents revision 8961 of our public repository. It +seems fitting that our 1.0 release comes at the moment where community +contributions overtake those made privately. + +Stability and forwards-compatibility +==================================== + +:doc:`The release of Django 1.0 </releases/1.0>` comes with a promise of API +stability and forwards-compatibility. In a nutshell, this means that code you +develop against Django 1.0 will continue to work against 1.1 unchanged, and you +should need to make only minor changes for any 1.X release. + +See the :doc:`API stability guide </misc/api-stability>` for full details. + +Backwards-incompatible changes +============================== + +Django 1.0 has a number of backwards-incompatible changes from Django 0.96. If +you have apps written against Django 0.96 that you need to port, see our +detailed porting guide: + +.. toctree:: + :maxdepth: 1 + + 1.0-porting-guide + +A complete list of backwards-incompatible changes can be found at +http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges. + +What's new in Django 1.0 +======================== + +A *lot*! + +Since Django 0.96, we've made over 4,000 code commits, fixed more than 2,000 +bugs, and edited, added, or removed around 350,000 lines of code. We've also +added 40,000 lines of new documentation, and greatly improved what was already +there. + +In fact, new documentation is one of our favorite features of Django 1.0, so we +might as well start there. First, there's a new documentation site: + + http://docs.djangoproject.com/ + +The documentation has been greatly improved, cleaned up, and generally made +awesome. There's now dedicated search, indexes, and more. + +We can't possibly document everything that's new in 1.0, but the documentation +will be your definitive guide. Anywhere you see something like: + +.. versionadded:: 1.0 + This feature is new in Django 1.0 + +You'll know that you're looking at something new or changed. + +The other major highlights of Django 1.0 are: + +Re-factored admin application +----------------------------- + +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: + +See the :doc:`admin reference </ref/contrib/admin/index>` for details + +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. + +See :doc:`/ref/unicode`. + +An improved 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`__. + +__ http://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. + +``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 shortly. Huge thanks go to +Justin Bronn, Jeremy Dunck, Brett Hoerner and Travis Pinney for their efforts in +creating and completing this feature. + +See http://geodjango.org/ for details. + +.. _Geographic Information Systems: http://en.wikipedia.org/wiki/Geographic_information_system + +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 </topics/files>`; 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. + +See :doc:`/howto/jython`. + +.. _Jython: http://www.jython.org/ + +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 <generic-relations>` for details. + +``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. + +See :ref:`ref-models-force-insert` for details. + +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 </topics/cache>`. + +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. :doc:`Full documentation +</ref/contrib/comments/index>` is available, as well as :doc:`an upgrade guide +</ref/contrib/comments/upgrade>` if you were using the previous incarnation of +the comments application. + +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. + +Known issues +============ + +We've done our best to make Django 1.0 as solid as possible, but unfortunately +there are a couple of issues that we know about in the release. + +Multi-table model inheritance with ``to_field`` +----------------------------------------------- + +If you're using :ref:`multiple table model inheritance +<multi-table-inheritance>`, be aware of this caveat: child models using a custom +``parent_link`` and ``to_field`` will cause database integrity errors. A set of +models like the following are **not valid**:: + + class Parent(models.Model): + name = models.CharField(max_length=10) + other_value = models.IntegerField(unique=True) + + class Child(Parent): + father = models.OneToOneField(Parent, primary_key=True, to_field="other_value", parent_link=True) + value = models.IntegerField() + +This bug will be fixed in the next release of Django. + +Caveats with support of certain databases +----------------------------------------- + +Django attempts to support as many features as possible on all database +backends. However, not all database backends are alike, and in particular many of the supported database differ greatly from version to version. It's a good idea to checkout our :doc:`notes on supported database </ref/databases>`: + + - :ref:`mysql-notes` + - :ref:`sqlite-notes` + - :ref:`oracle-notes` + diff --git a/parts/django/docs/releases/1.1-alpha-1.txt b/parts/django/docs/releases/1.1-alpha-1.txt new file mode 100644 index 0000000..b15a2a4 --- /dev/null +++ b/parts/django/docs/releases/1.1-alpha-1.txt @@ -0,0 +1,163 @@ +================================ +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:`QuerySet` with the results of the aggregate query. + +This feature is available as new :meth:`QuerySet.aggregate()`` and +:meth:`QuerySet.annotate()`` methods, and is covered in detail in :doc:`the ORM +aggregation documentation </topics/db/aggregation>` + +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 +:ref:`documentation for F expressions <query-expressions>`. + +Performance improvements +------------------------ + +.. currentmodule:: django.test + +Tests written using Django's :doc:`testing framework </topics/testing>` 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 </ref/contrib/csrf>` 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 </topics/forms/index>`) + now have two additional methods, ``hidden_fields()`` and ``visible_fields()``, + which return the list of hidden -- i.e., ``<input type="hidden">`` -- and + visible fields on the form, respectively. + +* The ``redirect_to`` generic view (see :doc:`the generic views documentation + </ref/generic-views>`) 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 <field-lookups>` 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 + </ref/templates/builtins>` 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: + + * http://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 </internals/contributing>` + +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/parts/django/docs/releases/1.1-beta-1.txt b/parts/django/docs/releases/1.1-beta-1.txt new file mode 100644 index 0000000..535f818 --- /dev/null +++ b/parts/django/docs/releases/1.1-beta-1.txt @@ -0,0 +1,208 @@ +=============================== +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 </releases/1.1-alpha-1>`, 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 :djadmin:`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 <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 +<proxy-models>`. 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 <proxy-vs-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.QuerySet.defer` and +:meth:`~django.db.models.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-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 </ref/contrib/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.client + +A couple of small but very useful improvements have been made to the +:doc:`testing framework </topics/testing>`: + + * 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 +</topics/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 </topics/cache>` 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 + </howto/auth-remote-user>` 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 <postgresql-notes>`. 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: + + * http://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 </internals/contributing>` + +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/parts/django/docs/releases/1.1-rc-1.txt b/parts/django/docs/releases/1.1-rc-1.txt new file mode 100644 index 0000000..f74444f --- /dev/null +++ b/parts/django/docs/releases/1.1-rc-1.txt @@ -0,0 +1,109 @@ +============================= +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 </releases/1.1-beta-1>`. + + +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 <naming-url-patterns>`. 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 +<topics-http-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 +<admin-reverse-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: + + * http://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 </internals/contributing>` + +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/parts/django/docs/releases/1.1.2.txt b/parts/django/docs/releases/1.1.2.txt new file mode 100644 index 0000000..90a6975 --- /dev/null +++ b/parts/django/docs/releases/1.1.2.txt @@ -0,0 +1,56 @@ +========================== +Django 1.1.2 release notes +========================== + +Welcome to Django 1.1.2! + +This is the second "bugfix" release in the Django 1.1 series, +improving the stability and performance of the Django 1.1 codebase. + +Django 1.1.2 maintains backwards compatibility with Django +1.1.0, but contain a number of fixes and other +improvements. Django 1.1.2 is a recommended upgrade for any +development or deployment currently using or targeting Django 1.1. + +For full details on the new features, backwards incompatibilities, and +deprecated features in the 1.1 branch, see the :doc:`/releases/1.1`. + +Backwards-incompatible changes in 1.1.2 +======================================= + +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. + +Cookie encoding +--------------- + +To fix bugs with cookies in Internet Explorer, Safari, and possibly other +browsers, our 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, especially if you are storing comma or semi-colon in +cookies and have javascript code that parses and manipulates cookie values +client-side. + +One new feature +=============== + +Ordinarily, a point release would not include new features, but in the +case of Django 1.1.2, we have made an exception to this rule. Django +1.2 (the next major release of Django) will contain a feature that +will improve protection against Cross-Site Request Forgery (CSRF) +attacks. This feature requires the use of a new :ttag:`csrf_token` +template tag in all forms that Django renders. + +To make it easier to support both 1.1.X and 1.2.X versions of Django with +the same templates, we have decided to introduce the :ttag:`csrf_token` template +tag to the 1.1.X branch. In the 1.1.X branch, :ttag:`csrf_token` does nothing - +it has no effect on templates or form processing. However, it means that the +same template will work with Django 1.2. diff --git a/parts/django/docs/releases/1.1.txt b/parts/django/docs/releases/1.1.txt new file mode 100644 index 0000000..3ca8344 --- /dev/null +++ b/parts/django/docs/releases/1.1.txt @@ -0,0 +1,463 @@ +======================== +Django 1.1 release notes +======================== + + +July 29, 2009 + +Welcome to Django 1.1! + +Django 1.1 includes a number of nifty `new features`_, lots of bug +fixes, and an easy upgrade path from Django 1.0. + +.. _new features: `What's new in Django 1.1`_ + +.. _backwards-incompatible-changes-1.1: + +Backwards-incompatible changes in 1.1 +===================================== + +Django has a policy of :doc:`API stability </misc/api-stability>`. This means +that, in general, code you develop against Django 1.0 should continue to work +against 1.1 unchanged. However, we do sometimes make backwards-incompatible +changes if they're necessary to resolve bugs, and there are a handful of such +(minor) changes between Django 1.0 and Django 1.1. + +Before upgrading to Django 1.1 you should double-check that the following +changes don't impact you, and upgrade your code if they do. + +Changes to constraint names +--------------------------- + +Django 1.1 modifies the method used to generate database constraint names so +that names are consistent regardless of machine word size. This change is +backwards incompatible for some users. + +If you are using a 32-bit platform, you're off the hook; you'll observe no +differences as a result of this change. + +However, **users on 64-bit platforms may experience some problems** using the +:djadmin:`reset` management command. Prior to this change, 64-bit platforms +would generate a 64-bit, 16 character digest in the constraint name; for +example:: + + ALTER TABLE myapp_sometable ADD CONSTRAINT object_id_refs_id_5e8f10c132091d1e FOREIGN KEY ... + +Following this change, all platforms, regardless of word size, will generate a +32-bit, 8 character digest in the constraint name; for example:: + + ALTER TABLE myapp_sometable ADD CONSTRAINT object_id_refs_id_32091d1e FOREIGN KEY ... + +As a result of this change, you will not be able to use the :djadmin:`reset` +management command on any table made by a 64-bit machine. This is because the +the new generated name will not match the historically generated name; as a +result, the SQL constructed by the reset command will be invalid. + +If you need to reset an application that was created with 64-bit constraints, +you will need to manually drop the old constraint prior to invoking +:djadmin:`reset`. + +Test cases are now run in a transaction +--------------------------------------- + +Django 1.1 runs tests inside a transaction, allowing better test performance +(see `test performance improvements`_ for details). + +This change is slightly backwards incompatible if existing tests need to test +transactional behavior, if they rely on invalid assumptions about the test +environment, or if they require a specific test case ordering. + +For these cases, :class:`~django.test.TransactionTestCase` can be used instead. +This is a just a quick fix to get around test case errors revealed by the new +rollback approach; in the long-term tests should be rewritten to correct the +test case. + +.. _removed-setremoteaddrfromforwardedfor-middleware: + +Removed ``SetRemoteAddrFromForwardedFor`` middleware +---------------------------------------------------- + +For convenience, Django 1.0 included an optional middleware class -- +``django.middleware.http.SetRemoteAddrFromForwardedFor`` -- which updated the +value of ``REMOTE_ADDR`` based on the HTTP ``X-Forwarded-For`` header commonly +set by some proxy configurations. + +It has been demonstrated that this mechanism cannot be made reliable enough for +general-purpose use, and that (despite documentation to the contrary) its +inclusion in Django may lead application developers to assume that the value of +``REMOTE_ADDR`` is "safe" or in some way reliable as a source of authentication. + +While not directly a security issue, we've decided to remove this middleware +with the Django 1.1 release. It has been replaced with a class that does nothing +other than raise a ``DeprecationWarning``. + +If you've been relying on this middleware, the easiest upgrade path is: + + * Examine `the code as it existed before it was removed`__. + + * Verify that it works correctly with your upstream proxy, modifying + it to support your particular proxy (if necessary). + + * Introduce your modified version of ``SetRemoteAddrFromForwardedFor`` as a + piece of middleware in your own project. + +__ http://code.djangoproject.com/browser/django/trunk/django/middleware/http.py?rev=11000#L33 + +Names of uploaded files are available later +------------------------------------------- + +.. currentmodule:: django.db.models + +In Django 1.0, files uploaded and stored in a model's :class:`FileField` were +saved to disk before the model was saved to the database. This meant that the +actual file name assigned to the file was available before saving. For example, +it was available in a model's pre-save signal handler. + +In Django 1.1 the file is saved as part of saving the model in the database, so +the actual file name used on disk cannot be relied on until *after* the model +has been saved. + +Changes to how model formsets are saved +--------------------------------------- + +.. currentmodule:: django.forms.models + +In Django 1.1, :class:`BaseModelFormSet` now calls :meth:`ModelForm.save()`. + +This is backwards-incompatible if you were modifying ``self.initial`` in a model +formset's ``__init__``, or if you relied on the internal ``_total_form_count`` +or ``_initial_form_count`` attributes of BaseFormSet. Those attributes are now +public methods. + +Fixed the ``join`` filter's escaping behavior +--------------------------------------------- + +The :ttag:`join` filter no longer escapes the literal value that is +passed in for the connector. + +This is backwards incompatible for the special situation of the literal string +containing one of the five special HTML characters. Thus, if you were writing +``{{ foo|join:"&" }}``, you now have to write ``{{ foo|join:"&" }}``. + +The previous behavior was a bug and contrary to what was documented +and expected. + +Permanent redirects and the ``redirect_to()`` generic view +---------------------------------------------------------- + +Django 1.1 adds a ``permanent`` argument to the +:func:`django.views.generic.simple.redirect_to()` view. This is technically +backwards-incompatible if you were using the ``redirect_to`` view with a +format-string key called 'permanent', which is highly unlikely. + +.. _deprecated-features-1.1: + +Features deprecated in 1.1 +========================== + +One feature has been marked as deprecated in Django 1.1: + + * You should no longer use ``AdminSite.root()`` to register that admin + views. That is, if your URLconf contains the line:: + + (r'^admin/(.*)', admin.site.root), + + You should change it to read:: + + (r'^admin/', include(admin.site.urls)), + +You should begin to remove use of this feature from your code immediately. + +``AdminSite.root`` will raise a ``PendingDeprecationWarning`` if used in +Django 1.1. This warning is hidden by default. In Django 1.2, this warning will +be upgraded to a ``DeprecationWarning``, which will be displayed loudly. Django +1.3 will remove ``AdminSite.root()`` entirely. + +For more details on our deprecation policies and strategy, see +:doc:`/internals/release-process`. + +What's new in Django 1.1 +======================== + +Quite a bit: since Django 1.0, we've made 1,290 code commits, fixed 1,206 bugs, +and added roughly 10,000 lines of documentation. + +The major new features in Django 1.1 are: + +ORM improvements +---------------- + +.. currentmodule:: django.db.models + +Two major enhancements have been added to Django's object-relational mapper +(ORM): aggregate support, and query expressions. + +Aggregate support +~~~~~~~~~~~~~~~~~ + +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:`QuerySet` with the results of the aggregate query. + +This feature is available as new :meth:`QuerySet.aggregate()`` and +:meth:`QuerySet.annotate()`` methods, and is covered in detail in :doc:`the ORM +aggregation documentation </topics/db/aggregation>`. + +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 +:ref:`documentation for F expressions <query-expressions>`. + +Model improvements +------------------ + +A number of features have been added to Django's model layer: + +"Unmanaged" models +~~~~~~~~~~~~~~~~~~ + +You can now control whether or not Django manages the life-cycle of the 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 the :djadmin:`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 <proxy-models>`: subclasses of existing +models that only add Python-level (rather than database-level) 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 +<proxy-models>`. 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 <proxy-vs-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.QuerySet.defer` and +:meth:`~django.db.models.QuerySet.only`. + +Testing improvements +-------------------- + +A few notable improvements have been made to the :doc:`testing framework +</topics/testing>`. + +Test performance improvements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. currentmodule:: django.test + +Tests written using Django's :doc:`testing framework </topics/testing>` 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. + +Test client improvements +------------------------ + +.. currentmodule:: django.test.client + +A couple of small -- but highly useful -- improvements have been made to the +test client: + + * 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 in the inheritance + chain, is still available if you need it. + +New admin features +------------------ + +Django 1.1 adds a couple of nifty new features to Django's admin interface: + +Editable fields on the change list +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can now make fields editable on the admin list views via the new +:ref:`list_editable <admin-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 </ref/contrib/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. + +Conditional view processing +--------------------------- + +Django now has much better support for :doc:`conditional view processing +</topics/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. + +URL namespaces +-------------- + +Django 1.1 improves :ref:`named URL patterns <naming-url-patterns>` with the +introduction of 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. In +other words, reusable applications like Django's admin interface may be +registered multiple times without URL conflicts. + +For full details, see :ref:`the documentation on defining URL namespaces +<topics-http-defining-url-namespaces>`. + +GeoDjango +--------- + +In Django 1.1, GeoDjango_ (i.e. ``django.contrib.gis``) has several new +features: + + * Support for SpatiaLite_ -- a spatial database for SQLite -- as a spatial + backend. + + * Geographic aggregates (``Collect``, ``Extent``, ``MakeLine``, ``Union``) + and ``F`` expressions. + + * New ``GeoQuerySet`` methods: ``collect``, ``geojson``, and + ``snap_to_grid``. + + * A new list interface methods for ``GEOSGeometry`` objects. + +For more details, see the `GeoDjango documentation`_. + +.. _geodjango: http://geodjango.org/ +.. _spatialite: http://www.gaia-gis.it/spatialite/ +.. _geodjango documentation: http://geodjango.org/docs/ + +Other improvements +------------------ + +Other new features and changes introduced since Django 1.0 include: + +* The :doc:`CSRF protection middleware </ref/contrib/csrf>` 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 </topics/forms/index>`) + now have two additional methods, ``hidden_fields()`` and ``visible_fields()``, + which return the list of hidden -- i.e., ``<input type="hidden">`` -- and + visible fields on the form, respectively. + +* The ``redirect_to`` generic view (see :doc:`the generic views documentation + </ref/generic-views>`) 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 <field-lookups>` 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 + </ref/templates/builtins>` for examples of this. + +* 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 </topics/cache>` 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 + </howto/auth-remote-user>` 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 <postgresql-notes>`. This is an advanced, PostgreSQL-specific + feature, that can make certain read-heavy applications a good deal + faster. + +What's next? +============ + +We'll take a short break, and then work on Django 1.2 will begin -- no rest for +the weary! If you'd like to help, 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``. Feel free to +join the discussions! + +Django's online documentation also includes pointers on how to contribute to +Django: + + * :doc:`How to contribute to Django </internals/contributing>` + +Contributions on any level -- developing code, writing documentation or simply +triaging tickets and helping to test proposed bugfixes -- are always welcome and +appreciated. + +And that's the way it is. diff --git a/parts/django/docs/releases/1.2-alpha-1.txt b/parts/django/docs/releases/1.2-alpha-1.txt new file mode 100644 index 0000000..4144a9a --- /dev/null +++ b/parts/django/docs/releases/1.2-alpha-1.txt @@ -0,0 +1,578 @@ +================================ +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 documentaton </ref/contrib/csrf>`. 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 :ref:`UPGRADE + INSTRUCTIONS <ref-csrf-upgrading-notes>` to fix those templates. + + * ``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<template-loaders>`. + +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<template_tag_thread_safety>`. + +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 :ref:`upgrading notes <ref-csrf-upgrading-notes>`. + +``SMTPConnection`` +------------------ + +The ``SMTPConnection`` class has been deprecated in favor of a generic +E-mail 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 e-mail 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 e-mail, 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 + ========================================= ========================== + :setting:`DATABASE_ENGINE` :setting:`ENGINE` + :setting:`DATABASE_HOST` :setting:`HOST` + :setting:`DATABASE_NAME` :setting:`NAME` + :setting:`DATABASE_OPTIONS` :setting:`OPTIONS` + :setting:`DATABASE_PASSWORD` :setting:`PASSWORD` + :setting:`DATABASE_PORT` :setting:`PORT` + :setting:`DATABASE_USER` :setting:`USER` + :setting:`TEST_DATABASE_CHARSET` :setting:`TEST_CHARSET` + :setting:`TEST_DATABASE_COLLATION` :setting:`TEST_COLLATION` + :setting:`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 </internals/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 </ref/contrib/messages>`. 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</ref/contrib/csrf>`. 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. + +E-mail Backends +--------------- + +You can now :ref:`configure the way that Django sends e-mail +<topic-email-backends>`. Instead of using SMTP to send all e-mail, you +can now choose a configurable e-mail 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 e-mail backend that will allow +Django's standard :doc:`mail sending methods</topics/email>` to use +those facilities. + +This also makes it easier to debug mail sending - Django ships with +backend implementations that allow you to send e-mail to a +:ref:`file<topic-email-file-backend>`, to the +:ref:`console<topic-email-console-backend>`, or to +:ref:`memory<topic-email-memory-backend>` - you can even configure all +e-mail to be :ref:`thrown away<topic-email-dummy-backend>`. + +Messages Framework +------------------ + +Django now includes a robust and configurable :doc:`messages framework +</ref/contrib/messages>` 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 +</topics/db/multi-db>` 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 + + <div + {% if user.email|lower == message.recipient|lower %} + class="highlight" + {% endif %} + >{{ message }}</div> + +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 <template-loaders>` 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<topic-template-alternate-language>`. + +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 </topics/i18n/index>` 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 <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 along side 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 <syntax-coloring>`. + + +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: + + * http://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 </internals/contributing>` + +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/parts/django/docs/releases/1.2-beta-1.txt b/parts/django/docs/releases/1.2-beta-1.txt new file mode 100644 index 0000000..2a12ef3 --- /dev/null +++ b/parts/django/docs/releases/1.2-beta-1.txt @@ -0,0 +1,173 @@ +=============================== +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 </releases/1.2-alpha-1>` 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 </misc/api-stability>`, +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 +<topics-testing-test_runner>`. + + +Syndication feeds +----------------- + +The :class:`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 </ref/contrib/syndication>`. + +.. _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 </topics/auth>` +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 </topics/auth>` 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: + + * http://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 </internals/contributing>` + +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/parts/django/docs/releases/1.2-rc-1.txt b/parts/django/docs/releases/1.2-rc-1.txt new file mode 100644 index 0000000..b599dcc --- /dev/null +++ b/parts/django/docs/releases/1.2-rc-1.txt @@ -0,0 +1,101 @@ +============================= +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 +</releases/1.2-alpha-1>` and :doc:`1.2 beta </releases/1.2-beta-1>` +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 </internals/release-process>`, 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: + + * http://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 </internals/contributing>` + +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/parts/django/docs/releases/1.2.2.txt b/parts/django/docs/releases/1.2.2.txt new file mode 100644 index 0000000..4ae74ab --- /dev/null +++ b/parts/django/docs/releases/1.2.2.txt @@ -0,0 +1,29 @@ +========================== +Django 1.2.2 release notes +========================== + +Welcome to Django 1.2.2! + +This is the second "bugfix" release in the Django 1.2 series, +improving the stability and performance of the Django 1.2 codebase. + +Django 1.2.2 maintains backwards compatibility with Django +1.2.1, but contain a number of fixes and other +improvements. Django 1.2.2 is a recommended upgrade for any +development or deployment currently using or targeting Django 1.2. + +For full details on the new features, backwards incompatibilities, and +deprecated features in the 1.2 branch, see the :doc:`/releases/1.2`. + +One new feature +=============== + +Ordinarily, a point release would not include new features, but in the +case of Django 1.2.2, we have made an exception to this rule. + +In order to test a bug fix that forms part of the 1.2.2 release, it +was necessary to add a feature -- the ``enforce_csrf_checks`` flag -- +to the :mod:`test client <django.test.client>`. This flag forces +the test client to perform full CSRF checks on forms. The default +behavior of the test client hasn't changed, but if you want to do +CSRF checks with the test client, it is now possible to do so. diff --git a/parts/django/docs/releases/1.2.4.txt b/parts/django/docs/releases/1.2.4.txt new file mode 100644 index 0000000..5472a28 --- /dev/null +++ b/parts/django/docs/releases/1.2.4.txt @@ -0,0 +1,52 @@ +========================== +Django 1.2.4 release notes +========================== + +Welcome to Django 1.2.4! + +This is the fourth "bugfix" release in the Django 1.2 series, +improving the stability and performance of the Django 1.2 codebase. + +Django 1.2.4 maintains backwards compatibility with Django +1.2.3, but contain a number of fixes and other +improvements. Django 1.2.4 is a recommended upgrade for any +development or deployment currently using or targeting Django 1.2. + +For full details on the new features, backwards incompatibilities, and +deprecated features in the 1.2 branch, see the :doc:`/releases/1.2`. + +One new feature +=============== + +Ordinarily, a point release would not include new features, but in the +case of Django 1.2.4, we have made an exception to this rule. + +One of the bugs fixed in Django 1.2.4 involves a set of +circumstances whereby a running a test suite on a multiple database +configuration could cause the original source database (i.e., the +actual production database) to be dropped, causing catastrophic loss +of data. In order to provide a fix for this problem, it was necessary +to introduce a new setting -- :setting:`TEST_DEPENDENCIES` -- that +allows you to define any creation order dependencies in your database +configuration. + +Most users -- even users with multiple-database configurations -- need +not be concerned about the data loss bug, or the manual configuration of +:setting:`TEST_DEPENDENCIES`. See the `original problem report`_ +documentation on :ref:`controlling the creation order of test +databases <topics-testing-creation-dependencies>` for details. + +.. _original problem report: http://code.djangoproject.com/ticket/14415 + +GeoDjango +========= + +The function-based :setting:`TEST_RUNNER` previously used to execute +the GeoDjango test suite, :func:`django.contrib.gis.tests.run_gis_tests`, +was finally deprecated in favor of a class-based test runner, +:class:`django.contrib.gis.tests.GeoDjangoTestSuiteRunner`, added in this +release. + +In addition, the GeoDjango test suite is now included when +:ref:`running the Django test suite <running-unit-tests>` with ``runtests.py`` +and using :ref:`spatial database backends <spatial-backends>`. diff --git a/parts/django/docs/releases/1.2.txt b/parts/django/docs/releases/1.2.txt new file mode 100644 index 0000000..efff2a6 --- /dev/null +++ b/parts/django/docs/releases/1.2.txt @@ -0,0 +1,1139 @@ +======================== +Django 1.2 release notes +======================== + +*May 17, 2010.* + +Welcome to Django 1.2! + +Nearly a year in the making, Django 1.2 packs an impressive list of `new +features`_ and lots of bug fixes. These release notes cover the new features, +as well as important changes you'll want to be aware of when upgrading from +Django 1.1 or older versions. + +.. _new features: `What's new in Django 1.2`_ + +Overview +======== + +Django 1.2 introduces several large, important new features, including: + + * Support for `multiple database connections`_ in a single Django instance. + + * `Model validation`_ inspired by Django's form validation. + + * Vastly `improved protection against Cross-Site Request Forgery`_ (CSRF). + + * A new `user "messages" framework`_ with support for cookie- and session-based + message for both anonymous and authenticated users. + + * Hooks for `object-level permissions`_, `permissions for anonymous users`_, + and `more flexible username requirements`_. + + * Customization of e-mail sending via `e-mail backends`_. + + * New :ref:`"smart" if template tag <new-in-1.2-smart-if>` which supports + comparison operators. + +.. _multiple database connections: `support for multiple databases`_ +.. _improved protection against Cross-Site Request Forgery: `improved CSRF protection`_ +.. _user "messages" framework: `messages framework`_ +.. _more flexible username requirements: `relaxed requirements for usernames`_ + +These are just the highlights; full details and a complete list of features `may +be found below`_. + +.. _may be found below: `what's new in django 1.2`_ + +.. seealso:: + + `Django Advent`_ covered the release of Django 1.2 with a series of + articles and tutorials that cover some of the new features in depth. + +.. _django advent: http://djangoadvent.com/ + +Wherever possible these features have been introduced in a backwards-compatible +manner per :doc:`our API stability policy </misc/api-stability>` policy. + +However, a handful of features *have* changed in ways that, for some users, will be +backwards-incompatible. The big changes are: + + * Support for Python 2.3 has been dropped. See the full notes + below. + + * The new CSRF protection framework is not backwards-compatible with + the old system. Users of the old system will not be affected until + the old system is removed in Django 1.4. + + However, upgrading to the new CSRF protection framework requires a few + important backwards-incompatible changes, detailed in `CSRF Protection`_, + below. + + * Authors of custom :class:`~django.db.models.Field` subclasses should be + aware that a number of methods have had a change in prototype, detailed + under `get_db_prep_*() methods on Field`_, below. + + * The internals of template tags have changed somewhat; authors of custom + template tags that need to store state (e.g. custom control flow tags) + should ensure that their code follows the new rules for `stateful template + tags`_ + + * The :func:`~django.contrib.auth.decorators.user_passes_test`, + :func:`~django.contrib.auth.decorators.login_required`, and + :func:`~django.contrib.auth.decorators.permission_required`, decorators + from :mod:`django.contrib.auth` only apply to functions and no longer + work on methods. There's a simple one-line fix `detailed below`_. + +.. _detailed below: `user_passes_test, login_required and permission_required`_ + +Again, these are just the big features that will affect the most users. Users +upgrading from previous versions of Django are heavily encouraged to consult +the complete list of :ref:`backwards-incompatible changes +<backwards-incompatible-changes-1.2>` and the list of :ref:`deprecated +features <deprecated-features-1.2>`. + +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 </internals/release-process>`, 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. + +What's new in Django 1.2 +======================== + +Support for multiple databases +------------------------------ + +Django 1.2 adds the ability to use :doc:`more than one database +</topics/db/multi-db>` in your Django project. Queries can be issued at a +specific database with the `using()` method on ``QuerySet`` objects. Individual +objects can be saved to a specific database by providing a ``using`` argument +when you call ``save()``. + +Model validation +---------------- + +Model instances now have support for :ref:`validating their own data +<validating-objects>`, and both model and form fields now accept configurable +lists of :doc:`validators </ref/validators>` specifying reusable, encapsulated +validation behavior. Note, however, that validation must still be performed +explicitly. Simply invoking a model instance's ``save()`` method will not +perform any validation of the instance's data. + +Improved CSRF protection +------------------------ + +Django now has much improved protection against :doc:`Cross-Site Request Forgery +(CSRF) attacks</ref/contrib/csrf>`. 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. + +Messages framework +------------------ + +Django now includes a robust and configurable :doc:`messages framework +</ref/contrib/messages>` 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). + +Object-level permissions +------------------------ + +A foundation for specifying permissions at the per-object level has been added. +Although there is no implementation of this in core, a custom authentication +backend can provide this implementation and it will be used by +:class:`django.contrib.auth.models.User`. See the :doc:`authentication docs +</topics/auth>` for more information. + +Permissions for anonymous users +------------------------------- + +If you provide a custom auth backend with ``supports_anonymous_user`` set to +``True``, AnonymousUser will check the backend for permissions, just like +User already did. This is useful for centralizing permission handling - apps +can always delegate the question of whether something is allowed or not to +the authorization/authentication backend. See the :doc:`authentication +docs </topics/auth>` for more details. + +Relaxed requirements for usernames +---------------------------------- + +The built-in :class:`~django.contrib.auth.models.User` model's +:attr:`~django.contrib.auth.models.User.username` field now allows a wider range +of characters, including ``@``, ``+``, ``.`` and ``-`` characters. + +E-mail backends +--------------- + +You can now :ref:`configure the way that Django sends e-mail +<topic-email-backends>`. Instead of using SMTP to send all e-mail, you +can now choose a configurable e-mail 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 e-mail backend that will allow +Django's standard :doc:`mail sending methods</topics/email>` to use +those facilities. + +This also makes it easier to debug mail sending. Django ships with +backend implementations that allow you to send e-mail to a +:ref:`file<topic-email-file-backend>`, to the +:ref:`console<topic-email-console-backend>`, or to +:ref:`memory<topic-email-memory-backend>`. You can even configure all +e-mail to be :ref:`thrown away<topic-email-dummy-backend>`. + +.. _new-in-1.2-smart-if: + +"Smart" :ttag:`if` tag +---------------------- + +The :ttag:`if` tag has been upgraded to be much more powerful. First, we've +added support for comparison operators. No longer will you have to type: + +.. code-block:: html+django + + {% ifnotequal a b %} + ... + {% endifnotequal %} + +You can now do this: + +.. code-block:: html+django + + {% if a != b %} + ... + {% endif %} + +There's really no reason to use ``{% ifequal %}`` or ``{% ifnotequal %}`` +anymore, unless you're the nostalgic type. + +The operators supported are ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=``, +``in`` and ``not 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 + + <div + {% if user.email|lower == message.recipient|lower %} + class="highlight" + {% endif %} + >{{ message }}</div> + +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 <template-loaders>` to load templates once, then +cache the 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<topic-template-alternate-language>`. + +Natural keys in fixtures +------------------------ + +Fixtures can now 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. + +Fast failure for tests +---------------------- + +Both the :djadmin:`test` subcommand of ``django-admin.py`` and the +``runtests.py`` script used to run Django's own test suite now support a +``--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 that +were run before the interruption. + +``BigIntegerField`` +------------------- + +Models can now use a 64-bit :class:`~django.db.models.BigIntegerField` type. + +Improved localization +--------------------- + +Django's :doc:`internationalization framework </topics/i18n/index>` has been expanded +with 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 <format-localization>` for more details. + +``readonly_fields`` in ``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 a ``DJANGO_COLORS`` environment variable to modify or disable +the colors used by ``django-admin.py`` to provide :ref:`syntax highlighting +<syntax-coloring>`. + +Syndication feeds as views +-------------------------- + +:doc:`Syndication feeds </ref/contrib/syndication>` can now be used directly as +views in your :doc:`URLconf </topics/http/urls>`. This means that you can +maintain complete control over the URL structure of your feeds. Like any other +view, feeds views are passed a ``request`` object, so you can do anything you +would normally do with a view, like user based access control, or making a feed +a named URL. + +GeoDjango +--------- + +The most significant new feature for :doc:`GeoDjango </ref/contrib/gis/index>` +in 1.2 is support for multiple spatial databases. As a result, +the following :ref:`spatial database backends <spatial-backends>` +are now included: + +* :mod:`django.contrib.gis.db.backends.postgis` +* :mod:`django.contrib.gis.db.backends.mysql` +* :mod:`django.contrib.gis.db.backends.oracle` +* :mod:`django.contrib.gis.db.backends.spatialite` + +GeoDjango now supports the rich capabilities added +in the `PostGIS 1.5 release <http://postgis.refractions.net/documentation/manual-1.5/>`_. +New features include suppport for the the :ref:`geography type <geography-type>` +and enabling of :ref:`distance queries <distance-queries>` +with non-point geometries on geographic coordinate systems. + +Support for 3D geometry fields was added, and may be enabled +by setting the :attr:`~django.contrib.gis.db.models.GeometryField.dim` +keyword to 3 in your :class:`~django.contrib.gis.db.models.GeometryField`. +The :class:`~django.contrib.gis.db.models.Extent3D` aggregate +and :meth:`~django.contrib.gis.db.models.GeoQuerySet.extent3d` ``GeoQuerySet`` +method were added as a part of this feature. + +The following :class:`~django.contrib.gis.db.models.GeoQuerySet` +methods are new in 1.2: + +* :meth:`~django.contrib.gis.db.models.GeoQuerySet.force_rhr` +* :meth:`~django.contrib.gis.db.models.GeoQuerySet.reverse_geom` +* :meth:`~django.contrib.gis.db.models.GeoQuerySet.geohash` + +The :ref:`GEOS interface <ref-geos>` was updated to use +thread-safe C library functions when available on the platform. + +The :ref:`GDAL interface <ref-gdal>` now allows the user to +set a :attr:`~django.contrib.gis.gdal.Layer.spatial_filter` on +the features returned when iterating over a +:class:`~django.contrib.gis.gdal.Layer`. + +Finally, :doc:`GeoDjango's documentation </ref/contrib/gis/index>` is now +included with Django's and is no longer +hosted separately at `geodjango.org <http://geodjango.org/>`_. + +.. _1.2-js-assisted-inlines: + +JavaScript-assisted handling of inline related objects in the admin +------------------------------------------------------------------- + +If a user has JavaScript enabled in their browser, the interface for +inline objects in the admin now allows inline objects to be +dynamically added and removed. Users without JavaScript-enabled +browsers will see no change in the behavior of inline objects. + +New ``now`` template tag format specifier characters: ``c`` and ``u`` +--------------------------------------------------------------------- + +The argument to the :ttag:`now` has gained two new format characters: +``c`` to specify that a datetime value should be formatted in ISO 8601 +format, and ``u`` that allows output of the microseconds part of a +datetime or time value. + +These are also available in others parts like the :tfilter:`date` and +:tfilter:`time` template filters, the ``humanize`` template tag library +and the new `format localization`_ framework. + +.. _format localization: `Improved localization`_ + +.. _backwards-incompatible-changes-1.2: + +Backwards-incompatible changes in 1.2 +===================================== + +Wherever possible the new features above have been introduced in a +backwards-compatible manner per :doc:`our API stability policy +</misc/api-stability>` policy. This means that practically all existing +code which worked with Django 1.1 will continue to work with Django +1.2; such code will, however, begin issuing warnings (see below for +details). + +However, a handful of features *have* changed in ways that, for some +users, will be immediately backwards-incompatible. Those changes are +detailed below. + +CSRF Protection +--------------- + +We've made large changes to the way CSRF protection works, detailed in +:doc:`the CSRF documentaton </ref/contrib/csrf>`. Here are the major changes you +should 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. If you + have used custom templates for contrib views, you MUST READ THE :ref:`UPGRADE + INSTRUCTIONS <ref-csrf-upgrading-notes>` to fix those templates. + + * ``CsrfViewMiddleware`` is included in :setting:`MIDDLEWARE_CLASSES` by + default. This turns on CSRF protection by default, so 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. + + * All of the CSRF has moved from contrib to core (with backwards + compatible imports in the old locations, which are deprecated and + will cease to be supported in Django 1.4). + +``get_db_prep_*()`` methods on ``Field`` +---------------------------------------- + +Prior to Django 1.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 db_type(self): + # ... + + 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 db_type(self, connection): + # ... + + 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 -- +``db_type`` and ``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 from 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. + +We've provided conversion functions that will transparently +convert functions adhering to the old prototype into functions +compatible with the new prototype. However, these conversion functions +will be removed in Django 1.4, so you should upgrade your ``Field`` +definitions to use the new prototype as soon as possible. + +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 their ``Node`` subclass +have always been vulnerable to thread-safety and other issues; as of +Django 1.2, however, they may also cause problems when used with the +new :ref:`cached template loader<template-loaders>`. + +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 from your own code, you should ensure that the +``Node`` implementation for each tag is thread-safe. For more +information, see +:ref:`template tag thread safety considerations<template_tag_thread_safety>`. + +You may also need to update your templates if you were relying on the +implementation of Django's template tags *not* being thread safe. The +:ttag:`cycle` tag is the most likely to be affected in this way, +especially when used in conjunction with the :ttag:`include` tag. +Consider the following template fragment:: + + {% for object in object_list %} + {% include "subtemplate.html" %} + {% endfor %} + +with a ``subtemplate.html`` that reads:: + + {% cycle 'even' 'odd' %} + +Using the non-thread-safe, pre-Django 1.2 renderer, this would output:: + + even odd even odd ... + +Using the thread-safe Django 1.2 renderer, you will instead get:: + + even even even even ... + +This is because each rendering of the :ttag:`include` tag is an +independent rendering. When the :ttag:`cycle` tag was not thread safe, +the state of the :ttag:`cycle` tag would leak between multiple +renderings of the same :ttag:`include`. Now that the :ttag:`cycle` tag +is thread safe, this leakage no longer occurs. + +``user_passes_test``, ``login_required`` and ``permission_required`` +-------------------------------------------------------------------- + +``django.contrib.auth.decorators`` provides the decorators +``login_required``, ``permission_required`` and +``user_passes_test``. Previously it was possible to use these +decorators both on functions (where the first argument is 'request') +and on methods (where the first argument is 'self', and the second +argument is 'request'). Unfortunately, flaws were discovered in the +code supporting this: it only works in limited circumstances, and +produces errors that are very difficult to debug when it does not +work. + +For this reason, the 'auto adapt' behavior has been removed, and if +you are using these decorators on methods, you will need to manually +apply :func:`django.utils.decorators.method_decorator` to convert the +decorator to one that works with methods. For example, you would +change code from this:: + + class MyClass(object): + + @login_required + def my_view(self, request): + pass + +to this:: + + from django.utils.decorators import method_decorator + + class MyClass(object): + + @method_decorator(login_required) + def my_view(self, request): + pass + +or:: + + from django.utils.decorators import method_decorator + + login_required_m = method_decorator(login_required) + + class MyClass(object): + + @login_required_m + def my_view(self, request): + pass + +For those of you who've been following the development trunk, this +change also applies to other decorators introduced since 1.1, +including ``csrf_protect``, ``cache_control`` and anything created +using ``decorator_from_middleware``. + +: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, +these strings could be used as variable names. Now, the keyword status +is always enforced, and template code such as ``{% if not %}`` or ``{% +if and %}`` will throw a ``TemplateSyntaxError``. Also, ``in`` is a +new keyword and so is not a valid variable name in this tag. + +``LazyObject`` +-------------- + +``LazyObject`` is an undocumented-but-often-used 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 named +``get_all_members()``. Since this could easily lead to name clashes, it has been +changed to use the standard Python introspection method, involving +``__members__`` and ``__dir__()``. + +If you used ``LazyObject`` in your own code +and implemented the ``get_all_members()`` method for wrapped objects, you'll need +to make a couple of changes: + +First, 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 +introspection method for Python 2.6 and above. If you require support for Python +versions earlier than 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 +be prepared to handle or filter out the ``_state`` attribute. + +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, because 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. + +Cookie encoding +--------------- + +To fix bugs with cookies in Internet Explorer, Safari, and possibly +other browsers, our encoding of cookie values was changed so that the +comma and semicolon are treated as non-safe characters, and are +therefore encoded as ``\054`` and ``\073`` respectively. This could +produce backwards incompatibilities, especially if you are storing +comma or semi-colon in cookies and have javascript code that parses +and manipulates cookie values client-side. + +``ModelForm.is_valid()`` and ``ModelForm.errors`` +------------------------------------------------- + +Much of the validation work for ModelForms has been moved down to the model +level. As a result, the first time you call ``ModelForm.is_valid()``, access +``ModelForm.errors`` or otherwise trigger form validation, your model will be +cleaned in-place. This conversion used to happen when the model was saved. If +you need an unmodified instance of your model, you should pass a copy to the +``ModelForm`` constructor. + +``BooleanField`` on MySQL +-------------------------- + +In previous versions of Django, a model's ``BooleanField`` under MySQL +would return its value as either ``1`` or ``0``, instead of ``True`` +or ``False``; for most people this wasn't a problem because ``bool`` +is a subclass of ``int`` in Python. In Django 1.2, however, +``BooleanField`` on MySQL correctly returns a real ``bool``. The only +time this should ever be an issue is if you were expecting the +``repr`` of a ``BooleanField`` to print ``1`` or ``0``. + +Changes to the interpretation of ``max_num`` in FormSets +-------------------------------------------------------- + +As part of enhancements made to the handling of FormSets, the default +value and interpretation of the ``max_num`` parameter to the +:ref:`django.forms.formsets.formset_factory() <formsets-max-num>` and +:ref:`django.forms.models.modelformset_factory() +<model-formsets-max-num>` functions has changed slightly. This +change also affects the way the ``max_num`` argument is :ref:`used for +inline admin objects <ref-contrib-admin-inline-max-num>` + +Previously, the default value for ``max_num`` was ``0`` (zero). +FormSets then used the boolean value of ``max_num`` to determine if a +limit was to be imposed on the number of generated forms. The default +value of ``0`` meant that there was no default limit on the number of +forms in a FormSet. + +Starting with 1.2, the default value for ``max_num`` has been changed +to ``None``, and FormSets will differentiate between a value of +``None`` and a value of ``0``. A value of ``None`` indicates that no +limit on the number of forms is to be imposed; a value of ``0`` +indicates that a maximum of 0 forms should be imposed. This doesn't +necessarily mean that no forms will be displayed -- see the +:ref:`ModelFormSet documentation <model-formsets-max-num>` for more +details. + +If you were manually specifying a value of ``0`` for ``max_num``, you +will need to update your FormSet and/or admin definitions. + +.. seealso:: + + :ref:`1.2-js-assisted-inlines` + +``email_re`` +------------ + +An undocumented regular expression for validating email addresses has been moved +from ``django.form.fields`` to ``django.core.validators``. You will need to +update your imports if you are using it. + +.. _deprecated-features-1.2: + +Features deprecated in 1.2 +========================== + +Finally, Django 1.2 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.2. This warning will be +silent by default, but may be turned on using Python's `warnings +module`_, or by running Python with a ``-Wd`` or `-Wall` flag. + +.. _warnings module: http://docs.python.org/library/warnings.html + +In Django 1.3, these warnings will become a ``DeprecationWarning``, +which is *not* silent. In Django 1.4 support for these features will +be removed entirely. + +.. seealso:: + + For more details, see the documentation :doc:`Django's release process + </internals/release-process>` and our :doc:`deprecation timeline + </internals/deprecation>`.` + +.. _specifying-databases: + +Specifying databases +-------------------- + +Prior to Django 1.2, 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. Until then, old-style database settings will be +automatically translated to the new-style format. + +In the old-style (pre 1.2) format, you had a number of ``DATABASE_`` +settings in your settings file. For example:: + + DATABASE_NAME = 'test_db' + DATABASE_ENGINE = 'postgresql_psycopg2' + DATABASE_USER = 'myusername' + DATABASE_PASSWORD = 's3krit' + +These settings are now in 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. The previous sample settings would now look like this:: + + DATABASES = { + 'default': { + 'NAME': 'test_db', + 'ENGINE': 'django.db.backends.postgresql_psycopg2', + 'USER': 'myusername', + 'PASSWORD': 's3krit', + } + } + +This affects the following settings: + + ========================================= ========================== + Old setting New Setting + ========================================= ========================== + :setting:`DATABASE_ENGINE` :setting:`ENGINE` + :setting:`DATABASE_HOST` :setting:`HOST` + :setting:`DATABASE_NAME` :setting:`NAME` + :setting:`DATABASE_OPTIONS` :setting:`OPTIONS` + :setting:`DATABASE_PASSWORD` :setting:`PASSWORD` + :setting:`DATABASE_PORT` :setting:`PORT` + :setting:`DATABASE_USER` :setting:`USER` + :setting:`TEST_DATABASE_CHARSET` :setting:`TEST_CHARSET` + :setting:`TEST_DATABASE_COLLATION` :setting:`TEST_COLLATION` + :setting:`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``). + +``postgresql`` database backend +------------------------------- + +The ``psycopg1`` library has not been updated since October 2005. As a +result, the ``postgresql`` database backend, which uses this library, +has been deprecated. + +If you are currently using the ``postgresql`` backend, you should +migrate to using the ``postgresql_psycopg2`` backend. To update your +code, install the ``psycopg2`` library and change the +:setting:`DATABASE_ENGINE` setting to use +``django.db.backends.postgresql_psycopg2``. + +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 :ref:`upgrading notes +<ref-csrf-upgrading-notes>`. + +``SMTPConnection`` +------------------ + +The ``SMTPConnection`` class has been deprecated in favor of a generic +e-mail 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 e-mail 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 e-mail, 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) + +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 </internals/release-process>`. + +To upgrade your code, you need to replace any instances of this:: + + 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 </ref/contrib/messages>`. 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 this:: + + 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. + +Function-based 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 +<topics-testing-test_runner>`. + +.. _1.2-updating-feeds: + +``Feed`` in ``django.contrib.syndication.feeds`` +------------------------------------------------ + +The :class:`django.contrib.syndication.feeds.Feed` class has been +replaced by the :class:`django.contrib.syndication.views.Feed` class. +The old ``feeds.Feed`` class is deprecated, and will be removed in +Django 1.4. + +The new class has an almost identical API, but allows instances to be +used as views. For example, consider the use of the old framework in +the following :doc:`URLconf </topics/http/urls>`:: + + from django.conf.urls.defaults import * + from myproject.feeds import LatestEntries, LatestEntriesByCategory + + feeds = { + 'latest': LatestEntries, + 'categories': LatestEntriesByCategory, + } + + urlpatterns = patterns('', + # ... + (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed', + {'feed_dict': feeds}), + # ... + ) + +Using the new Feed class, these feeds can be deployed directly as views:: + + from django.conf.urls.defaults import * + from myproject.feeds import LatestEntries, LatestEntriesByCategory + + urlpatterns = patterns('', + # ... + (r'^feeds/latest/$', LatestEntries()), + (r'^feeds/categories/(?P<category_id>\d+)/$', LatestEntriesByCategory()), + # ... + ) + +If you currently use the ``feed()`` view, the ``LatestEntries`` class would +often not need to be modified apart from subclassing the new +:class:`~django.contrib.syndication.views.Feed` class. The exception is if +Django was automatically working out the name of the template to use to render +the feed's description and title elements (if you were not specifying the +``title_template`` and ``description_template`` attributes). You should ensure +that you always specify ``title_template`` and ``description_template`` +attributes, or provide ``item_title()`` and ``item_description()`` methods. + +However, ``LatestEntriesByCategory`` uses the ``get_object()`` method +with the ``bits`` argument to specify a specific category to show. In +the new :class:`~django.contrib.syndication.views.Feed` class, +``get_object()`` method takes a ``request`` and arguments from the +URL, so it would look like this:: + + from django.contrib.syndication.views import Feed + from django.shortcuts import get_object_or_404 + from myproject.models import Category + + class LatestEntriesByCategory(Feed): + def get_object(self, request, category_id): + return get_object_or_404(Category, id=category_id) + + # ... + +Additionally, the ``get_feed()`` method on ``Feed`` classes now take +different arguments, which may impact you if you use the ``Feed`` +classes directly. Instead of just taking an optional ``url`` argument, +it now takes two arguments: the object returned by its own +``get_object()`` method, and the current ``request`` object. + +To take into account ``Feed`` classes not being initialized for each +request, the ``__init__()`` method now takes no arguments by default. +Previously it would have taken the ``slug`` from the URL and the +``request`` object. + +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 </ref/contrib/syndication>`. + +.. _RSS best practices: http://www.rssboard.org/rss-profile + +Technical message IDs +--------------------- + +Up to version 1.1 Django used :ref:`technical message IDs<technical-messages>` +to provide localizers the possibility to translate date and time formats. They +were translatable :term:`translation strings <translation string>` that could +be recognized because they were all upper case (for example +``DATETIME_FORMAT``, ``DATE_FORMAT``, ``TIME_FORMAT``). They have been +deprecated in favor of the new :ref:`Format localization +<format-localization>` infrastructure that allows localizers to specify that +information in a ``formats.py`` file in the corresponding +``django/conf/locale/<locale name>/`` directory. + +GeoDjango +--------- + +To allow support for multiple databases, the GeoDjango database internals were +changed substantially. The largest backwards-incompatible change is that +the module ``django.contrib.gis.db.backend`` was renamed to +:mod:`django.contrib.gis.db.backends`, where the full-fledged +:ref:`spatial database backends <spatial-backends>` now exist. The +following sections provide information on the most-popular APIs that +were affected by these changes. + +``SpatialBackend`` +^^^^^^^^^^^^^^^^^^ + +Prior to the creation of the separate spatial backends, the +``django.contrib.gis.db.backend.SpatialBackend`` object was +provided as an abstraction to introspect on the capabilities of +the spatial database. All of the attributes and routines provided by +``SpatialBackend`` are now a part of the ``ops`` attribute of the +database backend. + +The old module ``django.contrib.gis.db.backend`` is still provided +for backwards-compatibility access to a ``SpatialBackend`` object, +which is just an alias to the ``ops`` module of the +*default* spatial database connection. + +Users that were relying on undocumented modules and objects +within ``django.contrib.gis.db.backend``, rather the abstractions +provided by ``SpatialBackend``, are required to modify their code. +For example, the following import which would work in 1.1 and +below:: + + from django.contrib.gis.db.backend.postgis import PostGISAdaptor + +Would need to be changed:: + + from django.db import connection + PostGISAdaptor = connection.ops.Adapter + +``SpatialRefSys`` and ``GeometryColumns`` models +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In previous versions of GeoDjango, :mod:`django.contrib.gis.db.models` +had ``SpatialRefSys`` and ``GeometryColumns`` models for querying +the OGC spatial metadata tables ``spatial_ref_sys`` and ``geometry_columns``, +respectively. + +While these aliases are still provided, they are only for the +*default* database connection and exist only if the default connection +is using a supported spatial database backend. + +.. note:: + + Because the table structure of the OGC spatial metadata tables + differs across spatial databases, the ``SpatialRefSys`` and + ``GeometryColumns`` models can no longer be associated with + the ``gis`` application name. Thus, no models will be returned + when using the ``get_models`` method in the following example:: + + >>> from django.db.models import get_app, get_models + >>> get_models(get_app('gis')) + [] + +To get the correct ``SpatialRefSys`` and ``GeometryColumns`` +for your spatial database use the methods provided by the spatial backend:: + + >>> from django.db import connections + >>> SpatialRefSys = connections['my_spatialite'].ops.spatial_ref_sys() + >>> GeometryColumns = connections['my_postgis'].ops.geometry_columns() + +.. note:: + + When using the models returned from the ``spatial_ref_sys()`` and + ``geometry_columns()`` method, you'll still need to use the + correct database alias when querying on the non-default connection. + In other words, to ensure that the models in the example above + use the correct database:: + + sr_qs = SpatialRefSys.objects.using('my_spatialite').filter(...) + gc_qs = GeometryColumns.objects.using('my_postgis').filter(...) + +Language code ``no`` +-------------------- + +The currently used language code for Norwegian Bokmål ``no`` is being +replaced by the more common language code ``nb``. + diff --git a/parts/django/docs/releases/index.txt b/parts/django/docs/releases/index.txt new file mode 100644 index 0000000..7abaf78 --- /dev/null +++ b/parts/django/docs/releases/index.txt @@ -0,0 +1,70 @@ +============= +Release notes +============= + +Release notes for the official Django releases. Each release note will tell you +what's new in each version, and will also describe any backwards-incompatible +changes made in that version. + +For those upgrading to a new version of Django, you will need to check +all the backwards-incompatible changes and deprecated features for +each 'final' release from the one after your current Django version, +up to and including the new version. + +Final releases +============== + +1.2 release +----------- +.. toctree:: + :maxdepth: 1 + + 1.2.4 + 1.2.2 + 1.2 + +1.1 release +----------- +.. toctree:: + :maxdepth: 1 + + 1.1.2 + 1.1 + +1.0 release +----------- +.. toctree:: + :maxdepth: 1 + + 1.0.2 + 1.0.1 + 1.0 + +Pre-1.0 releases +---------------- +.. toctree:: + :maxdepth: 1 + + 0.96 + 0.95 + +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 + + 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 |