| 1 |
======================== |
| 2 |
Django 1.3 release notes |
| 3 |
======================== |
| 4 |
|
| 5 |
*March 23, 2011* |
| 6 |
|
| 7 |
Welcome to Django 1.3! |
| 8 |
|
| 9 |
Nearly a year in the making, Django 1.3 includes quite a few :ref:`new features |
| 10 |
<whats-new-1.3>` and plenty of bug fixes and improvements to existing features. |
| 11 |
These release notes cover the new features in 1.3, as well as some |
| 12 |
:ref:`backwards-incompatible changes <backwards-incompatible-changes-1.3>` |
| 13 |
you'll want to be aware of when upgrading from Django 1.2 or older versions. |
| 14 |
|
| 15 |
Overview |
| 16 |
======== |
| 17 |
|
| 18 |
Django 1.3's focus has mostly been on resolving smaller, long-standing |
| 19 |
feature requests, but that hasn't prevented a few fairly significant |
| 20 |
new features from landing, including: |
| 21 |
|
| 22 |
* A framework for writing `class-based views`_. |
| 23 |
|
| 24 |
* Built-in support for `using Python's logging facilities`_. |
| 25 |
|
| 26 |
* Contrib support for `easy handling of static files`_. |
| 27 |
|
| 28 |
* Django's testing framework now supports (and ships with a copy of) |
| 29 |
`the unittest2 library`_. |
| 30 |
|
| 31 |
Wherever possible, new features are introduced in a backwards-compatible manner |
| 32 |
per :doc:`our API stability policy </misc/api-stability>` policy. As a result |
| 33 |
of this policy, Django 1.3 :ref:`begins the deprecation process for some |
| 34 |
features <deprecated-features-1.3>`. |
| 35 |
|
| 36 |
.. _using Python's logging facilities: `Logging`_ |
| 37 |
.. _easy handling of static files: `Extended static files handling`_ |
| 38 |
.. _the unittest2 library: `unittest2 support`_ |
| 39 |
|
| 40 |
Python compatibility |
| 41 |
==================== |
| 42 |
|
| 43 |
The release of Django 1.2 was notable for having the first shift in |
| 44 |
Django's Python compatibility policy; prior to Django 1.2, Django |
| 45 |
supported any 2.x version of Python from 2.3 up. As of Django 1.2, the |
| 46 |
minimum requirement was raised to Python 2.4. |
| 47 |
|
| 48 |
Django 1.3 continues to support Python 2.4, but will be the final |
| 49 |
Django release series to do so; beginning with Django 1.4, the minimum |
| 50 |
supported Python version will be 2.5. A document outlining our full |
| 51 |
timeline for deprecating Python 2.x and moving to Python 3.x will be |
| 52 |
published shortly after the release of Django 1.3. |
| 53 |
|
| 54 |
.. _whats-new-1.3: |
| 55 |
|
| 56 |
What's new in Django 1.3 |
| 57 |
======================== |
| 58 |
|
| 59 |
Class-based views |
| 60 |
----------------- |
| 61 |
|
| 62 |
Django 1.3 adds a framework that allows you to use a class as a view. |
| 63 |
This means you can compose a view out of a collection of methods that |
| 64 |
can be subclassed and overridden to provide common views of data without |
| 65 |
having to write too much code. |
| 66 |
|
| 67 |
Analogs of all the old function-based generic views have been |
| 68 |
provided, along with a completely generic view base class that can be |
| 69 |
used as the basis for reusable applications that can be easily |
| 70 |
extended. |
| 71 |
|
| 72 |
See :doc:`the documentation on class-based generic views</topics/class-based-views/index>` |
| 73 |
for more details. There is also a document to help you `convert |
| 74 |
your function-based generic views to class-based |
| 75 |
views <https://raw.githubusercontent.com/django/django/ea9dc9f4b03ae034c1dc080730422dda7a9c2e47/docs/topics/generic-views-migration.txt>`_. |
| 76 |
|
| 77 |
Logging |
| 78 |
------- |
| 79 |
|
| 80 |
Django 1.3 adds framework-level support for Python's ``logging`` |
| 81 |
module. This means you can now easily configure and control logging |
| 82 |
as part of your Django project. A number of logging handlers and |
| 83 |
logging calls have been added to Django's own code as well -- most |
| 84 |
notably, the error emails sent on an HTTP 500 server error are now |
| 85 |
handled as a logging activity. See :doc:`the documentation on Django's |
| 86 |
logging interface </topics/logging>` for more details. |
| 87 |
|
| 88 |
Extended static files handling |
| 89 |
------------------------------ |
| 90 |
|
| 91 |
Django 1.3 ships with a new contrib app -- |
| 92 |
``django.contrib.staticfiles`` -- to help developers handle the static |
| 93 |
media files (images, CSS, JavaScript, etc.) that are needed to render |
| 94 |
a complete web page. |
| 95 |
|
| 96 |
In previous versions of Django, it was common to place static assets |
| 97 |
in :setting:`MEDIA_ROOT` along with user-uploaded files, and serve |
| 98 |
them both at :setting:`MEDIA_URL`. Part of the purpose of introducing |
| 99 |
the ``staticfiles`` app is to make it easier to keep static files |
| 100 |
separate from user-uploaded files. Static assets should now go in |
| 101 |
``static/`` subdirectories of your apps or in other static assets |
| 102 |
directories listed in :setting:`STATICFILES_DIRS`, and will be served |
| 103 |
at :setting:`STATIC_URL`. |
| 104 |
|
| 105 |
See the :doc:`reference documentation of the app </ref/contrib/staticfiles>` |
| 106 |
for more details or learn how to :doc:`manage static files |
| 107 |
</howto/static-files/index>`. |
| 108 |
|
| 109 |
``unittest2`` support |
| 110 |
---------------------- |
| 111 |
|
| 112 |
Python 2.7 introduced some major changes to the ``unittest`` library, |
| 113 |
adding some extremely useful features. To ensure that every Django |
| 114 |
project can benefit from these new features, Django ships with a copy |
| 115 |
of :pypi:`unittest2`, a copy of the Python 2.7 ``unittest`` library, |
| 116 |
backported for Python 2.4 compatibility. |
| 117 |
|
| 118 |
To access this library, Django provides the ``django.utils.unittest`` |
| 119 |
module alias. If you are using Python 2.7, or you have installed |
| 120 |
``unittest2`` locally, Django will map the alias to the installed |
| 121 |
version of the ``unittest`` library. Otherwise, Django will use its own |
| 122 |
bundled version of ``unittest2``. |
| 123 |
|
| 124 |
To take advantage of this alias, simply use:: |
| 125 |
|
| 126 |
from django.utils import unittest |
| 127 |
|
| 128 |
wherever you would have historically used:: |
| 129 |
|
| 130 |
import unittest |
| 131 |
|
| 132 |
If you want to continue to use the base ``unittest`` library, you can -- |
| 133 |
you just won't get any of the nice new ``unittest2`` features. |
| 134 |
|
| 135 |
Transaction context managers |
| 136 |
---------------------------- |
| 137 |
|
| 138 |
Users of Python 2.5 and above may now use transaction management functions as |
| 139 |
context managers. For example:: |
| 140 |
|
| 141 |
with transaction.autocommit(): |
| 142 |
... |
| 143 |
|
| 144 |
Configurable delete-cascade |
| 145 |
--------------------------- |
| 146 |
|
| 147 |
:class:`~django.db.models.ForeignKey` and |
| 148 |
:class:`~django.db.models.OneToOneField` now accept an |
| 149 |
:attr:`~django.db.models.ForeignKey.on_delete` argument to customize behavior |
| 150 |
when the referenced object is deleted. Previously, deletes were always |
| 151 |
cascaded; available alternatives now include set null, set default, set to any |
| 152 |
value, protect, or do nothing. |
| 153 |
|
| 154 |
For more information, see the :attr:`~django.db.models.ForeignKey.on_delete` |
| 155 |
documentation. |
| 156 |
|
| 157 |
Contextual markers and comments for translatable strings |
| 158 |
-------------------------------------------------------- |
| 159 |
|
| 160 |
For translation strings with ambiguous meaning, you can now |
| 161 |
use the ``pgettext`` function to specify the context of the string. |
| 162 |
|
| 163 |
And if you just want to add some information for translators, you |
| 164 |
can also add special translator comments in the source. |
| 165 |
|
| 166 |
For more information, see :ref:`contextual-markers` and |
| 167 |
:ref:`translator-comments`. |
| 168 |
|
| 169 |
Improvements to built-in template tags |
| 170 |
-------------------------------------- |
| 171 |
|
| 172 |
A number of improvements have been made to Django's built-in template tags: |
| 173 |
|
| 174 |
* The :ttag:`include` tag now accepts a ``with`` option, allowing |
| 175 |
you to specify context variables to the included template |
| 176 |
|
| 177 |
* The :ttag:`include` tag now accepts an ``only`` option, allowing |
| 178 |
you to exclude the current context from the included context |
| 179 |
|
| 180 |
* The :ttag:`with` tag now allows you to define multiple context |
| 181 |
variables in a single :ttag:`with` block. |
| 182 |
|
| 183 |
* The :ttag:`load` tag now accepts a ``from`` argument, allowing |
| 184 |
you to load a single tag or filter from a library. |
| 185 |
|
| 186 |
TemplateResponse |
| 187 |
---------------- |
| 188 |
|
| 189 |
It can sometimes be beneficial to allow decorators or middleware to |
| 190 |
modify a response *after* it has been constructed by the view. For |
| 191 |
example, you may want to change the template that is used, or put |
| 192 |
additional data into the context. |
| 193 |
|
| 194 |
However, you can't (easily) modify the content of a basic |
| 195 |
:class:`~django.http.HttpResponse` after it has been constructed. To |
| 196 |
overcome this limitation, Django 1.3 adds a new |
| 197 |
:class:`~django.template.response.TemplateResponse` class. Unlike basic |
| 198 |
:class:`~django.http.HttpResponse` objects, |
| 199 |
:class:`~django.template.response.TemplateResponse` objects retain the details |
| 200 |
of the template and context that was provided by the view to compute |
| 201 |
the response. The final output of the response is not computed until |
| 202 |
it is needed, later in the response process. |
| 203 |
|
| 204 |
For more details, see the :doc:`documentation </ref/template-response>` |
| 205 |
on the :class:`~django.template.response.TemplateResponse` class. |
| 206 |
|
| 207 |
Caching changes |
| 208 |
--------------- |
| 209 |
|
| 210 |
Django 1.3 sees the introduction of several improvements to the |
| 211 |
Django's caching infrastructure. |
| 212 |
|
| 213 |
Firstly, Django now supports multiple named caches. In the same way |
| 214 |
that Django 1.2 introduced support for multiple database connections, |
| 215 |
Django 1.3 allows you to use the new :setting:`CACHES` setting to |
| 216 |
define multiple named cache connections. |
| 217 |
|
| 218 |
Secondly, :ref:`versioning <cache_versioning>`, :ref:`site-wide |
| 219 |
prefixing <cache_key_prefixing>` and :ref:`transformation |
| 220 |
<cache_key_transformation>` have been added to the cache API. |
| 221 |
|
| 222 |
Thirdly, :ref:`cache key creation <using-vary-headers>` has been |
| 223 |
updated to take the request query string into account on ``GET`` |
| 224 |
requests. |
| 225 |
|
| 226 |
Finally, support for pylibmc_ has been added to the memcached cache |
| 227 |
backend. |
| 228 |
|
| 229 |
For more details, see the :doc:`documentation on |
| 230 |
caching in Django</topics/cache>`. |
| 231 |
|
| 232 |
.. _pylibmc: http://sendapatch.se/projects/pylibmc/ |
| 233 |
|
| 234 |
Permissions for inactive users |
| 235 |
------------------------------ |
| 236 |
|
| 237 |
If you provide a custom auth backend with ``supports_inactive_user`` |
| 238 |
set to ``True``, an inactive ``User`` instance will check the backend |
| 239 |
for permissions. This is useful for further centralizing the |
| 240 |
permission handling. See the :doc:`authentication docs </topics/auth/index>` |
| 241 |
for more details. |
| 242 |
|
| 243 |
GeoDjango |
| 244 |
--------- |
| 245 |
|
| 246 |
The GeoDjango test suite is now included when |
| 247 |
:ref:`running the Django test suite <running-unit-tests>` with ``runtests.py`` |
| 248 |
when using :ref:`spatial database backends <spatial-backends>`. |
| 249 |
|
| 250 |
:setting:`MEDIA_URL` and :setting:`STATIC_URL` must end in a slash |
| 251 |
------------------------------------------------------------------ |
| 252 |
|
| 253 |
Previously, the :setting:`MEDIA_URL` setting only required a trailing slash if |
| 254 |
it contained a suffix beyond the domain name. |
| 255 |
|
| 256 |
A trailing slash is now *required* for :setting:`MEDIA_URL` and the new |
| 257 |
:setting:`STATIC_URL` setting as long as it is not blank. This ensures there is |
| 258 |
a consistent way to combine paths in templates. |
| 259 |
|
| 260 |
Project settings which provide either of both settings without a trailing |
| 261 |
slash will now raise a ``PendingDeprecationWarning``. |
| 262 |
|
| 263 |
In Django 1.4 this same condition will raise ``DeprecationWarning``, |
| 264 |
and in Django 1.5 will raise an ``ImproperlyConfigured`` exception. |
| 265 |
|
| 266 |
Everything else |
| 267 |
--------------- |
| 268 |
|
| 269 |
Django :doc:`1.1 <1.1>` and :doc:`1.2 <1.2>` added |
| 270 |
lots of big ticket items to Django, like multiple-database support, |
| 271 |
model validation, and a session-based messages framework. However, |
| 272 |
this focus on big features came at the cost of lots of smaller |
| 273 |
features. |
| 274 |
|
| 275 |
To compensate for this, the focus of the Django 1.3 development |
| 276 |
process has been on adding lots of smaller, long standing feature |
| 277 |
requests. These include: |
| 278 |
|
| 279 |
* Improved tools for accessing and manipulating the current |
| 280 |
:class:`~django.contrib.sites.models.Site` object in |
| 281 |
:doc:`the sites framework </ref/contrib/sites>`. |
| 282 |
|
| 283 |
* A :class:`~django.test.RequestFactory` for mocking requests |
| 284 |
in tests. |
| 285 |
|
| 286 |
* A new test assertion -- |
| 287 |
:meth:`~django.test.TransactionTestCase.assertNumQueries` -- making it |
| 288 |
easier to test the database activity associated with a view. |
| 289 |
|
| 290 |
* Support for lookups spanning relations in admin's |
| 291 |
:attr:`~django.contrib.admin.ModelAdmin.list_filter`. |
| 292 |
|
| 293 |
* Support for HttpOnly_ cookies. |
| 294 |
|
| 295 |
* :func:`~django.core.mail.mail_admins` and |
| 296 |
:func:`~django.core.mail.mail_managers` now support easily attaching |
| 297 |
HTML content to messages. |
| 298 |
|
| 299 |
* :class:`~django.core.mail.EmailMessage` now supports CC's. |
| 300 |
|
| 301 |
* Error emails now include more of the detail and formatting of the |
| 302 |
debug server error page. |
| 303 |
|
| 304 |
* :meth:`~django.template.Library.simple_tag` now accepts a |
| 305 |
``takes_context`` argument, making it easier to write simple |
| 306 |
template tags that require access to template context. |
| 307 |
|
| 308 |
* A new :meth:`~django.shortcuts.render()` shortcut -- an alternative |
| 309 |
to ``django.shortcuts.render_to_response()`` providing a |
| 310 |
:class:`~django.template.RequestContext` by default. |
| 311 |
|
| 312 |
* Support for combining :class:`F expressions <django.db.models.F>` |
| 313 |
with ``timedelta`` values when retrieving or updating database values. |
| 314 |
|
| 315 |
.. _HttpOnly: https://owasp.org/www-community/HttpOnly |
| 316 |
|
| 317 |
.. _backwards-incompatible-changes-1.3: |
| 318 |
|
| 319 |
Backwards-incompatible changes in 1.3 |
| 320 |
===================================== |
| 321 |
|
| 322 |
CSRF validation now applies to AJAX requests |
| 323 |
-------------------------------------------- |
| 324 |
|
| 325 |
Prior to Django 1.2.5, Django's CSRF-prevention system exempted AJAX |
| 326 |
requests from CSRF verification; due to `security issues`_ reported to |
| 327 |
us, however, *all* requests are now subjected to CSRF |
| 328 |
verification. Consult :doc:`the Django CSRF documentation |
| 329 |
</ref/csrf>` for details on how to handle CSRF verification in |
| 330 |
AJAX requests. |
| 331 |
|
| 332 |
.. _security issues: https://www.djangoproject.com/weblog/2011/feb/08/security/ |
| 333 |
|
| 334 |
Restricted filters in admin interface |
| 335 |
------------------------------------- |
| 336 |
|
| 337 |
Prior to Django 1.2.5, the Django administrative interface allowed |
| 338 |
filtering on any model field or relation -- not just those specified |
| 339 |
in ``list_filter`` -- via query string manipulation. Due to security |
| 340 |
issues reported to us, however, query string lookup arguments in the |
| 341 |
admin must be for fields or relations specified in ``list_filter`` or |
| 342 |
``date_hierarchy``. |
| 343 |
|
| 344 |
Deleting a model doesn't delete associated files |
| 345 |
------------------------------------------------ |
| 346 |
|
| 347 |
In earlier Django versions, when a model instance containing a |
| 348 |
:class:`~django.db.models.FileField` was deleted, |
| 349 |
:class:`~django.db.models.FileField` took it upon itself to also delete the |
| 350 |
file from the backend storage. This opened the door to several data-loss |
| 351 |
scenarios, including rolled-back transactions and fields on different models |
| 352 |
referencing the same file. In Django 1.3, when a model is deleted the |
| 353 |
:class:`~django.db.models.FileField`’s ``delete()`` method won't be called. If |
| 354 |
you need cleanup of orphaned files, you'll need to handle it yourself (for |
| 355 |
instance, with a custom management command that can be run manually or |
| 356 |
scheduled to run periodically via e.g. cron). |
| 357 |
|
| 358 |
PasswordInput default rendering behavior |
| 359 |
---------------------------------------- |
| 360 |
|
| 361 |
The :class:`~django.forms.PasswordInput` form widget, intended for use |
| 362 |
with form fields which represent passwords, accepts a boolean keyword |
| 363 |
argument ``render_value`` indicating whether to send its data back to |
| 364 |
the browser when displaying a submitted form with errors. Prior to |
| 365 |
Django 1.3, this argument defaulted to ``True``, meaning that the |
| 366 |
submitted password would be sent back to the browser as part of the |
| 367 |
form. Developers who wished to add a bit of additional security by |
| 368 |
excluding that value from the redisplayed form could instantiate a |
| 369 |
:class:`~django.forms.PasswordInput` passing ``render_value=False`` . |
| 370 |
|
| 371 |
Due to the sensitive nature of passwords, however, Django 1.3 takes |
| 372 |
this step automatically; the default value of ``render_value`` is now |
| 373 |
``False``, and developers who want the password value returned to the |
| 374 |
browser on a submission with errors (the previous behavior) must now |
| 375 |
explicitly indicate this. For example:: |
| 376 |
|
| 377 |
class LoginForm(forms.Form): |
| 378 |
username = forms.CharField(max_length=100) |
| 379 |
password = forms.CharField(widget=forms.PasswordInput(render_value=True)) |
| 380 |
|
| 381 |
Clearable default widget for FileField |
| 382 |
-------------------------------------- |
| 383 |
|
| 384 |
Django 1.3 now includes a :class:`~django.forms.ClearableFileInput` form widget |
| 385 |
in addition to :class:`~django.forms.FileInput`. ``ClearableFileInput`` renders |
| 386 |
with a checkbox to clear the field's value (if the field has a value and is not |
| 387 |
required); ``FileInput`` provided no means for clearing an existing file from |
| 388 |
a ``FileField``. |
| 389 |
|
| 390 |
``ClearableFileInput`` is now the default widget for a ``FileField``, so |
| 391 |
existing forms including ``FileField`` without assigning a custom widget will |
| 392 |
need to account for the possible extra checkbox in the rendered form output. |
| 393 |
|
| 394 |
To return to the previous rendering (without the ability to clear the |
| 395 |
``FileField``), use the ``FileInput`` widget in place of |
| 396 |
``ClearableFileInput``. For instance, in a ``ModelForm`` for a hypothetical |
| 397 |
``Document`` model with a ``FileField`` named ``document``:: |
| 398 |
|
| 399 |
from django import forms |
| 400 |
from myapp.models import Document |
| 401 |
|
| 402 |
|
| 403 |
class DocumentForm(forms.ModelForm): |
| 404 |
class Meta: |
| 405 |
model = Document |
| 406 |
widgets = {"document": forms.FileInput} |
| 407 |
|
| 408 |
New index on database session table |
| 409 |
----------------------------------- |
| 410 |
|
| 411 |
Prior to Django 1.3, the database table used by the database backend |
| 412 |
for the :doc:`sessions </topics/http/sessions>` app had no index on |
| 413 |
the ``expire_date`` column. As a result, date-based queries on the |
| 414 |
session table -- such as the query that is needed to purge old |
| 415 |
sessions -- would be very slow if there were lots of sessions. |
| 416 |
|
| 417 |
If you have an existing project that is using the database session |
| 418 |
backend, you don't have to do anything to accommodate this change. |
| 419 |
However, you may get a significant performance boost if you manually |
| 420 |
add the new index to the session table. The SQL that will add the |
| 421 |
index can be found by running the ``sqlindexes`` admin command: |
| 422 |
|
| 423 |
.. code-block:: shell |
| 424 |
|
| 425 |
python manage.py sqlindexes sessions |
| 426 |
|
| 427 |
No more naughty words |
| 428 |
--------------------- |
| 429 |
|
| 430 |
Django has historically provided (and enforced) a list of profanities. |
| 431 |
The comments app has enforced this list of profanities, preventing people from |
| 432 |
submitting comments that contained one of those profanities. |
| 433 |
|
| 434 |
Unfortunately, the technique used to implement this profanities list |
| 435 |
was woefully naive, and prone to the `Scunthorpe problem`_. Improving |
| 436 |
the built-in filter to fix this problem would require significant |
| 437 |
effort, and since natural language processing isn't the normal domain |
| 438 |
of a web framework, we have "fixed" the problem by making the list of |
| 439 |
prohibited words an empty list. |
| 440 |
|
| 441 |
If you want to restore the old behavior, simply put a |
| 442 |
``PROFANITIES_LIST`` setting in your settings file that includes the |
| 443 |
words that you want to prohibit (see the :commit:`commit that implemented this |
| 444 |
change <edd767d2612d891a906268cf590571f541dd164f>` if you want to see the list |
| 445 |
of words that was historically prohibited). However, if avoiding profanities is |
| 446 |
important to you, you would be well advised to seek out a better, less naive |
| 447 |
approach to the problem. |
| 448 |
|
| 449 |
.. _Scunthorpe problem: https://en.wikipedia.org/wiki/Scunthorpe_problem |
| 450 |
|
| 451 |
Localflavor changes |
| 452 |
------------------- |
| 453 |
|
| 454 |
Django 1.3 introduces the following backwards-incompatible changes to |
| 455 |
local flavors: |
| 456 |
|
| 457 |
* Canada (ca) -- The province "Newfoundland and Labrador" has had its |
| 458 |
province code updated to "NL", rather than the older "NF". In |
| 459 |
addition, the Yukon Territory has had its province code corrected to |
| 460 |
"YT", instead of "YK". |
| 461 |
|
| 462 |
* Indonesia (id) -- The province "Nanggroe Aceh Darussalam (NAD)" has |
| 463 |
been removed from the province list in favor of the new official |
| 464 |
designation "Aceh (ACE)". |
| 465 |
|
| 466 |
* United States of America (us) -- The list of "states" used by |
| 467 |
``USStateField`` has expanded to include Armed Forces postal |
| 468 |
codes. This is backwards-incompatible if you were relying on |
| 469 |
``USStateField`` not including them. |
| 470 |
|
| 471 |
FormSet updates |
| 472 |
--------------- |
| 473 |
|
| 474 |
In Django 1.3 ``FormSet`` creation behavior is modified slightly. Historically |
| 475 |
the class didn't make a distinction between not being passed data and being |
| 476 |
passed empty dictionary. This was inconsistent with behavior in other parts of |
| 477 |
the framework. Starting with 1.3 if you pass in empty dictionary the |
| 478 |
``FormSet`` will raise a ``ValidationError``. |
| 479 |
|
| 480 |
For example with a ``FormSet``: |
| 481 |
|
| 482 |
.. code-block:: pycon |
| 483 |
|
| 484 |
>>> class ArticleForm(Form): |
| 485 |
... title = CharField() |
| 486 |
... pub_date = DateField() |
| 487 |
... |
| 488 |
>>> ArticleFormSet = formset_factory(ArticleForm) |
| 489 |
|
| 490 |
the following code will raise a ``ValidationError``: |
| 491 |
|
| 492 |
.. code-block:: pycon |
| 493 |
|
| 494 |
>>> ArticleFormSet({}) |
| 495 |
Traceback (most recent call last): |
| 496 |
... |
| 497 |
ValidationError: [u'ManagementForm data is missing or has been tampered with'] |
| 498 |
|
| 499 |
if you need to instantiate an empty ``FormSet``, don't pass in the data or use |
| 500 |
``None``: |
| 501 |
|
| 502 |
.. code-block:: pycon |
| 503 |
|
| 504 |
>>> formset = ArticleFormSet() |
| 505 |
>>> formset = ArticleFormSet(data=None) |
| 506 |
|
| 507 |
Callables in templates |
| 508 |
---------------------- |
| 509 |
|
| 510 |
Previously, a callable in a template would only be called automatically as part |
| 511 |
of the variable resolution process if it was retrieved via attribute |
| 512 |
lookup. This was an inconsistency that could result in confusing and unhelpful |
| 513 |
behavior: |
| 514 |
|
| 515 |
.. code-block:: pycon |
| 516 |
|
| 517 |
>>> Template("{{ user.get_full_name }}").render(Context({"user": user})) |
| 518 |
u'Joe Bloggs' |
| 519 |
>>> Template("{{ full_name }}").render(Context({"full_name": user.get_full_name})) |
| 520 |
u'<bound method User.get_full_name of <... |
| 521 |
|
| 522 |
This has been resolved in Django 1.3 - the result in both cases will be ``u'Joe |
| 523 |
Bloggs'``. Although the previous behavior was not useful for a template language |
| 524 |
designed for web designers, and was never deliberately supported, it is possible |
| 525 |
that some templates may be broken by this change. |
| 526 |
|
| 527 |
Use of custom SQL to load initial data in tests |
| 528 |
----------------------------------------------- |
| 529 |
|
| 530 |
Django provides a custom SQL hooks as a way to inject hand-crafted SQL |
| 531 |
into the database synchronization process. One of the possible uses |
| 532 |
for this custom SQL is to insert data into your database. If your |
| 533 |
custom SQL contains ``INSERT`` statements, those insertions will be |
| 534 |
performed every time your database is synchronized. This includes the |
| 535 |
synchronization of any test databases that are created when you run a |
| 536 |
test suite. |
| 537 |
|
| 538 |
However, in the process of testing the Django 1.3, it was discovered |
| 539 |
that this feature has never completely worked as advertised. When |
| 540 |
using database backends that don't support transactions, or when using |
| 541 |
a TransactionTestCase, data that has been inserted using custom SQL |
| 542 |
will not be visible during the testing process. |
| 543 |
|
| 544 |
Unfortunately, there was no way to rectify this problem without |
| 545 |
introducing a backwards incompatibility. Rather than leave |
| 546 |
SQL-inserted initial data in an uncertain state, Django now enforces |
| 547 |
the policy that data inserted by custom SQL will *not* be visible |
| 548 |
during testing. |
| 549 |
|
| 550 |
This change only affects the testing process. You can still use custom |
| 551 |
SQL to load data into your production database as part of the ``syncdb`` |
| 552 |
process. If you require data to exist during test conditions, you |
| 553 |
should either insert it using :ref:`test fixtures |
| 554 |
<topics-testing-fixtures>`, or using the ``setUp()`` method of your |
| 555 |
test case. |
| 556 |
|
| 557 |
Changed priority of translation loading |
| 558 |
--------------------------------------- |
| 559 |
|
| 560 |
Work has been done to simplify, rationalize and properly document the algorithm |
| 561 |
used by Django at runtime to build translations from the different translations |
| 562 |
found on disk, namely: |
| 563 |
|
| 564 |
For translatable literals found in Python code and templates (``'django'`` |
| 565 |
gettext domain): |
| 566 |
|
| 567 |
* Priorities of translations included with applications listed in the |
| 568 |
:setting:`INSTALLED_APPS` setting were changed. To provide a behavior |
| 569 |
consistent with other parts of Django that also use such setting (templates, |
| 570 |
etc.) now, when building the translation that will be made available, the |
| 571 |
apps listed first have higher precedence than the ones listed later. |
| 572 |
|
| 573 |
* Now it is possible to override the translations shipped with applications by |
| 574 |
using the :setting:`LOCALE_PATHS` setting whose translations have now higher |
| 575 |
precedence than the translations of :setting:`INSTALLED_APPS` applications. |
| 576 |
The relative priority among the values listed in this setting has also been |
| 577 |
modified so the paths listed first have higher precedence than the |
| 578 |
ones listed later. |
| 579 |
|
| 580 |
* The ``locale`` subdirectory of the directory containing the settings, that |
| 581 |
usually coincides with and is known as the *project directory* is being |
| 582 |
deprecated in this release as a source of translations. (the precedence of |
| 583 |
these translations is intermediate between applications and :setting:`LOCALE_PATHS` |
| 584 |
translations). See the `corresponding deprecated features section`_ |
| 585 |
of this document. |
| 586 |
|
| 587 |
For translatable literals found in JavaScript code (``'djangojs'`` gettext |
| 588 |
domain): |
| 589 |
|
| 590 |
* Similarly to the ``'django'`` domain translations: Overriding of |
| 591 |
translations shipped with applications by using the :setting:`LOCALE_PATHS` |
| 592 |
setting is now possible for this domain too. These translations have higher |
| 593 |
precedence than the translations of Python packages passed to the |
| 594 |
``javascript_catalog()`` view. Paths listed first have higher precedence than |
| 595 |
the ones listed later. |
| 596 |
|
| 597 |
* Translations under the ``locale`` subdirectory of the *project directory* |
| 598 |
have never been taken in account for JavaScript translations and remain in |
| 599 |
the same situation considering the deprecation of such location. |
| 600 |
|
| 601 |
.. _corresponding deprecated features section: loading_of_project_level_translations_ |
| 602 |
|
| 603 |
Transaction management |
| 604 |
---------------------- |
| 605 |
|
| 606 |
When using managed transactions -- that is, anything but the default |
| 607 |
autocommit mode -- it is important when a transaction is marked as |
| 608 |
"dirty". Dirty transactions are committed by the ``commit_on_success`` |
| 609 |
decorator or the ``django.middleware.transaction.TransactionMiddleware``, and |
| 610 |
``commit_manually`` forces them to be closed explicitly; clean transactions |
| 611 |
"get a pass", which means they are usually rolled back at the end of a request |
| 612 |
when the connection is closed. |
| 613 |
|
| 614 |
Until Django 1.3, transactions were only marked dirty when Django was |
| 615 |
aware of a modifying operation performed in them; that is, either some |
| 616 |
model was saved, some bulk update or delete was performed, or the user |
| 617 |
explicitly called ``transaction.set_dirty()``. In Django 1.3, a |
| 618 |
transaction is marked dirty when *any* database operation is |
| 619 |
performed. |
| 620 |
|
| 621 |
As a result of this change, you no longer need to set a transaction |
| 622 |
dirty explicitly when you execute raw SQL or use a data-modifying |
| 623 |
``SELECT``. However, you *do* need to explicitly close any read-only |
| 624 |
transactions that are being managed using ``commit_manually()``. For example:: |
| 625 |
|
| 626 |
@transaction.commit_manually |
| 627 |
def my_view(request, name): |
| 628 |
obj = get_object_or_404(MyObject, name__iexact=name) |
| 629 |
return render_to_response("template", {"object": obj}) |
| 630 |
|
| 631 |
Prior to Django 1.3, this would work without error. However, under |
| 632 |
Django 1.3, this will raise a |
| 633 |
:class:`~django.db.transaction.TransactionManagementError` because |
| 634 |
the read operation that retrieves the ``MyObject`` instance leaves the |
| 635 |
transaction in a dirty state. |
| 636 |
|
| 637 |
No password reset for inactive users |
| 638 |
------------------------------------ |
| 639 |
|
| 640 |
Prior to Django 1.3, inactive users were able to request a password reset email |
| 641 |
and reset their password. In Django 1.3 inactive users will receive the same |
| 642 |
message as a nonexistent account. |
| 643 |
|
| 644 |
Password reset view now accepts ``from_email`` |
| 645 |
---------------------------------------------- |
| 646 |
|
| 647 |
The ``django.contrib.auth.views.password_reset()`` view now accepts a |
| 648 |
``from_email`` parameter, which is passed to the ``password_reset_form``’s |
| 649 |
``save()`` method as a keyword argument. If you are using this view with a |
| 650 |
custom password reset form, then you will need to ensure your form's ``save()`` |
| 651 |
method accepts this keyword argument. |
| 652 |
|
| 653 |
.. _deprecated-features-1.3: |
| 654 |
|
| 655 |
Features deprecated in 1.3 |
| 656 |
========================== |
| 657 |
|
| 658 |
Django 1.3 deprecates some features from earlier releases. |
| 659 |
These features are still supported, but will be gradually phased out |
| 660 |
over the next few release cycles. |
| 661 |
|
| 662 |
Code taking advantage of any of the features below will raise a |
| 663 |
``PendingDeprecationWarning`` in Django 1.3. This warning will be |
| 664 |
silent by default, but may be turned on using Python's :mod:`warnings` |
| 665 |
module, or by running Python with a ``-Wd`` or ``-Wall`` flag. |
| 666 |
|
| 667 |
In Django 1.4, these warnings will become a ``DeprecationWarning``, |
| 668 |
which is *not* silent. In Django 1.5 support for these features will |
| 669 |
be removed entirely. |
| 670 |
|
| 671 |
.. seealso:: |
| 672 |
|
| 673 |
For more details, see the documentation :doc:`Django's release process |
| 674 |
</internals/release-process>` and our :doc:`deprecation timeline |
| 675 |
</internals/deprecation>`. |
| 676 |
|
| 677 |
``mod_python`` support |
| 678 |
---------------------- |
| 679 |
|
| 680 |
The ``mod_python`` library has not had a release since 2007 or a commit since |
| 681 |
2008. The Apache Foundation board voted to remove ``mod_python`` from the set |
| 682 |
of active projects in its version control repositories, and its lead developer |
| 683 |
has shifted all of his efforts toward the lighter, slimmer, more stable, and |
| 684 |
more flexible ``mod_wsgi`` backend. |
| 685 |
|
| 686 |
If you are currently using the ``mod_python`` request handler, you |
| 687 |
should redeploy your Django projects using another request handler. |
| 688 |
:doc:`mod_wsgi </howto/deployment/wsgi/modwsgi>` is the request handler |
| 689 |
recommended by the Django project, but FastCGI is also supported. Support for |
| 690 |
``mod_python`` deployment will be removed in Django 1.5. |
| 691 |
|
| 692 |
Function-based generic views |
| 693 |
---------------------------- |
| 694 |
|
| 695 |
As a result of the introduction of class-based generic views, the |
| 696 |
function-based generic views provided by Django have been deprecated. |
| 697 |
The following modules and the views they contain have been deprecated: |
| 698 |
|
| 699 |
* ``django.views.generic.create_update`` |
| 700 |
* ``django.views.generic.date_based`` |
| 701 |
* ``django.views.generic.list_detail`` |
| 702 |
* ``django.views.generic.simple`` |
| 703 |
|
| 704 |
Test client response ``template`` attribute |
| 705 |
------------------------------------------- |
| 706 |
|
| 707 |
Django's :ref:`test client <test-client>` returns |
| 708 |
:class:`~django.test.Response` objects annotated with extra testing |
| 709 |
information. In Django versions prior to 1.3, this included a ``template`` |
| 710 |
attribute containing information about templates rendered in generating the |
| 711 |
response: either None, a single :class:`~django.template.Template` object, or a |
| 712 |
list of :class:`~django.template.Template` objects. This inconsistency in |
| 713 |
return values (sometimes a list, sometimes not) made the attribute difficult |
| 714 |
to work with. |
| 715 |
|
| 716 |
In Django 1.3 the ``template`` attribute is deprecated in favor of a new |
| 717 |
:attr:`~django.test.Response.templates` attribute, which is always a |
| 718 |
list, even if it has only a single element or no elements. |
| 719 |
|
| 720 |
``DjangoTestRunner`` |
| 721 |
-------------------- |
| 722 |
|
| 723 |
As a result of the introduction of support for ``unittest2``, the features |
| 724 |
of ``django.test.simple.DjangoTestRunner`` (including fail-fast |
| 725 |
and Ctrl-C test termination) have been made redundant. In view of this |
| 726 |
redundancy, ``DjangoTestRunner`` has been turned into an empty placeholder |
| 727 |
class, and will be removed entirely in Django 1.5. |
| 728 |
|
| 729 |
Changes to ``url`` and ``ssi`` |
| 730 |
------------------------------ |
| 731 |
|
| 732 |
Most template tags will allow you to pass in either constants or |
| 733 |
variables as arguments -- for example: |
| 734 |
|
| 735 |
.. code-block:: html+django |
| 736 |
|
| 737 |
{% extends "base.html" %} |
| 738 |
|
| 739 |
allows you to specify a base template as a constant, but if you have a |
| 740 |
context variable ``templ`` that contains the value ``base.html``: |
| 741 |
|
| 742 |
.. code-block:: html+django |
| 743 |
|
| 744 |
{% extends templ %} |
| 745 |
|
| 746 |
is also legal. |
| 747 |
|
| 748 |
However, due to an accident of history, the ``url`` and ``ssi`` are different. |
| 749 |
These tags use the second, quoteless syntax, but interpret the argument as a |
| 750 |
constant. This means it isn't possible to use a context variable as the target |
| 751 |
of a ``url`` and ``ssi`` tag. |
| 752 |
|
| 753 |
Django 1.3 marks the start of the process to correct this historical |
| 754 |
accident. Django 1.3 adds a new template library -- ``future`` -- that |
| 755 |
provides alternate implementations of the ``url`` and ``ssi`` |
| 756 |
template tags. This ``future`` library implement behavior that makes |
| 757 |
the handling of the first argument consistent with the handling of all |
| 758 |
other variables. So, an existing template that contains: |
| 759 |
|
| 760 |
.. code-block:: html+django |
| 761 |
|
| 762 |
{% url sample %} |
| 763 |
|
| 764 |
should be replaced with: |
| 765 |
|
| 766 |
.. code-block:: html+django |
| 767 |
|
| 768 |
{% load url from future %} |
| 769 |
{% url 'sample' %} |
| 770 |
|
| 771 |
The tags implementing the old behavior have been deprecated, and in |
| 772 |
Django 1.5, the old behavior will be replaced with the new behavior. |
| 773 |
To ensure compatibility with future versions of Django, existing |
| 774 |
templates should be modified to use the new ``future`` libraries and |
| 775 |
syntax. |
| 776 |
|
| 777 |
Changes to the login methods of the admin |
| 778 |
----------------------------------------- |
| 779 |
|
| 780 |
In previous version the admin app defined login methods in multiple locations |
| 781 |
and ignored the almost identical implementation in the already used auth app. |
| 782 |
A side effect of this duplication was the missing adoption of the changes made |
| 783 |
in :commit:`r12634 <c8015052d935a99a5c8f96434b2d0cd16d8a4e14>` to support a |
| 784 |
broader set of characters for usernames. |
| 785 |
|
| 786 |
This release refactors the admin's login mechanism to use a subclass of the |
| 787 |
:class:`~django.contrib.auth.forms.AuthenticationForm` instead of a manual |
| 788 |
form validation. The previously undocumented method |
| 789 |
``'django.contrib.admin.sites.AdminSite.display_login_form'`` has been removed |
| 790 |
in favor of a new :attr:`~django.contrib.admin.AdminSite.login_form` |
| 791 |
attribute. |
| 792 |
|
| 793 |
``reset`` and ``sqlreset`` management commands |
| 794 |
---------------------------------------------- |
| 795 |
|
| 796 |
Those commands have been deprecated. The ``flush`` and ``sqlflush`` commands |
| 797 |
can be used to delete everything. You can also use ALTER TABLE or DROP TABLE |
| 798 |
statements manually. |
| 799 |
|
| 800 |
|
| 801 |
GeoDjango |
| 802 |
--------- |
| 803 |
|
| 804 |
* The function-based :setting:`TEST_RUNNER` previously used to execute |
| 805 |
the GeoDjango test suite, ``django.contrib.gis.tests.run_gis_tests``, was |
| 806 |
deprecated for the class-based runner, |
| 807 |
``django.contrib.gis.tests.GeoDjangoTestSuiteRunner``. |
| 808 |
|
| 809 |
* Previously, calling |
| 810 |
:meth:`~django.contrib.gis.geos.GEOSGeometry.transform` would |
| 811 |
silently do nothing when GDAL wasn't available. Now, a |
| 812 |
:class:`~django.contrib.gis.geos.GEOSException` is properly raised |
| 813 |
to indicate possible faulty application code. A warning is now |
| 814 |
raised if :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` is |
| 815 |
called when the SRID of the geometry is less than 0 or ``None``. |
| 816 |
|
| 817 |
``CZBirthNumberField.clean`` |
| 818 |
---------------------------- |
| 819 |
|
| 820 |
Previously this field's ``clean()`` method accepted a second, gender, argument |
| 821 |
which allowed stronger validation checks to be made, however since this |
| 822 |
argument could never actually be passed from the Django form machinery it is |
| 823 |
now pending deprecation. |
| 824 |
|
| 825 |
``CompatCookie`` |
| 826 |
---------------- |
| 827 |
|
| 828 |
Previously, ``django.http`` exposed an undocumented ``CompatCookie`` class, |
| 829 |
which was a bugfix wrapper around the standard library ``SimpleCookie``. As the |
| 830 |
fixes are moving upstream, this is now deprecated - you should use ``from |
| 831 |
django.http import SimpleCookie`` instead. |
| 832 |
|
| 833 |
.. _loading_of_project_level_translations: |
| 834 |
|
| 835 |
Loading of *project-level* translations |
| 836 |
--------------------------------------- |
| 837 |
|
| 838 |
This release of Django starts the deprecation process for inclusion of |
| 839 |
translations located under the so-called *project path* in the translation |
| 840 |
building process performed at runtime. The :setting:`LOCALE_PATHS` setting can |
| 841 |
be used for the same task by adding the filesystem path to a ``locale`` |
| 842 |
directory containing project-level translations to the value of that setting. |
| 843 |
|
| 844 |
Rationale for this decision: |
| 845 |
|
| 846 |
* The *project path* has always been a loosely defined concept |
| 847 |
(actually, the directory used for locating project-level |
| 848 |
translations is the directory containing the settings module) and |
| 849 |
there has been a shift in other parts of the framework to stop using |
| 850 |
it as a reference for location of assets at runtime. |
| 851 |
|
| 852 |
* Detection of the ``locale`` subdirectory tends to fail when the |
| 853 |
deployment scenario is more complex than the basic one. e.g. it |
| 854 |
fails when the settings module is a directory (ticket #10765). |
| 855 |
|
| 856 |
* There are potential strange development- and deployment-time |
| 857 |
problems like the fact that the ``project_dir/locale/`` subdir can |
| 858 |
generate spurious error messages when the project directory is added |
| 859 |
to the Python path (``manage.py runserver`` does this) and then it |
| 860 |
clashes with the equally named standard library module, this is a |
| 861 |
typical warning message: |
| 862 |
|
| 863 |
.. code-block:: pytb |
| 864 |
|
| 865 |
/usr/lib/python2.6/gettext.py:49: ImportWarning: Not importing directory '/path/to/project/locale': missing __init__.py. |
| 866 |
import locale, copy, os, re, struct, sys |
| 867 |
|
| 868 |
* This location wasn't included in the translation building process |
| 869 |
for JavaScript literals. This deprecation removes such |
| 870 |
inconsistency. |
| 871 |
|
| 872 |
``PermWrapper`` moved to ``django.contrib.auth.context_processors`` |
| 873 |
------------------------------------------------------------------- |
| 874 |
|
| 875 |
In Django 1.2, we began the process of changing the location of the |
| 876 |
``auth`` context processor from ``django.core.context_processors`` to |
| 877 |
``django.contrib.auth.context_processors``. However, the |
| 878 |
``PermWrapper`` support class was mistakenly omitted from that |
| 879 |
migration. In Django 1.3, the ``PermWrapper`` class has also been |
| 880 |
moved to ``django.contrib.auth.context_processors``, along with the |
| 881 |
``PermLookupDict`` support class. The new classes are functionally |
| 882 |
identical to their old versions; only the module location has changed. |
| 883 |
|
| 884 |
Removal of ``XMLField`` |
| 885 |
----------------------- |
| 886 |
|
| 887 |
When Django was first released, Django included an ``XMLField`` that performed |
| 888 |
automatic XML validation for any field input. However, this validation function |
| 889 |
hasn't been performed since the introduction of ``newforms``, prior to the 1.0 |
| 890 |
release. As a result, ``XMLField`` as currently implemented is functionally |
| 891 |
indistinguishable from a simple :class:`~django.db.models.TextField`. |
| 892 |
|
| 893 |
For this reason, Django 1.3 has fast-tracked the deprecation of |
| 894 |
``XMLField`` -- instead of a two-release deprecation, ``XMLField`` |
| 895 |
will be removed entirely in Django 1.4. |
| 896 |
|
| 897 |
It's easy to update your code to accommodate this change -- just |
| 898 |
replace all uses of ``XMLField`` with ``TextField``, and remove the |
| 899 |
``schema_path`` keyword argument (if it is specified). |