Changes between Version 24 and Version 25 of UnicodeBranch

Timestamp:

May 24, 2007, 9:19:25 PM (18 years ago)

Author:

Malcolm Tredinnick

Comment:

The 5-step porting guide now comes with 20% extra free stuff (yeah, I'm dumb... I forgot a step)

UnicodeBranch

@@ -60 +60 @@
 A detailed list of things you might wish to think about when writing your code is in the {{{unicode.txt}}} file in the documentation directory. For the programmer on a deadline, here is the cheatsheet version (if you only use ASCII strings, none of these changes are necessary):
 
+('''Note (25 May 2007):''' Early adopters will have seen five steps in this list. The all-important step number 3 was initially omitted.)
+
  1. Change the {{{__str__}}} methods on your models to be {{{__unicode__}}} methods. Just change the name. Usually, nothing else will be needed.
 
  2. Look for any {{{str()}}} calls in your code that operate on model fields. These should almost always be changed to {{{smart_unicode()}}} calls (which is imported from {{{django.utils.encoding}}}). In some cases, you may need to use {{{force_unicode()}}} (in the same module), but starting with a global change to {{{smart_unicode()}}} and then checking for problems is the "quick fix" way. (Details of the differences between the two functions are in {{{unicode.txt}}}.)
 
- 3. Use the unicode versions of the {{{django.utils.translation.*}}} functions. Replace {{{gettext}}} and {{{ngettext}}} with {{{ugettext}}} and {{{ungettext}}} respectively. There are also {{{ugettext_lazy}}} and {{{ungettext_lazy}}} functions if you use the lazy versions.
+ 3. Change your string literals that include Python format characters to be unicode strings. For example, change this:
+{{{
+#!python
+formal_name = '%s %s %s' % (title, firstname, surname)     # old version
+}}}
+ to this:
+{{{
+#!python
+formal_name = u'%s %s %s' % (title, firstname, surname)    # new version
+}}}
+ This is useful for two reasons. Firstly, if the parameters contain non-ASCII characters, you won't have an exception raised. Secondly, if any of the parameters are objects, Python will automaticay call their {{{__unicode__}}} method and convert them to the right type. The "before" code would have resulted in the {{{__str__}}} method being called instead.
+ Of course, this step is only a good idea if you are interpolating unicode strings. If your parameters are bytestrings, they will not automatically be decoded to unicode strings before being interpolated (Python cannot read your mind). Use {{{smart_unicode()}}} for that purpose.
+    * '''Warning for Python 2.3:''' There is a bug in the way Python 2.3 does string interpolation for unicode strings that you should be aware of if your code has to work with that verison of Python. In the second line of code, above, if any of the parameters are non-basestring objects, Python will call the {{{__str__}}} method on the object, not the {{{__unicode__}}} method! So, for Python 2.3-compatible code, you would need to write something like
+{{{
+#!python
+some_string = u'This is your object: %s' % unicode(some_object)
+}}}
+    Note the explicit call to {{{unicode()}}} here to force the object to be the right type.
 
- 4. Make sure your database can store all the data you will send to it. Usually, this means ensuring it is using UTF-8 (or similar) encoding internally.
+ 4. Use the unicode versions of the {{{django.utils.translation.*}}} functions. Replace {{{gettext}}} and {{{ngettext}}} with {{{ugettext}}} and {{{ungettext}}} respectively. There are also {{{ugettext_lazy}}} and {{{ungettext_lazy}}} functions if you use the lazy versions.
 
- 5. Use the {{{FILE_CHARSET}}} setting if your on-disk template files and initial SQL files are not UTF-8 encoded.
+ 5. Make sure your database can store all the data you will send to it. Usually, this means ensuring it is using UTF-8 (or similar) encoding internally.
+
+ 6. Use the {{{FILE_CHARSET}}} setting if your on-disk template files and initial SQL files are not UTF-8 encoded.
 
 That is all. Enjoy!