Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Made a bunch of edits and typo corrections to 1.0-porting-guide.txt

git-svn-id: http://code.djangoproject.com/svn/django/trunk@8966 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 6008485b807d2ca2d15a11f9ebd4175a1fdf4199 1 parent 1b39622
Adrian Holovaty authored September 05, 2008

Showing 1 changed file with 76 additions and 63 deletions. Show diff stats Hide diff stats

  1. 139  docs/releases/1.0-porting-guide.txt
139  docs/releases/1.0-porting-guide.txt
@@ -4,7 +4,7 @@ Porting your apps from Django 0.96 to 1.0
4 4
 
5 5
 .. highlight:: python
6 6
 
7  
-Django 1.0 breaks compatibility with 0.96 in some areas. 
  7
+Django 1.0 breaks compatibility with 0.96 in some areas.
8 8
 
9 9
 This guide will help you port 0.96 projects and apps to 1.0. The first part of
10 10
 this document includes the common changes needed to run with 1.0. If after going
@@ -97,7 +97,7 @@ New (1.0) ``admin.py``::
97 97
 
98 98
     from django.contrib import admin
99 99
     from models import Author
100  
-    
  100
+
101 101
     class AuthorAdmin(admin.ModelAdmin):
102 102
         list_display = ['first_name', 'last_name']
103 103
         prepopulated_fields = {
@@ -139,7 +139,7 @@ Old (0.96)::
139 139
 
140 140
     class Parent(models.Model):
141 141
         ...
142  
-        
  142
+
143 143
     class Child(models.Model):
144 144
         parent = models.ForeignKey(Parent, edit_inline=models.STACKED, num_in_admin=3)
145 145
 
@@ -149,13 +149,13 @@ New (1.0)::
149 149
     class ChildInline(admin.StackedInline):
150 150
         model = Child
151 151
         extra = 3
152  
-        
  152
+
153 153
     class ParentAdmin(models.ModelAdmin):
154 154
         model = Parent
155 155
         inlines = [ChildInline]
156  
-        
  156
+
157 157
     admin.site.register(Parent, ParentAdmin)
158  
-    
  158
+
159 159
 See :ref:`admin-inlines` for more details.
160 160
 
161 161
 Simplify ``fields``, or use ``fieldsets``
@@ -164,37 +164,37 @@ Simplify ``fields``, or use ``fieldsets``
164 164
 The old ``fields`` syntax was quite confusing, and has been simplified. The old
165 165
 syntax still works, but you'll need to use ``fieldsets`` instead.
166 166
 
167  
-Old (0.96)::    
  167
+Old (0.96)::
168 168
 
169 169
     class ModelOne(models.Model):
170 170
         ...
171  
-        
  171
+
172 172
         class Admin:
173 173
             fields = (
174 174
                 (None, {'fields': ('foo','bar')}),
175 175
             )
176  
-    
  176
+
177 177
     class ModelTwo(models.Model):
178 178
         ...
179  
-        
  179
+
180 180
         class Admin:
181 181
             fields = (
182 182
                 ('group1', {'fields': ('foo','bar'),   'classes': 'collapse'}),
183 183
                 ('group2', {'fields': ('spam','eggs'), 'classes': 'collapse wide'}),
184 184
             )
185  
-            
  185
+
186 186
 
187 187
 New (1.0)::
188 188
 
189 189
     class ModelOneAdmin(admin.ModelAdmin):
190 190
         fields = ('foo', 'bar')
191  
-        
  191
+
192 192
     class ModelTwoAdmin(admin.ModelAdmin):
193 193
         fieldsets = (
194 194
             ('group1', {'fields': ('foo','bar'),   'classes': 'collapse'}),
195 195
             ('group2', {'fields': ('spam','eggs'), 'classes': 'collapse wide'}),
196 196
         )
197  
-        
  197
+
198 198
 
199 199
 .. seealso::
200 200
 
@@ -212,7 +212,7 @@ URLs
212 212
 Update your root ``urls.py``
213 213
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
214 214
 
215  
-If you are using the admin site you need to update your root ``urls.py``.
  215
+If you're using the admin site, you need to update your root ``urls.py``.
216 216
 
217 217
 Old (0.96) ``urls.py``::
218 218
 
@@ -246,14 +246,23 @@ Use ``django.forms`` instead of ``newforms``
246 246
 
247 247
 Replace ``django.newforms`` with ``django.forms`` -- Django 1.0 renamed the
248 248
 ``newforms`` module (introduced in 0.96) to plain old ``forms``. The
249  
-``oldforms`` module was also removed removed.
  249
+``oldforms`` module was also removed.
250 250
 
251  
-If you are already using new forms all you have to do is change your import
252  
-statement. Instead of ``from django import newforms as forms``, use ``from
253  
-django import forms``.
  251
+If you're already using the ``newforms`` library, and you used our recommended
  252
+``import`` statement syntax, all you have to do is change your import
  253
+statements.
254 254
 
255  
-If you are using the old forms system, you will have to rewrite your forms. A
256  
-good place to start is the :ref:`forms documentation <topics-forms-index>`
  255
+Old::
  256
+
  257
+    from django import newforms as forms
  258
+
  259
+New::
  260
+
  261
+    from django import forms
  262
+
  263
+If you're using the old forms system (formerly known as ``django.forms`` and
  264
+``django.oldforms``), you'll have to rewrite your forms. A good place to start
  265
+is the :ref:`forms documentation <topics-forms-index>`
257 266
 
258 267
 Handle uploaded files using the new API
259 268
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -268,7 +277,7 @@ Thus, in a view like::
268 277
           f = request.FILES['file_field_name']
269 278
           ...
270 279
 
271  
-You'd need to make the following changes:
  280
+...you'd need to make the following changes:
272 281
 
273 282
 ===================== =====================
274 283
 Old (0.96)            New (1.0)
@@ -284,7 +293,7 @@ Templates
284 293
 Learn to love autoescaping
285 294
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
286 295
 
287  
-By default, the templating system now automatically HTML-escapes the output of
  296
+By default, the template system now automatically HTML-escapes the output of
288 297
 every variable. To learn more, see :ref:`automatic-html-escaping`.
289 298
 
290 299
 To disable auto-escaping for an individual variable, use the :tfilter:`safe`
@@ -352,18 +361,19 @@ Template tags
352 361
 :ttag:`spaceless` tag
353 362
 ~~~~~~~~~~~~~~~~~~~~~
354 363
 
355  
-The spaceless template tag removes *all* spaces between HTML tags instead of
356  
-preserving a single space.
  364
+The spaceless template tag now removes *all* spaces between HTML tags, instead
  365
+of preserving a single space.
357 366
 
358  
-Localflavor
359  
------------
  367
+Local flavors
  368
+-------------
360 369
 
361  
-US localflavor
362  
-~~~~~~~~~~~~~~
  370
+U.S. local flavor
  371
+~~~~~~~~~~~~~~~~~
363 372
 
364  
-``django.contrib.localflavor.usa`` has been renamed
365  
-:mod:`django.contribg.localflavor.us`. This change was made to match the naming
366  
-scheme of other local flavors.
  373
+``django.contrib.localflavor.usa`` has been renamed to
  374
+:mod:`django.contrib.localflavor.us`. This change was made to match the naming
  375
+scheme of other local flavors. To migrate your code, all you need to do is
  376
+change the imports.
367 377
 
368 378
 Sessions
369 379
 --------
@@ -372,7 +382,7 @@ Getting a new session key
372 382
 ~~~~~~~~~~~~~~~~~~~~~~~~~
373 383
 
374 384
 ``SeesionBase.get_new_session_key()`` has been renamed to
375  
-``_get_new_session_key()``; ``get_new_session_object()`` no longer exists.
  385
+``_get_new_session_key()``. ``get_new_session_object()`` no longer exists.
376 386
 
377 387
 Fixtures
378 388
 --------
@@ -390,7 +400,7 @@ Settings
390 400
 Better exceptions
391 401
 ~~~~~~~~~~~~~~~~~
392 402
 
393  
-The old :exc:`EnvironmentError` was split into an :exc:`ImportError` raised when
  403
+The old :exc:`EnvironmentError` has split into an :exc:`ImportError` when
394 404
 Django fails to find the settings module and a :exc:`RuntimeError` when you try
395 405
 to reconfigure settings after having already used them
396 406
 
@@ -401,15 +411,15 @@ The ``LOGIN_URL`` constant moved from ``django.contrib.auth`` into the
401 411
 ``settings`` module. Instead of using ``from django.contrib.auth import
402 412
 LOGIN_URL`` refer to :setting:`settings.LOGIN_URL <LOGIN_URL>`.
403 413
 
404  
-:setting:`APPEND_SLASH` behaviour has been updated
405  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  414
+:setting:`APPEND_SLASH` behavior has been updated
  415
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
406 416
 
407 417
 In 0.96, if a URL didn't end in a slash or have a period in the final
408  
-component of it's path, and ``APPEND_SLASH`` was True, Django would redirect
  418
+component of its path, and ``APPEND_SLASH`` was True, Django would redirect
409 419
 to the same URL, but with a slash appended to the end. Now, Django checks to
410  
-see if the pattern without the trailing slash would be matched by something in
411  
-your URL patterns. If so, no redirection takes place, because it is assumed
412  
-you deliberately wanted to catch that pattern.
  420
+see whether the pattern without the trailing slash would be matched by
  421
+something in your URL patterns. If so, no redirection takes place, because it
  422
+is assumed you deliberately wanted to catch that pattern.
413 423
 
414 424
 For most people, this won't require any changes. Some people, though, have URL
415 425
 patterns that look like this::
@@ -421,13 +431,13 @@ slash. If you always want a slash on such URLs, rewrite the pattern as::
421 431
 
422 432
     r'/some_prefix/(.*/)$'
423 433
 
424  
-Samller model changes
  434
+Smaller model changes
425 435
 ---------------------
426 436
 
427 437
 Different exception from ``get()``
428 438
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
429 439
 
430  
-The models manager now returns a :exc:`MultipleObjectsReturned` exception
  440
+Managers now return a :exc:`MultipleObjectsReturned` exception
431 441
 instead of :exc:`AssertionError`:
432 442
 
433 443
 Old (0.96)::
@@ -443,7 +453,7 @@ New (1.0)::
443 453
       Model.objects.get(...)
444 454
   except Model.MultipleObjectsReturned:
445 455
       handle_the_error()
446  
-      
  456
+
447 457
 ``LazyDate`` has been fired
448 458
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
449 459
 
@@ -482,28 +492,28 @@ New (1.0)::
482 492
         ...
483 493
 
484 494
 If you forget to make this change, you will see errors about ``FloatField``
485  
-not taking a ``max_digits`` attribute in ``__init__``, since the new
  495
+not taking a ``max_digits`` attribute in ``__init__``, because the new
486 496
 ``FloatField`` takes no precision-related arguments.
487 497
 
488  
-If you are using MySQL or PostgreSQL, there are no further changes needed. The
  498
+If you're using MySQL or PostgreSQL, no further changes are needed. The
489 499
 database column types for ``DecimalField`` are the same as for the old
490 500
 ``FloatField``.
491 501
 
492  
-If you are using SQLite, you need to force the database to view the
  502
+If you're using SQLite, you need to force the database to view the
493 503
 appropriate columns as decimal types, rather than floats. To do this, you'll
494 504
 need to reload your data. Do this after you have made the change to using
495 505
 ``DecimalField`` in your code and updated the Django code.
496 506
 
497 507
 .. warning::
498 508
 
499  
-  **Back up your database first!** 
500  
-  
  509
+  **Back up your database first!**
  510
+
501 511
   For SQLite, this means making a copy of the single file that stores the
502 512
   database (the name of that file is the ``DATABASE_NAME`` in your settings.py
503 513
   file).
504 514
 
505  
-To upgrade each application to use a ``DecimalField``, do the following,
506  
-replacing ``<app>`` in the code below with each app's name:
  515
+To upgrade each application to use a ``DecimalField``, you can do the
  516
+following, replacing ``<app>`` in the code below with each app's name:
507 517
 
508 518
 .. code-block:: bash
509 519
 
@@ -513,15 +523,15 @@ replacing ``<app>`` in the code below with each app's name:
513 523
 
514 524
 Notes:
515 525
 
516  
-  1. It is important that you remember to use XML format in the first step of
  526
+  1. It's important that you remember to use XML format in the first step of
517 527
      this process. We are exploiting a feature of the XML data dumps that makes
518 528
      porting floats to decimals with SQLite possible.
519  
-  
  529
+
520 530
   2. In the second step you will be asked to confirm that you are prepared to
521 531
      lose the data for the application(s) in question. Say yes; we'll restore
522 532
      this data in the third step, of course.
523  
-  
524  
-  3. ``DecimalField`` is not used in any of the apps shipped with Django prior 
  533
+
  534
+  3. ``DecimalField`` is not used in any of the apps shipped with Django prior
525 535
      to this change being made, so you do not need to worry about performing
526 536
      this procedure for any of the standard Django models.
527 537
 
@@ -544,10 +554,13 @@ some kind (e.g. a button).
544 554
 ``_()`` is no longer in builtins
545 555
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
546 556
 
547  
-``_()`` is no longer monkeypatched into builtins. If you were previously
548  
-relying on ``_()`` always being present, you should now explicitly import
549  
-``ugettext`` or ``ugettext_lazy``, if appropriate, and alias it to ``_``
550  
-yourself::
  557
+``_()`` (the callable object whose name is a single underscore) is no longer
  558
+monkeypatched into builtins -- that is, it's no longer available magically in
  559
+every module.
  560
+
  561
+If you were previously relying on ``_()`` always being present, you should now
  562
+explicitly import ``ugettext`` or ``ugettext_lazy``, if appropriate, and alias
  563
+it to ``_`` yourself::
551 564
 
552 565
     from django.utils.translation import ugettext as _
553 566
 
@@ -593,9 +606,9 @@ Management commands
593 606
 Running management commands from your code
594 607
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
595 608
 
596  
-:mod:`django.core.management`` has been greately refactored.
  609
+:mod:`django.core.management`` has been greatly refactored.
597 610
 
598  
-Calls to management services in your code will now need to use
  611
+Calls to management services in your code now need to use
599 612
 ``call_command``. For example, if you have some test code that calls flush and
600 613
 load_data::
601 614
 
@@ -603,7 +616,7 @@ load_data::
603 616
       management.flush(verbosity=0, interactive=False)
604 617
       management.load_data(['test_data'], verbosity=0)
605 618
 
606  
-You will need to change this code to read::
  619
+...you'll need to change this code to read::
607 620
 
608 621
       from django.core import management
609 622
       management.call_command('flush', verbosity=0, interactive=False)
@@ -619,7 +632,7 @@ options. So:
619 632
 
620 633
       $ django-admin.py --settings=foo.bar runserver
621 634
 
622  
-no longer works, and must be changed to:
  635
+...no longer works and should be changed to:
623 636
 
624 637
 .. code-block:: bash
625 638
 
@@ -631,7 +644,7 @@ Syndication
631 644
 ``Feed.__init__`` has changed
632 645
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
633 646
 
634  
-The ``__init__()`` parameters in in syndication framework's ``Feed`` class now
  647
+The ``__init__()`` parameters in the syndication framework's ``Feed`` class now
635 648
 take an ``HttpRequest`` object as its second parameter, instead of the feed's
636 649
 URL. This allows the syndication framework to work without requiring the sites
637 650
 framework. This only affects code that subclass ``Feed`` and overrides the
@@ -652,7 +665,7 @@ To update your code:
652 665
      1. Use :class:`django.utils.datastructures.SortedDict` wherever you were
653 666
         using ``django.newforms.forms.SortedDictFromList``.
654 667
 
655  
-     2. Since :meth:`django.utils.datastructures.SortedDict.copy` return a
  668
+     2. Because :meth:`django.utils.datastructures.SortedDict.copy` returns a
656 669
         deepcopy as ``SortedDictFromList`` method did, you will need to update
657 670
         your code if you were relying on a deepcopy. Do this by using
658 671
         ``copy.deepcopy`` directly.

0 notes on commit 6008485

Please sign in to comment.
Something went wrong with that request. Please try again.