",
+ loader: Optional["BaseLoader"] = None,
+ compress_whitespace: Union[bool, _UnsetMarker] = _UNSET,
+ autoescape: Optional[Union[str, _UnsetMarker]] = _UNSET,
+ whitespace: Optional[str] = None,
+ ) -> None:
+ """Construct a Template.
+
+ :arg str template_string: the contents of the template file.
+ :arg str name: the filename from which the template was loaded
+ (used for error message).
+ :arg olTornado.template.BaseLoader loader: the `~olTornado.template.BaseLoader` responsible
+ for this template, used to resolve ``{% include %}`` and ``{% extend %}`` directives.
+ :arg bool compress_whitespace: Deprecated since Tornado 4.3.
+ Equivalent to ``whitespace="single"`` if true and
+ ``whitespace="all"`` if false.
+ :arg str autoescape: The name of a function in the template
+ namespace, or ``None`` to disable escaping by default.
+ :arg str whitespace: A string specifying treatment of whitespace;
+ see `filter_whitespace` for options.
+
+ .. versionchanged:: 4.3
+ Added ``whitespace`` parameter; deprecated ``compress_whitespace``.
+ """
+ self.name = escape.native_str(name)
+
+ if compress_whitespace is not _UNSET:
+ # Convert deprecated compress_whitespace (bool) to whitespace (str).
+ if whitespace is not None:
+ raise Exception("cannot set both whitespace and compress_whitespace")
+ whitespace = "single" if compress_whitespace else "all"
+ if whitespace is None:
+ if loader and loader.whitespace:
+ whitespace = loader.whitespace
+ else:
+ # Whitespace defaults by filename.
+ if name.endswith(".html") or name.endswith(".js"):
+ whitespace = "single"
+ else:
+ whitespace = "all"
+ # Validate the whitespace setting.
+ assert whitespace is not None
+ filter_whitespace(whitespace, "")
+
+ if not isinstance(autoescape, _UnsetMarker):
+ self.autoescape = autoescape # type: Optional[str]
+ elif loader:
+ self.autoescape = loader.autoescape
+ else:
+ self.autoescape = _DEFAULT_AUTOESCAPE
+
+ self.namespace = loader.namespace if loader else {}
+ reader = _TemplateReader(name, escape.native_str(template_string), whitespace)
+ self.file = _File(self, _parse(reader, self))
+ self.code = self._generate_python(loader)
+ self.loader = loader
+ try:
+ # Under python2.5, the fake filename used here must match
+ # the module name used in __name__ below.
+ # The dont_inherit flag prevents template.py's future imports
+ # from being applied to the generated code.
+ self.compiled = compile(
+ escape.to_unicode(self.code),
+ "%s.generated.py" % self.name.replace(".", "_"),
+ "exec",
+ dont_inherit=True,
+ )
+ except Exception:
+ formatted_code = _format_code(self.code).rstrip()
+ app_log.error("%s code:\n%s", self.name, formatted_code)
+ raise
+
+ def generate(self, **kwargs: Any) -> bytes:
+ """Generate this template with the given arguments."""
+ namespace = {
+ "escape": escape.xhtml_escape,
+ "xhtml_escape": escape.xhtml_escape,
+ "url_escape": escape.url_escape,
+ "json_encode": escape.json_encode,
+ "squeeze": escape.squeeze,
+ "linkify": escape.linkify,
+ "datetime": datetime,
+ "_tt_utf8": escape.utf8, # for internal use
+ "_tt_string_types": (unicode_type, bytes),
+ # __name__ and __loader__ allow the traceback mechanism to find
+ # the generated source code.
+ "__name__": self.name.replace(".", "_"),
+ "__loader__": ObjectDict(get_source=lambda name: self.code),
+ }
+ namespace.update(self.namespace)
+ namespace.update(kwargs)
+ exec_in(self.compiled, namespace)
+ execute = typing.cast(Callable[[], bytes], namespace["_tt_execute"])
+ # Clear the traceback module's cache of source data now that
+ # we've generated a new template (mainly for this module's
+ # unittests, where different tests reuse the same name).
+ linecache.clearcache()
+ return execute()
+
+ def _generate_python(self, loader: Optional["BaseLoader"]) -> str:
+ buffer = StringIO()
+ try:
+ # named_blocks maps from names to _NamedBlock objects
+ named_blocks = {} # type: Dict[str, _NamedBlock]
+ ancestors = self._get_ancestors(loader)
+ ancestors.reverse()
+ for ancestor in ancestors:
+ ancestor.find_named_blocks(loader, named_blocks)
+ writer = _CodeWriter(buffer, named_blocks, loader, ancestors[0].template)
+ ancestors[0].generate(writer)
+ return buffer.getvalue()
+ finally:
+ buffer.close()
+
+ def _get_ancestors(self, loader: Optional["BaseLoader"]) -> List["_File"]:
+ ancestors = [self.file]
+ for chunk in self.file.body.chunks:
+ if isinstance(chunk, _ExtendsBlock):
+ if not loader:
+ raise ParseError(
+ "{% extends %} block found, but no " "template loader"
+ )
+ template = loader.load(chunk.name, self.name)
+ ancestors.extend(template._get_ancestors(loader))
+ return ancestors
+
+
+class BaseLoader(object):
+ """Base class for template loaders.
+
+ You must use a template loader to use template constructs like
+ ``{% extends %}`` and ``{% include %}``. The loader caches all
+ templates after they are loaded the first time.
+ """
+
+ def __init__(
+ self,
+ autoescape: str = _DEFAULT_AUTOESCAPE,
+ namespace: Optional[Dict[str, Any]] = None,
+ whitespace: Optional[str] = None,
+ ) -> None:
+ """Construct a template loader.
+
+ :arg str autoescape: The name of a function in the template
+ namespace, such as "xhtml_escape", or ``None`` to disable
+ autoescaping by default.
+ :arg dict namespace: A dictionary to be added to the default template
+ namespace, or ``None``.
+ :arg str whitespace: A string specifying default behavior for
+ whitespace in templates; see `filter_whitespace` for options.
+ Default is "single" for files ending in ".html" and ".js" and
+ "all" for other files.
+
+ .. versionchanged:: 4.3
+ Added ``whitespace`` parameter.
+ """
+ self.autoescape = autoescape
+ self.namespace = namespace or {}
+ self.whitespace = whitespace
+ self.templates = {} # type: Dict[str, Template]
+ # self.lock protects self.templates. It's a reentrant lock
+ # because templates may load other templates via `include` or
+ # `extends`. Note that thanks to the GIL this code would be safe
+ # even without the lock, but could lead to wasted work as multiple
+ # threads tried to compile the same template simultaneously.
+ self.lock = threading.RLock()
+
+ def reset(self) -> None:
+ """Resets the cache of compiled templates."""
+ with self.lock:
+ self.templates = {}
+
+ def resolve_path(self, name: str, parent_path: Optional[str] = None) -> str:
+ """Converts a possibly-relative path to absolute (used internally)."""
+ raise NotImplementedError()
+
+ def load(self, name: str, parent_path: Optional[str] = None) -> Template:
+ """Loads a template."""
+ name = self.resolve_path(name, parent_path=parent_path)
+ with self.lock:
+ if name not in self.templates:
+ self.templates[name] = self._create_template(name)
+ return self.templates[name]
+
+ def _create_template(self, name: str) -> Template:
+ raise NotImplementedError()
+
+
+class Loader(BaseLoader):
+ """A template loader that loads from a single root directory."""
+
+ def __init__(self, root_directory: str, **kwargs: Any) -> None:
+ super().__init__(**kwargs)
+ self.root = os.path.abspath(root_directory)
+
+ def resolve_path(self, name: str, parent_path: Optional[str] = None) -> str:
+ if (
+ parent_path
+ and not parent_path.startswith("<")
+ and not parent_path.startswith("/")
+ and not name.startswith("/")
+ ):
+ current_path = os.path.join(self.root, parent_path)
+ file_dir = os.path.dirname(os.path.abspath(current_path))
+ relative_path = os.path.abspath(os.path.join(file_dir, name))
+ if relative_path.startswith(self.root):
+ name = relative_path[len(self.root) + 1 :]
+ return name
+
+ def _create_template(self, name: str) -> Template:
+ path = os.path.join(self.root, name)
+ with open(path, "rb") as f:
+ template = Template(f.read(), name=name, loader=self)
+ return template
+
+
+class DictLoader(BaseLoader):
+ """A template loader that loads from a dictionary."""
+
+ def __init__(self, dict: Dict[str, str], **kwargs: Any) -> None:
+ super().__init__(**kwargs)
+ self.dict = dict
+
+ def resolve_path(self, name: str, parent_path: Optional[str] = None) -> str:
+ if (
+ parent_path
+ and not parent_path.startswith("<")
+ and not parent_path.startswith("/")
+ and not name.startswith("/")
+ ):
+ file_dir = posixpath.dirname(parent_path)
+ name = posixpath.normpath(posixpath.join(file_dir, name))
+ return name
+
+ def _create_template(self, name: str) -> Template:
+ return Template(self.dict[name], name=name, loader=self)
+
+
+class _Node(object):
+ def each_child(self) -> Iterable["_Node"]:
+ return ()
+
+ def generate(self, writer: "_CodeWriter") -> None:
+ raise NotImplementedError()
+
+ def find_named_blocks(
+ self, loader: Optional[BaseLoader], named_blocks: Dict[str, "_NamedBlock"]
+ ) -> None:
+ for child in self.each_child():
+ child.find_named_blocks(loader, named_blocks)
+
+
+class _File(_Node):
+ def __init__(self, template: Template, body: "_ChunkList") -> None:
+ self.template = template
+ self.body = body
+ self.line = 0
+
+ def generate(self, writer: "_CodeWriter") -> None:
+ writer.write_line("def _tt_execute():", self.line)
+ with writer.indent():
+ writer.write_line("_tt_buffer = []", self.line)
+ writer.write_line("_tt_append = _tt_buffer.append", self.line)
+ self.body.generate(writer)
+ writer.write_line("return _tt_utf8('').join(_tt_buffer)", self.line)
+
+ def each_child(self) -> Iterable["_Node"]:
+ return (self.body,)
+
+
+class _ChunkList(_Node):
+ def __init__(self, chunks: List[_Node]) -> None:
+ self.chunks = chunks
+
+ def generate(self, writer: "_CodeWriter") -> None:
+ for chunk in self.chunks:
+ chunk.generate(writer)
+
+ def each_child(self) -> Iterable["_Node"]:
+ return self.chunks
+
+
+class _NamedBlock(_Node):
+ def __init__(self, name: str, body: _Node, template: Template, line: int) -> None:
+ self.name = name
+ self.body = body
+ self.template = template
+ self.line = line
+
+ def each_child(self) -> Iterable["_Node"]:
+ return (self.body,)
+
+ def generate(self, writer: "_CodeWriter") -> None:
+ block = writer.named_blocks[self.name]
+ with writer.include(block.template, self.line):
+ block.body.generate(writer)
+
+ def find_named_blocks(
+ self, loader: Optional[BaseLoader], named_blocks: Dict[str, "_NamedBlock"]
+ ) -> None:
+ named_blocks[self.name] = self
+ _Node.find_named_blocks(self, loader, named_blocks)
+
+
+class _ExtendsBlock(_Node):
+ def __init__(self, name: str) -> None:
+ self.name = name
+
+
+class _IncludeBlock(_Node):
+ def __init__(self, name: str, reader: "_TemplateReader", line: int) -> None:
+ self.name = name
+ self.template_name = reader.name
+ self.line = line
+
+ def find_named_blocks(
+ self, loader: Optional[BaseLoader], named_blocks: Dict[str, _NamedBlock]
+ ) -> None:
+ assert loader is not None
+ included = loader.load(self.name, self.template_name)
+ included.file.find_named_blocks(loader, named_blocks)
+
+ def generate(self, writer: "_CodeWriter") -> None:
+ assert writer.loader is not None
+ included = writer.loader.load(self.name, self.template_name)
+ with writer.include(included, self.line):
+ included.file.body.generate(writer)
+
+
+class _ApplyBlock(_Node):
+ def __init__(self, method: str, line: int, body: _Node) -> None:
+ self.method = method
+ self.line = line
+ self.body = body
+
+ def each_child(self) -> Iterable["_Node"]:
+ return (self.body,)
+
+ def generate(self, writer: "_CodeWriter") -> None:
+ method_name = "_tt_apply%d" % writer.apply_counter
+ writer.apply_counter += 1
+ writer.write_line("def %s():" % method_name, self.line)
+ with writer.indent():
+ writer.write_line("_tt_buffer = []", self.line)
+ writer.write_line("_tt_append = _tt_buffer.append", self.line)
+ self.body.generate(writer)
+ writer.write_line("return _tt_utf8('').join(_tt_buffer)", self.line)
+ writer.write_line(
+ "_tt_append(_tt_utf8(%s(%s())))" % (self.method, method_name), self.line
+ )
+
+
+class _ControlBlock(_Node):
+ def __init__(self, statement: str, line: int, body: _Node) -> None:
+ self.statement = statement
+ self.line = line
+ self.body = body
+
+ def each_child(self) -> Iterable[_Node]:
+ return (self.body,)
+
+ def generate(self, writer: "_CodeWriter") -> None:
+ writer.write_line("%s:" % self.statement, self.line)
+ with writer.indent():
+ self.body.generate(writer)
+ # Just in case the body was empty
+ writer.write_line("pass", self.line)
+
+
+class _IntermediateControlBlock(_Node):
+ def __init__(self, statement: str, line: int) -> None:
+ self.statement = statement
+ self.line = line
+
+ def generate(self, writer: "_CodeWriter") -> None:
+ # In case the previous block was empty
+ writer.write_line("pass", self.line)
+ writer.write_line("%s:" % self.statement, self.line, writer.indent_size() - 1)
+
+
+class _Statement(_Node):
+ def __init__(self, statement: str, line: int) -> None:
+ self.statement = statement
+ self.line = line
+
+ def generate(self, writer: "_CodeWriter") -> None:
+ writer.write_line(self.statement, self.line)
+
+
+class _Expression(_Node):
+ def __init__(self, expression: str, line: int, raw: bool = False) -> None:
+ self.expression = expression
+ self.line = line
+ self.raw = raw
+
+ def generate(self, writer: "_CodeWriter") -> None:
+ writer.write_line("_tt_tmp = %s" % self.expression, self.line)
+ writer.write_line(
+ "if isinstance(_tt_tmp, _tt_string_types):" " _tt_tmp = _tt_utf8(_tt_tmp)",
+ self.line,
+ )
+ writer.write_line("else: _tt_tmp = _tt_utf8(str(_tt_tmp))", self.line)
+ if not self.raw and writer.current_template.autoescape is not None:
+ # In python3 functions like xhtml_escape return unicode,
+ # so we have to convert to utf8 again.
+ writer.write_line(
+ "_tt_tmp = _tt_utf8(%s(_tt_tmp))" % writer.current_template.autoescape,
+ self.line,
+ )
+ writer.write_line("_tt_append(_tt_tmp)", self.line)
+
+
+class _Module(_Expression):
+ def __init__(self, expression: str, line: int) -> None:
+ super().__init__("_tt_modules." + expression, line, raw=True)
+
+
+class _Text(_Node):
+ def __init__(self, value: str, line: int, whitespace: str) -> None:
+ self.value = value
+ self.line = line
+ self.whitespace = whitespace
+
+ def generate(self, writer: "_CodeWriter") -> None:
+ value = self.value
+
+ # Compress whitespace if requested, with a crude heuristic to avoid
+ # altering preformatted whitespace.
+ if "" not in value:
+ value = filter_whitespace(self.whitespace, value)
+
+ if value:
+ writer.write_line("_tt_append(%r)" % escape.utf8(value), self.line)
+
+
+class ParseError(Exception):
+ """Raised for template syntax errors.
+
+ ``ParseError`` instances have ``filename`` and ``lineno`` attributes
+ indicating the position of the error.
+
+ .. versionchanged:: 4.3
+ Added ``filename`` and ``lineno`` attributes.
+ """
+
+ def __init__(
+ self, message: str, filename: Optional[str] = None, lineno: int = 0
+ ) -> None:
+ self.message = message
+ # The names "filename" and "lineno" are chosen for consistency
+ # with python SyntaxError.
+ self.filename = filename
+ self.lineno = lineno
+
+ def __str__(self) -> str:
+ return "%s at %s:%d" % (self.message, self.filename, self.lineno)
+
+
+class _CodeWriter(object):
+ def __init__(
+ self,
+ file: TextIO,
+ named_blocks: Dict[str, _NamedBlock],
+ loader: Optional[BaseLoader],
+ current_template: Template,
+ ) -> None:
+ self.file = file
+ self.named_blocks = named_blocks
+ self.loader = loader
+ self.current_template = current_template
+ self.apply_counter = 0
+ self.include_stack = [] # type: List[Tuple[Template, int]]
+ self._indent = 0
+
+ def indent_size(self) -> int:
+ return self._indent
+
+ def indent(self) -> "ContextManager":
+ class Indenter(object):
+ def __enter__(_) -> "_CodeWriter":
+ self._indent += 1
+ return self
+
+ def __exit__(_, *args: Any) -> None:
+ assert self._indent > 0
+ self._indent -= 1
+
+ return Indenter()
+
+ def include(self, template: Template, line: int) -> "ContextManager":
+ self.include_stack.append((self.current_template, line))
+ self.current_template = template
+
+ class IncludeTemplate(object):
+ def __enter__(_) -> "_CodeWriter":
+ return self
+
+ def __exit__(_, *args: Any) -> None:
+ self.current_template = self.include_stack.pop()[0]
+
+ return IncludeTemplate()
+
+ def write_line(
+ self, line: str, line_number: int, indent: Optional[int] = None
+ ) -> None:
+ if indent is None:
+ indent = self._indent
+ line_comment = " # %s:%d" % (self.current_template.name, line_number)
+ if self.include_stack:
+ ancestors = [
+ "%s:%d" % (tmpl.name, lineno) for (tmpl, lineno) in self.include_stack
+ ]
+ line_comment += " (via %s)" % ", ".join(reversed(ancestors))
+ print(" " * indent + line + line_comment, file=self.file)
+
+
+class _TemplateReader(object):
+ def __init__(self, name: str, text: str, whitespace: str) -> None:
+ self.name = name
+ self.text = text
+ self.whitespace = whitespace
+ self.line = 1
+ self.pos = 0
+
+ def find(self, needle: str, start: int = 0, end: Optional[int] = None) -> int:
+ assert start >= 0, start
+ pos = self.pos
+ start += pos
+ if end is None:
+ index = self.text.find(needle, start)
+ else:
+ end += pos
+ assert end >= start
+ index = self.text.find(needle, start, end)
+ if index != -1:
+ index -= pos
+ return index
+
+ def consume(self, count: Optional[int] = None) -> str:
+ if count is None:
+ count = len(self.text) - self.pos
+ newpos = self.pos + count
+ self.line += self.text.count("\n", self.pos, newpos)
+ s = self.text[self.pos : newpos]
+ self.pos = newpos
+ return s
+
+ def remaining(self) -> int:
+ return len(self.text) - self.pos
+
+ def __len__(self) -> int:
+ return self.remaining()
+
+ def __getitem__(self, key: Union[int, slice]) -> str:
+ if isinstance(key, slice):
+ size = len(self)
+ start, stop, step = key.indices(size)
+ if start is None:
+ start = self.pos
+ else:
+ start += self.pos
+ if stop is not None:
+ stop += self.pos
+ return self.text[slice(start, stop, step)]
+ elif key < 0:
+ return self.text[key]
+ else:
+ return self.text[self.pos + key]
+
+ def __str__(self) -> str:
+ return self.text[self.pos :]
+
+ def raise_parse_error(self, msg: str) -> None:
+ raise ParseError(msg, self.name, self.line)
+
+
+def _format_code(code: str) -> str:
+ lines = code.splitlines()
+ format = "%%%dd %%s\n" % len(repr(len(lines) + 1))
+ return "".join([format % (i + 1, line) for (i, line) in enumerate(lines)])
+
+
+def _parse(
+ reader: _TemplateReader,
+ template: Template,
+ in_block: Optional[str] = None,
+ in_loop: Optional[str] = None,
+) -> _ChunkList:
+ body = _ChunkList([])
+ while True:
+ # Find next template directive
+ curly = 0
+ while True:
+ curly = reader.find("{", curly)
+ if curly == -1 or curly + 1 == reader.remaining():
+ # EOF
+ if in_block:
+ reader.raise_parse_error(
+ "Missing {%% end %%} block for %s" % in_block
+ )
+ body.chunks.append(
+ _Text(reader.consume(), reader.line, reader.whitespace)
+ )
+ return body
+ # If the first curly brace is not the start of a special token,
+ # start searching from the character after it
+ if reader[curly + 1] not in ("{", "%", "#"):
+ curly += 1
+ continue
+ # When there are more than 2 curlies in a row, use the
+ # innermost ones. This is useful when generating languages
+ # like latex where curlies are also meaningful
+ if (
+ curly + 2 < reader.remaining()
+ and reader[curly + 1] == "{"
+ and reader[curly + 2] == "{"
+ ):
+ curly += 1
+ continue
+ break
+
+ # Append any text before the special token
+ if curly > 0:
+ cons = reader.consume(curly)
+ body.chunks.append(_Text(cons, reader.line, reader.whitespace))
+
+ start_brace = reader.consume(2)
+ line = reader.line
+
+ # Template directives may be escaped as "{{!" or "{%!".
+ # In this case output the braces and consume the "!".
+ # This is especially useful in conjunction with jquery templates,
+ # which also use double braces.
+ if reader.remaining() and reader[0] == "!":
+ reader.consume(1)
+ body.chunks.append(_Text(start_brace, line, reader.whitespace))
+ continue
+
+ # Comment
+ if start_brace == "{#":
+ end = reader.find("#}")
+ if end == -1:
+ reader.raise_parse_error("Missing end comment #}")
+ contents = reader.consume(end).strip()
+ reader.consume(2)
+ continue
+
+ # Expression
+ if start_brace == "{{":
+ end = reader.find("}}")
+ if end == -1:
+ reader.raise_parse_error("Missing end expression }}")
+ contents = reader.consume(end).strip()
+ reader.consume(2)
+ if not contents:
+ reader.raise_parse_error("Empty expression")
+ body.chunks.append(_Expression(contents, line))
+ continue
+
+ # Block
+ assert start_brace == "{%", start_brace
+ end = reader.find("%}")
+ if end == -1:
+ reader.raise_parse_error("Missing end block %}")
+ contents = reader.consume(end).strip()
+ reader.consume(2)
+ if not contents:
+ reader.raise_parse_error("Empty block tag ({% %})")
+
+ operator, space, suffix = contents.partition(" ")
+ suffix = suffix.strip()
+
+ # Intermediate ("else", "elif", etc) blocks
+ intermediate_blocks = {
+ "else": set(["if", "for", "while", "try"]),
+ "elif": set(["if"]),
+ "except": set(["try"]),
+ "finally": set(["try"]),
+ }
+ allowed_parents = intermediate_blocks.get(operator)
+ if allowed_parents is not None:
+ if not in_block:
+ reader.raise_parse_error(
+ "%s outside %s block" % (operator, allowed_parents)
+ )
+ if in_block not in allowed_parents:
+ reader.raise_parse_error(
+ "%s block cannot be attached to %s block" % (operator, in_block)
+ )
+ body.chunks.append(_IntermediateControlBlock(contents, line))
+ continue
+
+ # End tag
+ elif operator == "end":
+ if not in_block:
+ reader.raise_parse_error("Extra {% end %} block")
+ return body
+
+ elif operator in (
+ "extends",
+ "include",
+ "set",
+ "import",
+ "from",
+ "comment",
+ "autoescape",
+ "whitespace",
+ "raw",
+ "module",
+ ):
+ if operator == "comment":
+ continue
+ if operator == "extends":
+ suffix = suffix.strip('"').strip("'")
+ if not suffix:
+ reader.raise_parse_error("extends missing file path")
+ block = _ExtendsBlock(suffix) # type: _Node
+ elif operator in ("import", "from"):
+ if not suffix:
+ reader.raise_parse_error("import missing statement")
+ block = _Statement(contents, line)
+ elif operator == "include":
+ suffix = suffix.strip('"').strip("'")
+ if not suffix:
+ reader.raise_parse_error("include missing file path")
+ block = _IncludeBlock(suffix, reader, line)
+ elif operator == "set":
+ if not suffix:
+ reader.raise_parse_error("set missing statement")
+ block = _Statement(suffix, line)
+ elif operator == "autoescape":
+ fn = suffix.strip() # type: Optional[str]
+ if fn == "None":
+ fn = None
+ template.autoescape = fn
+ continue
+ elif operator == "whitespace":
+ mode = suffix.strip()
+ # Validate the selected mode
+ filter_whitespace(mode, "")
+ reader.whitespace = mode
+ continue
+ elif operator == "raw":
+ block = _Expression(suffix, line, raw=True)
+ elif operator == "module":
+ block = _Module(suffix, line)
+ body.chunks.append(block)
+ continue
+
+ elif operator in ("apply", "block", "try", "if", "for", "while"):
+ # parse inner body recursively
+ if operator in ("for", "while"):
+ block_body = _parse(reader, template, operator, operator)
+ elif operator == "apply":
+ # apply creates a nested function so syntactically it's not
+ # in the loop.
+ block_body = _parse(reader, template, operator, None)
+ else:
+ block_body = _parse(reader, template, operator, in_loop)
+
+ if operator == "apply":
+ if not suffix:
+ reader.raise_parse_error("apply missing method name")
+ block = _ApplyBlock(suffix, line, block_body)
+ elif operator == "block":
+ if not suffix:
+ reader.raise_parse_error("block missing name")
+ block = _NamedBlock(suffix, block_body, template, line)
+ else:
+ block = _ControlBlock(contents, line, block_body)
+ body.chunks.append(block)
+ continue
+
+ elif operator in ("break", "continue"):
+ if not in_loop:
+ reader.raise_parse_error(
+ "%s outside %s block" % (operator, set(["for", "while"]))
+ )
+ body.chunks.append(_Statement(contents, line))
+ continue
+
+ else:
+ reader.raise_parse_error("unknown operator: %r" % operator)
\ No newline at end of file
diff --git a/min-image/runtimes/python/olTornado/util.py b/min-image/runtimes/python/olTornado/util.py
new file mode 100644
index 000000000..6e9784b99
--- /dev/null
+++ b/min-image/runtimes/python/olTornado/util.py
@@ -0,0 +1,462 @@
+"""Miscellaneous utility functions and classes.
+
+This module is used internally by Tornado. It is not necessarily expected
+that the functions and classes defined here will be useful to other
+applications, but they are documented here in case they are.
+
+The one public-facing part of this module is the `Configurable` class
+and its `~Configurable.configure` method, which becomes a part of the
+interface of its subclasses, including `.AsyncHTTPClient`, `.IOLoop`,
+and `.Resolver`.
+"""
+
+import array
+import asyncio
+import atexit
+from inspect import getfullargspec
+import os
+import re
+import typing
+import zlib
+
+from typing import (
+ Any,
+ Optional,
+ Dict,
+ Mapping,
+ List,
+ Tuple,
+ Match,
+ Callable,
+ Type,
+ Sequence,
+)
+
+if typing.TYPE_CHECKING:
+ # Additional imports only used in type comments.
+ # This lets us make these imports lazy.
+ import datetime # noqa: F401
+ from types import TracebackType # noqa: F401
+ from typing import Union # noqa: F401
+ import unittest # noqa: F401
+
+# Aliases for types that are spelled differently in different Python
+# versions. bytes_type is deprecated and no longer used in Tornado
+# itself but is left in case anyone outside Tornado is using it.
+bytes_type = bytes
+unicode_type = str
+basestring_type = str
+
+try:
+ from sys import is_finalizing
+except ImportError:
+ # Emulate it
+ def _get_emulated_is_finalizing() -> Callable[[], bool]:
+ L = [] # type: List[None]
+ atexit.register(lambda: L.append(None))
+
+ def is_finalizing() -> bool:
+ # Not referencing any globals here
+ return L != []
+
+ return is_finalizing
+
+ is_finalizing = _get_emulated_is_finalizing()
+
+
+# versionchanged:: 6.2
+# no longer our own TimeoutError, use standard asyncio class
+TimeoutError = asyncio.TimeoutError
+
+
+class ObjectDict(Dict[str, Any]):
+ """Makes a dictionary behave like an object, with attribute-style access."""
+
+ def __getattr__(self, name: str) -> Any:
+ try:
+ return self[name]
+ except KeyError:
+ raise AttributeError(name)
+
+ def __setattr__(self, name: str, value: Any) -> None:
+ self[name] = value
+
+
+class GzipDecompressor(object):
+ """Streaming gzip decompressor.
+
+ The interface is like that of `zlib.decompressobj` (without some of the
+ optional arguments, but it understands gzip headers and checksums.
+ """
+
+ def __init__(self) -> None:
+ # Magic parameter makes zlib module understand gzip header
+ # http://stackoverflow.com/questions/1838699/how-can-i-decompress-a-gzip-stream-with-zlib
+ # This works on cpython and pypy, but not jython.
+ self.decompressobj = zlib.decompressobj(16 + zlib.MAX_WBITS)
+
+ def decompress(self, value: bytes, max_length: int = 0) -> bytes:
+ """Decompress a chunk, returning newly-available data.
+
+ Some data may be buffered for later processing; `flush` must
+ be called when there is no more input data to ensure that
+ all data was processed.
+
+ If ``max_length`` is given, some input data may be left over
+ in ``unconsumed_tail``; you must retrieve this value and pass
+ it back to a future call to `decompress` if it is not empty.
+ """
+ return self.decompressobj.decompress(value, max_length)
+
+ @property
+ def unconsumed_tail(self) -> bytes:
+ """Returns the unconsumed portion left over"""
+ return self.decompressobj.unconsumed_tail
+
+ def flush(self) -> bytes:
+ """Return any remaining buffered data not yet returned by decompress.
+
+ Also checks for errors such as truncated input.
+ No other methods may be called on this object after `flush`.
+ """
+ return self.decompressobj.flush()
+
+
+def import_object(name: str) -> Any:
+ """Imports an object by name.
+
+ ``import_object('x')`` is equivalent to ``import x``.
+ ``import_object('x.y.z')`` is equivalent to ``from x.y import z``.
+
+ >>> import olTornado.escape
+ >>> import_object('olTornado.escape') is olTornado.escape
+ True
+ >>> import_object('olTornado.escape.utf8') is olTornado.escape.utf8
+ True
+ >>> import_object('tornado') is tornado
+ True
+ >>> import_object('olTornado.missing_module')
+ Traceback (most recent call last):
+ ...
+ ImportError: No module named missing_module
+ """
+ if name.count(".") == 0:
+ return __import__(name)
+
+ parts = name.split(".")
+ obj = __import__(".".join(parts[:-1]), fromlist=[parts[-1]])
+ try:
+ return getattr(obj, parts[-1])
+ except AttributeError:
+ raise ImportError("No module named %s" % parts[-1])
+
+
+def exec_in(
+ code: Any, glob: Dict[str, Any], loc: Optional[Optional[Mapping[str, Any]]] = None
+) -> None:
+ if isinstance(code, str):
+ # exec(string) inherits the caller's future imports; compile
+ # the string first to prevent that.
+ code = compile(code, "", "exec", dont_inherit=True)
+ exec(code, glob, loc)
+
+
+def raise_exc_info(
+ exc_info: Tuple[Optional[type], Optional[BaseException], Optional["TracebackType"]]
+) -> typing.NoReturn:
+ try:
+ if exc_info[1] is not None:
+ raise exc_info[1].with_traceback(exc_info[2])
+ else:
+ raise TypeError("raise_exc_info called with no exception")
+ finally:
+ # Clear the traceback reference from our stack frame to
+ # minimize circular references that slow down GC.
+ exc_info = (None, None, None)
+
+
+def errno_from_exception(e: BaseException) -> Optional[int]:
+ """Provides the errno from an Exception object.
+
+ There are cases that the errno attribute was not set so we pull
+ the errno out of the args but if someone instantiates an Exception
+ without any args you will get a tuple error. So this function
+ abstracts all that behavior to give you a safe way to get the
+ errno.
+ """
+
+ if hasattr(e, "errno"):
+ return e.errno # type: ignore
+ elif e.args:
+ return e.args[0]
+ else:
+ return None
+
+
+_alphanum = frozenset("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789")
+
+
+def _re_unescape_replacement(match: Match[str]) -> str:
+ group = match.group(1)
+ if group[0] in _alphanum:
+ raise ValueError("cannot unescape '\\\\%s'" % group[0])
+ return group
+
+
+_re_unescape_pattern = re.compile(r"\\(.)", re.DOTALL)
+
+
+def re_unescape(s: str) -> str:
+ r"""Unescape a string escaped by `re.escape`.
+
+ May raise ``ValueError`` for regular expressions which could not
+ have been produced by `re.escape` (for example, strings containing
+ ``\d`` cannot be unescaped).
+
+ .. versionadded:: 4.4
+ """
+ return _re_unescape_pattern.sub(_re_unescape_replacement, s)
+
+
+class Configurable(object):
+ """Base class for configurable interfaces.
+
+ A configurable interface is an (abstract) class whose constructor
+ acts as a factory function for one of its implementation subclasses.
+ The implementation subclass as well as optional keyword arguments to
+ its initializer can be set globally at runtime with `configure`.
+
+ By using the constructor as the factory method, the interface
+ looks like a normal class, `isinstance` works as usual, etc. This
+ pattern is most useful when the choice of implementation is likely
+ to be a global decision (e.g. when `~select.epoll` is available,
+ always use it instead of `~select.select`), or when a
+ previously-monolithic class has been split into specialized
+ subclasses.
+
+ Configurable subclasses must define the class methods
+ `configurable_base` and `configurable_default`, and use the instance
+ method `initialize` instead of ``__init__``.
+
+ .. versionchanged:: 5.0
+
+ It is now possible for configuration to be specified at
+ multiple levels of a class hierarchy.
+
+ """
+
+ # Type annotations on this class are mostly done with comments
+ # because they need to refer to Configurable, which isn't defined
+ # until after the class definition block. These can use regular
+ # annotations when our minimum python version is 3.7.
+ #
+ # There may be a clever way to use generics here to get more
+ # precise types (i.e. for a particular Configurable subclass T,
+ # all the types are subclasses of T, not just Configurable).
+ __impl_class = None # type: Optional[Type[Configurable]]
+ __impl_kwargs = None # type: Dict[str, Any]
+
+ def __new__(cls, *args: Any, **kwargs: Any) -> Any:
+ base = cls.configurable_base()
+ init_kwargs = {} # type: Dict[str, Any]
+ if cls is base:
+ impl = cls.configured_class()
+ if base.__impl_kwargs:
+ init_kwargs.update(base.__impl_kwargs)
+ else:
+ impl = cls
+ init_kwargs.update(kwargs)
+ if impl.configurable_base() is not base:
+ # The impl class is itself configurable, so recurse.
+ return impl(*args, **init_kwargs)
+ instance = super(Configurable, cls).__new__(impl)
+ # initialize vs __init__ chosen for compatibility with AsyncHTTPClient
+ # singleton magic. If we get rid of that we can switch to __init__
+ # here too.
+ instance.initialize(*args, **init_kwargs)
+ return instance
+
+ @classmethod
+ def configurable_base(cls):
+ # type: () -> Type[Configurable]
+ """Returns the base class of a configurable hierarchy.
+
+ This will normally return the class in which it is defined.
+ (which is *not* necessarily the same as the ``cls`` classmethod
+ parameter).
+
+ """
+ raise NotImplementedError()
+
+ @classmethod
+ def configurable_default(cls):
+ # type: () -> Type[Configurable]
+ """Returns the implementation class to be used if none is configured."""
+ raise NotImplementedError()
+
+ def _initialize(self) -> None:
+ pass
+
+ initialize = _initialize # type: Callable[..., None]
+ """Initialize a `Configurable` subclass instance.
+
+ Configurable classes should use `initialize` instead of ``__init__``.
+
+ .. versionchanged:: 4.2
+ Now accepts positional arguments in addition to keyword arguments.
+ """
+
+ @classmethod
+ def configure(cls, impl, **kwargs):
+ # type: (Union[None, str, Type[Configurable]], Any) -> None
+ """Sets the class to use when the base class is instantiated.
+
+ Keyword arguments will be saved and added to the arguments passed
+ to the constructor. This can be used to set global defaults for
+ some parameters.
+ """
+ base = cls.configurable_base()
+ if isinstance(impl, str):
+ impl = typing.cast(Type[Configurable], import_object(impl))
+ if impl is not None and not issubclass(impl, cls):
+ raise ValueError("Invalid subclass of %s" % cls)
+ base.__impl_class = impl
+ base.__impl_kwargs = kwargs
+
+ @classmethod
+ def configured_class(cls):
+ # type: () -> Type[Configurable]
+ """Returns the currently configured class."""
+ base = cls.configurable_base()
+ # Manually mangle the private name to see whether this base
+ # has been configured (and not another base higher in the
+ # hierarchy).
+ if base.__dict__.get("_Configurable__impl_class") is None:
+ base.__impl_class = cls.configurable_default()
+ if base.__impl_class is not None:
+ return base.__impl_class
+ else:
+ # Should be impossible, but mypy wants an explicit check.
+ raise ValueError("configured class not found")
+
+ @classmethod
+ def _save_configuration(cls):
+ # type: () -> Tuple[Optional[Type[Configurable]], Dict[str, Any]]
+ base = cls.configurable_base()
+ return (base.__impl_class, base.__impl_kwargs)
+
+ @classmethod
+ def _restore_configuration(cls, saved):
+ # type: (Tuple[Optional[Type[Configurable]], Dict[str, Any]]) -> None
+ base = cls.configurable_base()
+ base.__impl_class = saved[0]
+ base.__impl_kwargs = saved[1]
+
+
+class ArgReplacer(object):
+ """Replaces one value in an ``args, kwargs`` pair.
+
+ Inspects the function signature to find an argument by name
+ whether it is passed by position or keyword. For use in decorators
+ and similar wrappers.
+ """
+
+ def __init__(self, func: Callable, name: str) -> None:
+ self.name = name
+ try:
+ self.arg_pos = self._getargnames(func).index(name) # type: Optional[int]
+ except ValueError:
+ # Not a positional parameter
+ self.arg_pos = None
+
+ def _getargnames(self, func: Callable) -> List[str]:
+ try:
+ return getfullargspec(func).args
+ except TypeError:
+ if hasattr(func, "func_code"):
+ # Cython-generated code has all the attributes needed
+ # by inspect.getfullargspec, but the inspect module only
+ # works with ordinary functions. Inline the portion of
+ # getfullargspec that we need here. Note that for static
+ # functions the @cython.binding(True) decorator must
+ # be used (for methods it works out of the box).
+ code = func.func_code # type: ignore
+ return code.co_varnames[: code.co_argcount]
+ raise
+
+ def get_old_value(
+ self, args: Sequence[Any], kwargs: Dict[str, Any], default: Any = None
+ ) -> Any:
+ """Returns the old value of the named argument without replacing it.
+
+ Returns ``default`` if the argument is not present.
+ """
+ if self.arg_pos is not None and len(args) > self.arg_pos:
+ return args[self.arg_pos]
+ else:
+ return kwargs.get(self.name, default)
+
+ def replace(
+ self, new_value: Any, args: Sequence[Any], kwargs: Dict[str, Any]
+ ) -> Tuple[Any, Sequence[Any], Dict[str, Any]]:
+ """Replace the named argument in ``args, kwargs`` with ``new_value``.
+
+ Returns ``(old_value, args, kwargs)``. The returned ``args`` and
+ ``kwargs`` objects may not be the same as the input objects, or
+ the input objects may be mutated.
+
+ If the named argument was not found, ``new_value`` will be added
+ to ``kwargs`` and None will be returned as ``old_value``.
+ """
+ if self.arg_pos is not None and len(args) > self.arg_pos:
+ # The arg to replace is passed positionally
+ old_value = args[self.arg_pos]
+ args = list(args) # *args is normally a tuple
+ args[self.arg_pos] = new_value
+ else:
+ # The arg to replace is either omitted or passed by keyword.
+ old_value = kwargs.get(self.name)
+ kwargs[self.name] = new_value
+ return old_value, args, kwargs
+
+
+def timedelta_to_seconds(td):
+ # type: (datetime.timedelta) -> float
+ """Equivalent to ``td.total_seconds()`` (introduced in Python 2.7)."""
+ return td.total_seconds()
+
+
+def _websocket_mask_python(mask: bytes, data: bytes) -> bytes:
+ """Websocket masking function.
+
+ `mask` is a `bytes` object of length 4; `data` is a `bytes` object of any length.
+ Returns a `bytes` object of the same length as `data` with the mask applied
+ as specified in section 5.3 of RFC 6455.
+
+ This pure-python implementation may be replaced by an optimized version when available.
+ """
+ mask_arr = array.array("B", mask)
+ unmasked_arr = array.array("B", data)
+ for i in range(len(data)):
+ unmasked_arr[i] = unmasked_arr[i] ^ mask_arr[i % 4]
+ return unmasked_arr.tobytes()
+
+
+if os.environ.get("TORNADO_NO_EXTENSION") or os.environ.get("TORNADO_EXTENSION") == "0":
+ # These environment variables exist to make it easier to do performance
+ # comparisons; they are not guaranteed to remain supported in the future.
+ _websocket_mask = _websocket_mask_python
+else:
+ try:
+ from olTornado.speedups import websocket_mask as _websocket_mask
+ except ImportError:
+ if os.environ.get("TORNADO_EXTENSION") == "1":
+ raise
+ _websocket_mask = _websocket_mask_python
+
+
+def doctests():
+ # type: () -> unittest.TestSuite
+ import doctest
+
+ return doctest.DocTestSuite()
\ No newline at end of file
diff --git a/min-image/runtimes/python/olTornado/web.py b/min-image/runtimes/python/olTornado/web.py
new file mode 100644
index 000000000..9db766b3f
--- /dev/null
+++ b/min-image/runtimes/python/olTornado/web.py
@@ -0,0 +1,3716 @@
+#
+# Copyright 2009 Facebook
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""``olTornado.web`` provides a simple web framework with asynchronous
+features that allow it to scale to large numbers of open connections,
+making it ideal for `long polling
+`_.
+
+Here is a simple "Hello, world" example app:
+
+.. testcode::
+
+ import asyncio
+ import tornado
+
+ class MainHandler(olTornado.web.RequestHandler):
+ def get(self):
+ self.write("Hello, world")
+
+ async def main():
+ application = olTornado.web.Application([
+ (r"/", MainHandler),
+ ])
+ application.listen(8888)
+ await asyncio.Event().wait()
+
+ if __name__ == "__main__":
+ asyncio.run(main())
+
+.. testoutput::
+ :hide:
+
+
+See the :doc:`guide` for additional information.
+
+Thread-safety notes
+-------------------
+
+In general, methods on `RequestHandler` and elsewhere in Tornado are
+not thread-safe. In particular, methods such as
+`~RequestHandler.write()`, `~RequestHandler.finish()`, and
+`~RequestHandler.flush()` must only be called from the main thread. If
+you use multiple threads it is important to use `.IOLoop.add_callback`
+to transfer control back to the main thread before finishing the
+request, or to limit your use of other threads to
+`.IOLoop.run_in_executor` and ensure that your callbacks running in
+the executor do not refer to Tornado objects.
+
+"""
+
+import base64
+import binascii
+import datetime
+import email.utils
+import functools
+import gzip
+import hashlib
+import hmac
+import http.cookies
+from inspect import isclass
+from io import BytesIO
+import mimetypes
+import numbers
+import os.path
+import re
+import socket
+import sys
+import threading
+import time
+import warnings
+import olTornado
+import traceback
+import types
+import urllib.parse
+from urllib.parse import urlencode
+
+from olTornado.concurrent import Future, future_set_result_unless_cancelled
+from olTornado import escape
+from olTornado import gen
+from olTornado.httpserver import HTTPServer
+from olTornado import httputil
+from olTornado import iostream
+from olTornado import locale
+from olTornado.log import access_log, app_log, gen_log
+from olTornado import template
+from olTornado.escape import utf8, _unicode
+from olTornado.routing import (
+ AnyMatches,
+ DefaultHostMatches,
+ HostMatches,
+ ReversibleRouter,
+ Rule,
+ ReversibleRuleRouter,
+ URLSpec,
+ _RuleList,
+)
+from olTornado.util import ObjectDict, unicode_type, _websocket_mask
+
+url = URLSpec
+
+from typing import (
+ Dict,
+ Any,
+ Union,
+ Optional,
+ Awaitable,
+ Tuple,
+ List,
+ Callable,
+ Iterable,
+ Generator,
+ Type,
+ TypeVar,
+ cast,
+ overload,
+)
+from types import TracebackType
+import typing
+
+if typing.TYPE_CHECKING:
+ from typing import Set # noqa: F401
+
+
+# The following types are accepted by RequestHandler.set_header
+# and related methods.
+_HeaderTypes = Union[bytes, unicode_type, int, numbers.Integral, datetime.datetime]
+
+_CookieSecretTypes = Union[str, bytes, Dict[int, str], Dict[int, bytes]]
+
+
+MIN_SUPPORTED_SIGNED_VALUE_VERSION = 1
+"""The oldest signed value version supported by this version of Tornado.
+
+Signed values older than this version cannot be decoded.
+
+.. versionadded:: 3.2.1
+"""
+
+MAX_SUPPORTED_SIGNED_VALUE_VERSION = 2
+"""The newest signed value version supported by this version of Tornado.
+
+Signed values newer than this version cannot be decoded.
+
+.. versionadded:: 3.2.1
+"""
+
+DEFAULT_SIGNED_VALUE_VERSION = 2
+"""The signed value version produced by `.RequestHandler.create_signed_value`.
+
+May be overridden by passing a ``version`` keyword argument.
+
+.. versionadded:: 3.2.1
+"""
+
+DEFAULT_SIGNED_VALUE_MIN_VERSION = 1
+"""The oldest signed value accepted by `.RequestHandler.get_signed_cookie`.
+
+May be overridden by passing a ``min_version`` keyword argument.
+
+.. versionadded:: 3.2.1
+"""
+
+
+class _ArgDefaultMarker:
+ pass
+
+
+_ARG_DEFAULT = _ArgDefaultMarker()
+
+
+class RequestHandler(object):
+ """Base class for HTTP request handlers.
+
+ Subclasses must define at least one of the methods defined in the
+ "Entry points" section below.
+
+ Applications should not construct `RequestHandler` objects
+ directly and subclasses should not override ``__init__`` (override
+ `~RequestHandler.initialize` instead).
+
+ """
+
+ SUPPORTED_METHODS = ("GET", "HEAD", "POST", "DELETE", "PATCH", "PUT", "OPTIONS")
+
+ _template_loaders = {} # type: Dict[str, template.BaseLoader]
+ _template_loader_lock = threading.Lock()
+ _remove_control_chars_regex = re.compile(r"[\x00-\x08\x0e-\x1f]")
+
+ _stream_request_body = False
+
+ # Will be set in _execute.
+ _transforms = None # type: List[OutputTransform]
+ path_args = None # type: List[str]
+ path_kwargs = None # type: Dict[str, str]
+
+ def __init__(
+ self,
+ application: "Application",
+ request: httputil.HTTPServerRequest,
+ **kwargs: Any,
+ ) -> None:
+ super().__init__()
+
+ self.application = application
+ self.request = request
+ self._headers_written = False
+ self._finished = False
+ self._auto_finish = True
+ self._prepared_future = None
+ self.ui = ObjectDict(
+ (n, self._ui_method(m)) for n, m in application.ui_methods.items()
+ )
+ # UIModules are available as both `modules` and `_tt_modules` in the
+ # template namespace. Historically only `modules` was available
+ # but could be clobbered by user additions to the namespace.
+ # The template {% module %} directive looks in `_tt_modules` to avoid
+ # possible conflicts.
+ self.ui["_tt_modules"] = _UIModuleNamespace(self, application.ui_modules)
+ self.ui["modules"] = self.ui["_tt_modules"]
+ self.clear()
+ assert self.request.connection is not None
+ # TODO: need to add set_close_callback to HTTPConnection interface
+ self.request.connection.set_close_callback( # type: ignore
+ self.on_connection_close
+ )
+ self.initialize(**kwargs) # type: ignore
+
+ def _initialize(self) -> None:
+ pass
+
+ initialize = _initialize # type: Callable[..., None]
+ """Hook for subclass initialization. Called for each request.
+
+ A dictionary passed as the third argument of a ``URLSpec`` will be
+ supplied as keyword arguments to ``initialize()``.
+
+ Example::
+
+ class ProfileHandler(RequestHandler):
+ def initialize(self, database):
+ self.database = database
+
+ def get(self, username):
+ ...
+
+ app = Application([
+ (r'/user/(.*)', ProfileHandler, dict(database=database)),
+ ])
+ """
+
+ @property
+ def settings(self) -> Dict[str, Any]:
+ """An alias for `self.application.settings `."""
+ return self.application.settings
+
+ def _unimplemented_method(self, *args: str, **kwargs: str) -> None:
+ raise HTTPError(405)
+
+ head = _unimplemented_method # type: Callable[..., Optional[Awaitable[None]]]
+ get = _unimplemented_method # type: Callable[..., Optional[Awaitable[None]]]
+ post = _unimplemented_method # type: Callable[..., Optional[Awaitable[None]]]
+ delete = _unimplemented_method # type: Callable[..., Optional[Awaitable[None]]]
+ patch = _unimplemented_method # type: Callable[..., Optional[Awaitable[None]]]
+ put = _unimplemented_method # type: Callable[..., Optional[Awaitable[None]]]
+ options = _unimplemented_method # type: Callable[..., Optional[Awaitable[None]]]
+
+ def prepare(self) -> Optional[Awaitable[None]]:
+ """Called at the beginning of a request before `get`/`post`/etc.
+
+ Override this method to perform common initialization regardless
+ of the request method.
+
+ Asynchronous support: Use ``async def`` or decorate this method with
+ `.gen.coroutine` to make it asynchronous.
+ If this method returns an ``Awaitable`` execution will not proceed
+ until the ``Awaitable`` is done.
+
+ .. versionadded:: 3.1
+ Asynchronous support.
+ """
+ pass
+
+ def on_finish(self) -> None:
+ """Called after the end of a request.
+
+ Override this method to perform cleanup, logging, etc.
+ This method is a counterpart to `prepare`. ``on_finish`` may
+ not produce any output, as it is called after the response
+ has been sent to the client.
+ """
+ pass
+
+ def on_connection_close(self) -> None:
+ """Called in async handlers if the client closed the connection.
+
+ Override this to clean up resources associated with
+ long-lived connections. Note that this method is called only if
+ the connection was closed during asynchronous processing; if you
+ need to do cleanup after every request override `on_finish`
+ instead.
+
+ Proxies may keep a connection open for a time (perhaps
+ indefinitely) after the client has gone away, so this method
+ may not be called promptly after the end user closes their
+ connection.
+ """
+ if _has_stream_request_body(self.__class__):
+ if not self.request._body_future.done():
+ self.request._body_future.set_exception(iostream.StreamClosedError())
+ self.request._body_future.exception()
+
+ def clear(self) -> None:
+ """Resets all headers and content for this response."""
+ self._headers = httputil.HTTPHeaders(
+ {
+ "Server": "TornadoServer/%s" % olTornado.version,
+ "Content-Type": "text/html; charset=UTF-8",
+ "Date": httputil.format_timestamp(time.time()),
+ }
+ )
+ self.set_default_headers()
+ self._write_buffer = [] # type: List[bytes]
+ self._status_code = 200
+ self._reason = httputil.responses[200]
+
+ def set_default_headers(self) -> None:
+ """Override this to set HTTP headers at the beginning of the request.
+
+ For example, this is the place to set a custom ``Server`` header.
+ Note that setting such headers in the normal flow of request
+ processing may not do what you want, since headers may be reset
+ during error handling.
+ """
+ pass
+
+ def set_status(self, status_code: int, reason: Optional[str] = None) -> None:
+ """Sets the status code for our response.
+
+ :arg int status_code: Response status code.
+ :arg str reason: Human-readable reason phrase describing the status
+ code. If ``None``, it will be filled in from
+ `http.client.responses` or "Unknown".
+
+ .. versionchanged:: 5.0
+
+ No longer validates that the response code is in
+ `http.client.responses`.
+ """
+ self._status_code = status_code
+ if reason is not None:
+ self._reason = escape.native_str(reason)
+ else:
+ self._reason = httputil.responses.get(status_code, "Unknown")
+
+ def get_status(self) -> int:
+ """Returns the status code for our response."""
+ return self._status_code
+
+ def set_header(self, name: str, value: _HeaderTypes) -> None:
+ """Sets the given response header name and value.
+
+ All header values are converted to strings (`datetime` objects
+ are formatted according to the HTTP specification for the
+ ``Date`` header).
+
+ """
+ self._headers[name] = self._convert_header_value(value)
+
+ def add_header(self, name: str, value: _HeaderTypes) -> None:
+ """Adds the given response header and value.
+
+ Unlike `set_header`, `add_header` may be called multiple times
+ to return multiple values for the same header.
+ """
+ self._headers.add(name, self._convert_header_value(value))
+
+ def clear_header(self, name: str) -> None:
+ """Clears an outgoing header, undoing a previous `set_header` call.
+
+ Note that this method does not apply to multi-valued headers
+ set by `add_header`.
+ """
+ if name in self._headers:
+ del self._headers[name]
+
+ _INVALID_HEADER_CHAR_RE = re.compile(r"[\x00-\x1f]")
+
+ def _convert_header_value(self, value: _HeaderTypes) -> str:
+ # Convert the input value to a str. This type check is a bit
+ # subtle: The bytes case only executes on python 3, and the
+ # unicode case only executes on python 2, because the other
+ # cases are covered by the first match for str.
+ if isinstance(value, str):
+ retval = value
+ elif isinstance(value, bytes):
+ # Non-ascii characters in headers are not well supported,
+ # but if you pass bytes, use latin1 so they pass through as-is.
+ retval = value.decode("latin1")
+ elif isinstance(value, numbers.Integral):
+ # return immediately since we know the converted value will be safe
+ return str(value)
+ elif isinstance(value, datetime.datetime):
+ return httputil.format_timestamp(value)
+ else:
+ raise TypeError("Unsupported header value %r" % value)
+ # If \n is allowed into the header, it is possible to inject
+ # additional headers or split the request.
+ if RequestHandler._INVALID_HEADER_CHAR_RE.search(retval):
+ raise ValueError("Unsafe header value %r", retval)
+ return retval
+
+ @overload
+ def get_argument(self, name: str, default: str, strip: bool = True) -> str:
+ pass
+
+ @overload
+ def get_argument( # noqa: F811
+ self, name: str, default: _ArgDefaultMarker = _ARG_DEFAULT, strip: bool = True
+ ) -> str:
+ pass
+
+ @overload
+ def get_argument( # noqa: F811
+ self, name: str, default: None, strip: bool = True
+ ) -> Optional[str]:
+ pass
+
+ def get_argument( # noqa: F811
+ self,
+ name: str,
+ default: Union[None, str, _ArgDefaultMarker] = _ARG_DEFAULT,
+ strip: bool = True,
+ ) -> Optional[str]:
+ """Returns the value of the argument with the given name.
+
+ If default is not provided, the argument is considered to be
+ required, and we raise a `MissingArgumentError` if it is missing.
+
+ If the argument appears in the request more than once, we return the
+ last value.
+
+ This method searches both the query and body arguments.
+ """
+ return self._get_argument(name, default, self.request.arguments, strip)
+
+ def get_arguments(self, name: str, strip: bool = True) -> List[str]:
+ """Returns a list of the arguments with the given name.
+
+ If the argument is not present, returns an empty list.
+
+ This method searches both the query and body arguments.
+ """
+
+ # Make sure `get_arguments` isn't accidentally being called with a
+ # positional argument that's assumed to be a default (like in
+ # `get_argument`.)
+ assert isinstance(strip, bool)
+
+ return self._get_arguments(name, self.request.arguments, strip)
+
+ def get_body_argument(
+ self,
+ name: str,
+ default: Union[None, str, _ArgDefaultMarker] = _ARG_DEFAULT,
+ strip: bool = True,
+ ) -> Optional[str]:
+ """Returns the value of the argument with the given name
+ from the request body.
+
+ If default is not provided, the argument is considered to be
+ required, and we raise a `MissingArgumentError` if it is missing.
+
+ If the argument appears in the url more than once, we return the
+ last value.
+
+ .. versionadded:: 3.2
+ """
+ return self._get_argument(name, default, self.request.body_arguments, strip)
+
+ def get_body_arguments(self, name: str, strip: bool = True) -> List[str]:
+ """Returns a list of the body arguments with the given name.
+
+ If the argument is not present, returns an empty list.
+
+ .. versionadded:: 3.2
+ """
+ return self._get_arguments(name, self.request.body_arguments, strip)
+
+ def get_query_argument(
+ self,
+ name: str,
+ default: Union[None, str, _ArgDefaultMarker] = _ARG_DEFAULT,
+ strip: bool = True,
+ ) -> Optional[str]:
+ """Returns the value of the argument with the given name
+ from the request query string.
+
+ If default is not provided, the argument is considered to be
+ required, and we raise a `MissingArgumentError` if it is missing.
+
+ If the argument appears in the url more than once, we return the
+ last value.
+
+ .. versionadded:: 3.2
+ """
+ return self._get_argument(name, default, self.request.query_arguments, strip)
+
+ def get_query_arguments(self, name: str, strip: bool = True) -> List[str]:
+ """Returns a list of the query arguments with the given name.
+
+ If the argument is not present, returns an empty list.
+
+ .. versionadded:: 3.2
+ """
+ return self._get_arguments(name, self.request.query_arguments, strip)
+
+ def _get_argument(
+ self,
+ name: str,
+ default: Union[None, str, _ArgDefaultMarker],
+ source: Dict[str, List[bytes]],
+ strip: bool = True,
+ ) -> Optional[str]:
+ args = self._get_arguments(name, source, strip=strip)
+ if not args:
+ if isinstance(default, _ArgDefaultMarker):
+ raise MissingArgumentError(name)
+ return default
+ return args[-1]
+
+ def _get_arguments(
+ self, name: str, source: Dict[str, List[bytes]], strip: bool = True
+ ) -> List[str]:
+ values = []
+ for v in source.get(name, []):
+ s = self.decode_argument(v, name=name)
+ if isinstance(s, unicode_type):
+ # Get rid of any weird control chars (unless decoding gave
+ # us bytes, in which case leave it alone)
+ s = RequestHandler._remove_control_chars_regex.sub(" ", s)
+ if strip:
+ s = s.strip()
+ values.append(s)
+ return values
+
+ def decode_argument(self, value: bytes, name: Optional[str] = None) -> str:
+ """Decodes an argument from the request.
+
+ The argument has been percent-decoded and is now a byte string.
+ By default, this method decodes the argument as utf-8 and returns
+ a unicode string, but this may be overridden in subclasses.
+
+ This method is used as a filter for both `get_argument()` and for
+ values extracted from the url and passed to `get()`/`post()`/etc.
+
+ The name of the argument is provided if known, but may be None
+ (e.g. for unnamed groups in the url regex).
+ """
+ try:
+ return _unicode(value)
+ except UnicodeDecodeError:
+ raise HTTPError(
+ 400, "Invalid unicode in %s: %r" % (name or "url", value[:40])
+ )
+
+ @property
+ def cookies(self) -> Dict[str, http.cookies.Morsel]:
+ """An alias for
+ `self.request.cookies <.httputil.HTTPServerRequest.cookies>`."""
+ return self.request.cookies
+
+ def get_cookie(self, name: str, default: Optional[str] = None) -> Optional[str]:
+ """Returns the value of the request cookie with the given name.
+
+ If the named cookie is not present, returns ``default``.
+
+ This method only returns cookies that were present in the request.
+ It does not see the outgoing cookies set by `set_cookie` in this
+ handler.
+ """
+ if self.request.cookies is not None and name in self.request.cookies:
+ return self.request.cookies[name].value
+ return default
+
+ def set_cookie(
+ self,
+ name: str,
+ value: Union[str, bytes],
+ domain: Optional[str] = None,
+ expires: Optional[Union[float, Tuple, datetime.datetime]] = None,
+ path: str = "/",
+ expires_days: Optional[float] = None,
+ # Keyword-only args start here for historical reasons.
+ *,
+ max_age: Optional[int] = None,
+ httponly: bool = False,
+ secure: bool = False,
+ samesite: Optional[str] = None,
+ **kwargs: Any,
+ ) -> None:
+ """Sets an outgoing cookie name/value with the given options.
+
+ Newly-set cookies are not immediately visible via `get_cookie`;
+ they are not present until the next request.
+
+ Most arguments are passed directly to `http.cookies.Morsel` directly.
+ See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie
+ for more information.
+
+ ``expires`` may be a numeric timestamp as returned by `time.time`,
+ a time tuple as returned by `time.gmtime`, or a
+ `datetime.datetime` object. ``expires_days`` is provided as a convenience
+ to set an expiration time in days from today (if both are set, ``expires``
+ is used).
+
+ .. deprecated:: 6.3
+ Keyword arguments are currently accepted case-insensitively.
+ In Tornado 7.0 this will be changed to only accept lowercase
+ arguments.
+ """
+ # The cookie library only accepts type str, in both python 2 and 3
+ name = escape.native_str(name)
+ value = escape.native_str(value)
+ if re.search(r"[\x00-\x20]", name + value):
+ # Don't let us accidentally inject bad stuff
+ raise ValueError("Invalid cookie %r: %r" % (name, value))
+ if not hasattr(self, "_new_cookie"):
+ self._new_cookie = (
+ http.cookies.SimpleCookie()
+ ) # type: http.cookies.SimpleCookie
+ if name in self._new_cookie:
+ del self._new_cookie[name]
+ self._new_cookie[name] = value
+ morsel = self._new_cookie[name]
+ if domain:
+ morsel["domain"] = domain
+ if expires_days is not None and not expires:
+ expires = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(
+ days=expires_days
+ )
+ if expires:
+ morsel["expires"] = httputil.format_timestamp(expires)
+ if path:
+ morsel["path"] = path
+ if max_age:
+ # Note change from _ to -.
+ morsel["max-age"] = str(max_age)
+ if httponly:
+ # Note that SimpleCookie ignores the value here. The presense of an
+ # httponly (or secure) key is treated as true.
+ morsel["httponly"] = True
+ if secure:
+ morsel["secure"] = True
+ if samesite:
+ morsel["samesite"] = samesite
+ if kwargs:
+ # The setitem interface is case-insensitive, so continue to support
+ # kwargs for backwards compatibility until we can remove deprecated
+ # features.
+ for k, v in kwargs.items():
+ morsel[k] = v
+ warnings.warn(
+ f"Deprecated arguments to set_cookie: {set(kwargs.keys())} "
+ "(should be lowercase)",
+ DeprecationWarning,
+ )
+
+ def clear_cookie(self, name: str, **kwargs: Any) -> None:
+ """Deletes the cookie with the given name.
+
+ This method accepts the same arguments as `set_cookie`, except for
+ ``expires`` and ``max_age``. Clearing a cookie requires the same
+ ``domain`` and ``path`` arguments as when it was set. In some cases the
+ ``samesite`` and ``secure`` arguments are also required to match. Other
+ arguments are ignored.
+
+ Similar to `set_cookie`, the effect of this method will not be
+ seen until the following request.
+
+ .. versionchanged:: 6.3
+
+ Now accepts all keyword arguments that ``set_cookie`` does.
+ The ``samesite`` and ``secure`` flags have recently become
+ required for clearing ``samesite="none"`` cookies.
+ """
+ for excluded_arg in ["expires", "max_age"]:
+ if excluded_arg in kwargs:
+ raise TypeError(
+ f"clear_cookie() got an unexpected keyword argument '{excluded_arg}'"
+ )
+ expires = datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(
+ days=365
+ )
+ self.set_cookie(name, value="", expires=expires, **kwargs)
+
+ def clear_all_cookies(self, **kwargs: Any) -> None:
+ """Attempt to delete all the cookies the user sent with this request.
+
+ See `clear_cookie` for more information on keyword arguments. Due to
+ limitations of the cookie protocol, it is impossible to determine on the
+ server side which values are necessary for the ``domain``, ``path``,
+ ``samesite``, or ``secure`` arguments, this method can only be
+ successful if you consistently use the same values for these arguments
+ when setting cookies.
+
+ Similar to `set_cookie`, the effect of this method will not be seen
+ until the following request.
+
+ .. versionchanged:: 3.2
+
+ Added the ``path`` and ``domain`` parameters.
+
+ .. versionchanged:: 6.3
+
+ Now accepts all keyword arguments that ``set_cookie`` does.
+
+ .. deprecated:: 6.3
+
+ The increasingly complex rules governing cookies have made it
+ impossible for a ``clear_all_cookies`` method to work reliably
+ since all we know about cookies are their names. Applications
+ should generally use ``clear_cookie`` one at a time instead.
+ """
+ for name in self.request.cookies:
+ self.clear_cookie(name, **kwargs)
+
+ def set_signed_cookie(
+ self,
+ name: str,
+ value: Union[str, bytes],
+ expires_days: Optional[float] = 30,
+ version: Optional[int] = None,
+ **kwargs: Any,
+ ) -> None:
+ """Signs and timestamps a cookie so it cannot be forged.
+
+ You must specify the ``cookie_secret`` setting in your Application
+ to use this method. It should be a long, random sequence of bytes
+ to be used as the HMAC secret for the signature.
+
+ To read a cookie set with this method, use `get_signed_cookie()`.
+
+ Note that the ``expires_days`` parameter sets the lifetime of the
+ cookie in the browser, but is independent of the ``max_age_days``
+ parameter to `get_signed_cookie`.
+ A value of None limits the lifetime to the current browser session.
+
+ Secure cookies may contain arbitrary byte values, not just unicode
+ strings (unlike regular cookies)
+
+ Similar to `set_cookie`, the effect of this method will not be
+ seen until the following request.
+
+ .. versionchanged:: 3.2.1
+
+ Added the ``version`` argument. Introduced cookie version 2
+ and made it the default.
+
+ .. versionchanged:: 6.3
+
+ Renamed from ``set_secure_cookie`` to ``set_signed_cookie`` to
+ avoid confusion with other uses of "secure" in cookie attributes
+ and prefixes. The old name remains as an alias.
+ """
+ self.set_cookie(
+ name,
+ self.create_signed_value(name, value, version=version),
+ expires_days=expires_days,
+ **kwargs,
+ )
+
+ set_secure_cookie = set_signed_cookie
+
+ def create_signed_value(
+ self, name: str, value: Union[str, bytes], version: Optional[int] = None
+ ) -> bytes:
+ """Signs and timestamps a string so it cannot be forged.
+
+ Normally used via set_signed_cookie, but provided as a separate
+ method for non-cookie uses. To decode a value not stored
+ as a cookie use the optional value argument to get_signed_cookie.
+
+ .. versionchanged:: 3.2.1
+
+ Added the ``version`` argument. Introduced cookie version 2
+ and made it the default.
+ """
+ self.require_setting("cookie_secret", "secure cookies")
+ secret = self.application.settings["cookie_secret"]
+ key_version = None
+ if isinstance(secret, dict):
+ if self.application.settings.get("key_version") is None:
+ raise Exception("key_version setting must be used for secret_key dicts")
+ key_version = self.application.settings["key_version"]
+
+ return create_signed_value(
+ secret, name, value, version=version, key_version=key_version
+ )
+
+ def get_signed_cookie(
+ self,
+ name: str,
+ value: Optional[str] = None,
+ max_age_days: float = 31,
+ min_version: Optional[int] = None,
+ ) -> Optional[bytes]:
+ """Returns the given signed cookie if it validates, or None.
+
+ The decoded cookie value is returned as a byte string (unlike
+ `get_cookie`).
+
+ Similar to `get_cookie`, this method only returns cookies that
+ were present in the request. It does not see outgoing cookies set by
+ `set_signed_cookie` in this handler.
+
+ .. versionchanged:: 3.2.1
+
+ Added the ``min_version`` argument. Introduced cookie version 2;
+ both versions 1 and 2 are accepted by default.
+
+ .. versionchanged:: 6.3
+
+ Renamed from ``get_secure_cookie`` to ``get_signed_cookie`` to
+ avoid confusion with other uses of "secure" in cookie attributes
+ and prefixes. The old name remains as an alias.
+
+ """
+ self.require_setting("cookie_secret", "secure cookies")
+ if value is None:
+ value = self.get_cookie(name)
+ return decode_signed_value(
+ self.application.settings["cookie_secret"],
+ name,
+ value,
+ max_age_days=max_age_days,
+ min_version=min_version,
+ )
+
+ get_secure_cookie = get_signed_cookie
+
+ def get_signed_cookie_key_version(
+ self, name: str, value: Optional[str] = None
+ ) -> Optional[int]:
+ """Returns the signing key version of the secure cookie.
+
+ The version is returned as int.
+
+ .. versionchanged:: 6.3
+
+ Renamed from ``get_secure_cookie_key_version`` to
+ ``set_signed_cookie_key_version`` to avoid confusion with other
+ uses of "secure" in cookie attributes and prefixes. The old name
+ remains as an alias.
+
+ """
+ self.require_setting("cookie_secret", "secure cookies")
+ if value is None:
+ value = self.get_cookie(name)
+ if value is None:
+ return None
+ return get_signature_key_version(value)
+
+ get_secure_cookie_key_version = get_signed_cookie_key_version
+
+ def redirect(
+ self, url: str, permanent: bool = False, status: Optional[int] = None
+ ) -> None:
+ """Sends a redirect to the given (optionally relative) URL.
+
+ If the ``status`` argument is specified, that value is used as the
+ HTTP status code; otherwise either 301 (permanent) or 302
+ (temporary) is chosen based on the ``permanent`` argument.
+ The default is 302 (temporary).
+ """
+ if self._headers_written:
+ raise Exception("Cannot redirect after headers have been written")
+ if status is None:
+ status = 301 if permanent else 302
+ else:
+ assert isinstance(status, int) and 300 <= status <= 399
+ self.set_status(status)
+ self.set_header("Location", utf8(url))
+ self.finish()
+
+ def write(self, chunk: Union[str, bytes, dict]) -> None:
+ """Writes the given chunk to the output buffer.
+
+ To write the output to the network, use the `flush()` method below.
+
+ If the given chunk is a dictionary, we write it as JSON and set
+ the Content-Type of the response to be ``application/json``.
+ (if you want to send JSON as a different ``Content-Type``, call
+ ``set_header`` *after* calling ``write()``).
+
+ Note that lists are not converted to JSON because of a potential
+ cross-site security vulnerability. All JSON output should be
+ wrapped in a dictionary. More details at
+ http://haacked.com/archive/2009/06/25/json-hijacking.aspx/ and
+ https://github.com/facebook/tornado/issues/1009
+ """
+ if self._finished:
+ raise RuntimeError("Cannot write() after finish()")
+ if not isinstance(chunk, (bytes, unicode_type, dict)):
+ message = "write() only accepts bytes, unicode, and dict objects"
+ if isinstance(chunk, list):
+ message += (
+ ". Lists not accepted for security reasons; see "
+ + "http://www.tornadoweb.org/en/stable/web.html#olTornado.web.RequestHandler.write" # noqa: E501
+ )
+ raise TypeError(message)
+ if isinstance(chunk, dict):
+ chunk = escape.json_encode(chunk)
+ self.set_header("Content-Type", "application/json; charset=UTF-8")
+ chunk = utf8(chunk)
+ self._write_buffer.append(chunk)
+
+ def render(self, template_name: str, **kwargs: Any) -> "Future[None]":
+ """Renders the template with the given arguments as the response.
+
+ ``render()`` calls ``finish()``, so no other output methods can be called
+ after it.
+
+ Returns a `.Future` with the same semantics as the one returned by `finish`.
+ Awaiting this `.Future` is optional.
+
+ .. versionchanged:: 5.1
+
+ Now returns a `.Future` instead of ``None``.
+ """
+ if self._finished:
+ raise RuntimeError("Cannot render() after finish()")
+ html = self.render_string(template_name, **kwargs)
+
+ # Insert the additional JS and CSS added by the modules on the page
+ js_embed = []
+ js_files = []
+ css_embed = []
+ css_files = []
+ html_heads = []
+ html_bodies = []
+ for module in getattr(self, "_active_modules", {}).values():
+ embed_part = module.embedded_javascript()
+ if embed_part:
+ js_embed.append(utf8(embed_part))
+ file_part = module.javascript_files()
+ if file_part:
+ if isinstance(file_part, (unicode_type, bytes)):
+ js_files.append(_unicode(file_part))
+ else:
+ js_files.extend(file_part)
+ embed_part = module.embedded_css()
+ if embed_part:
+ css_embed.append(utf8(embed_part))
+ file_part = module.css_files()
+ if file_part:
+ if isinstance(file_part, (unicode_type, bytes)):
+ css_files.append(_unicode(file_part))
+ else:
+ css_files.extend(file_part)
+ head_part = module.html_head()
+ if head_part:
+ html_heads.append(utf8(head_part))
+ body_part = module.html_body()
+ if body_part:
+ html_bodies.append(utf8(body_part))
+
+ if js_files:
+ # Maintain order of JavaScript files given by modules
+ js = self.render_linked_js(js_files)
+ sloc = html.rindex(b"