Django 1.5 beta release notes¶

Python 3 support¶

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 applications 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.

Configurable User model¶

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 user’s names 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.

See the documentation on custom User models for more details.

Support for saving a subset of model’s fields¶

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.

See the Model.save() documentation for more details.

Caching of related model instances¶

When traversing relations, the ORM will avoid re-fetching objects that were previously loaded. For example, with the tutorial’s models:

>>> first_poll = Poll.objects.all()[0]
>>> first_choice = first_poll.choice_set.all()[0]
>>> first_choice.poll is first_poll
True

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.

Explicit support for streaming responses¶

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.

You can now explicitly generate a streaming response with the new StreamingHttpResponse class. This class exposes a streaming_content attribute which is an iterator.

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.

{% verbatim %} template tag¶

To make it easier to deal with javascript templates which collide with Django’s syntax, you can now use the verbatim block tag to avoid parsing the tag’s content.

Retrieval of ContentType instances associated with proxy models¶

The methods ContentTypeManager.get_for_model() and ContentTypeManager.get_for_models() have a new keyword argument – respectively for_concrete_model and for_concrete_models. By passing False using this argument it is now possible to retrieve the ContentType associated with proxy models.

New view variable in class-based views context¶

In all generic class-based views (or any class-based view inheriting from ContextMixin), the context dictionary contains a view variable that points to the View instance.

GeoDjango¶

• LineString and MultiLineString GEOS objects now support the interpolate() and project() methods (so-called linear referencing).
• The wkb and hex properties of GEOSGeometry objects preserve the Z dimension.
• Support for PostGIS 2.0 has been added and support for GDAL < 1.5 has been dropped.

Minor features¶

Django 1.5 also includes several smaller improvements worth noting:

• The template engine now interprets True, False and None as the corresponding Python objects.
• django.utils.timezone provides a helper for converting aware datetimes between time zones. See localtime().
• The generic views support OPTIONS requests.
• Management commands do not raise SystemExit any more when called by code from call_command. Any exception raised by the command (mostly CommandError) is propagated.
• The dumpdata management command outputs one row at a time, preventing out-of-memory errors when dumping large datasets.
• In the localflavor for Canada, “pq” was added to the acceptable codes for Quebec. It’s an old abbreviation.
• The receiver decorator is now able to connect to more than one signal by supplying a list of signals.
• In the admin, you can now filter users by groups which they are members of.
• QuerySet.bulk_create() now has a batch_size argument. By default the batch_size is unlimited except for SQLite where single batch is limited so that 999 parameters per query isn’t exceeded.
• The LOGIN_URL and LOGIN_REDIRECT_URL settings now also accept view function names and named URL patterns. This allows you to reduce configuration duplication. More information can be found in the login_required() documentation.
• Django now provides a mod_wsgi auth handler.
• The QuerySet.delete() and Model.delete() can now take fast-path in some cases. The fast-path allows for less queries and less objects fetched into memory. See QuerySet.delete() for details.
• 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' in perms %} 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.
• django.contrib.auth provides a new signal that is emitted whenever a user fails to login successfully. See user_login_failed
• The loaddata management command now supports an ignorenonexistent option to ignore data for fields that no longer exist.
• assertXMLEqual() and assertXMLNotEqual() new assertions allow you to test equality for XML content at a semantic level, without caring for syntax differences (spaces, attribute order, etc.).
• RemoteUserMiddleware now forces logout when the REMOTE_USER header disappears during the same browser session.
• The cache-based session backend can store session data in a non-default cache.
• Multi-column indexes can now be created on models. Read the index_together documentation for more information.
• During Django’s logging configuration verbose Deprecation warnings are enabled and warnings are captured into the logging system. Logged warnings are routed through the console logging handler, which by default requires DEBUG to be True for output to be generated. The result is that DeprecationWarnings should be printed to the console in development environments the way they have been in Python versions < 2.7.
• The API for django.contrib.admin.ModelAdmin.message_user() method has been modified to accept additional arguments adding capabilities similar to django.contrib.messages.add_message(). This is useful for generating error messages from admin actions.
• The admin’s list filters can now be customized per-request thanks to the new django.contrib.admin.ModelAdmin.get_list_filter() method.

Context in year archive class-based views¶

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.

Context in year and month archive class-based views¶

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 date in date_list reversed %}

ArchiveIndexView still provides a date_list in descending order.

Context in TemplateView¶

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.

Non-form data in HTTP requests¶

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.

OPTIONS, PUT and DELETE requests in the test client¶

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.

System version of simplejson no longer used¶

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. import simplejson 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
• A built-in copy of version 2.0.7 of simplejson.

In Django 1.5, those features use Python’s json module, which is based on version 2.0.9 of simplejson.

There are no known incompatibilities between Django’s copy of version 2.0.7 and Python’s copy of version 2.0.9. However, there are some incompatibilities between other versions of simplejson:

• While the simplejson API is documented as always returning unicode strings, the optional C implementation can return a byte string. This was fixed in Python 2.7.
• simplejson.JSONEncoder gained a namedtuple_as_object keyword argument in version 2.2.

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.

String types of hasher method parameters¶

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.

Validation of previous_page_number and next_page_number¶

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.

Behavior of autocommit database option on PostgreSQL changed¶

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.

Session not saved on 500 responses¶

Django’s session middleware will skip saving the session data if the response’s status code is 500.

Email checks on failed admin login¶

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.

Changes in tests execution¶

Some changes have been introduced in the execution of tests that might be backward-incompatible for some testing setups:

cleaned_data dictionary kept for invalid forms¶

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.

Behavior of syncdb with multiple databases¶

syncdb now queries the database routers to determine if content types (when contenttypes is enabled) and permissions (when auth is enabled) should be created in the target database. Previously, it created them in the default database, even when another database was specified with the --database option.

If you use syncdb on multiple databases, you should ensure that your routers allow synchronizing content types and permissions to only one of them. See the docs on the behavior of contrib apps with multiple databases for more information.

Miscellaneous¶

• django.forms.ModelMultipleChoiceField now returns an empty QuerySet as the empty value instead of an empty list.
• int_to_base36() properly raises a TypeError instead of ValueError for non-integer inputs.
• The slugify template filter is now available as a standard python function at django.utils.text.slugify(). Similarly, remove_tags is available at django.utils.html.remove_tags().
• 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 0666 (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.
• In a filter() call, when F() expressions contained lookups spanning multi-valued relations, they didn’t always reuse the same relations as other lookups along the same chain. This was changed, and now F() expressions will always use the same relations as other lookups within the same filter() call.
• 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.
• The template tags library adminmedia, which only contained the deprecated template tag {% admin_media_prefix %}, was removed. Attempting to load it with {% load adminmedia %} will fail. If your templates still contain that line you must remove it.

AUTH_PROFILE_MODULE¶

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.

Streaming behavior of HttpResponse¶

Django 1.5 deprecates the ability to stream a response by passing an iterator to HttpResponse. If you rely on this behavior, switch to StreamingHttpResponse. See Explicit support for streaming responses above.

In Django 1.7 and above, the iterator will be consumed immediately by HttpResponse.

django.utils.simplejson¶

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.

django.utils.encoding.StrAndUnicode¶

The StrAndUnicode mix-in has been deprecated. Define a __str__ method and apply the python_2_unicode_compatible() decorator instead.

django.utils.itercompat.product¶

The django.utils.itercompat.product function has been deprecated. Use the built-in itertools.product() instead.

django.utils.markup¶

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.

cleanup management command¶

The cleanup management command has been deprecated and replaced by clearsessions.

daily_cleanup.py script¶

The undocumented daily_cleanup.py script has been deprecated. Use the clearsessions management command instead.

depth keyword argument in select_related¶

The depth keyword argument in select_related() has been deprecated. You should use field names instead.