Language style guides#

Jinja templating language#

Use dot notation:

{{ pillar.host_id }}
{{ grains.kernel }}

AVOID bracket notation:

{{ pillar['host_id'] }}  # AVOID
{{ grains['kernel'] }}  # AVOID

Note

To allow the use of dot notation in Jinja, prefer underscores to hyphens in Pillar keys.

To test whether a key is present in a mapping, use the in operator:

{% if 'child' in pillar.parent %}

Note

Maintainers can check this style rule with this regular expression:

if .*get\(.(?!(?:autoremove|compilemessages|enabled|public_access|replication|smartmon|summarystats)\b)

To iterate over an optional mapping:

{% for key, value in pillar.mykey|items %}

Or:

{% for key, value in salt['pillar.get']('parent:child', {}).items() %}

Note

Maintainers can check this style rule with this regular expression:

\bif\b.*\n.*%.*\bfor\b

To iterate over an optional list:

{% for value in pillar.mykey|default([]) %}

Or:

{% for value in salt['pillar.get']('parent:child', []) %}

To test whether an optional boolean is true, use the .get() method:

{% if pillar.parent.get('enabled') %}

To get an optional key with a default value:

{{ entry.mykey|default(123) }}

If the default value is the empty string:

{{ entry.mykey|default }}

Note

Maintainers can check this style rule with this regular expression:

(?<!salt\['pillar)\.get\([^\s-]+,

If many parts of a Pillar key might not be set, use salt['pillar.get']():

{{ salt['pillar.get']('parent:child') }}

Note the colon (:) between parent and child.

Capitalize the True and False booleans, for consistency.

If unquoted, yes, no, True and False are parsed as booleans in YAML. Use quotes to parse as strings.
A blank value is parsed as None in YAML. Use the empty string '' to parse as a string.

For example, in the Jinja snippet below, if a is equal to an empty string, then b will be None:

{% set extracontext %}
b: {{ a }}
{% endset %}

Instead, surround it in quotes:

{% set extracontext %}
b: "{{ a }}"
{% endset %}