Edited Django 1.4 release notes:

============================================

Django 1.4 release notes - UNDER DEVELOPMENT

============================================

========================

Django 1.4 release notes

========================

This page documents release notes for the as-yet-unreleased Django

1.4. As such, it's tentative and subject to change. It provides

up-to-date information for those who are following trunk.

*March 23, 2012*

Django 1.4 includes various `new features`_ and some minor `backwards

incompatible changes`_. We've also dropped some features, which are detailed

in :doc:`our deprecation plan </internals/deprecation>`, and we've

`begun the deprecation process for some features`_.

Welcome to Django 1.4!

These release notes cover the `new features`_, as well

as some `backwards incompatible changes`_ you'll want to be aware of

when upgrading from Django 1.3 or older versions. We've also dropped some

features, which are detailed in :doc:`our deprecation plan

</internals/deprecation>`, and we've `begun the deprecation process for some

features`_.

.. _`new features`: `What's new in Django 1.4`_

.. _`backwards incompatible changes`: `Backwards incompatible changes in 1.4`_

.. _`begun the deprecation process for some features`: `Features deprecated in 1.4`_

Overview

========

The biggest new feature in Django 1.4 is `support for time zones`_ when

handling date/times. When enabled, this Django will store date/times in UTC,

use timezone-aware objects internally, and translate them to users' local

timezones for display.

If you're upgrading an existing project to Django 1.4, switching to the time-

zone aware mode may take some care: the new mode disallows some rather sloppy

behavior that used to be accepted. We encourage anyone who's upgrading to check

out the :ref:`timezone migration guide <time-zones-migration-guide>` and the

:ref:`timezone FAQ <time-zones-faq>` for useful pointers.

Other notable new features in Django 1.4 include:

* A number of ORM improvements, including `SELECT FOR UPDATE support`_,

  the ability to `bulk insert <Model.objects.bulk_create in the ORM>`_

  large datasets for improved performance, and

  `QuerySet.prefetch_related`_, a method to batch-load related objects

  in areas where :meth:`~django.db.models.QuerySet.select_related` does't

  work.

* Some nice security additions, including `improved password hashing`_

  (featuring PBKDF2_ and bcrypt_ support), new `tools for cryptographic

  signing`_, several `CSRF improvements`_, and `simple clickjacking

  protection`_.

* An `updated default project layout and manage.py`_ that removes the "magic"

  from prior versions. And for those who don't like the new layout, you can

  use `custom project and app templates`_ instead!

* `Support for in-browser testing frameworks`_ (like Selenium_).

* ... and a whole lot more; `see below <what's new in django 1.4>`_!

Wherever possible we try to introduce new features in a backwards-compatible

manner per :doc:`our API stability policy </misc/api-stability>` policy.

However, as with previous releases, Django 1.4 ships with some minor

`backwards incompatible changes`_; people upgrading from previous versions

of Django should read that list carefully.

Python compatibility

====================

What's new in Django 1.4

========================

Support for time zones

~~~~~~~~~~~~~~~~~~~~~~

In previous versions, Django used "naive" date/times (that is, date/times

without an associated time zone), leaving it up to each developer to interpret

what a given date/time "really means". This can cause all sorts of subtle

timezone-related bugs.

In Django 1.4, you can now switch Django into a more correct, time-zone aware

mode. In this mode, Django stores date and  time information in UTC in the

database, uses time-zone-aware datetime objects internally and translates them

to the end user's time zone in templates and forms. Reasons for using this

feature include:

- Customizing date and time display for users around the world.

- Storing datetimes in UTC for database portability and interoperability.

  (This argument doesn't apply to PostgreSQL, because it already stores

  timestamps with time zone information in Django 1.3.)

- Avoiding data corruption problems around DST transitions.

Time zone support is enabled by default in new projects created with

:djadmin:`startproject`. If you want to use this feature in an existing

project, read the :ref:`migration guide <time-zones-migration-guide>`. If you

encounter problems, there's a helpful :ref:`FAQ <time-zones-faq>`.

Support for in-browser testing frameworks

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _Selenium: http://seleniumhq.org/

Updated default project layout and ``manage.py``

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Django 1.4 ships with an updated default project layout and ``manage.py`` file

for the :djadmin:`startproject` management command. These fix some issues with

the previous ``manage.py`` handling of Python import paths that caused double

imports, trouble moving from development to deployment, and other

difficult-to-debug path issues.

The previous ``manage.py`` called functions that are now deprecated, and thus

projects upgrading to Django 1.4 should update their ``manage.py``. (The

old-style ``manage.py`` will continue to work as before until Django 1.6. In

1.5 it will raise ``DeprecationWarning``).

The new recommended ``manage.py`` file should look like this::

    #!/usr/bin/env python

    import os, sys

    if __name__ == "__main__":

        os.environ.setdefault("DJANGO_SETTINGS_MODULE", "{{ project_name }}.settings")

        from django.core.management import execute_from_command_line

        execute_from_command_line(sys.argv)

``{{ project_name }}`` should be replaced with the Python package name of the

actual project.

If settings, URLconfs and apps within the project are imported or referenced

using the project name prefix (e.g. ``myproject.settings``, ``ROOT_URLCONF =

"myproject.urls"``, etc), the new ``manage.py`` will need to be moved one

directory up, so it is outside the project package rather than adjacent to

``settings.py`` and ``urls.py``.

For instance, with the following layout::

    manage.py

    mysite/

        __init__.py

        settings.py

        urls.py

        myapp/

            __init__.py

            models.py

You could import ``mysite.settings``, ``mysite.urls``, and ``mysite.myapp``,

but not ``settings``, ``urls``, or ``myapp`` as top-level modules.

Anything imported as a top-level module can be placed adjacent to the new

``manage.py``. For instance, to decouple "myapp" from the project module and

import it as just ``myapp``, place it outside the ``mysite/`` directory::

    manage.py

    myapp/

        __init__.py

        models.py

    mysite/

        __init__.py

        settings.py

        urls.py

If the same code is imported inconsistently (some places with the project

prefix, some places without it), the imports will need to be cleaned up when

switching to the new ``manage.py``.

Custom project and app templates

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :djadmin:`startapp` and :djadmin:`startproject` management commands

now have a ``--template`` option for specifying a path or URL to a custom app

or project template.

For example, Django will use the ``/path/to/my_project_template`` directory

when you run the following command::

    django-admin.py startproject --template=/path/to/my_project_template myproject

You can also now provide a destination directory as the second

argument to both :djadmin:`startapp` and :djadmin:`startproject`::

    django-admin.py startapp myapp /path/to/new/app

    django-admin.py startproject myproject /path/to/new/project

For more information, see the :djadmin:`startapp` and :djadmin:`startproject`

documentation.

Improved WSGI support

~~~~~~~~~~~~~~~~~~~~~

The :djadmin:`startproject` management command now adds a :file:`wsgi.py`

module to the initial project layout, containing a simple WSGI application that

can be used for :doc:`deploying with WSGI app

servers</howto/deployment/wsgi/index>`.

The :djadmin:`built-in development server<runserver>` now supports using an

externally-defined WSGI callable, which makes it possible to run runserver

with the same WSGI configuration that is used for deployment. The new

:setting:`WSGI_APPLICATION` setting lets you configure which WSGI callable

:djadmin:`runserver` uses.

(The :djadmin:`runfcgi` management command also internally wraps the WSGI

callable configured via :setting:`WSGI_APPLICATION`.)

``SELECT FOR UPDATE`` support

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

New form wizard

~~~~~~~~~~~~~~~

The previous ``FormWizard`` from the formtools contrib app has been

The previous ``FormWizard`` from :mod:`django.contrib.formtools` has been

replaced with a new implementation based on the class-based views

introduced in Django 1.3. It features a pluggable storage API and doesn't

require the wizard to pass around hidden fields for every previous step.

Extended IPv6 support

~~~~~~~~~~~~~~~~~~~~~

The previously added support for IPv6 addresses when using the runserver

management command in Django 1.3 has been extended with

a :class:`~django.db.models.fields.GenericIPAddressField` model field,

a :class:`~django.forms.fields.GenericIPAddressField` form field and

Django 1.4 can now better handle IPv6 addresses with the new

:class:`~django.db.models.fields.GenericIPAddressField` model field,

:class:`~django.forms.fields.GenericIPAddressField` form field and

the validators :data:`~django.core.validators.validate_ipv46_address` and

:data:`~django.core.validators.validate_ipv6_address`

Updated default project layout and ``manage.py``

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Django 1.4 ships with an updated default project layout and ``manage.py`` file

for the :djadmin:`startproject` management command. These fix some issues with

the previous ``manage.py`` handling of Python import paths that caused double

imports, trouble moving from development to deployment, and other

difficult-to-debug path issues.

The previous ``manage.py`` called functions that are now deprecated, and thus

projects upgrading to Django 1.4 should update their ``manage.py``. (The

old-style ``manage.py`` will continue to work as before until Django 1.6. In

1.5 it will raise ``DeprecationWarning``).

The new recommended ``manage.py`` file should look like this::

    #!/usr/bin/env python

    import os, sys

    if __name__ == "__main__":

        os.environ.setdefault("DJANGO_SETTINGS_MODULE", "{{ project_name }}.settings")

        from django.core.management import execute_from_command_line

        execute_from_command_line(sys.argv)

``{{ project_name }}`` should be replaced with the Python package name of the

actual project.

If settings, URLconfs and apps within the project are imported or referenced

using the project name prefix (e.g. ``myproject.settings``, ``ROOT_URLCONF =

"myproject.urls"``, etc), the new ``manage.py`` will need to be moved one

directory up, so it is outside the project package rather than adjacent to

``settings.py`` and ``urls.py``.

For instance, with the following layout::

    manage.py

    mysite/

        __init__.py

        settings.py

        urls.py

        myapp/

            __init__.py

            models.py

You could import ``mysite.settings``, ``mysite.urls``, and ``mysite.myapp``,

but not ``settings``, ``urls``, or ``myapp`` as top-level modules.

Anything imported as a top-level module can be placed adjacent to the new

``manage.py``. For instance, to decouple "myapp" from the project module and

import it as just ``myapp``, place it outside the ``mysite/`` directory::

    manage.py

    myapp/

        __init__.py

        models.py

    mysite/

        __init__.py

        settings.py

        urls.py

If the same code is imported inconsistently (some places with the project

prefix, some places without it), the imports will need to be cleaned up when

switching to the new ``manage.py``.

Improved WSGI support

~~~~~~~~~~~~~~~~~~~~~

The :djadmin:`startproject` management command now adds a :file:`wsgi.py`

module to the initial project layout, containing a simple WSGI application that

can be used for :doc:`deploying with WSGI app

servers</howto/deployment/wsgi/index>`.

The :djadmin:`built-in development server<runserver>` now supports using an

externally-defined WSGI callable, which makes it possible to run runserver

with the same WSGI configuration that is used for deployment. The new

:setting:`WSGI_APPLICATION` setting lets you configure which WSGI callable

:djadmin:`runserver` uses.

(The :djadmin:`runfcgi` management command also internally wraps the WSGI

callable configured via :setting:`WSGI_APPLICATION`.)

Custom project and app templates

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :djadmin:`startapp` and :djadmin:`startproject` management commands

now have a ``--template`` option for specifying a path or URL to a custom app

or project template.

For example, Django will use the ``/path/to/my_project_template`` directory

when you run the following command::

    django-admin.py startproject --template=/path/to/my_project_template myproject

You can also now provide a destination directory as the second

argument to both :djadmin:`startapp` and :djadmin:`startproject`::

    django-admin.py startapp myapp /path/to/new/app

    django-admin.py startproject myproject /path/to/new/project

For more information, see the :djadmin:`startapp` and :djadmin:`startproject`

documentation.

Support for time zones

~~~~~~~~~~~~~~~~~~~~~~

Django 1.4 adds :ref:`support for time zones <time-zones>`. When it's enabled,

Django stores date and time information in UTC in the database, uses

time-zone-aware datetime objects internally and translates them to the end user's

time zone in templates and forms.

Reasons for using this feature include:

- Customizing date and time display for users around the world.

- Storing datetimes in UTC for database portability and interoperability.

  (This argument doesn't apply to PostgreSQL, because it already stores

  timestamps with time zone information in Django 1.3.)

- Avoiding data corruption problems around DST transitions.

Time zone support is enabled by default in new projects created with

:djadmin:`startproject`. If you want to use this feature in an existing

project, read the :ref:`migration guide <time-zones-migration-guide>`. If you

encounter problems, there's a helpful :ref:`FAQ <time-zones-faq>`.

:data:`~django.core.validators.validate_ipv6_address`.

HTML comparisons in tests

~~~~~~~~~~~~~~~~~~~~~~~~~