slapos.recipe.template 5.1

md5sum - 检查文件完整性

如果模板通过 url 选项指定，可以提供一个 MD5 校验和来检查模板的内容

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

在这种情况下，更新部分没有任何作用

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

如果校验和不匹配

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

内联

您可能更喜欢内联小模板

>>> 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

请注意，在这种情况下，渲染是由构建扩展本身完成的：它只创建一个包含 inline 值的文件。

mode - 指定文件系统权限

默认情况下，如果输出文件的内容看起来像可执行脚本（即它有一个指向可执行文件的 shebang），则设置可执行权限。这是通过尊重 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

可以使用八进制表示法使用 mode 选项强制设置文件权限（不需要 0 前缀）

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

md5sum, mode

与默认食谱相同。

once - 避免文件重新创建

标记文件的路径，以防止完全渲染。

通常，每次安装/更新部分时，都会重新生成文件。在某些情况下，这可能是不希望的。

once 允许指定一个标记文件，如果存在，则防止模板渲染

>>> 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.

模板已渲染

>>> cat('foo_once')
dummy

存在金丝雀

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

删除渲染文件并重新渲染

>>> 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'.

模板未渲染

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

删除金丝雀允许重新渲染模板

>>> 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

还可以使用相同的文件为 rendered 和 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.

模板已渲染

>>> cat('rendered')
initial content

当构建扩展选项被修改时，模板不会再次渲染

>>> 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.

即使我们使用了不同的模板，文件仍然包含第一个模板

>>> cat('rendered')
initial content

context - 模板变量和部分依赖关系

Jinja2 上下文指定，每行一个变量，用 3 个空格分隔的部分：类型、名称和表达式。下面描述了可用类型。“名称”是要声明的变量名称。表达式的语义根据类型而变化。

可用类型

raw

立即字面字符串。

key

间接字面字符串。

import

导入 Python 模块。

section

使整个构建扩展部分作为字典对模板可用。

间接目标指定为：[章节]:键 . 可以使用 buildout 的内置变量替换，而不是 键 类型，但请注意，对于此配方，不同行代表不同的变量。这可能正是您想要的（分解上下文块声明），否则应使用间接类型。

您可以在模板中使用 buildout 的其他部分。这样，这些部分将被安装为依赖项。

>>> 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.

这样，您可以获取在依赖项配方 __init__ 中计算的选项。

让我们创建一个示例配方，修改其选项字典。

>>> 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 []
... ''')

让我们只使用 buildout.cfg 并使用此 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 扩展

在渲染模板时启用 Jinja2 扩展，以空格分隔。默认情况下，不加载任何扩展。

>>> 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 - 模板导入

import-delimiter 指定了模板导入的分隔符字符。默认为 /。

import-list 是一个导入路径列表。格式类似于 上下文。“名称”成为导入的基本名称。可用类型

rawfile

文件的文本路径。

file

文件的间接路径。

rawfolder

文件夹的文本路径。可以导入此类文件夹中的任何文件。

folder

文件夹的间接路径。可以导入此类文件夹中的任何文件。

这是一个简单的模板，导入了一个同样简单的库

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

要从渲染的模板中导入模板，需要指定可以导入的内容

>>> 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 !

就像上下文定义一样，它也适用于间接值

>>> 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 !

这也允许从不同目录中的同名列文件中导入

>>> 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 %}')

所有模板都可以在两个文件夹中访问

>>> 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

可以覆盖默认路径分隔符（对最终路径没有影响）

>>> 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 - 强制在更新时重新渲染

默认情况下，如果模板在更新之前已知相同，则不会执行任何操作，无论是内联还是提供了 md5sum

>>> 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

但 Jinja2 如此，输出可能取决于构建出数据之外的其他事物，因此可能需要在这种情况下强制更新

>>> 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']

编码

输入模板和输出文件的编码。默认为 utf-8。