2626import re
2727import sys
2828
29- from tornado .util import PY3 , unicode_type , basestring_type
29+ from tornado .util import PY3 , unicode_type , basestring_type , StringTypes
3030
3131if PY3 :
3232 from urllib .parse import parse_qs as _parse_qs
3838 import htmlentitydefs
3939 import urllib as urllib_parse
4040
41+ try :
42+ import typing
43+ from typing import cast
44+ except ImportError :
45+ typing = None
46+
47+ def cast (typ , x ):
48+ return x
49+
4150
4251_XHTML_ESCAPE_RE = re .compile ('[&<>"\' ]' )
4352_XHTML_ESCAPE_DICT = {'&' : '&' , '<' : '<' , '>' : '>' , '"' : '"' ,
4453 '\' ' : ''' }
4554
4655
4756def xhtml_escape (value ):
57+ # type: (typing.Union[unicode_type, bytes]) -> str
4858 """Escapes a string so it is valid within HTML or XML.
4959
5060 Escapes the characters ``<``, ``>``, ``"``, ``'``, and ``&``.
@@ -60,14 +70,16 @@ def xhtml_escape(value):
6070
6171
6272def xhtml_unescape (value ):
73+ # type: (typing.Union[unicode_type, bytes]) -> str
6374 """Un-escapes an XML-escaped string."""
64- return re .sub (r "&(#?)(\w+?);" , _convert_entity , _unicode (value ))
75+ return re .sub (ur "&(#?)(\w+?);" , _convert_entity , to_unicode (value ))
6576
6677
6778# The fact that json_encode wraps json.dumps is an implementation detail.
6879# Please see https://github.com/tornadoweb/tornado/pull/706
6980# before sending a pull request that adds **kwargs to this function.
7081def json_encode (value ):
82+ # type: (typing.Any) -> str
7183 """JSON-encodes the given Python object."""
7284 # JSON permits but does not require forward slashes to be escaped.
7385 # This is useful when json data is emitted in a <script> tag
@@ -79,16 +91,19 @@ def json_encode(value):
7991
8092
8193def json_decode (value ):
94+ # type: (typing.Union[str, bytes]) -> typing.Any
8295 """Returns Python objects for the given JSON string."""
8396 return json .loads (to_basestring (value ))
8497
8598
8699def squeeze (value ):
100+ # type: (str) -> str
87101 """Replace all sequences of whitespace chars with a single space."""
88102 return re .sub (r"[\x00-\x20]+" , " " , value ).strip ()
89103
90104
91105def url_escape (value , plus = True ):
106+ # type: (typing.Union[unicode_type, bytes], bool) -> str
92107 """Returns a URL-encoded version of the given value.
93108
94109 If ``plus`` is true (the default), spaces will be represented
@@ -100,14 +115,15 @@ def url_escape(value, plus=True):
100115 The ``plus`` argument
101116 """
102117 quote = urllib_parse .quote_plus if plus else urllib_parse .quote
103- return quote (utf8 (value ))
118+ return quote (utf8 (value )) # type: ignore
104119
105120
106121# python 3 changed things around enough that we need two separate
107122# implementations of url_unescape. We also need our own implementation
108123# of parse_qs since python 3's version insists on decoding everything.
109124if not PY3 :
110125 def url_unescape (value , encoding = 'utf-8' , plus = True ):
126+ # type: (typing.Union[unicode_type, bytes], str, bool) -> typing.Union[unicode_type, bytes]
111127 """Decodes the given value from a URL.
112128
113129 The argument may be either a byte or unicode string.
@@ -133,6 +149,7 @@ def url_unescape(value, encoding='utf-8', plus=True):
133149 parse_qs_bytes = _parse_qs
134150else :
135151 def url_unescape (value , encoding = 'utf-8' , plus = True ):
152+ # type: (str, str, bool) -> typing.Union[unicode_type, bytes]
136153 """Decodes the given value from a URL.
137154
138155 The argument may be either a byte or unicode string.
@@ -160,6 +177,7 @@ def url_unescape(value, encoding='utf-8', plus=True):
160177 return unquote (to_basestring (value ), encoding = encoding )
161178
162179 def parse_qs_bytes (qs , keep_blank_values = False , strict_parsing = False ):
180+ # type: (str, bool, bool) -> typing.Dict[str, typing.List[bytes]]
163181 """Parses a query string like urlparse.parse_qs, but returns the
164182 values as byte strings.
165183
@@ -181,13 +199,14 @@ def parse_qs_bytes(qs, keep_blank_values=False, strict_parsing=False):
181199
182200
183201def utf8 (value ):
202+ # type: (typing.Union[unicode_type, bytes, None]) -> typing.Optional[bytes]
184203 """Converts a string argument to a byte string.
185204
186205 If the argument is already a byte string or None, it is returned unchanged.
187206 Otherwise it must be a unicode string and is encoded as utf8.
188207 """
189208 if isinstance (value , _UTF8_TYPES ):
190- return value
209+ return cast ( bytes , value )
191210 if not isinstance (value , unicode_type ):
192211 raise TypeError (
193212 "Expected bytes, unicode, or None; got %r" % type (value )
@@ -198,13 +217,14 @@ def utf8(value):
198217
199218
200219def to_unicode (value ):
220+ # type: (typing.Union[unicode_type, bytes, None]) -> typing.Optional[unicode_type]
201221 """Converts a string argument to a unicode string.
202222
203223 If the argument is already a unicode string or None, it is returned
204224 unchanged. Otherwise it must be a byte string and is decoded as utf8.
205225 """
206226 if isinstance (value , _TO_UNICODE_TYPES ):
207- return value
227+ return cast ( unicode_type , value )
208228 if not isinstance (value , bytes ):
209229 raise TypeError (
210230 "Expected bytes, unicode, or None; got %r" % type (value )
@@ -217,7 +237,7 @@ def to_unicode(value):
217237
218238# When dealing with the standard library across python 2 and 3 it is
219239# sometimes useful to have a direct conversion to the native string type
220- if str is unicode_type :
240+ if PY3 :
221241 native_str = to_unicode
222242else :
223243 native_str = utf8
@@ -226,6 +246,7 @@ def to_unicode(value):
226246
227247
228248def to_basestring (value ):
249+ # type: (typing.Union[unicode_type, bytes, None]) -> typing.Optional[StringTypes]
229250 """Converts a string argument to a subclass of basestring.
230251
231252 In python2, byte and unicode strings are mostly interchangeable,
@@ -235,7 +256,7 @@ def to_basestring(value):
235256 so this method is needed to convert byte strings to unicode.
236257 """
237258 if isinstance (value , _BASESTRING_TYPES ):
238- return value
259+ return cast ( StringTypes , value )
239260 if not isinstance (value , bytes ):
240261 raise TypeError (
241262 "Expected bytes, unicode, or None; got %r" % type (value )
@@ -244,6 +265,7 @@ def to_basestring(value):
244265
245266
246267def recursive_unicode (obj ):
268+ # type: (typing.Any) -> typing.Any
247269 """Walks a simple data structure, converting byte strings to unicode.
248270
249271 Supports lists, tuples, and dictionaries.
@@ -271,6 +293,7 @@ def recursive_unicode(obj):
271293
272294def linkify (text , shorten = False , extra_params = "" ,
273295 require_protocol = False , permitted_protocols = ["http" , "https" ]):
296+ # type: (typing.Union[unicode_type, bytes], bool, typing.Union[typing.Callable[[unicode_type], unicode_type], str], bool, typing.List[str]) -> unicode_type
274297 """Converts plain text into HTML with links.
275298
276299 For example: ``linkify("Hello http://tornadoweb.org!")`` would return
@@ -304,6 +327,7 @@ def extra_params_cb(url):
304327 extra_params = " " + extra_params .strip ()
305328
306329 def make_link (m ):
330+ # type: (typing.Match[unicode_type]) -> unicode_type
307331 url = m .group (1 )
308332 proto = m .group (2 )
309333 if require_protocol and not proto :
@@ -366,6 +390,7 @@ def make_link(m):
366390
367391
368392def _convert_entity (m ):
393+ # type: (typing.Match[unicode_type]) -> unicode_type
369394 if m .group (1 ) == "#" :
370395 try :
371396 if m .group (2 )[:1 ].lower () == 'x' :
@@ -381,9 +406,10 @@ def _convert_entity(m):
381406
382407
383408def _build_unicode_map ():
409+ # type: () -> typing.Dict[unicode_type, unicode_type]
384410 unicode_map = {}
385411 for name , value in htmlentitydefs .name2codepoint .items ():
386- unicode_map [name ] = unichr (value )
412+ unicode_map [to_unicode ( name ) ] = unichr (value )
387413 return unicode_map
388414
389- _HTML_UNICODE_MAP = _build_unicode_map ()
415+ _HTML_UNICODE_MAP = _build_unicode_map () # type: typing.Dict[unicode_type, unicode_type]
0 commit comments