slapos.recipe.template 5.1

md5sum - check file integrity

If the template is specified with the url option, an MD5 checksum can be given to check the contents of the template:

>>> base += """
... md5sum = 1993226f57db37c4a19cb785f826a1aa
... """
>>> write(sample_buildout, 'buildout.cfg', base)
>>> run_buildout()
Uninstalling template.
Installing template.
>>> cat('template.out')
value

In such case, updating the part does nothing:

>>> write('template.out', 'altered')
>>> run_buildout()
Updating template.
>>> cat('template.out')
altered

In case of checksum mismatch:

>>> run_buildout('template:md5sum=00000000000000000000000000000000')
While:
  Installing.
  Getting section template.
  Initializing section template.
Error: MD5 checksum mismatch for local resource at 'template.in'.

inline

You may prefer to inline small templates:

>>> write('buildout.cfg', """
... [buildout]
... parts = template
...
... [section]
... option = inlined
...
... [template]
... recipe = slapos.recipe.template
... inline = ${section:option}
... output = template.out
... """)
>>> run_buildout()
Uninstalling template.
Installing template.
>>> cat('template.out')
inlined

Note that in such case, the rendering is done by buildout itself: it just creates a file with the value of inline.

mode - specify filesystem permissions

By default, executable permissions are set if the content of the output file looks like an executable script, i.e. it has a shebang that points to an executable file. This is done by respecting umask:

>>> import os, stat
>>> os.access('template.out', os.X_OK)
False
>>> run_buildout('section:option=#!/bin/sh')
Uninstalling template.
Installing template.
>>> os.access('template.out', os.X_OK)
True

File permissions can be forced using the mode option in octal representation (no need for 0-prefix):

>>> run_buildout('template:mode=627')
Uninstalling template.
Installing template.
>>> print("0%o" % stat.S_IMODE(os.stat('template.out').st_mode))
0627

md5sum, mode

Same as for the default recipe.

once - avoiding file re-creation

Path of a marker file to prevents rendering altogether.

Normally, each time the section is installed/updated the file gets re-generated. This may be undesirable in some cases.

once allows specifying a marker file, which when present prevents template rendering:

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = template
...
... [template]
... recipe = slapos.recipe.template:jinja2
... inline = dummy
... output = foo_once
... once = foo_flag
... ''')
>>> run_buildout()
Uninstalling template.
Installing template.
The template install returned None.  A path or iterable os paths should be returned.

Template was rendered:

>>> cat('foo_once')
dummy

And canary exists:

>>> import os
>>> os.path.exists('foo_flag')
True

Remove rendered file and re-render:

>>> os.unlink('foo_once')
>>> with open('buildout.cfg', 'a') as f:
...     f.writelines(['extra = useless'])
>>> run_buildout()
Uninstalling template.
Installing template.
The template install returned None.  A path or iterable os paths should be returned.
Unused options for template: 'extra'.

Template was not rendered:

>>> os.path.exists('foo_once')
False

Removing the canary allows template to be re-rendered:

>>> os.unlink('foo_flag')
>>> with open('buildout.cfg', 'a') as f:
...     f.writelines(['moreextra = still useless'])
>>> run_buildout()
Uninstalling template.
Installing template.
The template install returned None.  A path or iterable os paths should be returned.
Unused options for template: 'extra'.
>>> cat('foo_once')
dummy

It’s also possible to use the same file for rendered and once:

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = template
...
... [template]
... recipe = slapos.recipe.template:jinja2
... inline = initial content
... output = rendered
... once = ${:output}
... ''')
>>> run_buildout() # doctest: +ELLIPSIS
Uninstalling template.
Installing template.
The template install returned None.  A path or iterable os paths should be returned.

Template was rendered:

>>> cat('rendered')
initial content

When buildout options are modified, the template will not be rendered again:

>>> with open('buildout.cfg', 'a') as f:
...     f.writelines(['inline = something different'])

>>> run_buildout()
Uninstalling template.
Installing template.
The template install returned None.  A path or iterable os paths should be returned.

Even though we used a different template, the file still contain the first template:

>>> cat('rendered')
initial content

context - template variables and section dependency

Jinja2 context specification, one variable per line, with 3 whitespace-separated parts: type, name and expression. Available types are described below. “name” is the variable name to declare. Expression semantic varies depending on the type.

Available types:

raw

Immediate literal string.

key

Indirect literal string.

import

Import a python module.

section

Make a whole buildout section available to template, as a dictionary.

Indirection targets are specified as: [section]:key . It is possible to use buildout’s buit-in variable replacement instead instead of key type, but keep in mind that different lines are different variables for this recipe. It might be what you want (factorising context chunk declarations), otherwise you should use indirect types.

You can use other part of buildout in the template. This way this parts will be installed as dependency:

>>> write('buildout.cfg', '''
... [buildout]
... parts = template
...
... [template]
... recipe = slapos.recipe.template:jinja2
... inline = {{bar}}
... output = foo
... context = key bar dependency:foobar
...
... [dependency]
... foobar = dependency content
... recipe = zc.buildout:debug
... ''')

>>> run_buildout()
Uninstalling template.
Installing dependency.
  foobar='dependency content'
  recipe='zc.buildout:debug'
Installing template.

This way you can get options which are computed in the __init__ of the dependent recipe.

Let’s create a sample recipe modifying its option dict:

>>> write('setup.py',
... '''
... from setuptools import setup
...
... setup(name='samplerecipe',
...       entry_points = {
...           'zc.buildout': [
...                'default = main:Recipe',
...           ],
...       }
...      )
... ''')
>>> write('main.py',
... '''
... class Recipe(object):
...
...     def __init__(self, buildout, name, options):
...         options['data'] = 'foobar'
...
...     def install(self):
...         return []
... ''')

Let’s just use buildout.cfg using this egg:

>>> write('buildout.cfg',
... '''
... [buildout]
... develop = .
... parts = template
...
... [template]
... recipe = slapos.recipe.template:jinja2
... inline =
...   {{bar}}
... output = foo
... context = key bar sample:data
...
... [sample]
... recipe = samplerecipe
... ''')
>>> run_buildout()
Develop: '/sample-buildout/.'
Uninstalling template.
Uninstalling dependency.
Installing sample.
Installing template.
>>> cat('foo')
foobar

extensions - Jinja2 extensions

Jinja2 extensions to enable when rendering the template, whitespace-separated. By default, none is loaded.

>>> write('foo.in',
... '''{% set foo = ['foo'] -%}
... {% do foo.append(bar) -%}
... {{ foo | join(', ') }}''')
>>> write('buildout.cfg',
... '''
... [buildout]
... develop = .
... parts = template
...
... [template]
... recipe = slapos.recipe.template:jinja2
... url = foo.in
... output = foo
... context = key bar buildout:parts
... # We don't actually use all those extensions in this minimal example.
... extensions = jinja2.ext.do jinja2.ext.loopcontrols
...   jinja2.ext.with_
... ''')
>>> run_buildout()
Develop: '/sample-buildout/.'
Uninstalling template.
Uninstalling sample.
Installing template.

>>> cat('foo')
foo, template

import-delimiter, import-list - template imports

import-delimiter specifies the delimiter character for in-temlate imports. Defaults to /.

import-list is a list of import paths. Format is similar to context. “name” becomes import’s base name. Available types:

rawfile

Literal path of a file.

file

Indirect path of a file.

rawfolder

Literal path of a folder. Any file in such folder can be imported.

folder

Indirect path of a folder. Any file in such folder can be imported.

Here is a simple template importing an equaly-simple library:

>>> write('template.in', '''
... {%- import "library" as library -%}
... {{ library.foo() }}
... ''')
>>> write('library.in', '{% macro foo() %}FOO !{% endmacro %}')

To import a template from rendered template, you need to specify what can be imported:

>>> write('buildout.cfg', '''
... [buildout]
... parts = template
...
... [template]
... recipe = slapos.recipe.template:jinja2
... url = template.in
... output = bar
... import-list = rawfile library library.in
... ''')
>>> run_buildout()
Uninstalling template.
Installing template.
>>> cat('bar')
FOO !

Just like context definition, it also works with indirect values:

>>> write('buildout.cfg', '''
... [buildout]
... parts = template
...
... [template-library]
... path = library.in
...
... [template]
... recipe = slapos.recipe.template:jinja2
... url = template.in
... output = bar
... import-list = file library template-library:path
... ''')
>>> run_buildout()
Uninstalling template.
Installing template.
>>> cat('bar')
FOO !

This also works to allow importing from identically-named files in different directories:

>>> write('template.in', '''
... {%- import "dir_a/1.in" as a1 -%}
... {%- import "dir_a/2.in" as a2 -%}
... {%- import "dir_b/1.in" as b1 -%}
... {%- import "dir_b/c/1.in" as bc1 -%}
... {{ a1.foo() }}
... {{ a2.foo() }}
... {{ b1.foo() }}
... {{ bc1.foo() }}
... ''')
>>> mkdir('a')
>>> mkdir('b')
>>> mkdir(join('b', 'c'))
>>> write(join('a', '1.in'), '{% macro foo() %}a1foo{% endmacro %}')
>>> write(join('a', '2.in'), '{% macro foo() %}a2foo{% endmacro %}')
>>> write(join('b', '1.in'), '{% macro foo() %}b1foo{% endmacro %}')
>>> write(join('b', 'c', '1.in'), '{% macro foo() %}bc1foo{% endmacro %}')

All templates can be accessed inside both folders:

>>> write('buildout.cfg', '''
... [buildout]
... parts = template
...
... [template-library]
... path = library.in
...
... [template]
... recipe = slapos.recipe.template:jinja2
... url = template.in
... output = bar
... import-list =
...     rawfolder dir_a a
...     rawfolder dir_b b
... ''')
>>> run_buildout()
Uninstalling template.
Installing template.
>>> cat('bar')
a1foo
a2foo
b1foo
bc1foo

It is possible to override default path delimiter (without any effect on final path):

>>> write('template.in', r'''
... {%- import "dir_a\\1.in" as a1 -%}
... {%- import "dir_a\\2.in" as a2 -%}
... {%- import "dir_b\\1.in" as b1 -%}
... {%- import "dir_b\\c\\1.in" as bc1 -%}
... {{ a1.foo() }}
... {{ a2.foo() }}
... {{ b1.foo() }}
... {{ bc1.foo() }}
... ''')
>>> write('buildout.cfg', r'''
... [buildout]
... parts = template
...
... [template-library]
... path = library.in
...
... [template]
... recipe = slapos.recipe.template:jinja2
... url = template.in
... output = bar
... import-delimiter = \
... import-list =
...     rawfolder dir_a a
...     rawfolder dir_b b
... ''')
>>> run_buildout()
Uninstalling template.
Installing template.
>>> cat('bar')
a1foo
a2foo
b1foo
bc1foo

update - force rerendering on update

By default, and like the default recipe, nothing is done on update if the template is known in advance to be the same, either because it’s inline or a md5sum is given:

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = template
...
... [template]
... recipe = slapos.recipe.template:jinja2
... inline = {{ os.environ['FOO'] }}
... output = foo
... context = import os os
... ''')
>>> os.environ['FOO'] = '1'
>>> run_buildout()
Uninstalling template.
Installing template.
>>> cat('foo')
1
>>> os.environ['FOO'] = '2'
>>> run_buildout()
Updating template.
>>> cat('foo')
1

But Jinja2 is such that the output may depend on other things than buildout data and it may be wanted to force update in such case:

>>> with open('buildout.cfg', 'a') as f:
...     f.writelines(['update = true'])
>>> run_buildout()
Uninstalling template.
Installing template.
>>> cat('foo')
2
>>> os.environ['FOO'] = '1'
>>> run_buildout()
Updating template.
>>> cat('foo')
1
>>> del os.environ['FOO']

encoding

Encoding for input template and output file. Defaults to utf-8.