Merge pull request #2379 from gabrieldemarmiesse/test_string_5

Adding tests for "Unicode and passing strings" part 5

docs/examples/tutorial/string/api_func.pyx

+from to_unicode cimport _ustring
+
+def api_func(s):
+    text = _ustring(s)
+    # ...

docs/examples/tutorial/string/to_unicode.pxd

+cdef unicode _ustring(s)

docs/examples/tutorial/string/to_unicode.pyx

+# to_unicode.pyx
+
+from cpython.version cimport PY_MAJOR_VERSION
+
+cdef unicode _ustring(s):
+    if type(s) is unicode:
+        # fast path for most common case(s)
+        return <unicode>s
+
+    elif PY_MAJOR_VERSION < 3 and isinstance(s, bytes):
+        # only accept byte strings in Python 2.x, not in Py3
+        return (<bytes>s).decode('ascii')
+
+    elif isinstance(s, unicode):
+        # an evil cast to <unicode> might work here in some(!) cases,
+        # depending on what the further processing does.  to be safe,
+        # we can always create a copy instead
+        return unicode(s)
+
+    else:
+        raise TypeError("Could not convert to unicode.")

docs/src/tutorial/strings.rst

@@ -236,30 +236,13 @@ way to go, since it allows for easy adaptation of the input normalisation
 process later.
 
 This kind of input normalisation function will commonly look similar to
-the following::
-
-    from cpython.version cimport PY_MAJOR_VERSION
-
-    cdef unicode _ustring(s):
-        if type(s) is unicode:
-            # fast path for most common case(s)
-            return <unicode>s
-        elif PY_MAJOR_VERSION < 3 and isinstance(s, bytes):
-            # only accept byte strings in Python 2.x, not in Py3
-            return (<bytes>s).decode('ascii')
-        elif isinstance(s, unicode):
-            # an evil cast to <unicode> might work here in some(!) cases,
-            # depending on what the further processing does.  to be safe,
-            # we can always create a copy instead
-            return unicode(s)
-        else:
-            raise TypeError(...)
+the following:
 
-And should then be used like this::
+.. literalinclude:: ../../examples/tutorial/string/to_unicode.pyx
 
-    def api_func(s):
-        text = _ustring(s)
-        ...
+And should then be used like this:
+
+.. literalinclude:: ../../examples/tutorial/string/api_func.pyx
 
 Similarly, if the further processing happens at the byte level, but Unicode
 string input should be accepted, then the following might work, if you are