Skip to content

Commit dfa3473

Browse files
committed
WIP: add type annotations to util and escape.
Passes on py3 except for a mypy bug (python/mypy#1135). Still some failures on py2.
1 parent b22da52 commit dfa3473

2 files changed

Lines changed: 95 additions & 26 deletions

File tree

‎tornado/escape.py‎

Lines changed: 35 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626
import re
2727
import sys
2828

29-
from tornado.util import PY3, unicode_type, basestring_type
29+
from tornado.util import PY3, unicode_type, basestring_type, StringTypes
3030

3131
if PY3:
3232
from urllib.parse import parse_qs as _parse_qs
@@ -38,13 +38,23 @@
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 = {'&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;',
4453
'\'': '&#39;'}
4554

4655

4756
def 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

6272
def 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.
7081
def 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

8193
def 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

8699
def 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

91105
def 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.
109124
if 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
134150
else:
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

183201
def 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

200219
def 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
222242
else:
223243
native_str = utf8
@@ -226,6 +246,7 @@ def to_unicode(value):
226246

227247

228248
def 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

246267
def 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

272294
def 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

368392
def _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

383408
def _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

Comments
 (0)