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

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: