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.
There have been large changes to the way that CSRF protection works, detailed in the CSRF documentation. The following are the major changes that developers must be aware of:
CsrfResponseMiddleware
and CsrfMiddleware
have been deprecated, and
will be removed completely in Django 1.4, in favor of a template tag that
should be inserted into forms.
All contrib apps use a csrf_protect
decorator to protect the view. This
requires the use of the csrf_token
template tag in the template, so if you
have used custom templates for contrib views, you MUST READ THE UPGRADE
INSTRUCTIONS to fix those templates.
Documentation removed
The upgrade notes have been removed in current Django docs. Please refer to the docs for Django 1.3 or older to find these instructions.
CsrfViewMiddleware
is included in 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).
if
tag changes¶Due to new features in the 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.
Template tags that store rendering state on the node itself may experience problems if they are used with the new cached template loader.
All of the built-in Django template tags are safe to use with the cached
loader, but if you’re using custom template tags that come from third
party packages, or that you wrote yourself, you should ensure that the
Node
implementation for each tag is thread-safe. For more
information, see
template tag thread safety considerations.
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.
CsrfResponseMiddleware
, the middleware that automatically inserted CSRF
tokens into POST forms in outgoing pages, has been deprecated in favor of a
template tag method (see above), and will be removed completely in Django
1.4. CsrfMiddleware
, which includes the functionality of
CsrfResponseMiddleware
and CsrfViewMiddleware
has likewise been
deprecated.
Also, the CSRF module has moved from contrib to core, and the old imports are deprecated, as described in the upgrading notes.
Documentation removed
The upgrade notes have been removed in current Django docs. Please refer to the docs for Django 1.3 or older to find these instructions.
SMTPConnection
¶The SMTPConnection
class has been deprecated in favor of a generic
Email backend API. Old code that explicitly instantiated an instance
of an SMTPConnection:
from django.core.mail import SMTPConnection
connection = SMTPConnection()
messages = get_notification_email()
connection.send_messages(messages)
should now call get_connection()
to
instantiate a generic email connection:
from django.core.mail import get_connection
connection = get_connection()
messages = get_notification_email()
connection.send_messages(messages)
Depending on the value of the EMAIL_BACKEND
setting, this
may not return an SMTP connection. If you explicitly require an SMTP
connection with which to send email, you can explicitly request an
SMTP connection:
from django.core.mail import get_connection
connection = get_connection('django.core.mail.backends.smtp.EmailBackend')
messages = get_notification_email()
connection.send_messages(messages)
If your call to construct an instance of SMTPConnection
required
additional arguments, those arguments can be passed to the
get_connection()
call:
connection = get_connection('django.core.mail.backends.smtp.EmailBackend', hostname='localhost', port=1234)
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
DATABASES
. Each item in the dictionary corresponds to a
single database connection, with the name 'default'
describing the
default database connection. The setting names have also been
shortened to reflect the fact that they are stored in a dictionary.
The sample settings given previously would now be stored using:
DATABASES = {
'default': {
'NAME': 'test_db',
'ENGINE': 'django.db.backends.postgresql_psycopg2',
'USER': 'myusername',
'PASSWORD': 's3krit',
}
}
This affects the following settings:
Old setting | New Setting |
---|---|
DATABASE_ENGINE | ENGINE |
DATABASE_HOST | HOST |
DATABASE_NAME | NAME |
DATABASE_OPTIONS | OPTIONS |
DATABASE_PASSWORD | PASSWORD |
DATABASE_PORT | PORT |
DATABASE_USER | USER |
TEST_DATABASE_CHARSET | TEST_CHARSET |
TEST_DATABASE_COLLATION | TEST_COLLATION |
TEST_DATABASE_NAME | 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
).
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 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 messages documentation. You should begin to update your code to use the new API immediately.
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 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.
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.
Django now has much improved protection against Cross-Site Request Forgery (CSRF) attacks. This type of attack occurs when a malicious Web site contains a link, a form button or some javascript that is intended to perform some action on your Web site, using the credentials of a logged-in user who visits the malicious site in their browser. A related type of attack, ‘login CSRF’, where an attacking site tricks a user’s browser into logging into a site with someone else’s credentials, is also covered.
You can now configure the way that Django sends email. Instead of using SMTP to send all email, you can now choose a configurable email backend to send messages. If your hosting provider uses a sandbox or some other non-SMTP technique for sending mail, you can now construct an email backend that will allow Django’s standard mail sending methods to use those facilities.
This also makes it easier to debug mail sending - Django ships with backend implementations that allow you to send email to a file, to the console, or to memory - you can even configure all email to be thrown away.
Django now includes a robust and configurable messages framework with built-in support for cookie- and session-based messaging, for both anonymous and authenticated clients. The messages framework replaces the deprecated user message API and allows you to temporarily store messages in one request and retrieve them for display in a subsequent request (usually the next one).
Django 1.2 adds the ability to use more than one database in your Django project. Queries can be
issued at a specific database with the using()
method on
querysets; individual objects can be saved to a specific database
by providing a using
argument when you save the instance.
The 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:
{% ifnotequal a b %}
...
{% endifnotequal %}
...as you can now do:
{% 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:
<div
{% if user.email|lower == message.recipient|lower %}
class="highlight"
{% endif %}
>{{ message }}</div>
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 cached
template loader to load templates once, then use
the cached result for every subsequent render. This can lead to a
significant performance improvement if your templates are broken into
lots of smaller subtemplates (using the {% extends %}
or {%
include %}
tags).
As a side effect, it is now much easier to support non-Django template languages. For more details, see the notes on supporting non-Django template languages.
Fixtures can refer to remote objects using 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 BigIntegerField
type.
The 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.
Django’s internationalization framework has been expanded by locale aware formatting and form processing. That means, if enabled, dates and numbers on templates will be displayed using the format specified for the current locale. Django will also use localized formats when parsing data in forms. See Format localization for more details.
readonly_fields
to ModelAdmin
¶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.
You can now use the DJANGO_COLORS
environment variable to modify
or disable the colors used by django-admin.py
to provide
syntax highlighting.
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:
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.
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:
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:
... 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:
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.
Apr 12, 2017