Debian Codegraph @

django/template/base.py

raw
1 """
2 This is the Django template system.
3
4 How it works:
5
6 The Lexer.tokenize() method converts a template string (i.e., a string
7 containing markup with custom template tags) to tokens, which can be either
8 plain text (TokenType.TEXT), variables (TokenType.VAR), or block statements
9 (TokenType.BLOCK).
10
11 The Parser() class takes a list of tokens in its constructor, and its parse()
12 method returns a compiled template -- which is, under the hood, a list of
13 Node objects.
14
15 Each Node is responsible for creating some sort of output -- e.g. simple text
16 (TextNode), variable values in a given context (VariableNode), results of basic
17 logic (IfNode), results of looping (ForNode), or anything else. The core Node
18 types are TextNode, VariableNode, IfNode and ForNode, but plugin modules can
19 define their own custom node types.
20
21 Each Node has a render() method, which takes a Context and returns a string of
22 the rendered node. For example, the render() method of a Variable Node returns
23 the variable's value as a string. The render() method of a ForNode returns the
24 rendered output of whatever was inside the loop, recursively.
25
26 The Template class is a convenient wrapper that takes care of template
27 compilation and rendering.
28
29 Usage:
30
31 The only thing you should ever use directly in this file is the Template class.
32 Create a compiled template object with a template_string, then call render()
33 with a context. In the compilation stage, the TemplateSyntaxError exception
34 will be raised if the template doesn't have proper syntax.
35
36 Sample code:
37
38 >>> from django import template
39 >>> s = '<html>{% if test %}<h1>{{ varvalue }}</h1>{% endif %}</html>'
40 >>> t = template.Template(s)
41
42 (t is now a compiled template, and its render() method can be called multiple
43 times with multiple contexts)
44
45 >>> c = template.Context({'test':True, 'varvalue': 'Hello'})
46 >>> t.render(c)
47 '<html><h1>Hello</h1></html>'
48 >>> c = template.Context({'test':False, 'varvalue': 'Hello'})
49 >>> t.render(c)
50 '<html></html>'
51 """
52
53 import inspect
54 import logging
55 import re
56 from enum import Enum
57
58 from django.template.context import BaseContext
59 from django.utils.formats import localize
60 from django.utils.html import conditional_escape
61 from django.utils.inspect import lazy_annotations, signature
62 from django.utils.regex_helper import _lazy_re_compile
63 from django.utils.safestring import SafeData, SafeString, mark_safe
64 from django.utils.text import get_text_list, smart_split, unescape_string_literal
65 from django.utils.timezone import template_localtime
66 from django.utils.translation import gettext_lazy, pgettext_lazy
67
68 from .exceptions import TemplateSyntaxError
69
70 # template syntax constants
71 FILTER_SEPARATOR = "|"
72 FILTER_ARGUMENT_SEPARATOR = ":"
73 VARIABLE_ATTRIBUTE_SEPARATOR = "."
74 BLOCK_TAG_START = "{%"
75 BLOCK_TAG_END = "%}"
76 VARIABLE_TAG_START = "{{"
77 VARIABLE_TAG_END = "}}"
78 COMMENT_TAG_START = "{#"
79 COMMENT_TAG_END = "#}"
80 SINGLE_BRACE_START = "{"
81 SINGLE_BRACE_END = "}"
82
83 # what to report as the origin for templates that come from non-loader sources
84 # (e.g. strings)
85 UNKNOWN_SOURCE = "<unknown source>"
86
87 # Match BLOCK_TAG_*, VARIABLE_TAG_*, and COMMENT_TAG_* tags and capture the
88 # entire tag, including start/end delimiters. Using re.compile() is faster
89 # than instantiating SimpleLazyObject with _lazy_re_compile().
90 tag_re = re.compile(r"({%.*?%}|{{.*?}}|{#.*?#})")
91
92 logger = logging.getLogger("django.template")
93
94
95 class TokenType(Enum):
96 TEXT = 0
97 VAR = 1
98 BLOCK = 2
99 COMMENT = 3
100
101
102 class VariableDoesNotExist(Exception):
103 def __init__(self, msg, params=()):
104 self.msg = msg
105 self.params = params
106
107 def __str__(self):
108 return self.msg % self.params
109
110
111 class Origin:
112 def __init__(self, name, template_name=None, loader=None):
113 self.name = name
114 self.template_name = template_name
115 self.loader = loader
116
117 def __str__(self):
118 return self.name
119
120 def __repr__(self):
121 return "<%s name=%r>" % (self.__class__.__qualname__, self.name)
122
123 def __eq__(self, other):
124 return (
125 isinstance(other, Origin)
126 and self.name == other.name
127 and self.loader == other.loader
128 )
129
130 @property
131 def loader_name(self):
132 if self.loader:
133 return "%s.%s" % (
134 self.loader.__module__,
135 self.loader.__class__.__name__,
136 )
137
138
139 class Template:
140 def __init__(self, template_string, origin=None, name=None, engine=None):
141 # If Template is instantiated directly rather than from an Engine and
142 # exactly one Django template engine is configured, use that engine.
143 # This is required to preserve backwards-compatibility for direct use
144 # e.g. Template('...').render(Context({...}))
145 if engine is None:
146 from .engine import Engine
147
148 engine = Engine.get_default()
149 if origin is None:
150 origin = Origin(UNKNOWN_SOURCE)
151 self.name = name
152 self.origin = origin
153 self.engine = engine
154 self.source = str(template_string) # May be lazy.
155 self.nodelist = self.compile_nodelist()
156
157 def __repr__(self):
158 return '<%s template_string="%s...">' % (
159 self.__class__.__qualname__,
160 self.source[:20].replace("\n", ""),
161 )
162
163 def _render(self, context):
164 return self.nodelist.render(context)
165
166 def render(self, context):
167 "Display stage -- can be called many times"
168 with context.render_context.push_state(self):
169 if context.template is None:
170 with context.bind_template(self):
171 context.template_name = self.name
172 return self._render(context)
173 else:
174 return self._render(context)
175
176 def compile_nodelist(self):
177 """
178 Parse and compile the template source into a nodelist. If debug
179 is True and an exception occurs during parsing, the exception is
180 annotated with contextual line information where it occurred in the
181 template source.
182 """
183 if self.engine.debug:
184 lexer = DebugLexer(self.source)
185 else:
186 lexer = Lexer(self.source)
187
188 tokens = lexer.tokenize()
189 parser = Parser(
190 tokens,
191 self.engine.template_libraries,
192 self.engine.template_builtins,
193 self.origin,
194 )
195
196 try:
197 nodelist = parser.parse()
198 self.extra_data = parser.extra_data
199 return nodelist
200 except Exception as e:
201 if self.engine.debug:
202 e.template_debug = self.get_exception_info(e, e.token)
203 raise
204
205 def get_exception_info(self, exception, token):
206 """
207 Return a dictionary containing contextual line information of where
208 the exception occurred in the template. The following information is
209 provided:
210
211 message
212 The message of the exception raised.
213
214 source_lines
215 The lines before, after, and including the line the exception
216 occurred on.
217
218 line
219 The line number the exception occurred on.
220
221 before, during, after
222 The line the exception occurred on split into three parts:
223 1. The content before the token that raised the error.
224 2. The token that raised the error.
225 3. The content after the token that raised the error.
226
227 total
228 The number of lines in source_lines.
229
230 top
231 The line number where source_lines starts.
232
233 bottom
234 The line number where source_lines ends.
235
236 start
237 The start position of the token in the template source.
238
239 end
240 The end position of the token in the template source.
241 """
242 start, end = token.position
243 context_lines = 10
244 line = 0
245 upto = 0
246 source_lines = []
247 before = during = after = ""
248 for num, next in enumerate(linebreak_iter(self.source)):
249 if start >= upto and end <= next:
250 line = num
251 before = self.source[upto:start]
252 during = self.source[start:end]
253 after = self.source[end:next]
254 source_lines.append((num, self.source[upto:next]))
255 upto = next
256 total = len(source_lines)
257
258 top = max(1, line - context_lines)
259 bottom = min(total, line + 1 + context_lines)
260
261 # In some rare cases exc_value.args can be empty or an invalid
262 # string.
263 try:
264 message = str(exception.args[0])
265 except (IndexError, UnicodeDecodeError):
266 message = "(Could not get exception message)"
267
268 return {
269 "message": message,
270 "source_lines": source_lines[top:bottom],
271 "before": before,
272 "during": during,
273 "after": after,
274 "top": top,
275 "bottom": bottom,
276 "total": total,
277 "line": line,
278 "name": self.origin.name,
279 "start": start,
280 "end": end,
281 }
282
283
284 def linebreak_iter(template_source):
285 yield 0
286 p = template_source.find("\n")
287 while p >= 0:
288 yield p + 1
289 p = template_source.find("\n", p + 1)
290 yield len(template_source) + 1
291
292
293 class Token:
294 def __init__(self, token_type, contents, position=None, lineno=None):
295 """
296 A token representing a string from the template.
297
298 token_type
299 A TokenType, either .TEXT, .VAR, .BLOCK, or .COMMENT.
300
301 contents
302 The token source string.
303
304 position
305 An optional tuple containing the start and end index of the token
306 in the template source. This is used for traceback information
307 when debug is on.
308
309 lineno
310 The line number the token appears on in the template source.
311 This is used for traceback information and gettext files.
312 """
313 self.token_type = token_type
314 self.contents = contents
315 self.lineno = lineno
316 self.position = position
317
318 def __repr__(self):
319 token_name = self.token_type.name.capitalize()
320 return '<%s token: "%s...">' % (
321 token_name,
322 self.contents[:20].replace("\n", ""),
323 )
324
325 def split_contents(self):
326 split = []
327 bits = smart_split(self.contents)
328 for bit in bits:
329 # Handle translation-marked template pieces
330 if bit.startswith(('_("', "_('")):
331 sentinel = bit[2] + ")"
332 trans_bit = [bit]
333 while not bit.endswith(sentinel):
334 bit = next(bits)
335 trans_bit.append(bit)
336 bit = " ".join(trans_bit)
337 split.append(bit)
338 return split
339
340
341 class Lexer:
342 def __init__(self, template_string):
343 self.template_string = template_string
344 self.verbatim = False
345
346 def __repr__(self):
347 return '<%s template_string="%s...", verbatim=%s>' % (
348 self.__class__.__qualname__,
349 self.template_string[:20].replace("\n", ""),
350 self.verbatim,
351 )
352
353 def tokenize(self):
354 """
355 Return a list of tokens from a given template_string.
356 """
357 in_tag = False
358 lineno = 1
359 result = []
360 for token_string in tag_re.split(self.template_string):
361 if token_string:
362 result.append(self.create_token(token_string, None, lineno, in_tag))
363 lineno += token_string.count("\n")
364 in_tag = not in_tag
365 return result
366
367 def create_token(self, token_string, position, lineno, in_tag):
368 """
369 Convert the given token string into a new Token object and return it.
370 If in_tag is True, we are processing something that matched a tag,
371 otherwise it should be treated as a literal string.
372 """
373 if in_tag:
374 # The [0:2] and [2:-2] ranges below strip off *_TAG_START and
375 # *_TAG_END. The 2's are hard-coded for performance. Using
376 # len(BLOCK_TAG_START) would permit BLOCK_TAG_START to be
377 # different, but it's not likely that the TAG_START values will
378 # change anytime soon.
379 token_start = token_string[0:2]
380 if token_start == BLOCK_TAG_START:
381 content = token_string[2:-2].strip()
382 if self.verbatim:
383 # Then a verbatim block is being processed.
384 if content != self.verbatim:
385 return Token(TokenType.TEXT, token_string, position, lineno)
386 # Otherwise, the current verbatim block is ending.
387 self.verbatim = False
388 elif content[:9] in ("verbatim", "verbatim "):
389 # Then a verbatim block is starting.
390 self.verbatim = "end%s" % content
391 return Token(TokenType.BLOCK, content, position, lineno)
392 if not self.verbatim:
393 content = token_string[2:-2].strip()
394 if token_start == VARIABLE_TAG_START:
395 return Token(TokenType.VAR, content, position, lineno)
396 # BLOCK_TAG_START was handled above.
397 assert token_start == COMMENT_TAG_START
398 return Token(TokenType.COMMENT, content, position, lineno)
399 return Token(TokenType.TEXT, token_string, position, lineno)
400
401
402 class DebugLexer(Lexer):
403 def _tag_re_split_positions(self):
404 last = 0
405 for match in tag_re.finditer(self.template_string):
406 start, end = match.span()
407 yield last, start
408 yield start, end
409 last = end
410 yield last, len(self.template_string)
411
412 # This parallels the use of tag_re.split() in Lexer.tokenize().
413 def _tag_re_split(self):
414 for position in self._tag_re_split_positions():
415 yield self.template_string[slice(*position)], position
416
417 def tokenize(self):
418 """
419 Split a template string into tokens and annotates each token with its
420 start and end position in the source. This is slower than the default
421 lexer so only use it when debug is True.
422 """
423 # For maintainability, it is helpful if the implementation below can
424 # continue to closely parallel Lexer.tokenize()'s implementation.
425 in_tag = False
426 lineno = 1
427 result = []
428 for token_string, position in self._tag_re_split():
429 if token_string:
430 result.append(self.create_token(token_string, position, lineno, in_tag))
431 lineno += token_string.count("\n")
432 in_tag = not in_tag
433 return result
434
435
436 class Parser:
437 def __init__(self, tokens, libraries=None, builtins=None, origin=None):
438 # Reverse the tokens so delete_first_token(), prepend_token(), and
439 # next_token() can operate at the end of the list in constant time.
440 self.tokens = list(reversed(tokens))
441 self.tags = {}
442 self.filters = {}
443 self.command_stack = []
444
445 # Custom template tags may store additional data on the parser that
446 # will be made available on the template instance. Library authors
447 # should use a key to namespace any added data. The 'django' namespace
448 # is reserved for internal use.
449 self.extra_data = {}
450
451 if libraries is None:
452 libraries = {}
453 if builtins is None:
454 builtins = []
455
456 self.libraries = libraries
457 for builtin in builtins:
458 self.add_library(builtin)
459 self.origin = origin
460
461 def __repr__(self):
462 return "<%s tokens=%r>" % (self.__class__.__qualname__, self.tokens)
463
464 def parse(self, parse_until=None):
465 """
466 Iterate through the parser tokens and compiles each one into a node.
467
468 If parse_until is provided, parsing will stop once one of the
469 specified tokens has been reached. This is formatted as a list of
470 tokens, e.g. ['elif', 'else', 'endif']. If no matching token is
471 reached, raise an exception with the unclosed block tag details.
472 """
473 if parse_until is None:
474 parse_until = []
475 nodelist = NodeList()
476 while self.tokens:
477 token = self.next_token()
478 # Use the raw values here for TokenType.* for a tiny performance boost.
479 token_type = token.token_type.value
480 if token_type == 0: # TokenType.TEXT
481 self.extend_nodelist(nodelist, TextNode(token.contents), token)
482 elif token_type == 1: # TokenType.VAR
483 if not token.contents:
484 raise self.error(
485 token, "Empty variable tag on line %d" % token.lineno
486 )
487 try:
488 filter_expression = self.compile_filter(token.contents)
489 except TemplateSyntaxError as e:
490 raise self.error(token, e)
491 var_node = VariableNode(filter_expression)
492 self.extend_nodelist(nodelist, var_node, token)
493 elif token_type == 2: # TokenType.BLOCK
494 try:
495 command = token.contents.split()[0]
496 except IndexError:
497 raise self.error(token, "Empty block tag on line %d" % token.lineno)
498 if command in parse_until:
499 # A matching token has been reached. Return control to
500 # the caller. Put the token back on the token list so the
501 # caller knows where it terminated.
502 self.prepend_token(token)
503 return nodelist
504 # Add the token to the command stack. This is used for error
505 # messages if further parsing fails due to an unclosed block
506 # tag.
507 self.command_stack.append((command, token))
508 # Get the tag callback function from the ones registered with
509 # the parser.
510 try:
511 compile_func = self.tags[command]
512 except KeyError:
513 self.invalid_block_tag(token, command, parse_until)
514 # Compile the callback into a node object and add it to
515 # the node list.
516 try:
517 compiled_result = compile_func(self, token)
518 except Exception as e:
519 raise self.error(token, e)
520 self.extend_nodelist(nodelist, compiled_result, token)
521 # Compile success. Remove the token from the command stack.
522 self.command_stack.pop()
523 if parse_until:
524 self.unclosed_block_tag(parse_until)
525 return nodelist
526
527 def skip_past(self, endtag):
528 while self.tokens:
529 token = self.next_token()
530 if token.token_type == TokenType.BLOCK and token.contents == endtag:
531 return
532 self.unclosed_block_tag([endtag])
533
534 def extend_nodelist(self, nodelist, node, token):
535 # Check that non-text nodes don't appear before an extends tag.
536 if node.must_be_first and nodelist.contains_nontext:
537 if self.origin.template_name:
538 origin = repr(self.origin.template_name)
539 else:
540 origin = "the template"
541 raise self.error(
542 token,
543 "{%% %s %%} must be the first tag in %s." % (token.contents, origin),
544 )
545 if not isinstance(node, TextNode):
546 nodelist.contains_nontext = True
547 # Set origin and token here since we can't modify the node __init__()
548 # method.
549 node.token = token
550 node.origin = self.origin
551 nodelist.append(node)
552
553 def error(self, token, e):
554 """
555 Return an exception annotated with the originating token. Since the
556 parser can be called recursively, check if a token is already set. This
557 ensures the innermost token is highlighted if an exception occurs,
558 e.g. a compile error within the body of an if statement.
559 """
560 if not isinstance(e, Exception):
561 e = TemplateSyntaxError(e)
562 if not hasattr(e, "token"):
563 e.token = token
564 return e
565
566 def invalid_block_tag(self, token, command, parse_until=None):
567 if parse_until:
568 raise self.error(
569 token,
570 "Invalid block tag on line %d: '%s', expected %s. Did you "
571 "forget to register or load this tag?"
572 % (
573 token.lineno,
574 command,
575 get_text_list(["'%s'" % p for p in parse_until], "or"),
576 ),
577 )
578 raise self.error(
579 token,
580 "Invalid block tag on line %d: '%s'. Did you forget to register "
581 "or load this tag?" % (token.lineno, command),
582 )
583
584 def unclosed_block_tag(self, parse_until):
585 command, token = self.command_stack.pop()
586 msg = "Unclosed tag on line %d: '%s'. Looking for one of: %s." % (
587 token.lineno,
588 command,
589 ", ".join(parse_until),
590 )
591 raise self.error(token, msg)
592
593 def next_token(self):
594 return self.tokens.pop()
595
596 def prepend_token(self, token):
597 self.tokens.append(token)
598
599 def delete_first_token(self):
600 del self.tokens[-1]
601
602 def add_library(self, lib):
603 self.tags.update(lib.tags)
604 self.filters.update(lib.filters)
605
606 def compile_filter(self, token):
607 """
608 Convenient wrapper for FilterExpression
609 """
610 return FilterExpression(token, self)
611
612 def find_filter(self, filter_name):
613 if filter_name in self.filters:
614 return self.filters[filter_name]
615 else:
616 raise TemplateSyntaxError("Invalid filter: '%s'" % filter_name)
617
618
619 # This only matches constant *strings* (things in quotes or marked for
620 # translation). Numbers are treated as variables for implementation reasons
621 # (so that they retain their type when passed to filters).
622 constant_string = r"""
623 (?:%(i18n_open)s%(strdq)s%(i18n_close)s|
624 %(i18n_open)s%(strsq)s%(i18n_close)s|
625 %(strdq)s|
626 %(strsq)s)
627 """ % {
628 "strdq": r'"[^"\\]*(?:\\.[^"\\]*)*"', # double-quoted string
629 "strsq": r"'[^'\\]*(?:\\.[^'\\]*)*'", # single-quoted string
630 "i18n_open": re.escape("_("),
631 "i18n_close": re.escape(")"),
632 }
633 constant_string = constant_string.replace("\n", "")
634
635 filter_raw_string = r"""
636 ^(?P<constant>%(constant)s)|
637 ^(?P<var>[%(var_chars)s]+|%(num)s)|
638 (?:\s*%(filter_sep)s\s*
639 (?P<filter_name>\w+)
640 (?:%(arg_sep)s
641 (?:
642 (?P<constant_arg>%(constant)s)|
643 (?P<var_arg>[%(var_chars)s]+|%(num)s)
644 )
645 )?
646 )""" % {
647 "constant": constant_string,
648 "num": r"[-+.]?\d[\d.e]*",
649 "var_chars": r"\w\.",
650 "filter_sep": re.escape(FILTER_SEPARATOR),
651 "arg_sep": re.escape(FILTER_ARGUMENT_SEPARATOR),
652 }
653
654 filter_re = _lazy_re_compile(filter_raw_string, re.VERBOSE)
655
656
657 class FilterExpression:
658 """
659 Parse a variable token and its optional filters (all as a single string),
660 and return a list of tuples of the filter name and arguments.
661 Sample::
662
663 >>> token = 'variable|default:"Default value"|date:"Y-m-d"'
664 >>> p = Parser('')
665 >>> fe = FilterExpression(token, p)
666 >>> len(fe.filters)
667 2
668 >>> fe.var
669 <Variable: 'variable'>
670 """
671
672 __slots__ = ("token", "filters", "var", "is_var")
673
674 def __init__(self, token, parser):
675 self.token = token
676 matches = filter_re.finditer(token)
677 var_obj = None
678 filters = []
679 upto = 0
680 for match in matches:
681 start = match.start()
682 if upto != start:
683 raise TemplateSyntaxError(
684 "Could not parse some characters: "
685 "%s|%s|%s" % (token[:upto], token[upto:start], token[start:])
686 )
687 if var_obj is None:
688 if constant := match["constant"]:
689 try:
690 var_obj = Variable(constant).resolve({})
691 except VariableDoesNotExist:
692 var_obj = None
693 elif (var := match["var"]) is None:
694 raise TemplateSyntaxError(
695 "Could not find variable at start of %s." % token
696 )
697 else:
698 var_obj = Variable(var)
699 else:
700 filter_name = match["filter_name"]
701 args = []
702 if constant_arg := match["constant_arg"]:
703 args.append((False, Variable(constant_arg).resolve({})))
704 elif var_arg := match["var_arg"]:
705 args.append((True, Variable(var_arg)))
706 filter_func = parser.find_filter(filter_name)
707 self.args_check(filter_name, filter_func, args)
708 filters.append((filter_func, args))
709 upto = match.end()
710 if upto != len(token):
711 raise TemplateSyntaxError(
712 "Could not parse the remainder: '%s' "
713 "from '%s'" % (token[upto:], token)
714 )
715
716 self.filters = filters
717 self.var = var_obj
718 self.is_var = isinstance(var_obj, Variable)
719
720 def resolve(self, context, ignore_failures=False):
721 if self.is_var:
722 try:
723 obj = self.var.resolve(context)
724 except VariableDoesNotExist:
725 if ignore_failures:
726 obj = None
727 else:
728 string_if_invalid = context.template.engine.string_if_invalid
729 if string_if_invalid:
730 if "%s" in string_if_invalid:
731 return string_if_invalid % self.var
732 else:
733 return string_if_invalid
734 else:
735 obj = string_if_invalid
736 else:
737 obj = self.var
738 for func, args in self.filters:
739 arg_vals = []
740 for lookup, arg in args:
741 if not lookup:
742 arg_vals.append(mark_safe(arg))
743 else:
744 arg_vals.append(arg.resolve(context))
745 if getattr(func, "expects_localtime", False):
746 obj = template_localtime(obj, context.use_tz)
747 if getattr(func, "needs_autoescape", False):
748 new_obj = func(obj, autoescape=context.autoescape, *arg_vals)
749 else:
750 new_obj = func(obj, *arg_vals)
751 if getattr(func, "is_safe", False) and isinstance(obj, SafeData):
752 obj = mark_safe(new_obj)
753 else:
754 obj = new_obj
755 return obj
756
757 def args_check(name, func, provided):
758 provided = list(provided)
759 # First argument, filter input, is implied.
760 plen = len(provided) + 1
761 # Check to see if a decorator is providing the real function.
762 func = inspect.unwrap(func)
763
764 with lazy_annotations():
765 args, _, _, defaults, _, _, _ = inspect.getfullargspec(func)
766 alen = len(args)
767 dlen = len(defaults or [])
768 # Not enough OR Too many
769 if plen < (alen - dlen) or plen > alen:
770 raise TemplateSyntaxError(
771 "%s requires %d arguments, %d provided" % (name, alen - dlen, plen)
772 )
773
774 return True
775
776 args_check = staticmethod(args_check)
777
778 def __str__(self):
779 return self.token
780
781 def __repr__(self):
782 return "<%s %r>" % (self.__class__.__qualname__, self.token)
783
784
785 class Variable:
786 """
787 A template variable, resolvable against a given context. The variable may
788 be a hard-coded string (if it begins and ends with single or double quote
789 marks)::
790
791 >>> c = {'article': {'section':'News'}}
792 >>> Variable('article.section').resolve(c)
793 'News'
794 >>> Variable('article').resolve(c)
795 {'section': 'News'}
796 >>> class AClass: pass
797 >>> c = AClass()
798 >>> c.article = AClass()
799 >>> c.article.section = 'News'
800
801 (The example assumes VARIABLE_ATTRIBUTE_SEPARATOR is '.')
802 """
803
804 __slots__ = ("var", "literal", "lookups", "translate", "message_context")
805
806 def __init__(self, var):
807 self.var = var
808 self.literal = None
809 self.lookups = None
810 self.translate = False
811 self.message_context = None
812
813 if not isinstance(var, str):
814 raise TypeError("Variable must be a string or number, got %s" % type(var))
815 try:
816 # First try to treat this variable as a number.
817 #
818 # Note that this could cause an OverflowError here that we're not
819 # catching. Since this should only happen at compile time, that's
820 # probably OK.
821
822 # Try to interpret values containing a period or an 'e'/'E'
823 # (possibly scientific notation) as a float; otherwise, try int.
824 if "." in var or "e" in var.lower():
825 self.literal = float(var)
826 # "2." is invalid
827 if var[-1] == ".":
828 raise ValueError
829 else:
830 self.literal = int(var)
831 except ValueError:
832 # A ValueError means that the variable isn't a number.
833 if var[0:2] == "_(" and var[-1] == ")":
834 # The result of the lookup should be translated at rendering
835 # time.
836 self.translate = True
837 var = var[2:-1]
838 # If it's wrapped with quotes (single or double), then
839 # we're also dealing with a literal.
840 try:
841 self.literal = mark_safe(unescape_string_literal(var))
842 except ValueError:
843 # Otherwise we'll set self.lookups so that resolve() knows we're
844 # dealing with a bonafide variable
845 if VARIABLE_ATTRIBUTE_SEPARATOR + "_" in var or var[0] == "_":
846 raise TemplateSyntaxError(
847 "Variables and attributes may "
848 "not begin with underscores: '%s'" % var
849 )
850 self.lookups = tuple(var.split(VARIABLE_ATTRIBUTE_SEPARATOR))
851
852 def resolve(self, context):
853 """Resolve this variable against a given context."""
854 if self.lookups is not None:
855 # We're dealing with a variable that needs to be resolved
856 value = self._resolve_lookup(context)
857 else:
858 # We're dealing with a literal, so it's already been "resolved"
859 value = self.literal
860 if self.translate:
861 is_safe = isinstance(value, SafeData)
862 msgid = value.replace("%", "%%")
863 msgid = mark_safe(msgid) if is_safe else msgid
864 if self.message_context:
865 return pgettext_lazy(self.message_context, msgid)
866 else:
867 return gettext_lazy(msgid)
868 return value
869
870 def __repr__(self):
871 return "<%s: %r>" % (self.__class__.__name__, self.var)
872
873 def __str__(self):
874 return self.var
875
876 def _resolve_lookup(self, context):
877 """
878 Perform resolution of a real variable (i.e. not a literal) against the
879 given context.
880
881 As indicated by the method's name, this method is an implementation
882 detail and shouldn't be called by external code. Use Variable.resolve()
883 instead.
884 """
885 current = context
886 try: # catch-all for silent variable failures
887 for bit in self.lookups:
888 try: # dictionary lookup
889 # Only allow if the metaclass implements __getitem__. See
890 # https://docs.python.org/3/reference/datamodel.html#classgetitem-versus-getitem
891 if not hasattr(type(current), "__getitem__"):
892 raise TypeError
893 current = current[bit]
894 # ValueError/IndexError are for numpy.array lookup on
895 # numpy < 1.9 and 1.9+ respectively
896 except (TypeError, AttributeError, KeyError, ValueError, IndexError):
897 try: # attribute lookup
898 # Don't return class attributes if the class is the context:
899 if isinstance(current, BaseContext) and getattr(
900 type(current), bit
901 ):
902 raise AttributeError
903 current = getattr(current, bit)
904 except (TypeError, AttributeError):
905 # Reraise if the exception was raised by a @property
906 if not isinstance(current, BaseContext) and bit in dir(current):
907 raise
908 try: # list-index lookup
909 current = current[int(bit)]
910 except (
911 IndexError, # list index out of range
912 ValueError, # invalid literal for int()
913 KeyError, # current is a dict without `int(bit)` key
914 TypeError,
915 ): # unsubscriptable object
916 raise VariableDoesNotExist(
917 "Failed lookup for key [%s] in %r",
918 (bit, current),
919 ) # missing attribute
920 if callable(current):
921 if getattr(current, "do_not_call_in_templates", False):
922 pass
923 elif getattr(current, "alters_data", False):
924 current = context.template.engine.string_if_invalid
925 else:
926 try: # method call (assuming no args required)
927 current = current()
928 except TypeError:
929 try:
930 current_signature = signature(current)
931 except ValueError: # No signature found.
932 current = context.template.engine.string_if_invalid
933 else:
934 try:
935 current_signature.bind()
936 except TypeError: # Arguments *were* required.
937 # Invalid method call.
938 current = context.template.engine.string_if_invalid
939 else:
940 raise
941 except Exception as e:
942 template_name = getattr(context, "template_name", None) or "unknown"
943 logger.debug(
944 "Exception while resolving variable '%s' in template '%s'.",
945 bit,
946 template_name,
947 exc_info=True,
948 )
949
950 if getattr(e, "silent_variable_failure", False):
951 current = context.template.engine.string_if_invalid
952 else:
953 raise
954
955 return current
956
957
958 class Node:
959 # Set this to True for nodes that must be first in the template (although
960 # they can be preceded by text nodes.
961 must_be_first = False
962 child_nodelists = ("nodelist",)
963 token = None
964
965 def render(self, context):
966 """
967 Return the node rendered as a string.
968 """
969 pass
970
971 def render_annotated(self, context):
972 """
973 Render the node. If debug is True and an exception occurs during
974 rendering, the exception is annotated with contextual line information
975 where it occurred in the template. For internal usage this method is
976 preferred over using the render method directly.
977 """
978 try:
979 return self.render(context)
980 except Exception as e:
981 if context.template.engine.debug:
982 # Store the actual node that caused the exception.
983 if not hasattr(e, "_culprit_node"):
984 e._culprit_node = self
985 if (
986 not hasattr(e, "template_debug")
987 and context.render_context.template.origin == e._culprit_node.origin
988 ):
989 e.template_debug = (
990 context.render_context.template.get_exception_info(
991 e,
992 e._culprit_node.token,
993 )
994 )
995 raise
996
997 def get_nodes_by_type(self, nodetype):
998 """
999 Return a list of all nodes (within this node and its nodelist)
1000 of the given type
1001 """
1002 nodes = []
1003 if isinstance(self, nodetype):
1004 nodes.append(self)
1005 for attr in self.child_nodelists:
1006 nodelist = getattr(self, attr, None)
1007 if nodelist:
1008 nodes.extend(nodelist.get_nodes_by_type(nodetype))
1009 return nodes
1010
1011
1012 class NodeList(list):
1013 # Set to True the first time a non-TextNode is inserted by
1014 # extend_nodelist().
1015 contains_nontext = False
1016
1017 def render(self, context):
1018 return SafeString("".join([node.render_annotated(context) for node in self]))
1019
1020 def get_nodes_by_type(self, nodetype):
1021 "Return a list of all nodes of the given type"
1022 nodes = []
1023 for node in self:
1024 nodes.extend(node.get_nodes_by_type(nodetype))
1025 return nodes
1026
1027
1028 class TextNode(Node):
1029 child_nodelists = ()
1030
1031 def __init__(self, s):
1032 self.s = s
1033
1034 def __repr__(self):
1035 return "<%s: %r>" % (self.__class__.__name__, self.s[:25])
1036
1037 def render(self, context):
1038 return self.s
1039
1040 def render_annotated(self, context):
1041 """
1042 Return the given value.
1043
1044 The default implementation of this method handles exceptions raised
1045 during rendering, which is not necessary for text nodes.
1046 """
1047 return self.s
1048
1049
1050 def render_value_in_context(value, context):
1051 """
1052 Convert any value to a string to become part of a rendered template. This
1053 means escaping, if required, and conversion to a string. If value is a
1054 string, it's expected to already be translated.
1055 """
1056 value = template_localtime(value, use_tz=context.use_tz)
1057 value = localize(value, use_l10n=context.use_l10n)
1058 if context.autoescape:
1059 if not issubclass(type(value), str):
1060 value = str(value)
1061 return conditional_escape(value)
1062 else:
1063 return str(value)
1064
1065
1066 class VariableNode(Node):
1067 child_nodelists = ()
1068
1069 def __init__(self, filter_expression):
1070 self.filter_expression = filter_expression
1071
1072 def __repr__(self):
1073 return "<Variable Node: %s>" % self.filter_expression
1074
1075 def render(self, context):
1076 try:
1077 output = self.filter_expression.resolve(context)
1078 except UnicodeDecodeError:
1079 # Unicode conversion can fail sometimes for reasons out of our
1080 # control (e.g. exception rendering). In that case, we fail
1081 # quietly.
1082 return ""
1083 return render_value_in_context(output, context)
1084
1085
1086 # Regex for token keyword arguments
1087 kwarg_re = _lazy_re_compile(r"(?:(\w+)=)?(.+)")
1088
1089
1090 def token_kwargs(bits, parser, support_legacy=False):
1091 """
1092 Parse token keyword arguments and return a dictionary of the arguments
1093 retrieved from the ``bits`` token list.
1094
1095 `bits` is a list containing the remainder of the token (split by spaces)
1096 that is to be checked for arguments. Valid arguments are removed from this
1097 list.
1098
1099 `support_legacy` - if True, the legacy format ``1 as foo`` is accepted.
1100 Otherwise, only the standard ``foo=1`` format is allowed.
1101
1102 There is no requirement for all remaining token ``bits`` to be keyword
1103 arguments, so return the dictionary as soon as an invalid argument format
1104 is reached.
1105 """
1106 if not bits:
1107 return {}
1108 match = kwarg_re.match(bits[0])
1109 kwarg_format = match and match[1]
1110 if not kwarg_format:
1111 if not support_legacy:
1112 return {}
1113 if len(bits) < 3 or bits[1] != "as":
1114 return {}
1115
1116 kwargs = {}
1117 while bits:
1118 if kwarg_format:
1119 match = kwarg_re.match(bits[0])
1120 if not match or not match[1]:
1121 return kwargs
1122 key, value = match.groups()
1123 del bits[:1]
1124 else:
1125 if len(bits) < 3 or bits[1] != "as":
1126 return kwargs
1127 key, value = bits[2], bits[0]
1128 del bits[:3]
1129 kwargs[key] = parser.compile_filter(value)
1130 if bits and not kwarg_format:
1131 if bits[0] != "and":
1132 return kwargs
1133 del bits[:1]
1134 return kwargs