| 1 |
========================================= |
| 2 |
Porting your apps from Django 0.96 to 1.0 |
| 3 |
========================================= |
| 4 |
|
| 5 |
Django 1.0 breaks compatibility with 0.96 in some areas. |
| 6 |
|
| 7 |
This guide will help you port 0.96 projects and apps to 1.0. The first part of |
| 8 |
this document includes the common changes needed to run with 1.0. If after going |
| 9 |
through the first part your code still breaks, check the section `Less-common |
| 10 |
Changes`_ for a list of a bunch of less-common compatibility issues. |
| 11 |
|
| 12 |
.. seealso:: |
| 13 |
|
| 14 |
The :doc:`1.0 release notes </releases/1.0>`. That document explains the new |
| 15 |
features in 1.0 more deeply; the porting guide is more concerned with |
| 16 |
helping you quickly update your code. |
| 17 |
|
| 18 |
Common changes |
| 19 |
============== |
| 20 |
|
| 21 |
This section describes the changes between 0.96 and 1.0 that most users will |
| 22 |
need to make. |
| 23 |
|
| 24 |
Use Unicode |
| 25 |
----------- |
| 26 |
|
| 27 |
Change string literals (``'foo'``) into Unicode literals (``u'foo'``). Django |
| 28 |
now uses Unicode strings throughout. In most places, raw strings will continue |
| 29 |
to work, but updating to use Unicode literals will prevent some obscure |
| 30 |
problems. |
| 31 |
|
| 32 |
See :doc:`/ref/unicode` for full details. |
| 33 |
|
| 34 |
Models |
| 35 |
------ |
| 36 |
|
| 37 |
Common changes to your models file: |
| 38 |
|
| 39 |
Rename ``maxlength`` to ``max_length`` |
| 40 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 41 |
|
| 42 |
Rename your ``maxlength`` argument to ``max_length`` (this was changed to be |
| 43 |
consistent with form fields): |
| 44 |
|
| 45 |
Replace ``__str__`` with ``__unicode__`` |
| 46 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 47 |
|
| 48 |
Replace your model's ``__str__`` function with a ``__unicode__`` method, and |
| 49 |
make sure you `use Unicode`_ (``u'foo'``) in that method. |
| 50 |
|
| 51 |
Remove ``prepopulated_from`` |
| 52 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 53 |
|
| 54 |
Remove the ``prepopulated_from`` argument on model fields. It's no longer valid |
| 55 |
and has been moved to the ``ModelAdmin`` class in ``admin.py``. See `the |
| 56 |
admin`_, below, for more details about changes to the admin. |
| 57 |
|
| 58 |
Remove ``core`` |
| 59 |
~~~~~~~~~~~~~~~ |
| 60 |
|
| 61 |
Remove the ``core`` argument from your model fields. It is no longer |
| 62 |
necessary, since the equivalent functionality (part of :ref:`inline editing |
| 63 |
<admin-inlines>`) is handled differently by the admin interface now. You don't |
| 64 |
have to worry about inline editing until you get to `the admin`_ section, |
| 65 |
below. For now, remove all references to ``core``. |
| 66 |
|
| 67 |
Replace ``class Admin:`` with ``admin.py`` |
| 68 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 69 |
|
| 70 |
Remove all your inner ``class Admin`` declarations from your models. They won't |
| 71 |
break anything if you leave them, but they also won't do anything. To register |
| 72 |
apps with the admin you'll move those declarations to an ``admin.py`` file; |
| 73 |
see `the admin`_ below for more details. |
| 74 |
|
| 75 |
.. seealso:: |
| 76 |
|
| 77 |
A contributor to djangosnippets__ has written a script that'll `scan your |
| 78 |
models.py and generate a corresponding admin.py`__. |
| 79 |
|
| 80 |
__ https://djangosnippets.org/ |
| 81 |
__ https://djangosnippets.org/snippets/603/ |
| 82 |
|
| 83 |
Example |
| 84 |
~~~~~~~ |
| 85 |
|
| 86 |
Below is an example ``models.py`` file with all the changes you'll need to make: |
| 87 |
|
| 88 |
Old (0.96) ``models.py``:: |
| 89 |
|
| 90 |
class Author(models.Model): |
| 91 |
first_name = models.CharField(maxlength=30) |
| 92 |
last_name = models.CharField(maxlength=30) |
| 93 |
slug = models.CharField(maxlength=60, prepopulate_from=("first_name", "last_name")) |
| 94 |
|
| 95 |
class Admin: |
| 96 |
list_display = ["first_name", "last_name"] |
| 97 |
|
| 98 |
def __str__(self): |
| 99 |
return "%s %s" % (self.first_name, self.last_name) |
| 100 |
|
| 101 |
New (1.0) ``models.py``:: |
| 102 |
|
| 103 |
class Author(models.Model): |
| 104 |
first_name = models.CharField(max_length=30) |
| 105 |
last_name = models.CharField(max_length=30) |
| 106 |
slug = models.CharField(max_length=60) |
| 107 |
|
| 108 |
def __unicode__(self): |
| 109 |
return "%s %s" % (self.first_name, self.last_name) |
| 110 |
|
| 111 |
New (1.0) ``admin.py``:: |
| 112 |
|
| 113 |
from django.contrib import admin |
| 114 |
from models import Author |
| 115 |
|
| 116 |
|
| 117 |
class AuthorAdmin(admin.ModelAdmin): |
| 118 |
list_display = ["first_name", "last_name"] |
| 119 |
prepopulated_fields = {"slug": ("first_name", "last_name")} |
| 120 |
|
| 121 |
|
| 122 |
admin.site.register(Author, AuthorAdmin) |
| 123 |
|
| 124 |
The Admin |
| 125 |
--------- |
| 126 |
|
| 127 |
One of the biggest changes in 1.0 is the new admin. The Django administrative |
| 128 |
interface (``django.contrib.admin``) has been completely refactored; admin |
| 129 |
definitions are now completely decoupled from model definitions, the framework |
| 130 |
has been rewritten to use Django's new form-handling library and redesigned with |
| 131 |
extensibility and customization in mind. |
| 132 |
|
| 133 |
Practically, this means you'll need to rewrite all of your ``class Admin`` |
| 134 |
declarations. You've already seen in `models`_ above how to replace your ``class |
| 135 |
Admin`` with an ``admin.site.register()`` call in an ``admin.py`` file. Below are |
| 136 |
some more details on how to rewrite that ``Admin`` declaration into the new |
| 137 |
syntax. |
| 138 |
|
| 139 |
Use new inline syntax |
| 140 |
~~~~~~~~~~~~~~~~~~~~~ |
| 141 |
|
| 142 |
The new ``edit_inline`` options have all been moved to ``admin.py``. Here's an |
| 143 |
example: |
| 144 |
|
| 145 |
Old (0.96):: |
| 146 |
|
| 147 |
class Parent(models.Model): ... |
| 148 |
|
| 149 |
|
| 150 |
class Child(models.Model): |
| 151 |
parent = models.ForeignKey(Parent, edit_inline=models.STACKED, num_in_admin=3) |
| 152 |
|
| 153 |
|
| 154 |
New (1.0):: |
| 155 |
|
| 156 |
class ChildInline(admin.StackedInline): |
| 157 |
model = Child |
| 158 |
extra = 3 |
| 159 |
|
| 160 |
|
| 161 |
class ParentAdmin(admin.ModelAdmin): |
| 162 |
model = Parent |
| 163 |
inlines = [ChildInline] |
| 164 |
|
| 165 |
|
| 166 |
admin.site.register(Parent, ParentAdmin) |
| 167 |
|
| 168 |
See :ref:`admin-inlines` for more details. |
| 169 |
|
| 170 |
Simplify ``fields``, or use ``fieldsets`` |
| 171 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 172 |
|
| 173 |
The old ``fields`` syntax was quite confusing, and has been simplified. The old |
| 174 |
syntax still works, but you'll need to use ``fieldsets`` instead. |
| 175 |
|
| 176 |
Old (0.96):: |
| 177 |
|
| 178 |
class ModelOne(models.Model): |
| 179 |
... |
| 180 |
|
| 181 |
class Admin: |
| 182 |
fields = ((None, {"fields": ("foo", "bar")}),) |
| 183 |
|
| 184 |
|
| 185 |
class ModelTwo(models.Model): |
| 186 |
... |
| 187 |
|
| 188 |
class Admin: |
| 189 |
fields = ( |
| 190 |
("group1", {"fields": ("foo", "bar"), "classes": "collapse"}), |
| 191 |
("group2", {"fields": ("spam", "eggs"), "classes": "collapse wide"}), |
| 192 |
) |
| 193 |
|
| 194 |
|
| 195 |
New (1.0):: |
| 196 |
|
| 197 |
class ModelOneAdmin(admin.ModelAdmin): |
| 198 |
fields = ("foo", "bar") |
| 199 |
|
| 200 |
|
| 201 |
class ModelTwoAdmin(admin.ModelAdmin): |
| 202 |
fieldsets = ( |
| 203 |
("group1", {"fields": ("foo", "bar"), "classes": "collapse"}), |
| 204 |
("group2", {"fields": ("spam", "eggs"), "classes": "collapse wide"}), |
| 205 |
) |
| 206 |
|
| 207 |
|
| 208 |
.. seealso:: |
| 209 |
|
| 210 |
* More detailed information about the changes and the reasons behind them |
| 211 |
can be found on the `NewformsAdminBranch wiki page`__ |
| 212 |
|
| 213 |
* The new admin comes with a ton of new features; you can read about them in |
| 214 |
the :doc:`admin documentation </ref/contrib/admin/index>`. |
| 215 |
|
| 216 |
__ https://code.djangoproject.com/wiki/NewformsAdminBranch |
| 217 |
|
| 218 |
URLs |
| 219 |
---- |
| 220 |
|
| 221 |
Update your root ``urls.py`` |
| 222 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 223 |
|
| 224 |
If you're using the admin site, you need to update your root ``urls.py``. |
| 225 |
|
| 226 |
Old (0.96) ``urls.py``:: |
| 227 |
|
| 228 |
from django.conf.urls.defaults import * |
| 229 |
|
| 230 |
urlpatterns = patterns( |
| 231 |
"", |
| 232 |
(r"^admin/", include("django.contrib.admin.urls")), |
| 233 |
# ... the rest of your URLs here ... |
| 234 |
) |
| 235 |
|
| 236 |
New (1.0) ``urls.py``:: |
| 237 |
|
| 238 |
from django.conf.urls.defaults import * |
| 239 |
|
| 240 |
# The next two lines enable the admin and load each admin.py file: |
| 241 |
from django.contrib import admin |
| 242 |
|
| 243 |
admin.autodiscover() |
| 244 |
|
| 245 |
urlpatterns = patterns( |
| 246 |
"", |
| 247 |
(r"^admin/(.*)", admin.site.root), |
| 248 |
# ... the rest of your URLs here ... |
| 249 |
) |
| 250 |
|
| 251 |
Views |
| 252 |
----- |
| 253 |
|
| 254 |
Use ``django.forms`` instead of ``newforms`` |
| 255 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 256 |
|
| 257 |
Replace ``django.newforms`` with ``django.forms`` -- Django 1.0 renamed the |
| 258 |
``newforms`` module (introduced in 0.96) to plain old ``forms``. The |
| 259 |
``oldforms`` module was also removed. |
| 260 |
|
| 261 |
If you're already using the ``newforms`` library, and you used our recommended |
| 262 |
``import`` statement syntax, all you have to do is change your import |
| 263 |
statements. |
| 264 |
|
| 265 |
Old:: |
| 266 |
|
| 267 |
from django import newforms as forms |
| 268 |
|
| 269 |
New:: |
| 270 |
|
| 271 |
from django import forms |
| 272 |
|
| 273 |
If you're using the old forms system (formerly known as ``django.forms`` and |
| 274 |
``django.oldforms``), you'll have to rewrite your forms. A good place to start |
| 275 |
is the :doc:`forms documentation </topics/forms/index>` |
| 276 |
|
| 277 |
Handle uploaded files using the new API |
| 278 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 279 |
|
| 280 |
Replace use of uploaded files -- that is, entries in ``request.FILES`` -- as |
| 281 |
simple dictionaries with the new |
| 282 |
:class:`~django.core.files.uploadedfile.UploadedFile`. The old dictionary |
| 283 |
syntax no longer works. |
| 284 |
|
| 285 |
Thus, in a view like:: |
| 286 |
|
| 287 |
def my_view(request): |
| 288 |
f = request.FILES["file_field_name"] |
| 289 |
... |
| 290 |
|
| 291 |
...you'd need to make the following changes: |
| 292 |
|
| 293 |
===================== ===================== |
| 294 |
Old (0.96) New (1.0) |
| 295 |
===================== ===================== |
| 296 |
``f['content']`` ``f.read()`` |
| 297 |
``f['filename']`` ``f.name`` |
| 298 |
``f['content-type']`` ``f.content_type`` |
| 299 |
===================== ===================== |
| 300 |
|
| 301 |
Work with file fields using the new API |
| 302 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 303 |
|
| 304 |
The internal implementation of :class:`django.db.models.FileField` have changed. |
| 305 |
A visible result of this is that the way you access special attributes (URL, |
| 306 |
filename, image size, etc.) of these model fields has changed. You will need to |
| 307 |
make the following changes, assuming your model's |
| 308 |
:class:`~django.db.models.FileField` is called ``myfile``: |
| 309 |
|
| 310 |
=================================== ======================== |
| 311 |
Old (0.96) New (1.0) |
| 312 |
=================================== ======================== |
| 313 |
``myfile.get_content_filename()`` ``myfile.content.path`` |
| 314 |
``myfile.get_content_url()`` ``myfile.content.url`` |
| 315 |
``myfile.get_content_size()`` ``myfile.content.size`` |
| 316 |
``myfile.save_content_file()`` ``myfile.content.save()`` |
| 317 |
``myfile.get_content_width()`` ``myfile.content.width`` |
| 318 |
``myfile.get_content_height()`` ``myfile.content.height`` |
| 319 |
=================================== ======================== |
| 320 |
|
| 321 |
Note that the ``width`` and ``height`` attributes only make sense for |
| 322 |
:class:`~django.db.models.ImageField` fields. More details can be found in the |
| 323 |
:doc:`model API </ref/models/fields>` documentation. |
| 324 |
|
| 325 |
Use ``Paginator`` instead of ``ObjectPaginator`` |
| 326 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 327 |
|
| 328 |
The ``ObjectPaginator`` in 0.96 has been removed and replaced with an improved |
| 329 |
version, :class:`django.core.paginator.Paginator`. |
| 330 |
|
| 331 |
Templates |
| 332 |
--------- |
| 333 |
|
| 334 |
Learn to love autoescaping |
| 335 |
~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 336 |
|
| 337 |
By default, the template system now automatically HTML-escapes the output of |
| 338 |
every variable. To learn more, see :ref:`automatic-html-escaping`. |
| 339 |
|
| 340 |
To disable auto-escaping for an individual variable, use the :tfilter:`safe` |
| 341 |
filter: |
| 342 |
|
| 343 |
.. code-block:: html+django |
| 344 |
|
| 345 |
This will be escaped: {{ data }} |
| 346 |
This will not be escaped: {{ data|safe }} |
| 347 |
|
| 348 |
To disable auto-escaping for an entire template, wrap the template (or just a |
| 349 |
particular section of the template) in the :ttag:`autoescape` tag: |
| 350 |
|
| 351 |
.. code-block:: html+django |
| 352 |
|
| 353 |
{% autoescape off %} |
| 354 |
... unescaped template content here ... |
| 355 |
{% endautoescape %} |
| 356 |
|
| 357 |
Less-common changes |
| 358 |
=================== |
| 359 |
|
| 360 |
The following changes are smaller, more localized changes. They should only |
| 361 |
affect more advanced users, but it's probably worth reading through the list and |
| 362 |
checking your code for these things. |
| 363 |
|
| 364 |
Signals |
| 365 |
------- |
| 366 |
|
| 367 |
* Add ``**kwargs`` to any registered signal handlers. |
| 368 |
|
| 369 |
* Connect, disconnect, and send signals via methods on the |
| 370 |
:class:`~django.dispatch.Signal` object instead of through module methods in |
| 371 |
``django.dispatch.dispatcher``. |
| 372 |
|
| 373 |
* Remove any use of the ``Anonymous`` and ``Any`` sender options; they no longer |
| 374 |
exist. You can still receive signals sent by any sender by using |
| 375 |
``sender=None`` |
| 376 |
|
| 377 |
* Make any custom signals you've declared into instances of |
| 378 |
:class:`django.dispatch.Signal` instead of anonymous objects. |
| 379 |
|
| 380 |
Here's quick summary of the code changes you'll need to make: |
| 381 |
|
| 382 |
================================================= ====================================== |
| 383 |
Old (0.96) New (1.0) |
| 384 |
================================================= ====================================== |
| 385 |
``def callback(sender)`` ``def callback(sender, **kwargs)`` |
| 386 |
``sig = object()`` ``sig = django.dispatch.Signal()`` |
| 387 |
``dispatcher.connect(callback, sig)`` ``sig.connect(callback)`` |
| 388 |
``dispatcher.send(sig, sender)`` ``sig.send(sender)`` |
| 389 |
``dispatcher.connect(callback, sig, sender=Any)`` ``sig.connect(callback, sender=None)`` |
| 390 |
================================================= ====================================== |
| 391 |
|
| 392 |
Comments |
| 393 |
-------- |
| 394 |
|
| 395 |
If you were using Django 0.96's ``django.contrib.comments`` app, you'll need to |
| 396 |
upgrade to the new comments app introduced in 1.0. See the upgrade guide |
| 397 |
for details. |
| 398 |
|
| 399 |
Template tags |
| 400 |
------------- |
| 401 |
|
| 402 |
:ttag:`spaceless` tag |
| 403 |
~~~~~~~~~~~~~~~~~~~~~ |
| 404 |
|
| 405 |
The ``spaceless`` template tag now removes *all* spaces between HTML tags, |
| 406 |
instead of preserving a single space. |
| 407 |
|
| 408 |
Local flavors |
| 409 |
------------- |
| 410 |
|
| 411 |
U.S. local flavor |
| 412 |
~~~~~~~~~~~~~~~~~ |
| 413 |
|
| 414 |
``django.contrib.localflavor.usa`` has been renamed to |
| 415 |
``django.contrib.localflavor.us``. This change was made to match the naming |
| 416 |
scheme of other local flavors. To migrate your code, all you need to do is |
| 417 |
change the imports. |
| 418 |
|
| 419 |
Sessions |
| 420 |
-------- |
| 421 |
|
| 422 |
Getting a new session key |
| 423 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 424 |
|
| 425 |
``SessionBase.get_new_session_key()`` has been renamed to |
| 426 |
``_get_new_session_key()``. ``get_new_session_object()`` no longer exists. |
| 427 |
|
| 428 |
Fixtures |
| 429 |
-------- |
| 430 |
|
| 431 |
Loading a row no longer calls ``save()`` |
| 432 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 433 |
|
| 434 |
Previously, loading a row automatically ran the model's ``save()`` method. This |
| 435 |
is no longer the case, so any fields (for example: timestamps) that were |
| 436 |
auto-populated by a ``save()`` now need explicit values in any fixture. |
| 437 |
|
| 438 |
Settings |
| 439 |
-------- |
| 440 |
|
| 441 |
Better exceptions |
| 442 |
~~~~~~~~~~~~~~~~~ |
| 443 |
|
| 444 |
The old :exc:`EnvironmentError` has split into an |
| 445 |
:exc:`ImportError` when Django fails to find the settings module |
| 446 |
and a :exc:`RuntimeError` when you try to reconfigure settings |
| 447 |
after having already used them. |
| 448 |
|
| 449 |
:setting:`LOGIN_URL` has moved |
| 450 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 451 |
|
| 452 |
The :setting:`LOGIN_URL` constant moved from ``django.contrib.auth`` into the |
| 453 |
``settings`` module. Instead of using ``from django.contrib.auth import |
| 454 |
LOGIN_URL`` refer to :setting:`settings.LOGIN_URL <LOGIN_URL>`. |
| 455 |
|
| 456 |
:setting:`APPEND_SLASH` behavior has been updated |
| 457 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 458 |
|
| 459 |
In 0.96, if a URL didn't end in a slash or have a period in the final |
| 460 |
component of its path, and :setting:`APPEND_SLASH` was True, Django would |
| 461 |
redirect to the same URL, but with a slash appended to the end. Now, Django |
| 462 |
checks to see whether the pattern without the trailing slash would be matched |
| 463 |
by something in your URL patterns. If so, no redirection takes place, because |
| 464 |
it is assumed you deliberately wanted to catch that pattern. |
| 465 |
|
| 466 |
For most people, this won't require any changes. Some people, though, have URL |
| 467 |
patterns that look like this:: |
| 468 |
|
| 469 |
r"/some_prefix/(.*)$" |
| 470 |
|
| 471 |
Previously, those patterns would have been redirected to have a trailing |
| 472 |
slash. If you always want a slash on such URLs, rewrite the pattern as:: |
| 473 |
|
| 474 |
r"/some_prefix/(.*/)$" |
| 475 |
|
| 476 |
Smaller model changes |
| 477 |
--------------------- |
| 478 |
|
| 479 |
Different exception from ``get()`` |
| 480 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 481 |
|
| 482 |
Managers now return a :exc:`~django.core.exceptions.MultipleObjectsReturned` |
| 483 |
exception instead of :exc:`AssertionError`: |
| 484 |
|
| 485 |
Old (0.96):: |
| 486 |
|
| 487 |
try: |
| 488 |
Model.objects.get(...) |
| 489 |
except AssertionError: |
| 490 |
handle_the_error() |
| 491 |
|
| 492 |
New (1.0):: |
| 493 |
|
| 494 |
try: |
| 495 |
Model.objects.get(...) |
| 496 |
except Model.MultipleObjectsReturned: |
| 497 |
handle_the_error() |
| 498 |
|
| 499 |
``LazyDate`` has been fired |
| 500 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 501 |
|
| 502 |
The ``LazyDate`` helper class no longer exists. |
| 503 |
|
| 504 |
Default field values and query arguments can both be callable objects, so |
| 505 |
instances of ``LazyDate`` can be replaced with a reference to ``datetime.datetime.now``: |
| 506 |
|
| 507 |
Old (0.96):: |
| 508 |
|
| 509 |
class Article(models.Model): |
| 510 |
title = models.CharField(maxlength=100) |
| 511 |
published = models.DateField(default=LazyDate()) |
| 512 |
|
| 513 |
New (1.0):: |
| 514 |
|
| 515 |
import datetime |
| 516 |
|
| 517 |
|
| 518 |
class Article(models.Model): |
| 519 |
title = models.CharField(max_length=100) |
| 520 |
published = models.DateField(default=datetime.datetime.now) |
| 521 |
|
| 522 |
``DecimalField`` is new, and ``FloatField`` is now a proper float |
| 523 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 524 |
|
| 525 |
Old (0.96):: |
| 526 |
|
| 527 |
class MyModel(models.Model): |
| 528 |
field_name = models.FloatField(max_digits=10, decimal_places=3) |
| 529 |
... |
| 530 |
|
| 531 |
New (1.0):: |
| 532 |
|
| 533 |
class MyModel(models.Model): |
| 534 |
field_name = models.DecimalField(max_digits=10, decimal_places=3) |
| 535 |
... |
| 536 |
|
| 537 |
If you forget to make this change, you will see errors about ``FloatField`` |
| 538 |
not taking a ``max_digits`` attribute in ``__init__``, because the new |
| 539 |
``FloatField`` takes no precision-related arguments. |
| 540 |
|
| 541 |
If you're using MySQL or PostgreSQL, no further changes are needed. The |
| 542 |
database column types for ``DecimalField`` are the same as for the old |
| 543 |
``FloatField``. |
| 544 |
|
| 545 |
If you're using SQLite, you need to force the database to view the |
| 546 |
appropriate columns as decimal types, rather than floats. To do this, you'll |
| 547 |
need to reload your data. Do this after you have made the change to using |
| 548 |
``DecimalField`` in your code and updated the Django code. |
| 549 |
|
| 550 |
.. warning:: |
| 551 |
|
| 552 |
**Back up your database first!** |
| 553 |
|
| 554 |
For SQLite, this means making a copy of the single file that stores the |
| 555 |
database (the name of that file is the ``DATABASE_NAME`` in your |
| 556 |
``settings.py`` file). |
| 557 |
|
| 558 |
To upgrade each application to use a ``DecimalField``, you can do the |
| 559 |
following, replacing ``<app>`` in the code below with each app's name: |
| 560 |
|
| 561 |
.. code-block:: console |
| 562 |
|
| 563 |
$ ./manage.py dumpdata --format=xml <app> > data-dump.xml |
| 564 |
$ ./manage.py reset <app> |
| 565 |
$ ./manage.py loaddata data-dump.xml |
| 566 |
|
| 567 |
Notes: |
| 568 |
|
| 569 |
1. It's important that you remember to use XML format in the first step of |
| 570 |
this process. We are exploiting a feature of the XML data dumps that makes |
| 571 |
porting floats to decimals with SQLite possible. |
| 572 |
|
| 573 |
2. In the second step you will be asked to confirm that you are prepared to |
| 574 |
lose the data for the application(s) in question. Say yes; we'll restore |
| 575 |
this data in the third step. |
| 576 |
|
| 577 |
3. ``DecimalField`` is not used in any of the apps shipped with Django prior |
| 578 |
to this change being made, so you do not need to worry about performing |
| 579 |
this procedure for any of the standard Django models. |
| 580 |
|
| 581 |
If something goes wrong in the above process, just copy your backed up |
| 582 |
database file over the original file and start again. |
| 583 |
|
| 584 |
Internationalization |
| 585 |
-------------------- |
| 586 |
|
| 587 |
:func:`django.views.i18n.set_language` now requires a POST request |
| 588 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 589 |
|
| 590 |
Previously, a GET request was used. The old behavior meant that state (the |
| 591 |
locale used to display the site) could be changed by a GET request, which is |
| 592 |
against the HTTP specification's recommendations. Code calling this view must |
| 593 |
ensure that a POST request is now made, instead of a GET. This means you can |
| 594 |
no longer use a link to access the view, but must use a form submission of |
| 595 |
some kind (e.g. a button). |
| 596 |
|
| 597 |
``_()`` is no longer in builtins |
| 598 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 599 |
|
| 600 |
``_()`` (the callable object whose name is a single underscore) is no longer |
| 601 |
monkeypatched into builtins -- that is, it's no longer available magically in |
| 602 |
every module. |
| 603 |
|
| 604 |
If you were previously relying on ``_()`` always being present, you should now |
| 605 |
explicitly import ``ugettext`` or ``ugettext_lazy``, if appropriate, and alias |
| 606 |
it to ``_`` yourself:: |
| 607 |
|
| 608 |
from django.utils.translation import ugettext as _ |
| 609 |
|
| 610 |
HTTP request/response objects |
| 611 |
----------------------------- |
| 612 |
|
| 613 |
Dictionary access to ``HttpRequest`` |
| 614 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 615 |
|
| 616 |
``HttpRequest`` objects no longer directly support dictionary-style |
| 617 |
access; previously, both ``GET`` and ``POST`` data were directly |
| 618 |
available on the ``HttpRequest`` object (e.g., you could check for a |
| 619 |
piece of form data by using ``if 'some_form_key' in request`` or by |
| 620 |
reading ``request['some_form_key']``. This is no longer supported; if |
| 621 |
you need access to the combined ``GET`` and ``POST`` data, use |
| 622 |
``request.REQUEST`` instead. |
| 623 |
|
| 624 |
It is strongly suggested, however, that you always explicitly look in |
| 625 |
the appropriate dictionary for the type of request you expect to |
| 626 |
receive (``request.GET`` or ``request.POST``); relying on the combined |
| 627 |
``request.REQUEST`` dictionary can mask the origin of incoming data. |
| 628 |
|
| 629 |
Accessing ``HTTPResponse`` headers |
| 630 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 631 |
|
| 632 |
``django.http.HttpResponse.headers`` has been renamed to ``_headers`` and |
| 633 |
:class:`~django.http.HttpResponse` now supports containment checking directly. |
| 634 |
So use ``if header in response:`` instead of ``if header in response.headers:``. |
| 635 |
|
| 636 |
Generic relations |
| 637 |
----------------- |
| 638 |
|
| 639 |
Generic relations have been moved out of core |
| 640 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 641 |
|
| 642 |
The generic relation classes -- ``GenericForeignKey`` and ``GenericRelation`` |
| 643 |
-- have moved into the :mod:`django.contrib.contenttypes` module. |
| 644 |
|
| 645 |
Testing |
| 646 |
------- |
| 647 |
|
| 648 |
:meth:`django.test.Client.login` has changed |
| 649 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 650 |
|
| 651 |
Old (0.96):: |
| 652 |
|
| 653 |
from django.test import Client |
| 654 |
|
| 655 |
c = Client() |
| 656 |
c.login("/path/to/login", "myuser", "mypassword") |
| 657 |
|
| 658 |
New (1.0):: |
| 659 |
|
| 660 |
# ... same as above, but then: |
| 661 |
c.login(username="myuser", password="mypassword") |
| 662 |
|
| 663 |
Management commands |
| 664 |
------------------- |
| 665 |
|
| 666 |
Running management commands from your code |
| 667 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 668 |
|
| 669 |
:mod:`django.core.management` has been greatly refactored. |
| 670 |
|
| 671 |
Calls to management services in your code now need to use |
| 672 |
``call_command``. For example, if you have some test code that calls flush and |
| 673 |
load_data:: |
| 674 |
|
| 675 |
from django.core import management |
| 676 |
|
| 677 |
management.flush(verbosity=0, interactive=False) |
| 678 |
management.load_data(["test_data"], verbosity=0) |
| 679 |
|
| 680 |
...you'll need to change this code to read:: |
| 681 |
|
| 682 |
from django.core import management |
| 683 |
|
| 684 |
management.call_command("flush", verbosity=0, interactive=False) |
| 685 |
management.call_command("loaddata", "test_data", verbosity=0) |
| 686 |
|
| 687 |
Subcommands must now precede options |
| 688 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 689 |
|
| 690 |
``django-admin.py`` and ``manage.py`` now require subcommands to precede |
| 691 |
options. So: |
| 692 |
|
| 693 |
.. code-block:: console |
| 694 |
|
| 695 |
$ django-admin.py --settings=foo.bar runserver |
| 696 |
|
| 697 |
...no longer works and should be changed to: |
| 698 |
|
| 699 |
.. code-block:: console |
| 700 |
|
| 701 |
$ django-admin.py runserver --settings=foo.bar |
| 702 |
|
| 703 |
Syndication |
| 704 |
----------- |
| 705 |
|
| 706 |
``Feed.__init__`` has changed |
| 707 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 708 |
|
| 709 |
The ``__init__()`` method of the syndication framework's ``Feed`` class now |
| 710 |
takes an ``HttpRequest`` object as its second parameter, instead of the feed's |
| 711 |
URL. This allows the syndication framework to work without requiring the sites |
| 712 |
framework. This only affects code that subclasses ``Feed`` and overrides the |
| 713 |
``__init__()`` method, and code that calls ``Feed.__init__()`` directly. |
| 714 |
|
| 715 |
Data structures |
| 716 |
--------------- |
| 717 |
|
| 718 |
``SortedDictFromList`` is gone |
| 719 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 720 |
|
| 721 |
``django.newforms.forms.SortedDictFromList`` was removed. |
| 722 |
``django.utils.datastructures.SortedDict`` can now be instantiated with |
| 723 |
a sequence of tuples. |
| 724 |
|
| 725 |
To update your code: |
| 726 |
|
| 727 |
1. Use ``django.utils.datastructures.SortedDict`` wherever you were |
| 728 |
using ``django.newforms.forms.SortedDictFromList``. |
| 729 |
|
| 730 |
2. Because ``django.utils.datastructures.SortedDict.copy`` doesn't |
| 731 |
return a deepcopy as ``SortedDictFromList.copy()`` did, you will need |
| 732 |
to update your code if you were relying on a deepcopy. Do this by using |
| 733 |
``copy.deepcopy`` directly. |
| 734 |
|
| 735 |
Database backend functions |
| 736 |
-------------------------- |
| 737 |
|
| 738 |
Database backend functions have been renamed |
| 739 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 740 |
|
| 741 |
Almost *all* of the database backend-level functions have been renamed and/or |
| 742 |
relocated. None of these were documented, but you'll need to change your code |
| 743 |
if you're using any of these functions, all of which are in :mod:`django.db`: |
| 744 |
|
| 745 |
======================================= =================================================== |
| 746 |
Old (0.96) New (1.0) |
| 747 |
======================================= =================================================== |
| 748 |
``backend.get_autoinc_sql`` ``connection.ops.autoinc_sql`` |
| 749 |
``backend.get_date_extract_sql`` ``connection.ops.date_extract_sql`` |
| 750 |
``backend.get_date_trunc_sql`` ``connection.ops.date_trunc_sql`` |
| 751 |
``backend.get_datetime_cast_sql`` ``connection.ops.datetime_cast_sql`` |
| 752 |
``backend.get_deferrable_sql`` ``connection.ops.deferrable_sql`` |
| 753 |
``backend.get_drop_foreignkey_sql`` ``connection.ops.drop_foreignkey_sql`` |
| 754 |
``backend.get_fulltext_search_sql`` ``connection.ops.fulltext_search_sql`` |
| 755 |
``backend.get_last_insert_id`` ``connection.ops.last_insert_id`` |
| 756 |
``backend.get_limit_offset_sql`` ``connection.ops.limit_offset_sql`` |
| 757 |
``backend.get_max_name_length`` ``connection.ops.max_name_length`` |
| 758 |
``backend.get_pk_default_value`` ``connection.ops.pk_default_value`` |
| 759 |
``backend.get_random_function_sql`` ``connection.ops.random_function_sql`` |
| 760 |
``backend.get_sql_flush`` ``connection.ops.sql_flush`` |
| 761 |
``backend.get_sql_sequence_reset`` ``connection.ops.sequence_reset_sql`` |
| 762 |
``backend.get_start_transaction_sql`` ``connection.ops.start_transaction_sql`` |
| 763 |
``backend.get_tablespace_sql`` ``connection.ops.tablespace_sql`` |
| 764 |
``backend.quote_name`` ``connection.ops.quote_name`` |
| 765 |
``backend.get_query_set_class`` ``connection.ops.query_set_class`` |
| 766 |
``backend.get_field_cast_sql`` ``connection.ops.field_cast_sql`` |
| 767 |
``backend.get_drop_sequence`` ``connection.ops.drop_sequence_sql`` |
| 768 |
``backend.OPERATOR_MAPPING`` ``connection.operators`` |
| 769 |
``backend.allows_group_by_ordinal`` ``connection.features.allows_group_by_ordinal`` |
| 770 |
``backend.allows_unique_and_pk`` ``connection.features.allows_unique_and_pk`` |
| 771 |
``backend.autoindexes_primary_keys`` ``connection.features.autoindexes_primary_keys`` |
| 772 |
``backend.needs_datetime_string_cast`` ``connection.features.needs_datetime_string_cast`` |
| 773 |
``backend.needs_upper_for_iops`` ``connection.features.needs_upper_for_iops`` |
| 774 |
``backend.supports_constraints`` ``connection.features.supports_constraints`` |
| 775 |
``backend.supports_tablespaces`` ``connection.features.supports_tablespaces`` |
| 776 |
``backend.uses_case_insensitive_names`` ``connection.features.uses_case_insensitive_names`` |
| 777 |
``backend.uses_custom_queryset`` ``connection.features.uses_custom_queryset`` |
| 778 |
======================================= =================================================== |