AVD Coding Style¶
This page provides a list of guidelines to apply when developing the Jinja2 template in the AVD context. These rules apply for either creation or update of any Jinja2 file available in a aristanetworks/ansible-avd
repository.
Python code style¶
As AVD is an Ansible collection, we’re required to follow guidelines from the official Ansible documentation for all Python code.
YAML Syntax guidelines¶
SYNTAX-1 - Use variable in Jinja¶
-
Description
A single space shall be added between Jinja2 curly brackets and a variable’s name
-
Example
SYNTAX-2 - Filter syntax¶
-
Description
When variables are used in combination with a filter,
|
shall be enclosed by space
-
Example
SYNTAX-3 - Indentation for statement blocks¶
-
Description
Nested jinja code block shall follow the next rules:
- All J2 statements must be enclosed by 1 space
- All J2 statements must be indented by 4 more spaces within the jinja delimiter
- To close a control, the end tag must have the same indentation level as the opening tag
- Indentation must be 4 spaces and NOT tabulation
-
Example
{# Initial block indentation #} {% if my_variable is arista.avd.defined %} {# Nested block indentation #} {% for ethernet_interface in ethernet_interfaces %} {% if ethernet_interface.name is arista.avd.defined %} {% set result = ethernet_interface.name %} {# ..... output truncated ..... #} {% endif %} {% endfor %}
SYNTAX-4 - Expand list on a single line¶
-
Description
Instead of doing a for loop on a single line, the
join
filter should be leveraged as much as possible
-
Example
SYNTAX-5 - Test if a variable in a list¶
-
Description
To test if a variable is part of a list, the
in
operator should be used as much as possible to avoid longif/elif/else
block.
-
Example
SYNTAX-6 - Render long CLI¶
-
Description
When a long CLI with multiple options needs to be built, use pure J2 logic and then print
-
Example
{% for ip_helper in vlan_interfaces[vlan_interface].ip_helpers | arista.avd.natural_sort %} {% set ip_helper_cli = "ip helper-address " ~ ip_helper %} {% if vlan_interfaces[vlan_interface].ip_helpers[ip_helper].vrf is arista.avd.defined %} {% set ip_helper_cli = ip_helper_cli ~ " vrf " ~ vlan_interfaces[vlan_interface].ip_helpers[ip_helper].vrf %} {% endif %} {% if vlan_interfaces[vlan_interface].ip_helpers[ip_helper].source_interface is arista.avd.defined %} {% set ip_helper_cli = ip_helper_cli ~ " source-interface " ~ vlan_interfaces[vlan_interface].ip_helpers[ip_helper].source_interface %} {% endif %} {{ ip_helper_cli }} {% endfor %}
YAML Variable definition¶
VAR-1 - Variable name case¶
-
Description
All variables shall use lower case
-
Example
VAR-2 - Variable name format¶
-
Description
If a variable is multi-words, underscore
_
shall be used as a separator.
-
Example
VAR-3 - Iterable variables¶
-
Description
For an iterable variable, the plural form shall be used
-
Example
VAR-4 - Variables in a For Loop¶
-
Description
For variables in a for loop, the singular form shall be used
-
Example
VAR-5 - Variables concatenation¶
-
Description
Tilde
~
should be used for string concatenation as it automatically converts variables to a string.
-
Example
VAR-6 - Variable type comparison¶
-
Description
To test the type of a variable, it’s recommended to use
is
/is not
keywords
-
Example
VAR-7 - Variable content comparison¶
-
Description
To test the content of a variable, it’s recommended to use
==
/!=
keywords
-
Example
{# Test if variable is equal to 'Ethernet1' #} {% if ethernet_interface == 'Ethernet1' %} {# Test if variable is not equal to 'Ethernet1' #} {% if ethernet_interface != 'Ethernet1' %}
Info
PLUGIN-2 can do a test if the variable is defined and has a specific value
VAR-8 - String comparison¶
-
Description
All strings should be compared based on lowercase format.
-
Example
AVD Plugins usage¶
Plugins documentation is available here
PLUGIN-1 - Test if a variable exists¶
-
Description
All tests to check if a variable is defined shall be done with
arista.avd.defined
. This test also does a deep test and doesn’t require a test at an upper level.
-
Example
PLUGIN-2 - Test if variable exists with a given value¶
-
Description
To test if a variable is defined and has a specific value, the test
arista.avd.defined
shall be used.
-
Example
PLUGIN-3 - Default value¶
-
Description
If a default value must be used, the
arista.avd.default
plugin shall be used instead of aif/else
block. The plugin can be used to fallback to different values until one of them is defined and valid.
-
Example