Improve str_is_unicode module and tests

edschofield · edschofield · commit 440d06b2915f · 2013-07-22T15:48:45.000+10:00
diff --git a/future/str_is_unicode.py b/future/str_is_unicode.py
@@ -1,5 +1,7 @@
 """
-This module redefines str on Python 2.x to be the unicode type.
+This module redefines str on Python 2.x to be the unicode type and
+provides a decorator called python_2_unicode_compatible to be applied to
+classes.
 
 It is designed to be used together with the unicode_literals import as
 follows:
@@ -25,20 +27,63 @@
 
 This module is designed to be imported together with unicode_literals on
 Python 2 to bring the meaning of str() back into alignment with
-unprefixed
-string literals.
+unprefixed string literals.
+
+Note that str() would then normally call the __unicode__ method on
+objects in Python 2. Therefore this module also defines a simple
+decorator called python_2_unicode_compatible (borrowed from
+django.utils.encoding) which defines __unicode__ and __str__ methods
+under Python 2. To support Python 2 and 3 with a single code base, simply
+define a __str__ method returning text and apply the
+python_2_unicode_compatible decorator to the class like this:::
+
+    from future import str_is_unicode
+
+    @python_2_unicode_compatible
+    class MyClass(object):
+        def __str__(self):
+            return u'Unicode string: \u5b54\u5b50'
+
+    a = MyClass()
+
+Then this is True on both Python 3 and 2:::
+
+    str(a) == bytes(a).decode('utf-8')
+
+and, on a Unicode-enabled terminal with the right fonts, these both print
+the Chinese name of Confucius:::
+
+    print(a)
+    print(str(a))
 
-Note that str() will then call the __unicode__ method on objects in
-Python 2, whereas print() will call __str__.
 """
 
 from __future__ import unicode_literals
 
+import __builtin__
 import inspect
+import imp
+import logging
 
 from . import six
 
 
+def python_2_unicode_compatible(klass):
+    """
+    A decorator that defines __unicode__ and __str__ methods under Python
+    2. Under Python 3 it does nothing.
+    
+    To support Python 2 and 3 with a single code base, define a __str__
+    method returning text and apply this decorator to the class.
+
+    The implementation comes from django.utils.encoding.
+    """
+    if not six.PY3:
+        klass.__unicode__ = klass.__str__
+        klass.__str__ = lambda self: self.__unicode__().encode('utf-8')
+    return klass
+
+
 if not six.PY3:
     caller = inspect.currentframe().f_back
     caller.f_globals['str'] = unicode
diff --git a/future/tests/test_str_is_unicode.py b/future/tests/test_str_is_unicode.py
@@ -1,12 +1,42 @@
-from __future__ import absolute_import
+# -*- coding: utf-8 -*-
+"""
+Tests for the future.str_is_unicode module
+"""
 
+from __future__ import absolute_import, unicode_literals, print_function
 from future import str_is_unicode
 
+from future import six
+
 import unittest
 
-class TestIterators(unittest.TestCase):
+
+class TestStrIsUnicode(unittest.TestCase):
     def test_str(self):
         self.assertIsNot(str, bytes)            # Py2: assertIsNot only in 2.7
         self.assertEqual(str('blah'), u'blah')  # Py3.3 and Py2 only
 
+    def test_python_2_unicode_compatible_decorator(self):
+        # With the decorator:
+        @str_is_unicode.python_2_unicode_compatible
+        class A(object):
+            def __str__(self):
+                return u'Unicode string: \u5b54\u5b50'
+        a = A()
+        self.assertEqual(str(a), bytes(a).decode('utf-8'))
+        assert len(str(a)) == 18
+        if not six.PY3:
+            assert hasattr(a, '__unicode__')
+        print(str(a))
+
+        # Manual equivalent without the decorator:
+        class B(object):
+            def __unicode__(self):
+                return u'Unicode string: \u5b54\u5b50'
+            def __str__(self):
+                return unicode(self).encode('utf-8')
+        b = B()
+        assert str(a) == str(b)
+
+
 unittest.main()
