Jinja Filters - Nautobot Design Builder Documentation

Skip to content

# Jinja Filters

## `nautobot_design_builder.jinja_filters`

Useful jinja2 filters for designs.

### `ip_network(input_str)`

Jinja2 filter to convert a string to an IPNetwork object.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`input_str` | `str` | String correctly formatted as an IP Address | required

Returns:

Name | Type | Description
--- | --- | ---
`IPNetwork` | `IPNetwork` | object that represents the input string

Source code in `nautobot_design_builder/jinja_filters.py`

    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    @library.filter
    def ip_network(input_str: str) -> IPNetwork:
        """Jinja2 filter to convert a string to an IPNetwork object.

        Args:
            input_str (str): String correctly formatted as an IP Address

        Returns:
            IPNetwork: object that represents the input string
        """
        return IPNetwork(input_str)

### `network_offset(prefix, offset)`

Jinja2 filter to compute an IPNetwork based off of a prefix and offset.

Example

> > > from design_builder.jinja2 import network_offset network_offset("1.1.0.0/16", "0.0.1.1") IPNetwork('1.1.1.1/16')

> > > from design_builder.jinja2 import network_offset network_offset("1.1.0.0/16", "0.0.1.0/24") IPNetwork('1.1.1.0/24')

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`prefix` | `str` | Prefix string in the form x.x.x.x/x | required
`offset` | `str` | Prefix string in the form x.x.x.x/x | required

Returns:

Name | Type | Description
--- | --- | ---
`IPNetwork` | `IPNetwork` | Returns an IPNetwork that is the result of prefix + offset. The
| `IPNetwork` | returned network object's prefix will be set to the longer prefix length
| `IPNetwork` | between the two inputs.

Source code in `nautobot_design_builder/jinja_filters.py`

    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    @library.filter
    def network_offset(prefix: str, offset: str) -> IPNetwork:
        """Jinja2 filter to compute an IPNetwork based off of a prefix and offset.

        Example:
            >>> from design_builder.jinja2 import network_offset
            >>> network_offset("1.1.0.0/16", "0.0.1.1")
            IPNetwork('1.1.1.1/16')

            >>> from design_builder.jinja2 import network_offset
            >>> network_offset("1.1.0.0/16", "0.0.1.0/24")
            IPNetwork('1.1.1.0/24')

        Args:
            prefix (str): Prefix string in the form x.x.x.x/x
            offset (str): Prefix string in the form x.x.x.x/x

        Returns:
            IPNetwork: Returns an IPNetwork that is the result of prefix + offset. The
            returned network object's prefix will be set to the longer prefix length
            between the two inputs.
        """
        try:
            prefix = IPNetwork(prefix)
        except AddrFormatError:
            # pylint: disable=raise-missing-from
            raise AddrFormatError(f"Invalid prefix {prefix}")

        try:
            offset = IPNetwork(offset)
        except AddrFormatError:
            # pylint: disable=raise-missing-from
            raise AddrFormatError(f"Invalid offset {offset}")

        # netaddr overloads the + operator to sum
        # each octet of a pair of addresses. For instance,
        # 1.1.1.1 + 1.2.3.4 = 2.3.4.5
        # The result of the expression is a netaddr.IPAddress
        new_prefix = IPNetwork(prefix.ip + offset.ip)
        if prefix.prefixlen > offset.prefixlen:
            new_prefix.prefixlen = prefix.prefixlen
        else:
            new_prefix.prefixlen = offset.prefixlen
        return new_prefix

### `network_string(network, attr='')`

Jinja2 filter to convert the IPNetwork object to a string.

If an attribute is supplied, first lookup the attribute on the IPNetwork object, then convert the returned value to a string.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`network` | `IPNetwork` | Object to convert to string | required
`attr` | `str` | Optional attribute to retrieve from the IPNetwork prior to converting to a string. Defaults to "". | `''`

Example:

          {{ "1.2.3.4/24" | ip_network | network_string("ip") }}

Returns:

Name | Type | Description
--- | --- | ---
`str` | `str` | Converted object

Source code in `nautobot_design_builder/jinja_filters.py`

    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    @library.filter
    def network_string(network: IPNetwork, attr="") -> str:
        """Jinja2 filter to convert the IPNetwork object to a string.

        If an attribute is supplied, first lookup the attribute on the IPNetwork
        object, then convert the returned value to a string.

        Args:
            network (IPNetwork): Object to convert to string
            attr (str, optional): Optional attribute to retrieve from the IPNetwork prior
                to converting to a string. Defaults to "".

        Example:
        ```jinja
              {{ "1.2.3.4/24" | ip_network | network_string("ip") }}
        ```

        Returns:
            str: Converted object
        """
        if attr:
            return str(getattr(network, attr))

        return str(network)

### `to_json(value)`

Jinja2 filter to render a value to properly formatted JSON.

This method will render a value to proper JSON. If the value is part of a Design Builder render context, then the correct type encoding (dictionary, list, etc) is used. The Nautobot `render_json` method does not handle `UserDict` or `UserList` which are the primary collection types for Design Builder contexts. This implementation will unwrap those types and render the contained data.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`value` | `Any` | The value to be encoded as JSON. | required

Returns:

Name | Type | Description
--- | --- | ---
`str` | `str` | JSON encoded value.

Source code in `nautobot_design_builder/jinja_filters.py`

    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    @library.filter
    def to_json(value: Any) -> str:
        """Jinja2 filter to render a value to properly formatted JSON.

        This method will render a value to proper JSON. If the value is part of a Design
        Builder render context, then the correct type encoding (dictionary, list, etc) is
        used. The Nautobot `render_json` method does not handle `UserDict` or `UserList`
        which are the primary collection types for Design Builder contexts. This implementation
        will unwrap those types and render the contained data.

        Args:
            value (Any): The value to be encoded as JSON.

        Returns:
            str: JSON encoded value.
        """
        return json.dumps(value, default=_json_default)

### `to_yaml(value, **kwargs)`

Jinja2 filter to render a value to properly formatted YAML.

This method will render a value to proper YAML. If the value is part of a Design Builder render context, then the correct type encoding (dictionary, list, etc) is used. The Nautobot `render_yaml` method does not handle `UserDict` or `UserList` which are the primary collection types for Design Builder contexts. This implementation will unwrap those types and render the contained data.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`value` | `Any` | The value to be rendered as YAML. | required
`kwargs` | `Any` | Any additional options to pass to the yaml.dump method. | `{}`

Returns:

Name | Type | Description
--- | --- | ---
`str` | `str` | YAML encoded value.

Source code in `nautobot_design_builder/jinja_filters.py`

    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    @library.filter
    def to_yaml(value: Any, **kwargs) -> str:
        """Jinja2 filter to render a value to properly formatted YAML.

        This method will render a value to proper YAML. If the value is part of a Design
        Builder render context, then the correct type encoding (dictionary, list, etc) is
        used. The Nautobot `render_yaml` method does not handle `UserDict` or `UserList`
        which are the primary collection types for Design Builder contexts. This implementation
        will unwrap those types and render the contained data.

        Args:
            value (Any): The value to be rendered as YAML.
            kwargs (Any): Any additional options to pass to the yaml.dump method.

        Returns:
            str: YAML encoded value.
        """
        default_flow_style = kwargs.pop("default_flow_style", False)

        return yaml.dump(json.loads(to_json(value)), allow_unicode=True, default_flow_style=default_flow_style, **kwargs)