#######
Engines
#######

`piecutter`'s engines use third-party template engines to generate output using
template and data.

Engines are callables that accept ``template, data`` as input then return
generated output as an iterable file-like object.

.. warning::

   Engines support only single templates. Rendering collections of templates
   involve interactions with loaders. This feature is implemented by
   :doc:`cutters </cutters>` level.


*************
Python format
*************

.. doctest::

   >>> import piecutter
   >>> render = piecutter.PythonFormatEngine()
   >>> output = render(u'Hello {who}!', {u'who': u'world'})
   >>> print(output.read())
   Hello world!


******
Jinja2
******

.. doctest::

   >>> import piecutter
   >>> render = piecutter.Jinja2Engine()
   >>> output = render(u'Hello {{ who }}!', {u'who': u'world'})
   >>> print(output.read())
   Hello world!


******
Django
******

.. doctest::

   >>> import piecutter
   >>> render = piecutter.DjangoEngine()
   >>> output = render(u'Hello {{ who }}!', {u'who': u'world'})
   >>> print(output.read())
   Hello world!


*****
Proxy
*****

This is a special renderer that tries to detect best engine matching template.

.. doctest::

   >>> import piecutter
   >>> render = piecutter.ProxyEngine(
   ...     engines={
   ...         'django': piecutter.DjangoEngine(),
   ...         'jinja2': piecutter.Jinja2Engine(),
   ...         'pythonformat': piecutter.PythonFormatEngine(),
   ...     },
   ... )

   >>> data = {u'who': u'world'}

   >>> template = piecutter.TextTemplate("{# Jinja2 #}Hello {{ who }}!")
   >>> print(render(template, data).read())
   Hello world!

   >>> template = piecutter.TextTemplate("{# Django #}Hello {{ who }}!")
   >>> print(render(template, data).read())
   Hello world!

   >>> template = piecutter.TextTemplate("Hello {who}!")
   >>> print(render(template, data).read())
   Hello world!

.. warning::

   ``piecutter.ProxyEngine`` is experimental and not yet optimized: it loads
   template content in memory in order to guess engine. Better implementations
   or alternatives (such as using template filename's extension) are welcome!


**************
Custom engines
**************

Engines typically are classes that inherit from ``piecutter.Engine``. Feel free
to write your own!

.. autoclass:: piecutter.engines.Engine
   :members:
   :undoc-members:
   :show-inheritance:
   :member-order: bysource