| 1 |
======================== |
| 2 |
Django 1.2 release notes |
| 3 |
======================== |
| 4 |
|
| 5 |
*May 17, 2010.* |
| 6 |
|
| 7 |
Welcome to Django 1.2! |
| 8 |
|
| 9 |
Nearly a year in the making, Django 1.2 packs an impressive list of :ref:`new |
| 10 |
features <whats-new-1.2>` and lots of bug fixes. These release notes cover |
| 11 |
the new features, as well as important changes you'll want to be aware of when |
| 12 |
upgrading from Django 1.1 or older versions. |
| 13 |
|
| 14 |
Overview |
| 15 |
======== |
| 16 |
|
| 17 |
Django 1.2 introduces several large, important new features, including: |
| 18 |
|
| 19 |
* Support for :ref:`multiple database connections |
| 20 |
<support-for-multiple-databases>` in a single Django instance. |
| 21 |
|
| 22 |
* `Model validation`_ inspired by Django's form validation. |
| 23 |
|
| 24 |
* Vastly :ref:`improved protection against Cross-Site Request Forgery |
| 25 |
<improved-csrf-protection>` (CSRF). |
| 26 |
|
| 27 |
* A new :ref:`user "messages" framework <messages-framework>` with support for |
| 28 |
cookie- and session-based message for both anonymous and authenticated users. |
| 29 |
|
| 30 |
* Hooks for `object-level permissions`_, `permissions for anonymous users`_, |
| 31 |
and :ref:`more flexible username requirements |
| 32 |
<relaxed-requirements-for-usernames>`. |
| 33 |
|
| 34 |
* Customization of email sending via `email backends`_. |
| 35 |
|
| 36 |
* New :ref:`"smart" if template tag <new-in-1.2-smart-if>` which supports |
| 37 |
comparison operators. |
| 38 |
|
| 39 |
These are just the highlights; full details and a complete list of features |
| 40 |
:ref:`may be found below <whats-new-1.2>`. |
| 41 |
|
| 42 |
.. seealso:: |
| 43 |
|
| 44 |
`Django Advent`_ covered the release of Django 1.2 with a series of |
| 45 |
articles and tutorials that cover some of the new features in depth. |
| 46 |
|
| 47 |
.. _django advent: https://github.com/djangoadvent/djangoadvent-articles |
| 48 |
|
| 49 |
Wherever possible these features have been introduced in a backwards-compatible |
| 50 |
manner per :doc:`our API stability policy </misc/api-stability>` policy. |
| 51 |
|
| 52 |
However, a handful of features *have* changed in ways that, for some users, will be |
| 53 |
backwards-incompatible. The big changes are: |
| 54 |
|
| 55 |
* Support for Python 2.3 has been dropped. See the full notes |
| 56 |
below. |
| 57 |
|
| 58 |
* The new CSRF protection framework is not backwards-compatible with |
| 59 |
the old system. Users of the old system will not be affected until |
| 60 |
the old system is removed in Django 1.4. |
| 61 |
|
| 62 |
However, upgrading to the new CSRF protection framework requires a few |
| 63 |
important backwards-incompatible changes, detailed in `CSRF Protection`_, |
| 64 |
below. |
| 65 |
|
| 66 |
* Authors of custom :class:`~django.db.models.Field` subclasses should be |
| 67 |
aware that a number of methods have had a change in prototype, detailed |
| 68 |
under `get_db_prep_*() methods on Field`_, below. |
| 69 |
|
| 70 |
* The internals of template tags have changed somewhat; authors of custom |
| 71 |
template tags that need to store state (e.g. custom control flow tags) |
| 72 |
should ensure that their code follows the new rules for `stateful template |
| 73 |
tags`_ |
| 74 |
|
| 75 |
* The :func:`~django.contrib.auth.decorators.user_passes_test`, |
| 76 |
:func:`~django.contrib.auth.decorators.login_required`, and |
| 77 |
:func:`~django.contrib.auth.decorators.permission_required`, decorators |
| 78 |
from :mod:`django.contrib.auth` only apply to functions and no longer |
| 79 |
work on methods. There's a simple one-line fix :ref:`detailed below |
| 80 |
<user-passes-test-login-required-permission-required>`. |
| 81 |
|
| 82 |
Again, these are just the big features that will affect the most users. Users |
| 83 |
upgrading from previous versions of Django are heavily encouraged to consult |
| 84 |
the complete list of :ref:`backwards-incompatible changes |
| 85 |
<backwards-incompatible-changes-1.2>` and the list of :ref:`deprecated |
| 86 |
features <deprecated-features-1.2>`. |
| 87 |
|
| 88 |
Python compatibility |
| 89 |
==================== |
| 90 |
|
| 91 |
While not a new feature, it's important to note that Django 1.2 |
| 92 |
introduces the first shift in our Python compatibility policy since |
| 93 |
Django's initial public debut. Previous Django releases were tested |
| 94 |
and supported on 2.x Python versions from 2.3 up; Django 1.2, however, |
| 95 |
drops official support for Python 2.3. As such, the minimum Python |
| 96 |
version required for Django is now 2.4, and Django is tested and |
| 97 |
supported on Python 2.4, 2.5 and 2.6, and will be supported on the |
| 98 |
as-yet-unreleased Python 2.7. |
| 99 |
|
| 100 |
This change should affect only a small number of Django users, as most |
| 101 |
operating-system vendors today are shipping Python 2.4 or newer as |
| 102 |
their default version. If you're still using Python 2.3, however, |
| 103 |
you'll need to stick to Django 1.1 until you can upgrade; per |
| 104 |
:doc:`our support policy </internals/release-process>`, Django 1.1 will |
| 105 |
continue to receive security support until the release of Django 1.3. |
| 106 |
|
| 107 |
A roadmap for Django's overall 2.x Python support, and eventual |
| 108 |
transition to Python 3.x, is currently being developed, and will be |
| 109 |
announced prior to the release of Django 1.3. |
| 110 |
|
| 111 |
.. _whats-new-1.2: |
| 112 |
|
| 113 |
What's new in Django 1.2 |
| 114 |
======================== |
| 115 |
|
| 116 |
.. _support-for-multiple-databases: |
| 117 |
|
| 118 |
Support for multiple databases |
| 119 |
------------------------------ |
| 120 |
|
| 121 |
Django 1.2 adds the ability to use :doc:`more than one database |
| 122 |
</topics/db/multi-db>` in your Django project. Queries can be issued at a |
| 123 |
specific database with the ``using()`` method on ``QuerySet`` objects. |
| 124 |
Individual objects can be saved to a specific database by providing a ``using`` |
| 125 |
argument when you call ``save()``. |
| 126 |
|
| 127 |
Model validation |
| 128 |
---------------- |
| 129 |
|
| 130 |
Model instances now have support for :ref:`validating their own data |
| 131 |
<validating-objects>`, and both model and form fields now accept configurable |
| 132 |
lists of :doc:`validators </ref/validators>` specifying reusable, encapsulated |
| 133 |
validation behavior. Note, however, that validation must still be performed |
| 134 |
explicitly. Simply invoking a model instance's ``save()`` method will not |
| 135 |
perform any validation of the instance's data. |
| 136 |
|
| 137 |
.. _improved-csrf-protection: |
| 138 |
|
| 139 |
Improved CSRF protection |
| 140 |
------------------------ |
| 141 |
|
| 142 |
Django now has much improved protection against :doc:`Cross-Site Request Forgery |
| 143 |
(CSRF) attacks</ref/csrf>`. This type of attack occurs when a malicious |
| 144 |
website contains a link, a form button or some JavaScript that is intended to |
| 145 |
perform some action on your website, using the credentials of a logged-in user |
| 146 |
who visits the malicious site in their browser. A related type of attack, "login |
| 147 |
CSRF," where an attacking site tricks a user's browser into logging into a site |
| 148 |
with someone else's credentials, is also covered. |
| 149 |
|
| 150 |
.. _messages-framework: |
| 151 |
|
| 152 |
Messages framework |
| 153 |
------------------ |
| 154 |
|
| 155 |
Django now includes a robust and configurable :doc:`messages framework |
| 156 |
</ref/contrib/messages>` with built-in support for cookie- and session-based |
| 157 |
messaging, for both anonymous and authenticated clients. The messages framework |
| 158 |
replaces the deprecated user message API and allows you to temporarily store |
| 159 |
messages in one request and retrieve them for display in a subsequent request |
| 160 |
(usually the next one). |
| 161 |
|
| 162 |
Object-level permissions |
| 163 |
------------------------ |
| 164 |
|
| 165 |
A foundation for specifying permissions at the per-object level has been added. |
| 166 |
Although there is no implementation of this in core, a custom authentication |
| 167 |
backend can provide this implementation and it will be used by |
| 168 |
:class:`django.contrib.auth.models.User`. See the :doc:`authentication docs |
| 169 |
</topics/auth/index>` for more information. |
| 170 |
|
| 171 |
Permissions for anonymous users |
| 172 |
------------------------------- |
| 173 |
|
| 174 |
If you provide a custom auth backend with ``supports_anonymous_user`` set to |
| 175 |
``True``, AnonymousUser will check the backend for permissions, just like |
| 176 |
User already did. This is useful for centralizing permission handling - apps |
| 177 |
can always delegate the question of whether something is allowed or not to |
| 178 |
the authorization/authentication backend. See the :doc:`authentication |
| 179 |
docs </topics/auth/index>` for more details. |
| 180 |
|
| 181 |
.. _relaxed-requirements-for-usernames: |
| 182 |
|
| 183 |
Relaxed requirements for usernames |
| 184 |
---------------------------------- |
| 185 |
|
| 186 |
The built-in :class:`~django.contrib.auth.models.User` model's |
| 187 |
:attr:`~django.contrib.auth.models.User.username` field now allows a wider range |
| 188 |
of characters, including ``@``, ``+``, ``.`` and ``-`` characters. |
| 189 |
|
| 190 |
Email backends |
| 191 |
-------------- |
| 192 |
|
| 193 |
You can now :ref:`configure the way that Django sends email |
| 194 |
<topic-email-backends>`. Instead of using SMTP to send all email, you |
| 195 |
can now choose a configurable email backend to send messages. If your |
| 196 |
hosting provider uses a sandbox or some other non-SMTP technique for |
| 197 |
sending mail, you can now construct an email backend that will allow |
| 198 |
Django's standard :doc:`mail sending methods</topics/email>` to use |
| 199 |
those facilities. |
| 200 |
|
| 201 |
This also makes it easier to debug mail sending. Django ships with |
| 202 |
backend implementations that allow you to send email to a |
| 203 |
:ref:`file<topic-email-file-backend>`, to the |
| 204 |
:ref:`console<topic-email-console-backend>`, or to |
| 205 |
:ref:`memory<topic-email-memory-backend>`. You can even configure all |
| 206 |
email to be :ref:`thrown away<topic-email-dummy-backend>`. |
| 207 |
|
| 208 |
.. _new-in-1.2-smart-if: |
| 209 |
|
| 210 |
"Smart" :ttag:`if` tag |
| 211 |
---------------------- |
| 212 |
|
| 213 |
The :ttag:`if` tag has been upgraded to be much more powerful. First, we've |
| 214 |
added support for comparison operators. No longer will you have to type: |
| 215 |
|
| 216 |
.. code-block:: html+django |
| 217 |
|
| 218 |
{% ifnotequal a b %} |
| 219 |
... |
| 220 |
{% endifnotequal %} |
| 221 |
|
| 222 |
You can now do this: |
| 223 |
|
| 224 |
.. code-block:: html+django |
| 225 |
|
| 226 |
{% if a != b %} |
| 227 |
... |
| 228 |
{% endif %} |
| 229 |
|
| 230 |
There's really no reason to use ``{% ifequal %}`` or ``{% ifnotequal %}`` |
| 231 |
anymore, unless you're the nostalgic type. |
| 232 |
|
| 233 |
The operators supported are ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=``, |
| 234 |
``in`` and ``not in``, all of which work like the Python operators, in addition |
| 235 |
to ``and``, ``or`` and ``not``, which were already supported. |
| 236 |
|
| 237 |
Also, filters may now be used in the ``if`` expression. For example: |
| 238 |
|
| 239 |
.. code-block:: html+django |
| 240 |
|
| 241 |
<div |
| 242 |
{% if user.email|lower == message.recipient|lower %} |
| 243 |
class="highlight" |
| 244 |
{% endif %} |
| 245 |
>{{ message }}</div> |
| 246 |
|
| 247 |
Template caching |
| 248 |
---------------- |
| 249 |
|
| 250 |
In previous versions of Django, every time you rendered a template, it |
| 251 |
would be reloaded from disk. In Django 1.2, you can use a :ref:`cached |
| 252 |
template loader <template-loaders>` to load templates once, then |
| 253 |
cache the result for every subsequent render. This can lead to a |
| 254 |
significant performance improvement if your templates are broken into |
| 255 |
lots of smaller subtemplates (using the ``{% extends %}`` or ``{% |
| 256 |
include %}`` tags). |
| 257 |
|
| 258 |
As a side effect, it is now much easier to support non-Django template |
| 259 |
languages. |
| 260 |
|
| 261 |
Class-based template loaders |
| 262 |
---------------------------- |
| 263 |
|
| 264 |
As part of the changes made to introduce `Template caching`_ and following |
| 265 |
a general trend in Django, the template loaders API has been modified |
| 266 |
to use template loading mechanisms that are encapsulated in Python classes as |
| 267 |
opposed to functions, the only method available until Django 1.1. |
| 268 |
|
| 269 |
All the template loaders :ref:`shipped with Django <template-loaders>` have |
| 270 |
been ported to the new API but they still implement the function-based API and |
| 271 |
the template core machinery still accepts function-based loaders (builtin or |
| 272 |
third party) so there is no immediate need to modify your ``TEMPLATE_LOADERS`` |
| 273 |
setting in existing projects, things will keep working if you leave it |
| 274 |
untouched up to and including the Django 1.3 release. |
| 275 |
|
| 276 |
If you have developed your own custom template loaders we suggest to consider |
| 277 |
porting them to a class-based implementation because the code for backwards |
| 278 |
compatibility with function-based loaders starts its deprecation process in |
| 279 |
Django 1.2 and will be removed in Django 1.4. There is a description of the |
| 280 |
API these loader classes must implement in the template API reference and you |
| 281 |
can also examine the source code of the loaders shipped with Django. |
| 282 |
|
| 283 |
Natural keys in fixtures |
| 284 |
------------------------ |
| 285 |
|
| 286 |
Fixtures can now refer to remote objects using |
| 287 |
:ref:`topics-serialization-natural-keys`. This lookup scheme is an |
| 288 |
alternative to the normal primary-key based object references in a |
| 289 |
fixture, improving readability and resolving problems referring to |
| 290 |
objects whose primary key value may not be predictable or known. |
| 291 |
|
| 292 |
Fast failure for tests |
| 293 |
---------------------- |
| 294 |
|
| 295 |
Both the :djadmin:`test` subcommand of ``django-admin.py`` and the |
| 296 |
``runtests.py`` script used to run Django's own test suite now support a |
| 297 |
``--failfast`` option. When specified, this option causes the test runner to |
| 298 |
exit after encountering a failure instead of continuing with the test run. In |
| 299 |
addition, the handling of ``Ctrl-C`` during a test run has been improved to |
| 300 |
trigger a graceful exit from the test run that reports details of the tests that |
| 301 |
were run before the interruption. |
| 302 |
|
| 303 |
``BigIntegerField`` |
| 304 |
------------------- |
| 305 |
|
| 306 |
Models can now use a 64-bit :class:`~django.db.models.BigIntegerField` type. |
| 307 |
|
| 308 |
Improved localization |
| 309 |
--------------------- |
| 310 |
|
| 311 |
Django's :doc:`internationalization framework </topics/i18n/index>` has been expanded |
| 312 |
with locale-aware formatting and form processing. That means, if enabled, dates |
| 313 |
and numbers on templates will be displayed using the format specified for the |
| 314 |
current locale. Django will also use localized formats when parsing data in |
| 315 |
forms. See :doc:`/topics/i18n/formatting` for more details. |
| 316 |
|
| 317 |
``readonly_fields`` in ``ModelAdmin`` |
| 318 |
------------------------------------- |
| 319 |
|
| 320 |
:attr:`django.contrib.admin.ModelAdmin.readonly_fields` has been added to |
| 321 |
enable non-editable fields in add/change pages for models and inlines. Field |
| 322 |
and calculated values can be displayed alongside editable fields. |
| 323 |
|
| 324 |
Customizable syntax highlighting |
| 325 |
-------------------------------- |
| 326 |
|
| 327 |
You can now use a :envvar:`DJANGO_COLORS` environment variable to modify or |
| 328 |
disable the colors used by ``django-admin.py`` to provide :ref:`syntax |
| 329 |
highlighting <syntax-coloring>`. |
| 330 |
|
| 331 |
Syndication feeds as views |
| 332 |
-------------------------- |
| 333 |
|
| 334 |
:doc:`Syndication feeds </ref/contrib/syndication>` can now be used directly as |
| 335 |
views in your :doc:`URLconf </topics/http/urls>`. This means that you can |
| 336 |
maintain complete control over the URL structure of your feeds. Like any other |
| 337 |
view, feeds views are passed a ``request`` object, so you can do anything you |
| 338 |
would normally do with a view, like user based access control, or making a feed |
| 339 |
a named URL. |
| 340 |
|
| 341 |
GeoDjango |
| 342 |
--------- |
| 343 |
|
| 344 |
The most significant new feature for :doc:`GeoDjango </ref/contrib/gis/index>` |
| 345 |
in 1.2 is support for multiple spatial databases. As a result, |
| 346 |
the following :ref:`spatial database backends <spatial-backends>` |
| 347 |
are now included: |
| 348 |
|
| 349 |
* ``django.contrib.gis.db.backends.postgis`` |
| 350 |
* ``django.contrib.gis.db.backends.mysql`` |
| 351 |
* ``django.contrib.gis.db.backends.oracle`` |
| 352 |
* ``django.contrib.gis.db.backends.spatialite`` |
| 353 |
|
| 354 |
GeoDjango now supports the rich capabilities added in the PostGIS 1.5 release. |
| 355 |
New features include support for the :ref:`geography type <geography-type>` |
| 356 |
and enabling of :ref:`distance queries <distance-queries>` |
| 357 |
with non-point geometries on geographic coordinate systems. |
| 358 |
|
| 359 |
Support for 3D geometry fields was added, and may be enabled |
| 360 |
by setting the :attr:`~django.contrib.gis.db.models.GeometryField.dim` |
| 361 |
keyword to 3 in your :class:`~django.contrib.gis.db.models.GeometryField`. |
| 362 |
The :class:`~django.contrib.gis.db.models.Extent3D` aggregate |
| 363 |
and ``extent3d()`` ``GeoQuerySet`` method were added as a part of this feature. |
| 364 |
|
| 365 |
The ``force_rhr()``, ``reverse_geom()``, and ``geohash()`` ``GeoQuerySet`` |
| 366 |
methods are new. |
| 367 |
|
| 368 |
The GEOS interface was updated to use thread-safe C library functions when |
| 369 |
available on the platform. |
| 370 |
|
| 371 |
The GDAL interface now allows the user to set a |
| 372 |
:attr:`~django.contrib.gis.gdal.Layer.spatial_filter` on the features returned |
| 373 |
when iterating over a :class:`~django.contrib.gis.gdal.Layer`. |
| 374 |
|
| 375 |
Finally, :doc:`GeoDjango's documentation </ref/contrib/gis/index>` is now |
| 376 |
included with Django's and is no longer hosted separately at ``geodjango.org``. |
| 377 |
|
| 378 |
.. _1.2-js-assisted-inlines: |
| 379 |
|
| 380 |
JavaScript-assisted handling of inline related objects in the admin |
| 381 |
------------------------------------------------------------------- |
| 382 |
|
| 383 |
If a user has JavaScript enabled in their browser, the interface for |
| 384 |
inline objects in the admin now allows inline objects to be |
| 385 |
dynamically added and removed. Users without JavaScript-enabled |
| 386 |
browsers will see no change in the behavior of inline objects. |
| 387 |
|
| 388 |
New ``now`` template tag format specifier characters: ``c`` and ``u`` |
| 389 |
--------------------------------------------------------------------- |
| 390 |
|
| 391 |
The argument to the :ttag:`now` has gained two new format characters: |
| 392 |
``c`` to specify that a datetime value should be formatted in ISO 8601 |
| 393 |
format, and ``u`` that allows output of the microseconds part of a |
| 394 |
datetime or time value. |
| 395 |
|
| 396 |
These are also available in others parts like the :tfilter:`date` and |
| 397 |
:tfilter:`time` template filters, the ``humanize`` template tag library |
| 398 |
and the new `format localization`_ framework. |
| 399 |
|
| 400 |
.. _format localization: `Improved localization`_ |
| 401 |
|
| 402 |
.. _backwards-incompatible-changes-1.2: |
| 403 |
|
| 404 |
Backwards-incompatible changes in 1.2 |
| 405 |
===================================== |
| 406 |
|
| 407 |
Wherever possible the new features above have been introduced in a |
| 408 |
backwards-compatible manner per :doc:`our API stability policy |
| 409 |
</misc/api-stability>` policy. This means that practically all existing |
| 410 |
code which worked with Django 1.1 will continue to work with Django |
| 411 |
1.2; such code will, however, begin issuing warnings (see below for |
| 412 |
details). |
| 413 |
|
| 414 |
However, a handful of features *have* changed in ways that, for some |
| 415 |
users, will be immediately backwards-incompatible. Those changes are |
| 416 |
detailed below. |
| 417 |
|
| 418 |
CSRF Protection |
| 419 |
--------------- |
| 420 |
|
| 421 |
We've made large changes to the way CSRF protection works, detailed in |
| 422 |
:doc:`the CSRF documentation </ref/csrf>`. Here are the major changes you |
| 423 |
should be aware of: |
| 424 |
|
| 425 |
* ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` have been deprecated and |
| 426 |
will be removed completely in Django 1.4, in favor of a template tag that |
| 427 |
should be inserted into forms. |
| 428 |
|
| 429 |
* All contrib apps use a ``csrf_protect`` decorator to protect the view. This |
| 430 |
requires the use of the ``csrf_token`` template tag in the template. If you |
| 431 |
have used custom templates for contrib views, you MUST READ THE UPGRADE |
| 432 |
INSTRUCTIONS to fix those templates. |
| 433 |
|
| 434 |
.. admonition:: Documentation removed |
| 435 |
|
| 436 |
The upgrade notes have been removed in current Django docs. Please refer |
| 437 |
to the docs for Django 1.3 or older to find these instructions. |
| 438 |
|
| 439 |
* ``CsrfViewMiddleware`` is included in ``MIDDLEWARE_CLASSES`` by |
| 440 |
default. This turns on CSRF protection by default, so views that accept |
| 441 |
POST requests need to be written to work with the middleware. Instructions |
| 442 |
on how to do this are found in the CSRF docs. |
| 443 |
|
| 444 |
* All of the CSRF has moved from contrib to core (with backwards |
| 445 |
compatible imports in the old locations, which are deprecated and |
| 446 |
will cease to be supported in Django 1.4). |
| 447 |
|
| 448 |
``get_db_prep_*()`` methods on ``Field`` |
| 449 |
---------------------------------------- |
| 450 |
|
| 451 |
Prior to Django 1.2, a custom ``Field`` had the option of defining |
| 452 |
several functions to support conversion of Python values into |
| 453 |
database-compatible values. A custom field might look something like:: |
| 454 |
|
| 455 |
class CustomModelField(models.Field): |
| 456 |
... |
| 457 |
|
| 458 |
def db_type(self): ... |
| 459 |
|
| 460 |
def get_db_prep_save(self, value): ... |
| 461 |
|
| 462 |
def get_db_prep_value(self, value): ... |
| 463 |
|
| 464 |
def get_db_prep_lookup(self, lookup_type, value): ... |
| 465 |
|
| 466 |
In 1.2, these three methods have undergone a change in prototype, and |
| 467 |
two extra methods have been introduced:: |
| 468 |
|
| 469 |
class CustomModelField(models.Field): |
| 470 |
... |
| 471 |
|
| 472 |
def db_type(self, connection): ... |
| 473 |
|
| 474 |
def get_prep_value(self, value): ... |
| 475 |
|
| 476 |
def get_prep_lookup(self, lookup_type, value): ... |
| 477 |
|
| 478 |
def get_db_prep_save(self, value, connection): ... |
| 479 |
|
| 480 |
def get_db_prep_value(self, value, connection, prepared=False): ... |
| 481 |
|
| 482 |
def get_db_prep_lookup(self, lookup_type, value, connection, prepared=False): ... |
| 483 |
|
| 484 |
These changes are required to support multiple databases -- |
| 485 |
``db_type`` and ``get_db_prep_*`` can no longer make any assumptions |
| 486 |
regarding the database for which it is preparing. The ``connection`` |
| 487 |
argument now provides the preparation methods with the specific |
| 488 |
connection for which the value is being prepared. |
| 489 |
|
| 490 |
The two new methods exist to differentiate general data-preparation |
| 491 |
requirements from requirements that are database-specific. The |
| 492 |
``prepared`` argument is used to indicate to the database-preparation |
| 493 |
methods whether generic value preparation has been performed. If |
| 494 |
an unprepared (i.e., ``prepared=False``) value is provided to the |
| 495 |
``get_db_prep_*()`` calls, they should invoke the corresponding |
| 496 |
``get_prep_*()`` calls to perform generic data preparation. |
| 497 |
|
| 498 |
We've provided conversion functions that will transparently |
| 499 |
convert functions adhering to the old prototype into functions |
| 500 |
compatible with the new prototype. However, these conversion functions |
| 501 |
will be removed in Django 1.4, so you should upgrade your ``Field`` |
| 502 |
definitions to use the new prototype as soon as possible. |
| 503 |
|
| 504 |
If your ``get_db_prep_*()`` methods made no use of the database |
| 505 |
connection, you should be able to upgrade by renaming |
| 506 |
``get_db_prep_value()`` to ``get_prep_value()`` and |
| 507 |
``get_db_prep_lookup()`` to ``get_prep_lookup()``. If you require |
| 508 |
database specific conversions, then you will need to provide an |
| 509 |
implementation ``get_db_prep_*`` that uses the ``connection`` |
| 510 |
argument to resolve database-specific values. |
| 511 |
|
| 512 |
Stateful template tags |
| 513 |
---------------------- |
| 514 |
|
| 515 |
Template tags that store rendering state on their ``Node`` subclass |
| 516 |
have always been vulnerable to thread-safety and other issues; as of |
| 517 |
Django 1.2, however, they may also cause problems when used with the |
| 518 |
new :ref:`cached template loader<template-loaders>`. |
| 519 |
|
| 520 |
All of the built-in Django template tags are safe to use with the cached |
| 521 |
loader, but if you're using custom template tags that come from third |
| 522 |
party packages, or from your own code, you should ensure that the |
| 523 |
``Node`` implementation for each tag is thread-safe. For more |
| 524 |
information, see |
| 525 |
:ref:`template tag thread safety considerations<template_tag_thread_safety>`. |
| 526 |
|
| 527 |
You may also need to update your templates if you were relying on the |
| 528 |
implementation of Django's template tags *not* being thread safe. The |
| 529 |
:ttag:`cycle` tag is the most likely to be affected in this way, |
| 530 |
especially when used in conjunction with the :ttag:`include` tag. |
| 531 |
Consider the following template fragment: |
| 532 |
|
| 533 |
.. code-block:: html+django |
| 534 |
|
| 535 |
{% for object in object_list %} |
| 536 |
{% include "subtemplate.html" %} |
| 537 |
{% endfor %} |
| 538 |
|
| 539 |
with a ``subtemplate.html`` that reads: |
| 540 |
|
| 541 |
.. code-block:: html+django |
| 542 |
|
| 543 |
{% cycle 'even' 'odd' %} |
| 544 |
|
| 545 |
Using the non-thread-safe, pre-Django 1.2 renderer, this would output: |
| 546 |
|
| 547 |
.. code-block:: text |
| 548 |
|
| 549 |
even odd even odd ... |
| 550 |
|
| 551 |
Using the thread-safe Django 1.2 renderer, you will instead get: |
| 552 |
|
| 553 |
.. code-block:: text |
| 554 |
|
| 555 |
even even even even ... |
| 556 |
|
| 557 |
This is because each rendering of the :ttag:`include` tag is an |
| 558 |
independent rendering. When the :ttag:`cycle` tag was not thread safe, |
| 559 |
the state of the :ttag:`cycle` tag would leak between multiple |
| 560 |
renderings of the same :ttag:`include`. Now that the :ttag:`cycle` tag |
| 561 |
is thread safe, this leakage no longer occurs. |
| 562 |
|
| 563 |
.. _user-passes-test-login-required-permission-required: |
| 564 |
|
| 565 |
``user_passes_test``, ``login_required`` and ``permission_required`` |
| 566 |
-------------------------------------------------------------------- |
| 567 |
|
| 568 |
``django.contrib.auth.decorators`` provides the decorators |
| 569 |
``login_required``, ``permission_required`` and |
| 570 |
``user_passes_test``. Previously it was possible to use these |
| 571 |
decorators both on functions (where the first argument is 'request') |
| 572 |
and on methods (where the first argument is 'self', and the second |
| 573 |
argument is 'request'). Unfortunately, flaws were discovered in the |
| 574 |
code supporting this: it only works in limited circumstances, and |
| 575 |
produces errors that are very difficult to debug when it does not |
| 576 |
work. |
| 577 |
|
| 578 |
For this reason, the 'auto adapt' behavior has been removed, and if |
| 579 |
you are using these decorators on methods, you will need to manually |
| 580 |
apply :func:`django.utils.decorators.method_decorator` to convert the |
| 581 |
decorator to one that works with methods. For example, you would |
| 582 |
change code from this:: |
| 583 |
|
| 584 |
class MyClass(object): |
| 585 |
@login_required |
| 586 |
def my_view(self, request): |
| 587 |
pass |
| 588 |
|
| 589 |
to this:: |
| 590 |
|
| 591 |
from django.utils.decorators import method_decorator |
| 592 |
|
| 593 |
|
| 594 |
class MyClass(object): |
| 595 |
@method_decorator(login_required) |
| 596 |
def my_view(self, request): |
| 597 |
pass |
| 598 |
|
| 599 |
or:: |
| 600 |
|
| 601 |
from django.utils.decorators import method_decorator |
| 602 |
|
| 603 |
login_required_m = method_decorator(login_required) |
| 604 |
|
| 605 |
|
| 606 |
class MyClass(object): |
| 607 |
@login_required_m |
| 608 |
def my_view(self, request): |
| 609 |
pass |
| 610 |
|
| 611 |
For those of you who've been following the development trunk, this |
| 612 |
change also applies to other decorators introduced since 1.1, |
| 613 |
including ``csrf_protect``, ``cache_control`` and anything created |
| 614 |
using ``decorator_from_middleware``. |
| 615 |
|
| 616 |
:ttag:`if` tag changes |
| 617 |
---------------------- |
| 618 |
|
| 619 |
Due to new features in the :ttag:`if` template tag, it no longer |
| 620 |
accepts 'and', 'or' and 'not' as valid **variable** names. Previously, |
| 621 |
these strings could be used as variable names. Now, the keyword status |
| 622 |
is always enforced, and template code such as ``{% if not %}`` or ``{% |
| 623 |
if and %}`` will throw a ``TemplateSyntaxError``. Also, ``in`` is a |
| 624 |
new keyword and so is not a valid variable name in this tag. |
| 625 |
|
| 626 |
``LazyObject`` |
| 627 |
-------------- |
| 628 |
|
| 629 |
``LazyObject`` is an undocumented-but-often-used utility class used for lazily |
| 630 |
wrapping other objects of unknown type. |
| 631 |
|
| 632 |
In Django 1.1 and earlier, it handled introspection in a non-standard way, |
| 633 |
depending on wrapped objects implementing a public method named |
| 634 |
``get_all_members()``. Since this could easily lead to name clashes, it has been |
| 635 |
changed to use the standard Python introspection method, involving |
| 636 |
``__members__`` and ``__dir__()``. |
| 637 |
|
| 638 |
If you used ``LazyObject`` in your own code |
| 639 |
and implemented the ``get_all_members()`` method for wrapped objects, you'll need |
| 640 |
to make a couple of changes: |
| 641 |
|
| 642 |
First, if your class does not have special requirements for introspection (i.e., |
| 643 |
you have not implemented ``__getattr__()`` or other methods that allow for |
| 644 |
attributes not discoverable by normal mechanisms), you can simply remove the |
| 645 |
``get_all_members()`` method. The default implementation on ``LazyObject`` will |
| 646 |
do the right thing. |
| 647 |
|
| 648 |
If you have more complex requirements for introspection, first rename the |
| 649 |
``get_all_members()`` method to ``__dir__()``. This is the standard |
| 650 |
introspection method for Python 2.6 and above. If you require support for Python |
| 651 |
versions earlier than 2.6, add the following code to the class:: |
| 652 |
|
| 653 |
__members__ = property(lambda self: self.__dir__()) |
| 654 |
|
| 655 |
``__dict__`` on model instances |
| 656 |
------------------------------- |
| 657 |
|
| 658 |
Historically, the ``__dict__`` attribute of a model instance has only contained |
| 659 |
attributes corresponding to the fields on a model. |
| 660 |
|
| 661 |
In order to support multiple database configurations, Django 1.2 has |
| 662 |
added a ``_state`` attribute to object instances. This attribute will |
| 663 |
appear in ``__dict__`` for a model instance. If your code relies on |
| 664 |
iterating over ``__dict__`` to obtain a list of fields, you must now |
| 665 |
be prepared to handle or filter out the ``_state`` attribute. |
| 666 |
|
| 667 |
Test runner exit status code |
| 668 |
---------------------------- |
| 669 |
|
| 670 |
The exit status code of the test runners (``tests/runtests.py`` and ``python |
| 671 |
manage.py test``) no longer represents the number of failed tests, because a |
| 672 |
failure of 256 or more tests resulted in a wrong exit status code. The exit |
| 673 |
status code for the test runner is now 0 for success (no failing tests) and 1 |
| 674 |
for any number of test failures. If needed, the number of test failures can be |
| 675 |
found at the end of the test runner's output. |
| 676 |
|
| 677 |
Cookie encoding |
| 678 |
--------------- |
| 679 |
|
| 680 |
To fix bugs with cookies in Internet Explorer, Safari, and possibly |
| 681 |
other browsers, our encoding of cookie values was changed so that the |
| 682 |
comma and semicolon are treated as non-safe characters, and are |
| 683 |
therefore encoded as ``\054`` and ``\073`` respectively. This could |
| 684 |
produce backwards incompatibilities, especially if you are storing |
| 685 |
comma or semi-colon in cookies and have JavaScript code that parses |
| 686 |
and manipulates cookie values client-side. |
| 687 |
|
| 688 |
``ModelForm.is_valid()`` and ``ModelForm.errors`` |
| 689 |
------------------------------------------------- |
| 690 |
|
| 691 |
Much of the validation work for ModelForms has been moved down to the model |
| 692 |
level. As a result, the first time you call ``ModelForm.is_valid()``, access |
| 693 |
``ModelForm.errors`` or otherwise trigger form validation, your model will be |
| 694 |
cleaned in-place. This conversion used to happen when the model was saved. If |
| 695 |
you need an unmodified instance of your model, you should pass a copy to the |
| 696 |
``ModelForm`` constructor. |
| 697 |
|
| 698 |
``BooleanField`` on MySQL |
| 699 |
-------------------------- |
| 700 |
|
| 701 |
In previous versions of Django, a model's ``BooleanField`` under MySQL |
| 702 |
would return its value as either ``1`` or ``0``, instead of ``True`` |
| 703 |
or ``False``; for most people this wasn't a problem because ``bool`` |
| 704 |
is a subclass of ``int`` in Python. In Django 1.2, however, |
| 705 |
``BooleanField`` on MySQL correctly returns a real ``bool``. The only |
| 706 |
time this should ever be an issue is if you were expecting the |
| 707 |
``repr`` of a ``BooleanField`` to print ``1`` or ``0``. |
| 708 |
|
| 709 |
Changes to the interpretation of ``max_num`` in FormSets |
| 710 |
-------------------------------------------------------- |
| 711 |
|
| 712 |
As part of enhancements made to the handling of FormSets, the default |
| 713 |
value and interpretation of the ``max_num`` parameter to the |
| 714 |
:ref:`django.forms.formsets.formset_factory() <formsets-max-num>` and |
| 715 |
:ref:`django.forms.models.modelformset_factory() |
| 716 |
<model-formsets-max-num>` functions has changed slightly. This |
| 717 |
change also affects the way the |
| 718 |
:attr:`~django.contrib.admin.InlineModelAdmin.max_num` argument is used for |
| 719 |
inline admin objects. |
| 720 |
|
| 721 |
Previously, the default value for ``max_num`` was ``0`` (zero). |
| 722 |
FormSets then used the boolean value of ``max_num`` to determine if a |
| 723 |
limit was to be imposed on the number of generated forms. The default |
| 724 |
value of ``0`` meant that there was no default limit on the number of |
| 725 |
forms in a FormSet. |
| 726 |
|
| 727 |
Starting with 1.2, the default value for ``max_num`` has been changed |
| 728 |
to ``None``, and FormSets will differentiate between a value of |
| 729 |
``None`` and a value of ``0``. A value of ``None`` indicates that no |
| 730 |
limit on the number of forms is to be imposed; a value of ``0`` |
| 731 |
indicates that a maximum of 0 forms should be imposed. This doesn't |
| 732 |
necessarily mean that no forms will be displayed -- see the |
| 733 |
:ref:`ModelFormSet documentation <model-formsets-max-num>` for more |
| 734 |
details. |
| 735 |
|
| 736 |
If you were manually specifying a value of ``0`` for ``max_num``, you |
| 737 |
will need to update your FormSet and/or admin definitions. |
| 738 |
|
| 739 |
.. seealso:: |
| 740 |
|
| 741 |
:ref:`1.2-js-assisted-inlines` |
| 742 |
|
| 743 |
``email_re`` |
| 744 |
------------ |
| 745 |
|
| 746 |
An undocumented regular expression for validating email addresses has been moved |
| 747 |
from ``django.form.fields`` to ``django.core.validators``. You will need to |
| 748 |
update your imports if you are using it. |
| 749 |
|
| 750 |
.. _deprecated-features-1.2: |
| 751 |
|
| 752 |
Features deprecated in 1.2 |
| 753 |
========================== |
| 754 |
|
| 755 |
Finally, Django 1.2 deprecates some features from earlier releases. |
| 756 |
These features are still supported, but will be gradually phased out |
| 757 |
over the next few release cycles. |
| 758 |
|
| 759 |
Code taking advantage of any of the features below will raise a |
| 760 |
``PendingDeprecationWarning`` in Django 1.2. This warning will be |
| 761 |
silent by default, but may be turned on using Python's :mod:`warnings` |
| 762 |
module, or by running Python with a ``-Wd`` or ``-Wall`` flag. |
| 763 |
|
| 764 |
In Django 1.3, these warnings will become a ``DeprecationWarning``, |
| 765 |
which is *not* silent. In Django 1.4 support for these features will |
| 766 |
be removed entirely. |
| 767 |
|
| 768 |
.. seealso:: |
| 769 |
|
| 770 |
For more details, see the documentation :doc:`Django's release process |
| 771 |
</internals/release-process>` and our :doc:`deprecation timeline |
| 772 |
</internals/deprecation>`.` |
| 773 |
|
| 774 |
.. _specifying-databases: |
| 775 |
|
| 776 |
Specifying databases |
| 777 |
-------------------- |
| 778 |
|
| 779 |
Prior to Django 1.2, Django used a number of settings to control |
| 780 |
access to a single database. Django 1.2 introduces support for |
| 781 |
multiple databases, and as a result the way you define database |
| 782 |
settings has changed. |
| 783 |
|
| 784 |
Any existing Django settings file will continue to work as expected |
| 785 |
until Django 1.4. Until then, old-style database settings will be |
| 786 |
automatically translated to the new-style format. |
| 787 |
|
| 788 |
In the old-style (pre 1.2) format, you had a number of ``DATABASE_`` |
| 789 |
settings in your settings file. For example:: |
| 790 |
|
| 791 |
DATABASE_NAME = "test_db" |
| 792 |
DATABASE_ENGINE = "postgresql_psycopg2" |
| 793 |
DATABASE_USER = "myusername" |
| 794 |
DATABASE_PASSWORD = "s3krit" |
| 795 |
|
| 796 |
These settings are now in a dictionary named |
| 797 |
:setting:`DATABASES`. Each item in the dictionary corresponds to a |
| 798 |
single database connection, with the name ``'default'`` describing the |
| 799 |
default database connection. The setting names have also been |
| 800 |
shortened. The previous sample settings would now look like this:: |
| 801 |
|
| 802 |
DATABASES = { |
| 803 |
"default": { |
| 804 |
"NAME": "test_db", |
| 805 |
"ENGINE": "django.db.backends.postgresql_psycopg2", |
| 806 |
"USER": "myusername", |
| 807 |
"PASSWORD": "s3krit", |
| 808 |
} |
| 809 |
} |
| 810 |
|
| 811 |
This affects the following settings: |
| 812 |
|
| 813 |
========================================= ========================== |
| 814 |
Old setting New Setting |
| 815 |
========================================= ========================== |
| 816 |
``DATABASE_ENGINE`` :setting:`ENGINE <DATABASE-ENGINE>` |
| 817 |
``DATABASE_HOST`` :setting:`HOST` |
| 818 |
``DATABASE_NAME`` :setting:`NAME` |
| 819 |
``DATABASE_OPTIONS`` :setting:`OPTIONS` |
| 820 |
``DATABASE_PASSWORD`` :setting:`PASSWORD` |
| 821 |
``DATABASE_PORT`` :setting:`PORT` |
| 822 |
``DATABASE_USER`` :setting:`USER` |
| 823 |
``TEST_DATABASE_CHARSET`` :setting:`TEST_CHARSET` |
| 824 |
``TEST_DATABASE_COLLATION`` :setting:`TEST_COLLATION` |
| 825 |
``TEST_DATABASE_NAME`` :setting:`TEST_NAME` |
| 826 |
========================================= ========================== |
| 827 |
|
| 828 |
These changes are also required if you have manually created a database |
| 829 |
connection using ``DatabaseWrapper()`` from your database backend of choice. |
| 830 |
|
| 831 |
In addition to the change in structure, Django 1.2 removes the special |
| 832 |
handling for the built-in database backends. All database backends |
| 833 |
must now be specified by a fully qualified module name (i.e., |
| 834 |
``django.db.backends.postgresql_psycopg2``, rather than just |
| 835 |
``postgresql_psycopg2``). |
| 836 |
|
| 837 |
``postgresql`` database backend |
| 838 |
------------------------------- |
| 839 |
|
| 840 |
The ``psycopg1`` library has not been updated since October 2005. As a |
| 841 |
result, the ``postgresql`` database backend, which uses this library, |
| 842 |
has been deprecated. |
| 843 |
|
| 844 |
If you are currently using the ``postgresql`` backend, you should |
| 845 |
migrate to using the ``postgresql_psycopg2`` backend. To update your |
| 846 |
code, install the ``psycopg2`` library and change the |
| 847 |
:setting:`ENGINE <DATABASE-ENGINE>` setting to use |
| 848 |
``django.db.backends.postgresql_psycopg2``. |
| 849 |
|
| 850 |
CSRF response-rewriting middleware |
| 851 |
---------------------------------- |
| 852 |
|
| 853 |
``CsrfResponseMiddleware``, the middleware that automatically inserted |
| 854 |
CSRF tokens into ``POST`` forms in outgoing pages, has been deprecated |
| 855 |
in favor of a template tag method (see above), and will be removed |
| 856 |
completely in Django 1.4. ``CsrfMiddleware``, which includes the |
| 857 |
functionality of ``CsrfResponseMiddleware`` and |
| 858 |
``CsrfViewMiddleware``, has likewise been deprecated. |
| 859 |
|
| 860 |
Also, the CSRF module has moved from contrib to core, and the old |
| 861 |
imports are deprecated, as described in the upgrading notes. |
| 862 |
|
| 863 |
.. admonition:: Documentation removed |
| 864 |
|
| 865 |
The upgrade notes have been removed in current Django docs. Please refer |
| 866 |
to the docs for Django 1.3 or older to find these instructions. |
| 867 |
|
| 868 |
``SMTPConnection`` |
| 869 |
------------------ |
| 870 |
|
| 871 |
The ``SMTPConnection`` class has been deprecated in favor of a generic |
| 872 |
email backend API. Old code that explicitly instantiated an instance |
| 873 |
of an SMTPConnection:: |
| 874 |
|
| 875 |
from django.core.mail import SMTPConnection |
| 876 |
|
| 877 |
connection = SMTPConnection() |
| 878 |
messages = get_notification_email() |
| 879 |
connection.send_messages(messages) |
| 880 |
|
| 881 |
...should now call :func:`~django.core.mail.get_connection` to |
| 882 |
instantiate a generic email connection:: |
| 883 |
|
| 884 |
from django.core.mail import get_connection |
| 885 |
|
| 886 |
connection = get_connection() |
| 887 |
messages = get_notification_email() |
| 888 |
connection.send_messages(messages) |
| 889 |
|
| 890 |
Depending on the value of the :setting:`EMAIL_BACKEND` setting, this |
| 891 |
may not return an SMTP connection. If you explicitly require an SMTP |
| 892 |
connection with which to send email, you can explicitly request an |
| 893 |
SMTP connection:: |
| 894 |
|
| 895 |
from django.core.mail import get_connection |
| 896 |
|
| 897 |
connection = get_connection("django.core.mail.backends.smtp.EmailBackend") |
| 898 |
messages = get_notification_email() |
| 899 |
connection.send_messages(messages) |
| 900 |
|
| 901 |
If your call to construct an instance of ``SMTPConnection`` required |
| 902 |
additional arguments, those arguments can be passed to the |
| 903 |
:func:`~django.core.mail.get_connection` call:: |
| 904 |
|
| 905 |
connection = get_connection( |
| 906 |
"django.core.mail.backends.smtp.EmailBackend", hostname="localhost", port=1234 |
| 907 |
) |
| 908 |
|
| 909 |
User Messages API |
| 910 |
----------------- |
| 911 |
|
| 912 |
The API for storing messages in the user ``Message`` model (via |
| 913 |
``user.message_set.create``) is now deprecated and will be removed in Django |
| 914 |
1.4 according to the standard :doc:`release process </internals/release-process>`. |
| 915 |
|
| 916 |
To upgrade your code, you need to replace any instances of this:: |
| 917 |
|
| 918 |
user.message_set.create("a message") |
| 919 |
|
| 920 |
...with the following:: |
| 921 |
|
| 922 |
from django.contrib import messages |
| 923 |
|
| 924 |
messages.add_message(request, messages.INFO, "a message") |
| 925 |
|
| 926 |
Additionally, if you make use of the method, you need to replace the |
| 927 |
following:: |
| 928 |
|
| 929 |
for message in user.get_and_delete_messages(): |
| 930 |
... |
| 931 |
|
| 932 |
...with:: |
| 933 |
|
| 934 |
from django.contrib import messages |
| 935 |
|
| 936 |
for message in messages.get_messages(request): |
| 937 |
... |
| 938 |
|
| 939 |
For more information, see the full |
| 940 |
:doc:`messages documentation </ref/contrib/messages>`. You should begin to |
| 941 |
update your code to use the new API immediately. |
| 942 |
|
| 943 |
Date format helper functions |
| 944 |
---------------------------- |
| 945 |
|
| 946 |
``django.utils.translation.get_date_formats()`` and |
| 947 |
``django.utils.translation.get_partial_date_formats()`` have been deprecated |
| 948 |
in favor of the appropriate calls to ``django.utils.formats.get_format()``, |
| 949 |
which is locale-aware when ``USE_L10N`` is set to ``True``, and falls |
| 950 |
back to default settings if set to ``False``. |
| 951 |
|
| 952 |
To get the different date formats, instead of writing this:: |
| 953 |
|
| 954 |
from django.utils.translation import get_date_formats |
| 955 |
|
| 956 |
date_format, datetime_format, time_format = get_date_formats() |
| 957 |
|
| 958 |
...use:: |
| 959 |
|
| 960 |
from django.utils import formats |
| 961 |
|
| 962 |
date_format = formats.get_format("DATE_FORMAT") |
| 963 |
datetime_format = formats.get_format("DATETIME_FORMAT") |
| 964 |
time_format = formats.get_format("TIME_FORMAT") |
| 965 |
|
| 966 |
Or, when directly formatting a date value:: |
| 967 |
|
| 968 |
from django.utils import formats |
| 969 |
|
| 970 |
value_formatted = formats.date_format(value, "DATETIME_FORMAT") |
| 971 |
|
| 972 |
The same applies to the globals found in ``django.forms.fields``: |
| 973 |
|
| 974 |
* ``DEFAULT_DATE_INPUT_FORMATS`` |
| 975 |
* ``DEFAULT_TIME_INPUT_FORMATS`` |
| 976 |
* ``DEFAULT_DATETIME_INPUT_FORMATS`` |
| 977 |
|
| 978 |
Use ``django.utils.formats.get_format()`` to get the appropriate formats. |
| 979 |
|
| 980 |
Function-based test runners |
| 981 |
--------------------------- |
| 982 |
|
| 983 |
Django 1.2 changes the test runner tools to use a class-based |
| 984 |
approach. Old style function-based test runners will still work, but |
| 985 |
should be updated to use the new :ref:`class-based runners |
| 986 |
<topics-testing-test_runner>`. |
| 987 |
|
| 988 |
.. _1.2-updating-feeds: |
| 989 |
|
| 990 |
``Feed`` in ``django.contrib.syndication.feeds`` |
| 991 |
------------------------------------------------ |
| 992 |
|
| 993 |
The ``django.contrib.syndication.feeds.Feed`` class has been |
| 994 |
replaced by the :class:`django.contrib.syndication.views.Feed` class. |
| 995 |
The old ``feeds.Feed`` class is deprecated, and will be removed in |
| 996 |
Django 1.4. |
| 997 |
|
| 998 |
The new class has an almost identical API, but allows instances to be |
| 999 |
used as views. For example, consider the use of the old framework in |
| 1000 |
the following :doc:`URLconf </topics/http/urls>`:: |
| 1001 |
|
| 1002 |
from django.conf.urls.defaults import * |
| 1003 |
from myproject.feeds import LatestEntries, LatestEntriesByCategory |
| 1004 |
|
| 1005 |
feeds = { |
| 1006 |
"latest": LatestEntries, |
| 1007 |
"categories": LatestEntriesByCategory, |
| 1008 |
} |
| 1009 |
|
| 1010 |
urlpatterns = patterns( |
| 1011 |
"", |
| 1012 |
# ... |
| 1013 |
( |
| 1014 |
r"^feeds/(?P<url>.*)/$", |
| 1015 |
"django.contrib.syndication.views.feed", |
| 1016 |
{"feed_dict": feeds}, |
| 1017 |
), |
| 1018 |
# ... |
| 1019 |
) |
| 1020 |
|
| 1021 |
Using the new Feed class, these feeds can be deployed directly as views:: |
| 1022 |
|
| 1023 |
from django.conf.urls.defaults import * |
| 1024 |
from myproject.feeds import LatestEntries, LatestEntriesByCategory |
| 1025 |
|
| 1026 |
urlpatterns = patterns( |
| 1027 |
"", |
| 1028 |
# ... |
| 1029 |
(r"^feeds/latest/$", LatestEntries()), |
| 1030 |
(r"^feeds/categories/(?P<category_id>\d+)/$", LatestEntriesByCategory()), |
| 1031 |
# ... |
| 1032 |
) |
| 1033 |
|
| 1034 |
If you currently use the ``feed()`` view, the ``LatestEntries`` class would |
| 1035 |
often not need to be modified apart from subclassing the new |
| 1036 |
:class:`~django.contrib.syndication.views.Feed` class. The exception is if |
| 1037 |
Django was automatically working out the name of the template to use to render |
| 1038 |
the feed's description and title elements (if you were not specifying the |
| 1039 |
``title_template`` and ``description_template`` attributes). You should ensure |
| 1040 |
that you always specify ``title_template`` and ``description_template`` |
| 1041 |
attributes, or provide ``item_title()`` and ``item_description()`` methods. |
| 1042 |
|
| 1043 |
However, ``LatestEntriesByCategory`` uses the ``get_object()`` method |
| 1044 |
with the ``bits`` argument to specify a specific category to show. In |
| 1045 |
the new :class:`~django.contrib.syndication.views.Feed` class, |
| 1046 |
``get_object()`` method takes a ``request`` and arguments from the |
| 1047 |
URL, so it would look like this:: |
| 1048 |
|
| 1049 |
from django.contrib.syndication.views import Feed |
| 1050 |
from django.shortcuts import get_object_or_404 |
| 1051 |
from myproject.models import Category |
| 1052 |
|
| 1053 |
|
| 1054 |
class LatestEntriesByCategory(Feed): |
| 1055 |
def get_object(self, request, category_id): |
| 1056 |
return get_object_or_404(Category, id=category_id) |
| 1057 |
|
| 1058 |
# ... |
| 1059 |
|
| 1060 |
Additionally, the ``get_feed()`` method on ``Feed`` classes now take |
| 1061 |
different arguments, which may impact you if you use the ``Feed`` |
| 1062 |
classes directly. Instead of just taking an optional ``url`` argument, |
| 1063 |
it now takes two arguments: the object returned by its own |
| 1064 |
``get_object()`` method, and the current ``request`` object. |
| 1065 |
|
| 1066 |
To take into account ``Feed`` classes not being initialized for each |
| 1067 |
request, the ``__init__()`` method now takes no arguments by default. |
| 1068 |
Previously it would have taken the ``slug`` from the URL and the |
| 1069 |
``request`` object. |
| 1070 |
|
| 1071 |
In accordance with `RSS best practices`_, RSS feeds will now include |
| 1072 |
an ``atom:link`` element. You may need to update your tests to take |
| 1073 |
this into account. |
| 1074 |
|
| 1075 |
For more information, see the full :doc:`syndication framework |
| 1076 |
documentation </ref/contrib/syndication>`. |
| 1077 |
|
| 1078 |
.. _RSS best practices: https://www.rssboard.org/rss-profile |
| 1079 |
|
| 1080 |
Technical message IDs |
| 1081 |
--------------------- |
| 1082 |
|
| 1083 |
Up to version 1.1 Django used technical message IDs |
| 1084 |
to provide localizers the possibility to translate date and time formats. They |
| 1085 |
were translatable :term:`translation strings <translation string>` that could |
| 1086 |
be recognized because they were all upper case (for example |
| 1087 |
:setting:`DATETIME_FORMAT`, :setting:`DATE_FORMAT`, :setting:`TIME_FORMAT`). |
| 1088 |
They have been deprecated in favor of the new :doc:`/topics/i18n/formatting` |
| 1089 |
infrastructure that allows localizers to specify that information in a |
| 1090 |
``formats.py`` file in the corresponding ``django/conf/locale/<locale name>/`` |
| 1091 |
directory. |
| 1092 |
|
| 1093 |
GeoDjango |
| 1094 |
--------- |
| 1095 |
|
| 1096 |
To allow support for multiple databases, the GeoDjango database internals were |
| 1097 |
changed substantially. The largest backwards-incompatible change is that |
| 1098 |
the module ``django.contrib.gis.db.backend`` was renamed to |
| 1099 |
:mod:`django.contrib.gis.db.backends`, where the full-fledged |
| 1100 |
:ref:`spatial database backends <spatial-backends>` now exist. The |
| 1101 |
following sections provide information on the most-popular APIs that |
| 1102 |
were affected by these changes. |
| 1103 |
|
| 1104 |
``SpatialBackend`` |
| 1105 |
~~~~~~~~~~~~~~~~~~ |
| 1106 |
|
| 1107 |
Prior to the creation of the separate spatial backends, the |
| 1108 |
``django.contrib.gis.db.backend.SpatialBackend`` object was |
| 1109 |
provided as an abstraction to introspect on the capabilities of |
| 1110 |
the spatial database. All of the attributes and routines provided by |
| 1111 |
``SpatialBackend`` are now a part of the ``ops`` attribute of the |
| 1112 |
database backend. |
| 1113 |
|
| 1114 |
The old module ``django.contrib.gis.db.backend`` is still provided |
| 1115 |
for backwards-compatibility access to a ``SpatialBackend`` object, |
| 1116 |
which is just an alias to the ``ops`` module of the |
| 1117 |
*default* spatial database connection. |
| 1118 |
|
| 1119 |
Users that were relying on undocumented modules and objects |
| 1120 |
within ``django.contrib.gis.db.backend``, rather the abstractions |
| 1121 |
provided by ``SpatialBackend``, are required to modify their code. |
| 1122 |
For example, the following import which would work in 1.1 and |
| 1123 |
below:: |
| 1124 |
|
| 1125 |
from django.contrib.gis.db.backend.postgis import PostGISAdaptor |
| 1126 |
|
| 1127 |
Would need to be changed:: |
| 1128 |
|
| 1129 |
from django.db import connection |
| 1130 |
|
| 1131 |
PostGISAdaptor = connection.ops.Adapter |
| 1132 |
|
| 1133 |
``SpatialRefSys`` and ``GeometryColumns`` models |
| 1134 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1135 |
|
| 1136 |
In previous versions of GeoDjango, :mod:`django.contrib.gis.db.models` |
| 1137 |
had ``SpatialRefSys`` and ``GeometryColumns`` models for querying |
| 1138 |
the OGC spatial metadata tables ``spatial_ref_sys`` and ``geometry_columns``, |
| 1139 |
respectively. |
| 1140 |
|
| 1141 |
While these aliases are still provided, they are only for the |
| 1142 |
*default* database connection and exist only if the default connection |
| 1143 |
is using a supported spatial database backend. |
| 1144 |
|
| 1145 |
.. note:: |
| 1146 |
|
| 1147 |
Because the table structure of the OGC spatial metadata tables |
| 1148 |
differs across spatial databases, the ``SpatialRefSys`` and |
| 1149 |
``GeometryColumns`` models can no longer be associated with |
| 1150 |
the ``gis`` application name. Thus, no models will be returned |
| 1151 |
when using the ``get_models`` method in the following example: |
| 1152 |
|
| 1153 |
.. code-block:: pycon |
| 1154 |
|
| 1155 |
>>> from django.db.models import get_app, get_models |
| 1156 |
>>> get_models(get_app("gis")) |
| 1157 |
[] |
| 1158 |
|
| 1159 |
To get the correct ``SpatialRefSys`` and ``GeometryColumns`` |
| 1160 |
for your spatial database use the methods provided by the spatial backend: |
| 1161 |
|
| 1162 |
.. code-block:: pycon |
| 1163 |
|
| 1164 |
>>> from django.db import connections |
| 1165 |
>>> SpatialRefSys = connections["my_spatialite"].ops.spatial_ref_sys() |
| 1166 |
>>> GeometryColumns = connections["my_postgis"].ops.geometry_columns() |
| 1167 |
|
| 1168 |
.. note:: |
| 1169 |
|
| 1170 |
When using the models returned from the ``spatial_ref_sys()`` and |
| 1171 |
``geometry_columns()`` method, you'll still need to use the |
| 1172 |
correct database alias when querying on the non-default connection. |
| 1173 |
In other words, to ensure that the models in the example above |
| 1174 |
use the correct database:: |
| 1175 |
|
| 1176 |
sr_qs = SpatialRefSys.objects.using("my_spatialite").filter(...) |
| 1177 |
gc_qs = GeometryColumns.objects.using("my_postgis").filter(...) |
| 1178 |
|
| 1179 |
Language code ``no`` |
| 1180 |
-------------------- |
| 1181 |
|
| 1182 |
The currently used language code for Norwegian Bokmål ``no`` is being |
| 1183 |
replaced by the more common language code ``nb``. |
| 1184 |
|
| 1185 |
Function-based template loaders |
| 1186 |
------------------------------- |
| 1187 |
|
| 1188 |
Django 1.2 changes the template loading mechanism to use a class-based |
| 1189 |
approach. Old style function-based template loaders will still work, but should |
| 1190 |
be updated to use the new class-based template loaders. |