thecodingchicken
diff --git a/‎docs/source/isinstance.rst
Lines changed: 53 additions & 0 deletions b/‎docs/source/isinstance.rst
Lines changed: 53 additions & 0 deletions
diff --git a/‎docs/source/what_else.rst
Lines changed: 1 addition & 0 deletions b/‎docs/source/what_else.rst
Lines changed: 1 addition & 0 deletions
diff --git a/‎future/tests/test_utils.py
Lines changed: 36 additions & 0 deletions b/‎future/tests/test_utils.py
Lines changed: 36 additions & 0 deletions
diff --git a/‎future/utils/__init__.py
Lines changed: 7 additions & 0 deletions b/‎future/utils/__init__.py
Lines changed: 7 additions & 0 deletions
@@ -0,0 +1,53 @@
+Distinguishing bytes from unicode text
+--------------------------------------
+
+After these imports::
+    
+    from __future__ import unicode_literals
+    from future.builtins import *
+
+the following tests pass on Py3 but fail on Py2::
+
+    >>> s = 'my unicode string'
+    >>> assert isinstance(s, str)
+
+    >>> b = b'my byte-string'
+    >>> assert isinstance(b, bytes)
+
+This is a corner case that results on Py2 with :func:`isinstance` because
+(unicode) string literals ``'...'`` and byte-string literals ``b'...'``
+create instances of the superclasses of the backported :class:`str` and
 :class:`bytes` types from :mod:`future.builtins` (i.e. the native Py2
+unicode and 8-bit string types).
+
+If type-checking is necessary to distinguish unicode text from bytes
+portably across Py3 and Py2, utility functions called :func:`is_text` and
+:func:`is_bytes` are available in :mod:`future.utils`. You can use them
+as follows::
+
+    >>> from __future__ import unicode_literals
+    >>> from future.builtins import *
+    >>> from future.utils import is_text, is_bytes
+
+    >>> assert is_text('My (unicode) string')
+    >>> assert is_text(str('My (unicode) string'))
+
+    >>> assert is_bytes(b'My byte-string')
+    >>> assert is_bytes(bytes(b'My byte-string'))
+
+``is_text(s)`` tests whether the object ``s`` is (or inherits from) a
+unicode string. It is equivalent to the following expression::
+
+    isinstance(s, type(u''))
+
+which is ``True`` if ``s`` is a native Py3 string, Py2 unicode object, or
+:class:`future.builtins.str` object on Py2.
+
+Likewise, ``is_bytes(b)`` tests whether ``b`` is (or inherits from) an
+8-bit byte-string. It is equivalent to::
+
+    isinstance(b, type(b''))
+
+which is ``True`` if ``b`` is a native Py3 bytes object, Py2 8-bit str,
+or :class:`future.builtins.bytes` object on Py2.
+
@@ -14,6 +14,7 @@ Essentials
 
 .. include:: bytes_object.rst
 .. include:: str_object.rst
+.. include:: isinstance.rst
 .. include:: open_function.rst
 .. include:: dict_methods.rst
 .. include:: custom_str_methods.rst
 
@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""
+Tests for the various utility functions and classes in ``future.utils``
+"""
+
+from __future__ import absolute_import, unicode_literals, print_function
+from future.builtins import *
+from future import utils
+
+import unittest
+
+TEST_UNICODE_STR = u'ℝεα∂@ßʟ℮ ☂ℯṧт υηḯ¢☺ḓ℮'
+
+
+class TestUtils(unittest.TestCase):
+    def setUp(self):
+        self.s = TEST_UNICODE_STR
+        self.s2 = str(self.s)
+        self.b = b'ABCDEFG'
+        self.b2 = bytes(self.b)
+
+    def test_is_text(self):
+        self.assertTrue(utils.is_text(self.s))
+        self.assertTrue(utils.is_text(self.s2))
+        self.assertFalse(utils.is_text(self.b))
+        self.assertFalse(utils.is_text(self.b2))
+
+    def test_is_bytes(self):
+        self.assertTrue(utils.is_bytes(self.b))
+        self.assertTrue(utils.is_bytes(self.b2))
+        self.assertFalse(utils.is_bytes(self.s))
+        self.assertFalse(utils.is_bytes(self.s2))
+
+
+if __name__ == '__main__':
+    unittest.main()
@@ -376,6 +376,13 @@ def is_new_style(cls):
 # ``from future.builtins import *``.
 native_str = str
 
+def is_text(obj):
+    return isinstance(obj, type(u''))
+
+
+def is_bytes(obj):
+    return isinstance(obj, type(b''))
+
 
 __all__ = ['PY3', 'PY2', 'PYPY', 'python_2_unicode_compatible',
            'with_metaclass', 'bchr', 'bstr', 'bord',