Merge ~jocave/plainbox:expose-env-vars-to-jinja2-templates into plainbox:master

[Jonathan Cave]

Allow use of system environment variables in all job fields when using the jinja2 template-engine for templating.

[Jonathan Cave (jocave)]

Modified the "additional features" section to address in which engines those variables are available.

[Sylvain Pineau (sylvain-pineau)]

one last doc fix, see inline. Otherwise looks good. thanks for digging into plainbox internals!

review: Needs Fixing

[Maciej Kisielewski (kissiel)]

Two comments below.

[Jonathan Cave (jocave)]

Applied Maciej's and Sylvain's suggestions.

[Sylvain Pineau (sylvain-pineau)]

+1, thx

review: Approve

diff --git a/docs/manpages/plainbox-template-units.rst b/docs/manpages/plainbox-template-units.rst
index 259862f..a737950 100644
--- a/docs/manpages/plainbox-template-units.rst
+++ b/docs/manpages/plainbox-template-units.rst
@@ -171,7 +171,7 @@ that generates a job for each hard drive available on the system::
    _summary: Check stats changes for each disk
    id: disk/stats
    requires: device.category == 'DISK'
-   _description: 
+   _description:
     This test generates some disk activity and checks the stats to ensure drive
     activity is being recorded properly.
    command:
@@ -206,3 +206,37 @@ After migration to a template unit job, it looks like this::
 The ``template-resource`` used here (``device``) refers to a resource job using the ``udev_resource`` script to get information about the system. The ``udev_resource`` script returns a list of items with attributes such as ``path`` and ``name``, so we can use these directly in our template.
 
 We end up with a shorter (from 19 lines to 11!) and more readable template.
+
+Simple Jinja templates example
+------------------------------
+
+Jinja2 can be used as the templating engine instead of python string formatting. This allows the author to access some powerful templating features including expressions.
+
+First here is the previous disk stats example converted to jinja2::
+
+    unit: template
+    template-resource: device
+    template-filter: device.category == 'DISK'
+    template-engine: jinja2
+    plugin: shell
+    category_id: 2013.com.canonical.plainbox::disk
+    id: disk/stats_{{ name }}
+    requires:
+    device.path == "{{ path }}"
+    block_device.{{ name }}_state != 'removable'
+    user: root
+    command: disk_stats_test {{ name }}
+    _description: This test checks {{ name }} disk stats, generates some activity and rechecks stats to verify they've changed. It also verifies that disks appear in the various files they're supposed to.
+
+Template engine additional features
+-----------------------------------
+
+Plainbox populates the template parameter dictionary with some extra keys to aid the author.
+
+``__index__``:
+    If a template unit can result in N content jobs then this variable is equal to how many jobs have been created so far.
+
+``__system_env__``:
+    When the plainbox encounters a template to render it will populate this variable with the executing shell's enviroment variables as ``os.environ``
+
+    Available for ``template-engine``: ``jinja2``
diff --git a/plainbox/impl/unit/unit.py b/plainbox/impl/unit/unit.py
index 3e740e0..a46e5f5 100644
--- a/plainbox/impl/unit/unit.py
+++ b/plainbox/impl/unit/unit.py
@@ -27,6 +27,7 @@ import collections
 import hashlib
 import json
 import logging
+import os
 import string
 
 from jinja2 import Template
@@ -579,7 +580,14 @@ class Unit(metaclass=UnitType):
             value = self._data.get(name, default)
         if value is not None and self.is_parametric:
             if self.template_engine == 'jinja2':
-                value = Template(value).render(self.parameters)
+                # Add the current system environment variables to the
+                # parameters so that they can be used in all fields (i.e. not
+                # just in the command shell). By adding here rather than in the
+                # template instantiation we avoid problems with creation of
+                # checkpoints
+                tmp_params = self.parameters.copy()
+                tmp_params.update({'__system_env__': os.environ})
+                value = Template(value).render(tmp_params)
             else:
                 value = string.Formatter().vformat(value, (), self.parameters)
         return value