Project: Django

Revision: 8966

Author: adrian

Date: 04 Sep 2008 20:48:34

Diff at Trac: http://code.djangoproject.com/changeset/8966

• /django/trunk/docs/releases/1.0-porting-guide.txt

  ......	@@ -4,7 +4,7 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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 @@
  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.