Armin Ronacher | 0553093 | 2008-04-20 13:27:49 +0200 | [diff] [blame] | 1 | # -*- coding: utf-8 -*- |
| 2 | """ |
| 3 | jinja2.ext |
| 4 | ~~~~~~~~~~ |
| 5 | |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 6 | Jinja extensions allow to add custom tags similar to the way django custom |
| 7 | tags work. By default two example extensions exist: an i18n and a cache |
| 8 | extension. |
Armin Ronacher | 0553093 | 2008-04-20 13:27:49 +0200 | [diff] [blame] | 9 | |
| 10 | :copyright: Copyright 2008 by Armin Ronacher. |
| 11 | :license: BSD. |
| 12 | """ |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 13 | from collections import deque |
Armin Ronacher | 0553093 | 2008-04-20 13:27:49 +0200 | [diff] [blame] | 14 | from jinja2 import nodes |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 15 | from jinja2.environment import get_spontaneous_environment |
Armin Ronacher | 2feed1d | 2008-04-26 16:26:52 +0200 | [diff] [blame] | 16 | from jinja2.runtime import Undefined, concat |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 17 | from jinja2.parser import statement_end_tokens |
| 18 | from jinja2.exceptions import TemplateAssertionError |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame^] | 19 | from jinja2.utils import import_string, Markup |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 20 | |
| 21 | |
| 22 | # the only real useful gettext functions for a Jinja template. Note |
| 23 | # that ugettext must be assigned to gettext as Jinja doesn't support |
| 24 | # non unicode strings. |
| 25 | GETTEXT_FUNCTIONS = ('_', 'gettext', 'ngettext') |
Armin Ronacher | 0553093 | 2008-04-20 13:27:49 +0200 | [diff] [blame] | 26 | |
| 27 | |
| 28 | class Extension(object): |
| 29 | """Instances of this class store parser extensions.""" |
| 30 | |
| 31 | #: if this extension parses this is the list of tags it's listening to. |
| 32 | tags = set() |
| 33 | |
| 34 | def __init__(self, environment): |
| 35 | self.environment = environment |
| 36 | |
Armin Ronacher | 0553093 | 2008-04-20 13:27:49 +0200 | [diff] [blame] | 37 | def parse(self, parser): |
| 38 | """Called if one of the tags matched.""" |
| 39 | |
| 40 | |
| 41 | class CacheExtension(Extension): |
Armin Ronacher | 2b60fe5 | 2008-04-21 08:23:59 +0200 | [diff] [blame] | 42 | """An example extension that adds cacheable blocks.""" |
Armin Ronacher | 0553093 | 2008-04-20 13:27:49 +0200 | [diff] [blame] | 43 | tags = set(['cache']) |
| 44 | |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 45 | def __init__(self, environment): |
| 46 | Extension.__init__(self, environment) |
| 47 | def dummy_cache_support(name, timeout=None, caller=None): |
| 48 | if caller is not None: |
| 49 | return caller() |
| 50 | environment.globals['cache_support'] = dummy_cache_support |
| 51 | |
Armin Ronacher | 0553093 | 2008-04-20 13:27:49 +0200 | [diff] [blame] | 52 | def parse(self, parser): |
| 53 | lineno = parser.stream.next().lineno |
| 54 | args = [parser.parse_expression()] |
Armin Ronacher | 4f7d2d5 | 2008-04-22 10:40:26 +0200 | [diff] [blame] | 55 | if parser.stream.current.type is 'comma': |
| 56 | parser.stream.next() |
Armin Ronacher | 0553093 | 2008-04-20 13:27:49 +0200 | [diff] [blame] | 57 | args.append(parser.parse_expression()) |
| 58 | body = parser.parse_statements(('name:endcache',), drop_needle=True) |
| 59 | return nodes.CallBlock( |
Armin Ronacher | 4f7d2d5 | 2008-04-22 10:40:26 +0200 | [diff] [blame] | 60 | nodes.Call(nodes.Name('cache_support', 'load'), args, [], None, None), |
Armin Ronacher | 0553093 | 2008-04-20 13:27:49 +0200 | [diff] [blame] | 61 | [], [], body |
| 62 | ) |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 63 | |
| 64 | |
| 65 | class TransExtension(Extension): |
| 66 | """This extension adds gettext support to Jinja.""" |
| 67 | tags = set(['trans']) |
| 68 | |
| 69 | def __init__(self, environment): |
| 70 | Extension.__init__(self, environment) |
| 71 | environment.globals.update({ |
| 72 | '_': lambda x: x, |
| 73 | 'gettext': lambda x: x, |
| 74 | 'ngettext': lambda s, p, n: (s, p)[n != 1] |
| 75 | }) |
| 76 | |
| 77 | def parse(self, parser): |
| 78 | """Parse a translatable tag.""" |
| 79 | lineno = parser.stream.next().lineno |
| 80 | |
| 81 | # skip colon for python compatibility |
| 82 | if parser.stream.current.type is 'colon': |
| 83 | parser.stream.next() |
| 84 | |
| 85 | # find all the variables referenced. Additionally a variable can be |
| 86 | # defined in the body of the trans block too, but this is checked at |
| 87 | # a later state. |
| 88 | plural_expr = None |
| 89 | variables = {} |
| 90 | while parser.stream.current.type is not 'block_end': |
| 91 | if variables: |
| 92 | parser.stream.expect('comma') |
| 93 | name = parser.stream.expect('name') |
| 94 | if name.value in variables: |
| 95 | raise TemplateAssertionError('translatable variable %r defined ' |
| 96 | 'twice.' % name.value, name.lineno, |
| 97 | parser.filename) |
| 98 | |
| 99 | # expressions |
| 100 | if parser.stream.current.type is 'assign': |
| 101 | parser.stream.next() |
| 102 | variables[name.value] = var = parser.parse_expression() |
| 103 | else: |
| 104 | variables[name.value] = var = nodes.Name(name.value, 'load') |
| 105 | if plural_expr is None: |
| 106 | plural_expr = var |
| 107 | parser.stream.expect('block_end') |
| 108 | |
| 109 | plural = plural_names = None |
| 110 | have_plural = False |
| 111 | referenced = set() |
| 112 | |
| 113 | # now parse until endtrans or pluralize |
| 114 | singular_names, singular = self._parse_block(parser, True) |
| 115 | if singular_names: |
| 116 | referenced.update(singular_names) |
| 117 | if plural_expr is None: |
| 118 | plural_expr = nodes.Name(singular_names[0], 'load') |
| 119 | |
| 120 | # if we have a pluralize block, we parse that too |
| 121 | if parser.stream.current.test('name:pluralize'): |
| 122 | have_plural = True |
| 123 | parser.stream.next() |
| 124 | if parser.stream.current.type is not 'block_end': |
| 125 | plural_expr = parser.parse_expression() |
| 126 | parser.stream.expect('block_end') |
| 127 | plural_names, plural = self._parse_block(parser, False) |
| 128 | parser.stream.next() |
| 129 | referenced.update(plural_names) |
| 130 | else: |
| 131 | parser.stream.next() |
| 132 | |
| 133 | # register free names as simple name expressions |
| 134 | for var in referenced: |
| 135 | if var not in variables: |
| 136 | variables[var] = nodes.Name(var, 'load') |
| 137 | |
| 138 | # no variables referenced? no need to escape |
| 139 | if not referenced: |
| 140 | singular = singular.replace('%%', '%') |
| 141 | if plural: |
| 142 | plural = plural.replace('%%', '%') |
| 143 | |
| 144 | if not have_plural: |
| 145 | plural_expr = None |
| 146 | elif plural_expr is None: |
| 147 | raise TemplateAssertionError('pluralize without variables', |
| 148 | lineno, parser.filename) |
| 149 | |
| 150 | if variables: |
| 151 | variables = nodes.Dict([nodes.Pair(nodes.Const(x, lineno=lineno), y) |
| 152 | for x, y in variables.items()]) |
| 153 | else: |
| 154 | variables = None |
| 155 | |
| 156 | node = self._make_node(singular, plural, variables, plural_expr) |
| 157 | node.set_lineno(lineno) |
| 158 | return node |
| 159 | |
| 160 | def _parse_block(self, parser, allow_pluralize): |
| 161 | """Parse until the next block tag with a given name.""" |
| 162 | referenced = [] |
| 163 | buf = [] |
| 164 | while 1: |
| 165 | if parser.stream.current.type is 'data': |
| 166 | buf.append(parser.stream.current.value.replace('%', '%%')) |
| 167 | parser.stream.next() |
| 168 | elif parser.stream.current.type is 'variable_begin': |
| 169 | parser.stream.next() |
| 170 | name = parser.stream.expect('name').value |
| 171 | referenced.append(name) |
| 172 | buf.append('%%(%s)s' % name) |
| 173 | parser.stream.expect('variable_end') |
| 174 | elif parser.stream.current.type is 'block_begin': |
| 175 | parser.stream.next() |
| 176 | if parser.stream.current.test('name:endtrans'): |
| 177 | break |
| 178 | elif parser.stream.current.test('name:pluralize'): |
| 179 | if allow_pluralize: |
| 180 | break |
| 181 | raise TemplateSyntaxError('a translatable section can ' |
| 182 | 'have only one pluralize ' |
| 183 | 'section', |
| 184 | parser.stream.current.lineno, |
| 185 | parser.filename) |
| 186 | raise TemplateSyntaxError('control structures in translatable' |
| 187 | ' sections are not allowed.', |
| 188 | parser.stream.current.lineno, |
| 189 | parser.filename) |
| 190 | else: |
| 191 | assert False, 'internal parser error' |
| 192 | |
Armin Ronacher | 2feed1d | 2008-04-26 16:26:52 +0200 | [diff] [blame] | 193 | return referenced, concat(buf) |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 194 | |
| 195 | def _make_node(self, singular, plural, variables, plural_expr): |
| 196 | """Generates a useful node from the data provided.""" |
| 197 | # singular only: |
| 198 | if plural_expr is None: |
| 199 | gettext = nodes.Name('gettext', 'load') |
| 200 | node = nodes.Call(gettext, [nodes.Const(singular)], |
| 201 | [], None, None) |
| 202 | if variables: |
| 203 | node = nodes.Mod(node, variables) |
| 204 | |
| 205 | # singular and plural |
| 206 | else: |
| 207 | ngettext = nodes.Name('ngettext', 'load') |
| 208 | node = nodes.Call(ngettext, [ |
| 209 | nodes.Const(singular), |
| 210 | nodes.Const(plural), |
| 211 | plural_expr |
| 212 | ], [], None, None) |
| 213 | if variables: |
| 214 | node = nodes.Mod(node, variables) |
| 215 | return nodes.Output([node]) |
| 216 | |
| 217 | |
| 218 | def extract_from_ast(node, gettext_functions=GETTEXT_FUNCTIONS): |
| 219 | """Extract localizable strings from the given template node. |
| 220 | |
| 221 | For every string found this function yields a ``(lineno, function, |
| 222 | message)`` tuple, where: |
| 223 | |
| 224 | * ``lineno`` is the number of the line on which the string was found, |
| 225 | * ``function`` is the name of the ``gettext`` function used (if the |
| 226 | string was extracted from embedded Python code), and |
| 227 | * ``message`` is the string itself (a ``unicode`` object, or a tuple |
| 228 | of ``unicode`` objects for functions with multiple string arguments). |
| 229 | """ |
| 230 | for node in node.find_all(nodes.Call): |
| 231 | if not isinstance(node.node, nodes.Name) or \ |
| 232 | node.node.name not in gettext_functions: |
| 233 | continue |
| 234 | |
| 235 | strings = [] |
| 236 | for arg in node.args: |
| 237 | if isinstance(arg, nodes.Const) and \ |
| 238 | isinstance(arg.value, basestring): |
| 239 | strings.append(arg.value) |
| 240 | else: |
| 241 | strings.append(None) |
| 242 | |
| 243 | if len(strings) == 1: |
| 244 | strings = strings[0] |
| 245 | else: |
| 246 | strings = tuple(strings) |
| 247 | yield node.lineno, node.node.name, strings |
| 248 | |
| 249 | |
| 250 | def babel_extract(fileobj, keywords, comment_tags, options): |
| 251 | """Babel extraction method for Jinja templates. |
| 252 | |
| 253 | :param fileobj: the file-like object the messages should be extracted from |
| 254 | :param keywords: a list of keywords (i.e. function names) that should be |
| 255 | recognized as translation functions |
| 256 | :param comment_tags: a list of translator tags to search for and include |
| 257 | in the results. (Unused) |
| 258 | :param options: a dictionary of additional options (optional) |
| 259 | :return: an iterator over ``(lineno, funcname, message, comments)`` tuples. |
| 260 | (comments will be empty currently) |
| 261 | """ |
| 262 | encoding = options.get('encoding', 'utf-8') |
| 263 | |
| 264 | have_trans_extension = False |
| 265 | extensions = [] |
| 266 | for extension in options.get('extensions', '').split(','): |
| 267 | extension = extension.strip() |
| 268 | if not extension: |
| 269 | continue |
| 270 | extension = import_string(extension) |
| 271 | if extension is TransExtension: |
| 272 | have_trans_extension = True |
| 273 | extensions.append(extension) |
| 274 | if not have_trans_extension: |
| 275 | extensions.append(TransExtension) |
| 276 | |
| 277 | environment = get_spontaneous_environment( |
| 278 | options.get('block_start_string', '{%'), |
| 279 | options.get('block_end_string', '%}'), |
| 280 | options.get('variable_start_string', '{{'), |
| 281 | options.get('variable_end_string', '}}'), |
| 282 | options.get('comment_start_string', '{#'), |
| 283 | options.get('comment_end_string', '#}'), |
| 284 | options.get('line_statement_prefix') or None, |
| 285 | options.get('trim_blocks', '').lower() in ('1', 'on', 'yes', 'true'), |
| 286 | tuple(extensions), |
| 287 | # fill with defaults so that environments are shared |
| 288 | # with other spontaneus environments. |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame^] | 289 | True, Undefined, None, False |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 290 | ) |
| 291 | |
| 292 | node = environment.parse(fileobj.read().decode(encoding)) |
| 293 | for lineno, func, message in extract_from_ast(node, keywords): |
| 294 | yield lineno, func, message, [] |