Emrichen – YAML & JSON模板引擎

Emrichen接受用YAML或JSON编写的模板，处理诸如变量替换之类的标签，并输出YAML或JSON。

与基于文本的模板系统相比，Emrichen在生成YAML或JSON方面更出色，因为它可以在YAML（或JSON）内部工作。

是否尝试过将列表或字典替换到YAML文档中，但遇到了缩进问题？太糟糕了！处理引号和双反斜杠转义？不！

在Emrichen中，变量以熟悉的JSON类型输入，这使得这些问题不再成为问题。Emrichen是一种实用且强大的生成YAML和JSON的方法。

考虑以下生成最小Kubernetes部署的模板：

!Defaults
tag: latest
image: !Format "nginx:{tag}"
replicas: 3
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: !Var replicas
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: !Var image
        ports:
        - containerPort: 80

这个小模板已经展示了Emrichen的三个强大标签：提供变量默认值的!Defaults；执行简单变量替换的!Var；以及执行字符串格式化的!Format。

将其放入一个文件中，例如nginx.in.yaml（我们使用.in.yaml表示模板），并使用以下命令渲染它

emrichen nginx.in.yaml

喜欢JSON输出？

emrichen --output-format json nginx.in.yaml

想要更改标签？

emrichen --define tag=1-alpine nginx.in.yaml

注意如何懒惰地评估image – 您不需要覆盖image即可更改tag！

以下表格列出了支持的标签。有很多标签。如果您需要尚未提供的标签，请向我们发送问题或PR。

安装

需要Python 3.6+。Python 2不受支持，也不会受支持。

pip install emrichen

如果您已从GitHub克隆了Emrichen（用于开发）

pip install -e .

支持的标签

JSON中的标签

JSON没有原生的标签构造。相反，使用一个对象，其单键是标签的名称（包括感叹号，例如 !Var）。例如

{
    "foo": {
        "!Var": "foo"
    }
}

JSON支持的局限性

• 以!开头的对象键不受支持。
• 渲染为JSON的模板只能包含单个文档。
  • JSON模板始终只有一个文档。
  • YAML模板只能包含一个非!Void、非!Defaults文档。
• 由于!Defaults必须出现在自己的文档中，因此不支持在JSON模板中。请使用变量文件。

标签组合

由于YAML，您不能执行!Base64 !Var foo。我们提供了一个方便的解决方案：!Base64,Var foo。

自定义标签

您可以在Python中实现自己的自定义标签。标签是继承自emrichen.tags.base.BaseTag类的类，并实现了enrich(self, context: emrichen.context.Context)方法。有关标签实现的示例，请参阅内置标签下的emrichen/tags/或tests/custom_tags/中的示例。

将实现放在一个位于PYTHONPATH的Python模块中。通常，与模板相同的目录就足够了。

只要包含它们的模块被导入，所有BaseTag的子类都会自动注册。如果您正在使用CLI，请将-m your_tags添加到命令行，其中your_tags对应于your_tags.py。如果您以编程方式使用Emrichen，请确保在实例化模板之前导入您的自定义标签（import your_tags)。

以下是一个自定义标签示例，您可以尝试使用以下方法（假设您已从GitHub克隆了Emrichen并使用pip install -e .安装了它）。此示例在从PyPI安装Emrichen时不会安装（pip install emrichen）。

emrichen -m tests.custom_tags examples/custom_tags.yml

此示例定义了一个!KubeEnv自定义标签，它将键值映射字典转换为Kubernetes期望的格式的一组环境变量列表。

CLI

usage: emrichen [-h] [--template-format {yaml,json}] [--var-file VAR_FILE]
usage: emrichen [-h] [--template-format {yaml,json}] [--var-file VAR_FILE]
                [--define VAR=VALUE] [--output-file OUTPUT_FILE]
                [--output-format {yaml,json,pprint}] [--include-env]
                [template_file]

A YAML to YAML preprocessor.

positional arguments:
  template_file         The YAML template to process. If unspecified, the
                        template is read from stdin.

optional arguments:
  -h, --help            show this help message and exit
  --template-format {yaml,json}
                        Template format. If unspecified, attempted to be
                        autodetected from the input filename (but defaults to
                        YAML).
  --var-file VAR_FILE, -f VAR_FILE
                        A YAML file containing an object whose top-level keys
                        will be defined as variables. May be specified
                        multiple times.
  --define VAR=VALUE, -D VAR=VALUE
                        Defines a single variable. May be specified multiple
                        times.
  --output-file OUTPUT_FILE, -o OUTPUT_FILE
                        Output file. If unspecified, the template output is
                        written into stdout.
  --output-format {yaml,json,pprint}
                        Output format. If unspecified, attempted to be
                        autodetected from the output filename (but defaults to
                        YAML).
  --include-env, -e     Expose process environment variables to the template.

Variable precedence: -D > -e > -f > !Defaults

示例

cd examples/kubernetes
emrichen -f vars.yml -D tag=build-256 deployment.in.yml

Python API

待办事项

emrichen(template, *variable_sources, **override_variables)

Context(*variable_sources, **override_variables)

Template(template_source)

许可

The MIT License (MIT)

Copyright © 2018–2022 Santtu Pajukanta
Copyright © 2018–2022 Aarni Koskela

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.