engines Package

engines Package

Template engines.

class diecutter.engines.Engine

Bases: object

Base class for template engines.

Mostly used to document engine API.

Subclasses must implement render():

>>> from diecutter.engines import Engine
>>> engine = Engine()
>>> engine.render('fake-template', {'fake': 1})
... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
Traceback (most recent call last):
  ...
NotImplementedError: Subclasses of "diecutter.engines.Engine" must
implement render() method.

render(template, context)

Return the rendered template against context.

django Module

Django template engine.

class diecutter.engines.django.DjangoEngine

Bases: diecutter.engines.Engine

Django template engine.

render(template, context)

Return the rendered template against context.

filename Module

Template engine specialized to render filenames.

class diecutter.engines.filename.FilenameEngine

Bases: diecutter.engines.Engine

render(template, context)

Return rendered filename template against context.

Warning

Only flat string variables are accepted. Other variables are ignored silently!

jinja Module

Jinja2 template engine.

class diecutter.engines.jinja.Jinja2Engine(environment=None)

Bases: diecutter.engines.Engine

Jinja2 template engine.

register_environment_functions()

Populate self.environment.globals with some global functions.

render(template, context)

Return the rendered template against context.

diecutter.engines.jinja.path_join(*args, **kwargs)

Return args joined as file paths like with os.path.join().

>>> from diecutter.engines.jinja import path_join
>>> path_join('foo', 'bar')
'foo/bar'

Paths are normalized.

>>> path_join('foo', '..', 'bar')
'bar'

You can pass an extra keyword argument ‘target_os’: a value in os.name capabilities.

>>> path_join('foo', 'bar', target_os='posix')
'foo/bar'

Currently, this is using os.path, i.e. the separator and rules for the computer running Jinja2 engine. A NotImplementedError exception will be raised if ‘os’ argument differs from ‘os.name’.

>>> import os
>>> os.name == 'posix'  # Sorry if you are running tests on another OS.
True
>>> path_join('foo', 'bar', target_os='nt')  # Doctest: +ELLIPSIS
Traceback (most recent call last):
  ...
NotImplementedError: Cannot join path with "nt" style. Host OS is "posix".

diecutter.engines.jinja.path_normalize(path, target_os=None)

Normalize path (like os.path.normpath) for given os.

>>> from diecutter.engines.jinja import path_normalize
>>> path_normalize('foo/bar')
'foo/bar'
>>> path_normalize('foo/toto/../bar')
'foo/bar'

Currently, this is using os.path, i.e. the separator and rules for the computer running Jinja2 engine. A NotImplementedError exception will be raised if ‘os’ argument differs from ‘os.name’.

>>> import os
>>> os.name == 'posix'  # Sorry if you are running tests on another OS.
True
>>> path_normalize('foo/bar', target_os='nt')  # Doctest: +ELLIPSIS
Traceback (most recent call last):
  ...
NotImplementedError: Cannot join path with "nt" style. Host OS is "posix".

mock Module

Mock template engine, for use in tests.

class diecutter.engines.mock.MockEngine(render_result=u'RENDER WITH ARGS={args!s} AND KWARGS={kwargs!s}', fail=None)

Bases: diecutter.engines.Engine

Template engine mock.

Typical usage:

>>> from diecutter.engines.mock import MockEngine
>>> mock_result = u'this is expected result'
>>> mock = MockEngine(mock_result)
>>> args = ('arg 1', 'arg 2')
>>> kwargs = {'kwarg1': 'kwarg 1', 'kwarg2': 'kwarg 2'}
>>> mock.render(*args, **kwargs) == mock_result
True
>>> mock.args == args
True
>>> mock.kwargs == kwargs
True

You can use {args} and {kwargs} in mock result, because render() uses self.render_result.format(args=args, kwargs=kwargs). This feature is used by default:

>>> mock = MockEngine()
>>> mock.render_result
u'RENDER WITH ARGS={args!s} AND KWARGS={kwargs!s}'
>>> mock.render()
u'RENDER WITH ARGS=() AND KWARGS={}'

If you setup an exception as fail attribute, then render() will raise that exception.

>>> mock = MockEngine(fail=Exception('An error occured'))
>>> mock.render()  # Doctest: +ELLIPSIS
Traceback (most recent call last):
...
Exception: An error occured

args = None

Stores positional arguments of the last call to render().

fail = None

Whether to raise a TemplateError or not. Also, value used as message in the exception.

kwargs = None

Stores keyword arguments of the last call to render().

render(*args, **kwargs)

Return self.render_result + populates args and kwargs.

If self.fail is not None, then raises a TemplateError(self.fail).

render_result = None

Value to be returned by render().

diecutter.engines.mock.default_render_result = u'RENDER WITH ARGS={args!s} AND KWARGS={kwargs!s}'

Default value used as MockEngine.render_result