I have just been trying to figure out how string interpolation works for "%s", when Unicode strings are involved. It seems it's a bit complicated, but the Python documentation doesn't really describe it. It just says %s "converts any Python object using str()".

Here is what I have found (I think), and it could be worth improving the documentation of this somehow.

Example 1:
    "%s" % test_object

From what I can tell, in this case:
1. test_object.__str__() is called.
2. If test_object.__str__() returns a string object, then that is substituted.
3. If test_object.__str__() returns a Unicode object (for some reason), then test_object.__unicode__() is called, then _that_ is substituted instead. The output string is turned into Unicode. This behaviour is surprising.

[Note that the call to test_object.__str__() is not the same as str(test_object), because the former can return a Unicode object without causing an error, while the latter, if it gets a Unicode object, will then try to encode('ascii') to a string, possibly generating a UnicodeEncodeError exception.]


Example 2:
    u"%s" % test_object

In this case:
1. test_object.__unicode__() is called, if it exists, and the result is substituted. The output string is Unicode.
2. If test_object.__unicode__() doesn't exist, then test_object.__str__() is called instead, converted to Unicode, and substituted. The output string is Unicode.


Example 3:
    "%s %s" % (u'unicode', test_object)

In this case:
1. The first substitution causes the output string to be Unicode.
2. It seems that (1) causes the second substitution to follow the same rules as Example 2. This is a little surprising.