AVD Coding Style¶
This page lists guidelines for developing Python code or Jinja2 templates in the AVD context. These rules apply to creating or updating any Python or 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.
Furthermore, the CI Pipeline (& pre-commit) for AVD enforces the following:
- Maximum line length of 160
- Black version 22.8.0
- isort version 5.12.0
- Flake-8 version 4.0.1
- pylint version 2.6.0
Configurations for the above tools can be found in:
Jinja2 Syntax guidelines¶
SYNTAX-1 - Using variables 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
The nested jinja code block shall follow the following rules:
- All J2 statements must be enclosed by one space
- All J2 statements must be indented by four 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 four 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 must be built, use pure J2 logic and 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 lowercase.
-
Example
VAR-2 - Variable name format¶
-
Description
An underscore
_
should be used as a separator for a multi-word variable.
-
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¶
See the menu on the left for Ansible Collection Plugins.
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 a variable exists with a given value¶
-
Description
The test
arista.avd.defined
shall be used to test if a variable is defined and has a specific value.
-
Example
PLUGIN-3 - Default value¶
-
Description
If a default value must be used, the
arista.avd.default
plugin shall be used instead of anif/else
block. The plugin can be used to fallback to different values until one of them is defined and valid.
-
Example