Porting Applications (The Quick Checklist) ¶
One of the design goals of the Unicode branch is that very little significant changes to existing third-party code should be required. However, there are some things that developers should be aware of when writing applications designed to handle international input.
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 (also online). 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. Change your string literals that include Python format characters to be unicode strings. For example, change this:
formal_name = '%s %s %s' % (title, firstname, surname) # old version
to this:
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 automatically 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 version 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 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. 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. 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!