jinja2/ext.py

   1 # -*- coding: utf-8 -*-
   2 """
   3     jinja2.ext
   4     ~~~~~~~~~~
   5
   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.
   9
  10     :copyright: Copyright 2008 by Armin Ronacher.
  11     :license: BSD.
  12 """
  13 from collections import deque
  14 from jinja2 import nodes
  15 from jinja2.environment import get_spontaneous_environment
  16 from jinja2.runtime import Undefined, concat
  17 from jinja2.parser import statement_end_tokens
  18 from jinja2.exceptions import TemplateAssertionError, TemplateSyntaxError
  19 from jinja2.utils import import_string, Markup
  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')
  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
  37     def parse(self, parser):
  38         """Called if one of the tags matched."""
  39
  40
  41 class CacheExtension(Extension):
  42     """An example extension that adds cacheable blocks."""
  43     tags = set(['cache'])
  44
  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
  52     def parse(self, parser):
  53         lineno = parser.stream.next().lineno
  54         args = [parser.parse_expression()]
  55         if parser.stream.current.type is 'comma':
  56             parser.stream.next()
  57             args.append(parser.parse_expression())
  58         body = parser.parse_statements(('name:endcache',), drop_needle=True)
  59         return nodes.CallBlock(
  60             nodes.Call(nodes.Name('cache_support', 'load'), args, [], None, None),
  61             [], [], body
  62         )
  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
 193         return referenced, concat(buf)
 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.
 289         True, Undefined, None, False
 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, []