This is the first in a series of preview/development releases leading up to the
eventual release of Django 1.5, scheduled for December 2012. This release is
primarily targeted at developers who are interested in trying out new features
and testing the Django codebase to help identify and resolve bugs prior to the
final 1.5 release.

As such, this release is not intended for production use, and any such use
is discouraged.

In particular, we need the community’s help to test Django 1.5’s new Python 3
support – not just to report bugs on Python 3, but also regressions on Python
2. While Django is very conservative with regards to backwards compatibility,
mistakes are always possible, and it’s likely that the Python 3 refactoring work
introduced some regressions.

The biggest new feature in Django 1.5 is the configurable User model. Before
Django 1.5, applications that wanted to use Django’s auth framework
(django.contrib.auth) were forced to use Django’s definition of a “user”.
In Django 1.5, you can now swap out the User model for one that you write
yourself. This could be a simple extension to the existing User model – for
example, you could add a Twitter or Facebook ID field – or you could completely
replace the User with one totally customized for your site.

Django 1.5 is also the first release with Python 3 support! We’re labeling
this support “experimental” because we don’t yet consider it production-ready,
but everything’s in place for you to start porting your apps to Python 3.
Our next release, Django 1.6, will support Python 3 without reservations.

Wherever possible we try to introduce new features in a backwards-compatible
manner per our API stability policy policy.
However, as with previous releases, Django 1.5 ships with some minor
backwards incompatible changes; people upgrading from previous versions
of Django should read that list carefully.

One deprecated feature worth noting is the shift to “new-style” url tag.
Prior to Django 1.3, syntax like {%urlmyview%} was interpreted
incorrectly (Django considered "myview" to be a literal name of a view, not
a template variable named myview). Django 1.3 and above introduced the
{%loadurlfromfuture%} syntax to bring in the corrected behavior where
myview was seen as a variable.

The upshot of this is that if you are not using {%loadurlfromfuture%}
in your templates, you’ll need to change tags like {%urlmyview%} to
{%url"myview"%}. If you were using {%loadurlfromfuture%} you
can simply remove that line under Django 1.5

Django 1.5 requires Python 2.6.5 or above, though we highly recommended
Python 2.7.3 or above. Support for Python 2.5 and below has been dropped.

This change should affect only a small number of Django users, as most
operating-system vendors today are shipping Python 2.6 or newer as their default
version. If you’re still using Python 2.5, however, you’ll need to stick to
Django 1.4 until you can upgrade your Python version. Per our support
policy, Django 1.4 will continue to receive
security support until the release of Django 1.6.

Django 1.5 does not run on a Jython final release, because Jython’s latest
release doesn’t currently support Python 2.6. However, Jython currently does
offer an alpha release featuring 2.7 support, and Django 1.5 supports that alpha
release.

Django 1.5 introduces support for Python 3 - specifically, Python
3.2 and above. This comes in the form of a single codebase; you don’t
need to install a different version of Django on Python 3. This means that
you can write application targeted for just Python 2, just Python 3, or single
applications that support both platforms.

However, we’re labeling this support “experimental” for now: although it’s
received extensive testing via our automated test suite, it’s received very
little real-world testing. We’ve done our best to eliminate bugs, but we can’t
be sure we covered all possible uses of Django. Further, Django’s more than a
web framework; it’s an ecosystem of pluggable components. At this point, very
few third-party applications have been ported to Python 3, so it’s unlikely
that a real-world application will have all its dependencies satisfied under
Python 3.

Thus, we’re recommending that Django 1.5 not be used in production under Python
3. Instead, use this opportunity to begin porting applications to Python 3. If you’re an author of a pluggable component, we encourage you
to start porting now.

We plan to offer first-class, production-ready support for Python 3 in our next
release, Django 1.6.

In Django 1.5, you can now use your own model as the store for user-related
data. If your project needs a username with more than 30 characters, or if
you want to store usernames in a format other than first name/last name, or
you want to put custom profile information onto your User object, you can
now do so.

If you have a third-party reusable application that references the User model,
you may need to make some changes to the way you reference User instances. You
should also document any specific features of the User model that your
application relies upon.

The method Model.save() has a new
keyword argument update_fields. By using this argument it is possible to
save only a select list of model’s fields. This can be useful for performance
reasons or when trying to avoid overwriting concurrent changes.

Deferred instances (those loaded by .only() or .defer()) will automatically
save just the loaded fields. If any field is set manually after load, that
field will also get updated on save.

In Django 1.5, the third line no longer triggers a new SQL query to fetch
first_choice.poll; it was set by the second line.

For one-to-one relationships, both sides can be cached. For many-to-one
relationships, only the single side of the relationship can be cached. This
is particularly helpful in combination with prefetch_related.

Before Django 1.5, it was possible to create a streaming response by passing
an iterator to HttpResponse. But this was unreliable:
any middleware that accessed the content
attribute would consume the iterator prematurely.

Since StreamingHttpResponse does not have a content
attribute, middleware that needs access to the response content must test for
streaming responses and behave accordingly. See process_response for
more information.

An instance of ResolverMatch is stored on
the request as resolver_match.

By default, all logging messages reaching the django logger when
DEBUG is True are sent to the console (unless you redefine the
logger in your LOGGING setting).

When using RequestContext, it is now possible to
look up permissions by using {%if'someapp.someperm'inperms%}
in templates.

It’s not required any more to have 404.html and 500.html templates in
the root templates directory. Django will output some basic error messages for
both situations when those templates are not found. Of course, it’s still
recommended as good practice to provide those templates in order to present
pretty error pages to the user.

In addition to the changes outlined in this section, be sure to review the
deprecation plan for any features that
have been removed. If you haven’t updated your code within the
deprecation timeline for a given feature, its removal may appear as a
backwards incompatible change.

For consistency with the other date-based generic views,
YearArchiveView now passes year in
the context as a datetime.date rather than a string. If you are
using {{year}} in your templates, you must replace it with {{year|date:"Y"}}.

next_year and previous_year were also added in the context. They are
calculated according to allow_empty and allow_future.

YearArchiveView and
MonthArchiveView were documented to
provide a date_list sorted in ascending order in the context, like their
function-based predecessors, but it actually was in descending order. In 1.5,
the documented order was restored. You may want to add (or remove) the
reversed keyword when you’re iterating on date_list in a template:

For consistency with the design of the other generic views,
TemplateView no longer passes a params
dictionary into the context, instead passing the variables from the URLconf
directly into the context.

request.POST will no longer include data
posted via HTTP requests with non form-specific content-types in the header.
In prior versions, data posted with content-types other than
multipart/form-data or application/x-www-form-urlencoded would still
end up represented in the request.POST
attribute. Developers wishing to access the raw POST data for these cases,
should use the request.body attribute
instead.

Unlike GET and POST, these HTTP methods aren’t implemented by web browsers.
Rather, they’re used in APIs, which transfer data in various formats such as
JSON or XML. Since such requests may contain arbitrary data, Django doesn’t
attempt to decode their body.

However, the test client used to build a query string for OPTIONS and DELETE
requests like for GET, and a request body for PUT requests like for POST. This
encoding was arbitrary and inconsistent with Django’s behavior when it
receives the requests, so it was removed in Django 1.5.

If you were using the data parameter in an OPTIONS or a DELETE request,
you must convert it to a query string and append it to the path parameter.

If you were using the data parameter in a PUT request without a
content_type, you must encode your data before passing it to the test
client and set the content_type argument.

As explained below, Django 1.5 deprecates
django.utils.simplejson in favor of Python 2.6’s built-in json
module. In theory, this change is harmless. Unfortunately, because of
incompatibilities between versions of simplejson, it may trigger errors
in some circumstances.

JSON-related features in Django 1.4 always used django.utils.simplejson.
This module was actually:

A system version of simplejson, if one was available (ie. importsimplejson works), if it was more recent than Django’s built-in copy or it
had the C speedups, or

The json module from the standard library, if it was available (ie.
Python 2.6 or greater), or

More information on these incompatibilities is available in ticket #18023.

The net result is that, if you have installed simplejson and your code
uses Django’s serialization internals directly – for instance
django.core.serializers.json.DjangoJSONEncoder, the switch from
simplejson to json could break your code. (In general, changes to
internals aren’t documented; we’re making an exception here.)

At this point, the maintainers of Django believe that using json from
the standard library offers the strongest guarantee of backwards-compatibility.
They recommend to use it from now on.

If you have written a custom password hasher,
your encode(), verify() or safe_summary() methods should accept
Unicode parameters (password, salt or encoded). If any of the
hashing methods need byte strings, you can use the
force_bytes() utility to encode the strings.

When using object pagination,
the previous_page_number() and next_page_number() methods of the
Page object did not check if the returned
number was inside the existing page range.
It does check it now and raises an InvalidPage
exception when the number is either too low or too high.

PostgreSQL’s autocommit option didn’t work as advertised previously. It did
work for single transaction block, but after the first block was left the
autocommit behavior was never restored. This bug is now fixed in 1.5. While
this is only a bug fix, it is worth checking your applications behavior if
you are using PostgreSQL together with the autocommit option.

Prior to Django 1.5, if you attempted to log into the admin interface and
mistakenly used your email address instead of your username, the admin
interface would provide a warning advising that your email address was
not your username. In Django 1.5, the introduction of
custom User models has required the removal of this
warning. This doesn’t change the login behavior of the admin site; it only
affects the warning message that is displayed under one particular mode of
login failure.

Then any other tests (e.g. doctests) that may alter the database without
restoring it to its original state are run.

This should not cause any problems unless you have existing doctests which
assume a TransactionTestCase executed earlier left some
database state behind or unit tests that rely on some form of state being
preserved after the execution of other tests. Such tests are already very
fragile, and must now be changed to be able to run independently.

The cleaned_data dictionary is now always present
after form validation. When the form doesn’t validate, it contains only the
fields that passed validation. You should test the success of the validation
with the is_valid() method and not with the
presence or absence of the cleaned_data attribute
on the form.

Uploaded files are no longer created as executable by default. If you need
them to be executable change FILE_UPLOAD_PERMISSIONS to your
needs. The new default value is 0o666 (octal) and the current umask value
is first masked out.

The F() expressions supported bitwise operators by
& and |. These operators are now available using .bitand() and
.bitor() instead. The removal of & and | was done to be consistent with
Q() expressions and QuerySet combining where
the operators are used as boolean AND and OR operators.

The csrf_token template tag is no longer enclosed in a div. If you need
HTML validation against pre-HTML5 Strict DTDs, you should add a div around it
in your pages.

With the introduction of custom User models, there is
no longer any need for a built-in mechanism to store user profile data.

You can still define user profiles models that have a one-to-one relation with
the User model - in fact, for many applications needing to associate data with
a User account, this will be an appropriate design pattern to follow. However,
the AUTH_PROFILE_MODULE setting, and the
get_profile() method for accessing
the user profile model, should not be used any longer.

Since Django 1.5 drops support for Python 2.5, we can now rely on the
json module being available in Python’s standard library, so we’ve
removed our own copy of simplejson. You should now import json
instead of django.utils.simplejson.

Unfortunately, this change might have unwanted side-effects, because of
incompatibilities between versions of simplejson – see the backwards-
incompatible changes section. If you rely on features added to simplejson
after it became Python’s json, you should import simplejson
explicitly.

The markup contrib module has been deprecated and will follow an accelerated
deprecation schedule. Direct use of python markup libraries or 3rd party tag
libraries is preferred to Django maintaining this functionality in the
framework.