escape: Update docs

Replace to_basestring with an alias for to_unicode, since the two are
equivalent on py3.

diff --git a/docs/escape.rst b/docs/escape.rst
index 54f1ca9d2d6ca68e3d382ccbbf9124fb1224a94b..2a03eddb383d6c060124d2a273b6f1b091d841b4 100644 (file)
--- a/docs/escape.rst
+++ b/docs/escape.rst
@@ -17,19 +17,15 @@
 
    Byte/unicode conversions
    ------------------------
-   These functions are used extensively within Tornado itself,
-   but should not be directly needed by most applications.  Note that 
-   much of the complexity of these functions comes from the fact that
-   Tornado supports both Python 2 and Python 3.
 
    .. autofunction:: utf8
    .. autofunction:: to_unicode
    .. function:: native_str
+   .. function:: to_basestring
 
-      Converts a byte or unicode string into type `str`.  Equivalent to
-      `utf8` on Python 2 and `to_unicode` on Python 3.
-
-   .. autofunction:: to_basestring
+      Converts a byte or unicode string into type `str`. These functions
+      were used to help transition from Python 2 to Python 3 but are now
+      deprecated aliases for `to_unicode`.
 
    .. autofunction:: recursive_unicode
 

diff --git a/tornado/escape.py b/tornado/escape.py
index bd73e305bf8f8b0c0c2cea40e5b1244354097979..b0ec33230174ed1ac23bb651cd7bd113d90da89d 100644 (file)
--- a/tornado/escape.py
+++ b/tornado/escape.py
@@ -24,7 +24,7 @@ import json
 import re
 import urllib.parse
 
-from tornado.util import unicode_type, basestring_type
+from tornado.util import unicode_type
 
 import typing
 from typing import Union, Any, Optional, Dict, List, Callable
@@ -76,7 +76,10 @@ def json_encode(value: Any) -> str:
 
 
 def json_decode(value: Union[str, bytes]) -> Any:
-    """Returns Python objects for the given JSON string."""
+    """Returns Python objects for the given JSON string.
+
+    Supports both `str` and `bytes` inputs.
+    """
     return json.loads(to_basestring(value))
 
 
@@ -231,39 +234,7 @@ _unicode = to_unicode
 # When dealing with the standard library across python 2 and 3 it is
 # sometimes useful to have a direct conversion to the native string type
 native_str = to_unicode
-
-_BASESTRING_TYPES = (basestring_type, type(None))
-
-
-@typing.overload
-def to_basestring(value: str) -> str:
-    pass
-
-
-@typing.overload  # noqa: F811
-def to_basestring(value: bytes) -> str:
-    pass
-
-
-@typing.overload  # noqa: F811
-def to_basestring(value: None) -> None:
-    pass
-
-
-def to_basestring(value: Union[None, str, bytes]) -> Optional[str]:  # noqa: F811
-    """Converts a string argument to a subclass of basestring.
-
-    In python2, byte and unicode strings are mostly interchangeable,
-    so functions that deal with a user-supplied argument in combination
-    with ascii string constants can use either and should return the type
-    the user supplied.  In python3, the two types are not interchangeable,
-    so this method is needed to convert byte strings to unicode.
-    """
-    if isinstance(value, _BASESTRING_TYPES):
-        return value
-    if not isinstance(value, bytes):
-        raise TypeError("Expected bytes, unicode, or None; got %r" % type(value))
-    return value.decode("utf-8")
+to_basestring = to_unicode
 
 
 def recursive_unicode(obj: Any) -> Any: