template.py 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650
  1. # mako/template.py
  2. # Copyright (C) 2006-2012 the Mako authors and contributors <see AUTHORS file>
  3. #
  4. # This module is part of Mako and is released under
  5. # the MIT License: http://www.opensource.org/licenses/mit-license.php
  6. """Provides the Template class, a facade for parsing, generating and executing
  7. template strings, as well as template runtime operations."""
  8. from mako.lexer import Lexer
  9. from mako import runtime, util, exceptions, codegen, cache
  10. import os, re, shutil, stat, sys, tempfile, types, weakref
  11. class Template(object):
  12. """Represents a compiled template.
  13. :class:`.Template` includes a reference to the original
  14. template source (via the :attr:`.source` attribute)
  15. as well as the source code of the
  16. generated Python module (i.e. the :attr:`.code` attribute),
  17. as well as a reference to an actual Python module.
  18. :class:`.Template` is constructed using either a literal string
  19. representing the template text, or a filename representing a filesystem
  20. path to a source file.
  21. :param text: textual template source. This argument is mutually
  22. exclusive versus the ``filename`` parameter.
  23. :param filename: filename of the source template. This argument is
  24. mutually exclusive versus the ``text`` parameter.
  25. :param buffer_filters: string list of filters to be applied
  26. to the output of ``%def``\ s which are buffered, cached, or otherwise
  27. filtered, after all filters
  28. defined with the ``%def`` itself have been applied. Allows the
  29. creation of default expression filters that let the output
  30. of return-valued ``%def``\ s "opt out" of that filtering via
  31. passing special attributes or objects.
  32. :param bytestring_passthrough: When ``True``, and ``output_encoding`` is
  33. set to ``None``, and :meth:`.Template.render` is used to render,
  34. the `StringIO` or `cStringIO` buffer will be used instead of the
  35. default "fast" buffer. This allows raw bytestrings in the
  36. output stream, such as in expressions, to pass straight
  37. through to the buffer. This flag is forced
  38. to ``True`` if ``disable_unicode`` is also configured.
  39. .. versionadded:: 0.4
  40. Added to provide the same behavior as that of the previous series.
  41. :param cache_args: Dictionary of cache configuration arguments that
  42. will be passed to the :class:`.CacheImpl`. See :ref:`caching_toplevel`.
  43. :param cache_dir:
  44. .. deprecated:: 0.6
  45. Use the ``'dir'`` argument in the ``cache_args`` dictionary.
  46. See :ref:`caching_toplevel`.
  47. :param cache_enabled: Boolean flag which enables caching of this
  48. template. See :ref:`caching_toplevel`.
  49. :param cache_impl: String name of a :class:`.CacheImpl` caching
  50. implementation to use. Defaults to ``'beaker'``.
  51. :param cache_type:
  52. .. deprecated:: 0.6
  53. Use the ``'type'`` argument in the ``cache_args`` dictionary.
  54. See :ref:`caching_toplevel`.
  55. :param cache_url:
  56. .. deprecated:: 0.6
  57. Use the ``'url'`` argument in the ``cache_args`` dictionary.
  58. See :ref:`caching_toplevel`.
  59. :param default_filters: List of string filter names that will
  60. be applied to all expressions. See :ref:`filtering_default_filters`.
  61. :param disable_unicode: Disables all awareness of Python Unicode
  62. objects. See :ref:`unicode_disabled`.
  63. :param enable_loop: When ``True``, enable the ``loop`` context variable.
  64. This can be set to ``False`` to support templates that may
  65. be making usage of the name "``loop``". Individual templates can
  66. re-enable the "loop" context by placing the directive
  67. ``enable_loop="True"`` inside the ``<%page>`` tag -- see
  68. :ref:`migrating_loop`.
  69. :param encoding_errors: Error parameter passed to ``encode()`` when
  70. string encoding is performed. See :ref:`usage_unicode`.
  71. :param error_handler: Python callable which is called whenever
  72. compile or runtime exceptions occur. The callable is passed
  73. the current context as well as the exception. If the
  74. callable returns ``True``, the exception is considered to
  75. be handled, else it is re-raised after the function
  76. completes. Is used to provide custom error-rendering
  77. functions.
  78. :param format_exceptions: if ``True``, exceptions which occur during
  79. the render phase of this template will be caught and
  80. formatted into an HTML error page, which then becomes the
  81. rendered result of the :meth:`.render` call. Otherwise,
  82. runtime exceptions are propagated outwards.
  83. :param imports: String list of Python statements, typically individual
  84. "import" lines, which will be placed into the module level
  85. preamble of all generated Python modules. See the example
  86. in :ref:`filtering_default_filters`.
  87. :param input_encoding: Encoding of the template's source code. Can
  88. be used in lieu of the coding comment. See
  89. :ref:`usage_unicode` as well as :ref:`unicode_toplevel` for
  90. details on source encoding.
  91. :param lookup: a :class:`.TemplateLookup` instance that will be used
  92. for all file lookups via the ``<%namespace>``,
  93. ``<%include>``, and ``<%inherit>`` tags. See
  94. :ref:`usage_templatelookup`.
  95. :param module_directory: Filesystem location where generated
  96. Python module files will be placed.
  97. :param module_filename: Overrides the filename of the generated
  98. Python module file. For advanced usage only.
  99. :param module_writer: A callable which overrides how the Python
  100. module is written entirely. The callable is passed the
  101. encoded source content of the module and the destination
  102. path to be written to. The default behavior of module writing
  103. uses a tempfile in conjunction with a file move in order
  104. to make the operation atomic. So a user-defined module
  105. writing function that mimics the default behavior would be:
  106. .. sourcecode:: python
  107. import tempfile
  108. import os
  109. import shutil
  110. def module_writer(source, outputpath):
  111. (dest, name) = \\
  112. tempfile.mkstemp(
  113. dir=os.path.dirname(outputpath)
  114. )
  115. os.write(dest, source)
  116. os.close(dest)
  117. shutil.move(name, outputpath)
  118. from mako.template import Template
  119. mytemplate = Template(
  120. file="index.html",
  121. module_directory="/path/to/modules",
  122. module_writer=module_writer
  123. )
  124. The function is provided for unusual configurations where
  125. certain platform-specific permissions or other special
  126. steps are needed.
  127. :param output_encoding: The encoding to use when :meth:`.render`
  128. is called.
  129. See :ref:`usage_unicode` as well as :ref:`unicode_toplevel`.
  130. :param preprocessor: Python callable which will be passed
  131. the full template source before it is parsed. The return
  132. result of the callable will be used as the template source
  133. code.
  134. :param strict_undefined: Replaces the automatic usage of
  135. ``UNDEFINED`` for any undeclared variables not located in
  136. the :class:`.Context` with an immediate raise of
  137. ``NameError``. The advantage is immediate reporting of
  138. missing variables which include the name.
  139. .. versionadded:: 0.3.6
  140. :param uri: string URI or other identifier for this template.
  141. If not provided, the ``uri`` is generated from the filesystem
  142. path, or from the in-memory identity of a non-file-based
  143. template. The primary usage of the ``uri`` is to provide a key
  144. within :class:`.TemplateLookup`, as well as to generate the
  145. file path of the generated Python module file, if
  146. ``module_directory`` is specified.
  147. """
  148. def __init__(self,
  149. text=None,
  150. filename=None,
  151. uri=None,
  152. format_exceptions=False,
  153. error_handler=None,
  154. lookup=None,
  155. output_encoding=None,
  156. encoding_errors='strict',
  157. module_directory=None,
  158. cache_args=None,
  159. cache_impl='beaker',
  160. cache_enabled=True,
  161. cache_type=None,
  162. cache_dir=None,
  163. cache_url=None,
  164. module_filename=None,
  165. input_encoding=None,
  166. disable_unicode=False,
  167. module_writer=None,
  168. bytestring_passthrough=False,
  169. default_filters=None,
  170. buffer_filters=(),
  171. strict_undefined=False,
  172. imports=None,
  173. enable_loop=True,
  174. preprocessor=None):
  175. if uri:
  176. self.module_id = re.sub(r'\W', "_", uri)
  177. self.uri = uri
  178. elif filename:
  179. self.module_id = re.sub(r'\W', "_", filename)
  180. drive, path = os.path.splitdrive(filename)
  181. path = os.path.normpath(path).replace(os.path.sep, "/")
  182. self.uri = path
  183. else:
  184. self.module_id = "memory:" + hex(id(self))
  185. self.uri = self.module_id
  186. u_norm = self.uri
  187. if u_norm.startswith("/"):
  188. u_norm = u_norm[1:]
  189. u_norm = os.path.normpath(u_norm)
  190. if u_norm.startswith(".."):
  191. raise exceptions.TemplateLookupException(
  192. "Template uri \"%s\" is invalid - "
  193. "it cannot be relative outside "
  194. "of the root path." % self.uri)
  195. self.input_encoding = input_encoding
  196. self.output_encoding = output_encoding
  197. self.encoding_errors = encoding_errors
  198. self.disable_unicode = disable_unicode
  199. self.bytestring_passthrough = bytestring_passthrough or disable_unicode
  200. self.enable_loop = enable_loop
  201. self.strict_undefined = strict_undefined
  202. self.module_writer = module_writer
  203. if util.py3k and disable_unicode:
  204. raise exceptions.UnsupportedError(
  205. "Mako for Python 3 does not "
  206. "support disabling Unicode")
  207. elif output_encoding and disable_unicode:
  208. raise exceptions.UnsupportedError(
  209. "output_encoding must be set to "
  210. "None when disable_unicode is used.")
  211. if default_filters is None:
  212. if util.py3k or self.disable_unicode:
  213. self.default_filters = ['str']
  214. else:
  215. self.default_filters = ['unicode']
  216. else:
  217. self.default_filters = default_filters
  218. self.buffer_filters = buffer_filters
  219. self.imports = imports
  220. self.preprocessor = preprocessor
  221. # if plain text, compile code in memory only
  222. if text is not None:
  223. (code, module) = _compile_text(self, text, filename)
  224. self._code = code
  225. self._source = text
  226. ModuleInfo(module, None, self, filename, code, text)
  227. elif filename is not None:
  228. # if template filename and a module directory, load
  229. # a filesystem-based module file, generating if needed
  230. if module_filename is not None:
  231. path = module_filename
  232. elif module_directory is not None:
  233. path = os.path.abspath(
  234. os.path.join(
  235. os.path.normpath(module_directory),
  236. u_norm + ".py"
  237. )
  238. )
  239. else:
  240. path = None
  241. module = self._compile_from_file(path, filename)
  242. else:
  243. raise exceptions.RuntimeException(
  244. "Template requires text or filename")
  245. self.module = module
  246. self.filename = filename
  247. self.callable_ = self.module.render_body
  248. self.format_exceptions = format_exceptions
  249. self.error_handler = error_handler
  250. self.lookup = lookup
  251. self.module_directory = module_directory
  252. self._setup_cache_args(
  253. cache_impl, cache_enabled, cache_args,
  254. cache_type, cache_dir, cache_url
  255. )
  256. @util.memoized_property
  257. def reserved_names(self):
  258. if self.enable_loop:
  259. return codegen.RESERVED_NAMES
  260. else:
  261. return codegen.RESERVED_NAMES.difference(['loop'])
  262. def _setup_cache_args(self,
  263. cache_impl, cache_enabled, cache_args,
  264. cache_type, cache_dir, cache_url):
  265. self.cache_impl = cache_impl
  266. self.cache_enabled = cache_enabled
  267. if cache_args:
  268. self.cache_args = cache_args
  269. else:
  270. self.cache_args = {}
  271. # transfer deprecated cache_* args
  272. if cache_type:
  273. self.cache_args['type'] = cache_type
  274. if cache_dir:
  275. self.cache_args['dir'] = cache_dir
  276. if cache_url:
  277. self.cache_args['url'] = cache_url
  278. def _compile_from_file(self, path, filename):
  279. if path is not None:
  280. util.verify_directory(os.path.dirname(path))
  281. filemtime = os.stat(filename)[stat.ST_MTIME]
  282. if not os.path.exists(path) or \
  283. os.stat(path)[stat.ST_MTIME] < filemtime:
  284. data = util.read_file(filename)
  285. _compile_module_file(
  286. self,
  287. data,
  288. filename,
  289. path,
  290. self.module_writer)
  291. module = util.load_module(self.module_id, path)
  292. del sys.modules[self.module_id]
  293. if module._magic_number != codegen.MAGIC_NUMBER:
  294. data = util.read_file(filename)
  295. _compile_module_file(
  296. self,
  297. data,
  298. filename,
  299. path,
  300. self.module_writer)
  301. module = util.load_module(self.module_id, path)
  302. del sys.modules[self.module_id]
  303. ModuleInfo(module, path, self, filename, None, None)
  304. else:
  305. # template filename and no module directory, compile code
  306. # in memory
  307. data = util.read_file(filename)
  308. code, module = _compile_text(
  309. self,
  310. data,
  311. filename)
  312. self._source = None
  313. self._code = code
  314. ModuleInfo(module, None, self, filename, code, None)
  315. return module
  316. @property
  317. def source(self):
  318. """Return the template source code for this :class:`.Template`."""
  319. return _get_module_info_from_callable(self.callable_).source
  320. @property
  321. def code(self):
  322. """Return the module source code for this :class:`.Template`."""
  323. return _get_module_info_from_callable(self.callable_).code
  324. @util.memoized_property
  325. def cache(self):
  326. return cache.Cache(self)
  327. @property
  328. def cache_dir(self):
  329. return self.cache_args['dir']
  330. @property
  331. def cache_url(self):
  332. return self.cache_args['url']
  333. @property
  334. def cache_type(self):
  335. return self.cache_args['type']
  336. def render(self, *args, **data):
  337. """Render the output of this template as a string.
  338. If the template specifies an output encoding, the string
  339. will be encoded accordingly, else the output is raw (raw
  340. output uses `cStringIO` and can't handle multibyte
  341. characters). A :class:`.Context` object is created corresponding
  342. to the given data. Arguments that are explicitly declared
  343. by this template's internal rendering method are also
  344. pulled from the given ``*args``, ``**data`` members.
  345. """
  346. return runtime._render(self, self.callable_, args, data)
  347. def render_unicode(self, *args, **data):
  348. """Render the output of this template as a unicode object."""
  349. return runtime._render(self,
  350. self.callable_,
  351. args,
  352. data,
  353. as_unicode=True)
  354. def render_context(self, context, *args, **kwargs):
  355. """Render this :class:`.Template` with the given context.
  356. The data is written to the context's buffer.
  357. """
  358. if getattr(context, '_with_template', None) is None:
  359. context._set_with_template(self)
  360. runtime._render_context(self,
  361. self.callable_,
  362. context,
  363. *args,
  364. **kwargs)
  365. def has_def(self, name):
  366. return hasattr(self.module, "render_%s" % name)
  367. def get_def(self, name):
  368. """Return a def of this template as a :class:`.DefTemplate`."""
  369. return DefTemplate(self, getattr(self.module, "render_%s" % name))
  370. def _get_def_callable(self, name):
  371. return getattr(self.module, "render_%s" % name)
  372. @property
  373. def last_modified(self):
  374. return self.module._modified_time
  375. class ModuleTemplate(Template):
  376. """A Template which is constructed given an existing Python module.
  377. e.g.::
  378. t = Template("this is a template")
  379. f = file("mymodule.py", "w")
  380. f.write(t.code)
  381. f.close()
  382. import mymodule
  383. t = ModuleTemplate(mymodule)
  384. print t.render()
  385. """
  386. def __init__(self, module,
  387. module_filename=None,
  388. template=None,
  389. template_filename=None,
  390. module_source=None,
  391. template_source=None,
  392. output_encoding=None,
  393. encoding_errors='strict',
  394. disable_unicode=False,
  395. bytestring_passthrough=False,
  396. format_exceptions=False,
  397. error_handler=None,
  398. lookup=None,
  399. cache_args=None,
  400. cache_impl='beaker',
  401. cache_enabled=True,
  402. cache_type=None,
  403. cache_dir=None,
  404. cache_url=None,
  405. ):
  406. self.module_id = re.sub(r'\W', "_", module._template_uri)
  407. self.uri = module._template_uri
  408. self.input_encoding = module._source_encoding
  409. self.output_encoding = output_encoding
  410. self.encoding_errors = encoding_errors
  411. self.disable_unicode = disable_unicode
  412. self.bytestring_passthrough = bytestring_passthrough or disable_unicode
  413. self.enable_loop = module._enable_loop
  414. if util.py3k and disable_unicode:
  415. raise exceptions.UnsupportedError(
  416. "Mako for Python 3 does not "
  417. "support disabling Unicode")
  418. elif output_encoding and disable_unicode:
  419. raise exceptions.UnsupportedError(
  420. "output_encoding must be set to "
  421. "None when disable_unicode is used.")
  422. self.module = module
  423. self.filename = template_filename
  424. ModuleInfo(module,
  425. module_filename,
  426. self,
  427. template_filename,
  428. module_source,
  429. template_source)
  430. self.callable_ = self.module.render_body
  431. self.format_exceptions = format_exceptions
  432. self.error_handler = error_handler
  433. self.lookup = lookup
  434. self._setup_cache_args(
  435. cache_impl, cache_enabled, cache_args,
  436. cache_type, cache_dir, cache_url
  437. )
  438. class DefTemplate(Template):
  439. """A :class:`.Template` which represents a callable def in a parent
  440. template."""
  441. def __init__(self, parent, callable_):
  442. self.parent = parent
  443. self.callable_ = callable_
  444. self.output_encoding = parent.output_encoding
  445. self.module = parent.module
  446. self.encoding_errors = parent.encoding_errors
  447. self.format_exceptions = parent.format_exceptions
  448. self.error_handler = parent.error_handler
  449. self.enable_loop = parent.enable_loop
  450. self.lookup = parent.lookup
  451. self.bytestring_passthrough = parent.bytestring_passthrough
  452. def get_def(self, name):
  453. return self.parent.get_def(name)
  454. class ModuleInfo(object):
  455. """Stores information about a module currently loaded into
  456. memory, provides reverse lookups of template source, module
  457. source code based on a module's identifier.
  458. """
  459. _modules = weakref.WeakValueDictionary()
  460. def __init__(self,
  461. module,
  462. module_filename,
  463. template,
  464. template_filename,
  465. module_source,
  466. template_source):
  467. self.module = module
  468. self.module_filename = module_filename
  469. self.template_filename = template_filename
  470. self.module_source = module_source
  471. self.template_source = template_source
  472. self._modules[module.__name__] = template._mmarker = self
  473. if module_filename:
  474. self._modules[module_filename] = self
  475. @property
  476. def code(self):
  477. if self.module_source is not None:
  478. return self.module_source
  479. else:
  480. return util.read_file(self.module_filename)
  481. @property
  482. def source(self):
  483. if self.template_source is not None:
  484. if self.module._source_encoding and \
  485. not isinstance(self.template_source, unicode):
  486. return self.template_source.decode(
  487. self.module._source_encoding)
  488. else:
  489. return self.template_source
  490. else:
  491. data = util.read_file(self.template_filename)
  492. if self.module._source_encoding:
  493. return data.decode(self.module._source_encoding)
  494. else:
  495. return data
  496. def _compile(template, text, filename, generate_magic_comment):
  497. lexer = Lexer(text,
  498. filename,
  499. disable_unicode=template.disable_unicode,
  500. input_encoding=template.input_encoding,
  501. preprocessor=template.preprocessor)
  502. node = lexer.parse()
  503. source = codegen.compile(node,
  504. template.uri,
  505. filename,
  506. default_filters=template.default_filters,
  507. buffer_filters=template.buffer_filters,
  508. imports=template.imports,
  509. source_encoding=lexer.encoding,
  510. generate_magic_comment=generate_magic_comment,
  511. disable_unicode=template.disable_unicode,
  512. strict_undefined=template.strict_undefined,
  513. enable_loop=template.enable_loop,
  514. reserved_names=template.reserved_names)
  515. return source, lexer
  516. def _compile_text(template, text, filename):
  517. identifier = template.module_id
  518. source, lexer = _compile(template, text, filename,
  519. generate_magic_comment=template.disable_unicode)
  520. cid = identifier
  521. if not util.py3k and isinstance(cid, unicode):
  522. cid = cid.encode()
  523. module = types.ModuleType(cid)
  524. code = compile(source, cid, 'exec')
  525. exec code in module.__dict__, module.__dict__
  526. return (source, module)
  527. def _compile_module_file(template, text, filename, outputpath, module_writer):
  528. identifier = template.module_id
  529. source, lexer = _compile(template, text, filename,
  530. generate_magic_comment=True)
  531. if isinstance(source, unicode):
  532. source = source.encode(lexer.encoding or 'ascii')
  533. if module_writer:
  534. module_writer(source, outputpath)
  535. else:
  536. # make tempfiles in the same location as the ultimate
  537. # location. this ensures they're on the same filesystem,
  538. # avoiding synchronization issues.
  539. (dest, name) = tempfile.mkstemp(dir=os.path.dirname(outputpath))
  540. os.write(dest, source)
  541. os.close(dest)
  542. shutil.move(name, outputpath)
  543. def _get_module_info_from_callable(callable_):
  544. return _get_module_info(callable_.func_globals['__name__'])
  545. def _get_module_info(filename):
  546. return ModuleInfo._modules[filename]