Refactor(pyavd): Add AVDTemplar to avoid accessing private Ansible Templar attributes and triggering deprecation (#6658)

gmuloc · ClausHolbechArista · web-flow · commit d1434faebf05 · 2026-03-09T07:26:36.000Z
Co-authored-by: Claus Holbech &lt;holbech@arista.com&gt;
diff --git a/ansible_collections/arista/avd/plugins/action/eos_designs_facts.py b/ansible_collections/arista/avd/plugins/action/eos_designs_facts.py
@@ -14,8 +14,8 @@
 from ansible.parsing.yaml.dumper import AnsibleDumper
 from ansible.plugins.action import ActionBase
 
+from ansible_collections.arista.avd.plugins.plugin_utils.constants import ANSIBLE_ABOVE_2_19
 from ansible_collections.arista.avd.plugins.plugin_utils.utils import (
-    ANSIBLE_ABOVE_2_19,
     AVDFileHandler,
     AVDVaultHandler,
     get_eos_designs_facts_path,
diff --git a/ansible_collections/arista/avd/plugins/action/eos_designs_structured_config.py b/ansible_collections/arista/avd/plugins/action/eos_designs_structured_config.py
@@ -15,8 +15,8 @@
 from ansible.parsing.yaml.dumper import AnsibleDumper
 from ansible.plugins.action import ActionBase
 
+from ansible_collections.arista.avd.plugins.plugin_utils.constants import ANSIBLE_ABOVE_2_19
 from ansible_collections.arista.avd.plugins.plugin_utils.utils import (
-    ANSIBLE_ABOVE_2_19,
     AVDFileHandler,
     AvdSwitchFactsDefaultDict,
     AVDVaultHandler,
@@ -123,6 +123,7 @@ def run(self, tmp: Any = None, task_vars: dict | None = None) -> dict:
                 template = template_item["template"]
 
                 # Here we parse the template, expecting the result to be a YAML formatted string
+                # self.templar is an AVDTemplar instance which already contains loader and searchpath
                 template_result = templater(template, template_vars, self.templar)
 
                 # Skip if template result is None or empty string
diff --git a/ansible_collections/arista/avd/plugins/plugin_utils/constants.py b/ansible_collections/arista/avd/plugins/plugin_utils/constants.py
diff --git a/ansible_collections/arista/avd/plugins/plugin_utils/pyavd_wrappers.py b/ansible_collections/arista/avd/plugins/plugin_utils/pyavd_wrappers.py
@@ -8,10 +8,17 @@
 from typing import TYPE_CHECKING, Any, Literal
 
 from ansible.errors import AnsibleFilterError, AnsibleInternalError, AnsibleUndefinedVariable
-from ansible.module_utils.basic import to_native
 from ansible.utils.display import Display
 from jinja2.exceptions import UndefinedError
 
+from .constants import ANSIBLE_ABOVE_2_19
+
+if ANSIBLE_ABOVE_2_19:
+    from ansible.module_utils.common.text.converters import to_native
+else:
+    # Fallback for ansible-core < 2.19
+    from ansible.module_utils.basic import to_native
+
 if TYPE_CHECKING:
     from collections.abc import Callable
     from typing import NoReturn
diff --git a/ansible_collections/arista/avd/plugins/plugin_utils/utils/__init__.py b/ansible_collections/arista/avd/plugins/plugin_utils/utils/__init__.py
@@ -7,7 +7,6 @@
 from .avd_switch_facts_default_dict import AvdSwitchFactsDefaultDict
 from .avd_vault_handler import AVDVaultHandler
 from .compile_searchpath import compile_searchpath
-from .constants import ANSIBLE_ABOVE_2_19
 from .cprofile_decorator import cprofile
 from .get_templar import get_templar
 from .get_workers import get_workers
@@ -20,7 +19,6 @@
 from .yaml_loader import YamlLoader
 
 __all__ = [
-    "ANSIBLE_ABOVE_2_19",
     "AVDFileHandler",
     "AVDVaultHandler",
     "ActionPluginVars",
diff --git a/ansible_collections/arista/avd/plugins/plugin_utils/utils/action_plugin_vars.py b/ansible_collections/arista/avd/plugins/plugin_utils/utils/action_plugin_vars.py
@@ -7,7 +7,7 @@
 
 from ansible.vars.hostvars import HostVarsVars
 
-from .constants import ANSIBLE_ABOVE_2_19
+from ansible_collections.arista.avd.plugins.plugin_utils.constants import ANSIBLE_ABOVE_2_19
 
 if TYPE_CHECKING:  # pragma: no cover
     from ansible.inventory.manager import InventoryManager
diff --git a/ansible_collections/arista/avd/plugins/plugin_utils/utils/get_templar.py b/ansible_collections/arista/avd/plugins/plugin_utils/utils/get_templar.py
@@ -3,22 +3,39 @@
 # that can be found in the LICENSE file.
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from ansible.plugins.action import ActionBase
-    from ansible.template import Templar
+
+from ansible_collections.arista.avd.plugins.plugin_utils.pyavd_wrappers import RaiseOnUse
 
 from .compile_searchpath import compile_searchpath
 
+if TYPE_CHECKING:
+    from pyavd._utils import AVDTemplar
+else:
+    try:
+        from pyavd._utils import AVDTemplar
+    except ImportError as e:
+        AVDTemplar = RaiseOnUse(ImportError(f"The 'arista.avd' collection requires the 'pyavd' Python library. Got import error {e}"))
+
 
-def get_templar(action_plugin_instance: ActionBase, task_vars: dict) -> Templar:
+def get_templar(action_plugin_instance: ActionBase, task_vars: dict[str, Any]) -> AVDTemplar:
     """
-    Return a new instance of Ansible Templar Class based on the "._templar" from the given action_plugin_instance.
+    Return a new AVDTemplar instance based on the action plugin instance.
 
-    The new instance is loaded with new searchpath based on
+    The templar is loaded with new searchpath based on
     ".ansible_search_path" from the given task_vars.
+
+    Args:
+        action_plugin_instance: The Ansible ActionBase plugin instance
+        task_vars: Task variables containing ansible_search_path
+
+    Returns:
+        AVDTemplar instance with configured templar, loader, and searchpath
     """
-    return action_plugin_instance._templar.copy_with_new_env(
-        searchpath=compile_searchpath(task_vars.get("ansible_search_path", [])),
-    )
+    searchpath = compile_searchpath(task_vars.get("ansible_search_path", []))
+    templar = action_plugin_instance._templar.copy_with_new_env(searchpath=searchpath)
+    loader = action_plugin_instance._task.get_loader()
+    return AVDTemplar(templar, loader, searchpath)
diff --git a/ansible_collections/arista/avd/plugins/vars/global_vars.py b/ansible_collections/arista/avd/plugins/vars/global_vars.py
@@ -89,11 +89,15 @@
 from ansible.errors import AnsibleParserError
 from ansible.inventory.group import Group
 from ansible.inventory.host import Host
-from ansible.module_utils.basic import to_native
 from ansible.plugins.vars import BaseVarsPlugin
 from ansible.utils.vars import combine_vars
 
-from ansible_collections.arista.avd.plugins.plugin_utils.utils import ANSIBLE_ABOVE_2_19
+from ansible_collections.arista.avd.plugins.plugin_utils.constants import ANSIBLE_ABOVE_2_19
+
+if ANSIBLE_ABOVE_2_19:
+    from ansible.module_utils.common.text.converters import to_native
+else:
+    from ansible.module_utils.basic import to_native
 
 if ANSIBLE_ABOVE_2_19:
     from ansible.template import trust_as_template
diff --git a/python-avd/pyavd/_eos_designs/eos_designs_facts/get_facts.py b/python-avd/pyavd/_eos_designs/eos_designs_facts/get_facts.py
@@ -12,8 +12,7 @@
 if TYPE_CHECKING:
     from collections.abc import Mapping, MutableMapping
 
-    from ansible.template import Templar
-
+    from pyavd._utils import AVDTemplar
     from pyavd.api.pool_manager import PoolManager
     from pyavd.api.schemas import AVDDesign
 
@@ -23,7 +22,7 @@
 def get_facts(
     all_inputs: Mapping[str, AVDDesign | Mapping],
     all_hostvars: Mapping[str, MutableMapping[str, Any]] | None = None,
-    templar: Templar | None = None,
+    templar: AVDTemplar | None = None,
     pool_manager: PoolManager | None = None,
     digital_twin: bool = False,
 ) -> dict[str, EosDesignsFacts]:
@@ -35,7 +34,7 @@ def get_facts(
             Supporting dicts as well for backwards compatibility.
         all_hostvars: Raw hostvars exposed to custom jinja templates or custom python logic for each device.
             This is optional and only needed if custom templates or python modules are used for descriptions or IP addressing.
-        templar: Templater used to render custom jinja templates.
+        templar: AVDTemplar wrapper used to render custom jinja templates.
             This is optional and only needed if custom templates are used for descriptions or IP addressing.
         pool_manager: instance of pool-manager used for dynamic assignments like node ids.
         digital_twin: Optional flag to enable avd_digital_twin_mode.
@@ -91,7 +90,7 @@ def _create_generator_instance(
     hostname: str,
     inputs: AVDDesign,
     hostvars: MutableMapping,
-    templar: Templar | None,
+    templar: AVDTemplar | None,
     pool_manager: PoolManager | None,
     digital_twin: bool,
     peer_facts_generators: dict[str, EosDesignsFactsGenerator],
diff --git a/python-avd/pyavd/_eos_designs/shared_utils/__init__.py b/python-avd/pyavd/_eos_designs/shared_utils/__init__.py
@@ -35,10 +35,9 @@
 if TYPE_CHECKING:
     from collections.abc import Mapping, MutableMapping
 
-    from ansible.template import Templar
-
     from pyavd._eos_designs.eos_designs_facts.schema import EosDesignsFactsProtocol
     from pyavd._eos_designs.schema import EosDesigns
+    from pyavd._utils import AVDTemplar
     from pyavd.api.pool_manager import PoolManager
 
 
@@ -73,7 +72,7 @@ class SharedUtilsProtocol(
     hostname: str
     hostvars: MutableMapping
     inputs: EosDesigns
-    templar: Templar | None
+    templar: AVDTemplar | None
     peer_facts: Mapping[str, EosDesignsFactsProtocol]
     pool_manager: PoolManager | None
     digital_twin: bool
@@ -97,7 +96,7 @@ def __init__(
         hostname: str,
         hostvars: MutableMapping,
         inputs: EosDesigns,
-        templar: Templar | None,
+        templar: AVDTemplar | None,
         peer_facts: Mapping[str, EosDesignsFactsProtocol],
         pool_manager: PoolManager | None = None,
         digital_twin: bool = False,
diff --git a/python-avd/pyavd/_eos_designs/structured_config/__init__.py b/python-avd/pyavd/_eos_designs/structured_config/__init__.py
@@ -24,10 +24,9 @@
 if TYPE_CHECKING:
     from collections.abc import Mapping, MutableMapping
 
-    from ansible.template import Templar
-
     from pyavd._eos_designs.eos_designs_facts.schema import EosDesignsFacts
     from pyavd._eos_designs.schema import EosDesigns
+    from pyavd._utils import AVDTemplar
 
     from .structured_config_generator import StructuredConfigGenerator
 
@@ -63,7 +62,7 @@ def get_structured_config(
     inputs: EosDesigns,
     all_facts: Mapping[str, EosDesignsFacts],
     hostvars: MutableMapping | None = None,
-    templar: Templar | None = None,
+    templar: AVDTemplar | None = None,
     digital_twin: bool = False,
 ) -> EosCliConfigGen:
     """
diff --git a/python-avd/pyavd/_utils/__init__.py b/python-avd/pyavd/_utils/__init__.py
@@ -3,6 +3,7 @@
 # that can be found in the LICENSE file.
 from .append_if_not_duplicate import append_if_not_duplicate
 from .as_path_list_match_from_bgp_asns import as_path_list_match_from_bgp_asns
+from .avd_templar import AVDTemplar
 from .batch import batch
 from .compare_dicts import compare_dicts
 from .default import default
@@ -27,6 +28,7 @@
 from .unique import unique
 
 __all__ = [
+    "AVDTemplar",
     "AvdStringFormatter",
     "Undefined",
     "UndefinedType",
diff --git a/python-avd/pyavd/_utils/avd_templar.py b/python-avd/pyavd/_utils/avd_templar.py
@@ -0,0 +1,46 @@
+# Copyright (c) 2026 Arista Networks, Inc.
+# Use of this source code is governed by the Apache License 2.0
+# that can be found in the LICENSE file.
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ansible.parsing.dataloader import DataLoader
+    from ansible.template import Templar
+
+
+class AVDTemplar:
+    """
+    Wrapper around Ansible Templar that also stores the DataLoader and searchpath.
+
+    This allows us to pass templar, loader, and searchpath together,
+    avoiding the need to access templar._loader and templar.environment (which are deprecated).
+
+    Attributes:
+        templar: Ansible Templar instance
+        loader: Ansible DataLoader instance
+        searchpath: List of paths to search for templates
+    """
+
+    templar: Templar
+    """Ansible Templar instance"""
+
+    loader: DataLoader
+    """Ansible DataLoader instance"""
+
+    searchpath: list[str]
+    """List of paths to search for templates"""
+
+    def __init__(self, templar: Templar, loader: DataLoader, searchpath: list[str]) -> None:
+        """
+        Initialize AVDTemplar with an Ansible Templar, DataLoader, and searchpath.
+
+        Args:
+            templar: Ansible Templar instance
+            loader: Ansible DataLoader instance
+            searchpath: List of paths to search for templates
+        """
+        self.templar = templar
+        self.loader = loader
+        self.searchpath = searchpath
diff --git a/python-avd/pyavd/_utils/template.py b/python-avd/pyavd/_utils/template.py
@@ -9,11 +9,10 @@
     from collections import ChainMap
     from typing import Any
 
-    from ansible.parsing.dataloader import DataLoader
-    from ansible.template import Templar
+    from pyavd._utils.avd_templar import AVDTemplar
 
 
-def template(template_file: str, template_vars: dict[str, Any] | ChainMap[str, Any], templar: Templar | None) -> Any:
+def template(template_file: str, template_vars: dict[str, Any] | ChainMap[str, Any], templar: AVDTemplar | None) -> Any:
     """
     Run Ansible Templar with template file.
 
@@ -23,52 +22,44 @@ def template(template_file: str, template_vars: dict[str, Any] | ChainMap[str, A
     - No configurable convert_data (we set it to True to match Ansible 2.19+)
     - Maybe something else we have not discovered yet...
 
-    Parameters
-    ----------
-    template_file : str
-        Path to Jinja2 template file
-    template_vars : any
-        Variables to use when rendering template
-    templar : func
-        Instance of Ansible Templar class
-    searchpath : list of str
-        List of Paths
+    Args:
+        template_file : str
+            Path to Jinja2 template file
+        template_vars : any
+            Variables to use when rendering template
+        templar : AVDTemplar | None
+            Instance of AVDTemplar wrapper containing Ansible Templar, DataLoader, and searchpath
 
     Returns:
-    -------
-    Any
-        The rendered template result. Can be of any type depending on the template.
+        Any
+            The rendered template result. Can be of any type depending on the template.
     """
     if templar is None:
         msg = "Jinja Templating is not implemented in pyavd"
         raise NotImplementedError(msg)
 
     # We only get here when running from Ansible, so it is safe to import from ansible and jinja2.
-    from ansible_collections.arista.avd.plugins.plugin_utils.utils import ANSIBLE_ABOVE_2_19  # noqa: PLC0415
-    from jinja2.loaders import FileSystemLoader  # noqa: PLC0415
+    from ansible_collections.arista.avd.plugins.plugin_utils.constants import ANSIBLE_ABOVE_2_19  # noqa: PLC0415
 
-    dataloader: DataLoader = templar._loader
-    jinjaloader = templar.environment.loader
-    searchpath = jinjaloader.searchpath if isinstance(jinjaloader, FileSystemLoader) else []
-    template_file_path = dataloader.path_dwim_relative_stack(searchpath, "templates", template_file)
+    template_file_path = templar.loader.path_dwim_relative_stack(templar.searchpath, "", template_file)
 
     if ANSIBLE_ABOVE_2_19:
         # New templar from ansible-core 2.19 and above
         from ansible.template import trust_as_template  # noqa: PLC0415 # pyright: ignore reportAttributeAccessIssue
 
-        j2template = trust_as_template(dataloader.get_text_file_contents(template_file_path))  # pyright: ignore [reportAttributeAccessIssue]
-        tmp_templar = templar.copy_with_new_env(available_variables=template_vars)
+        j2template = trust_as_template(templar.loader.get_text_file_contents(template_file_path))  # pyright: ignore [reportAttributeAccessIssue]
+        tmp_templar = templar.templar.copy_with_new_env(available_variables=template_vars)
         output = tmp_templar.template(j2template, escape_backslashes=False)
 
     else:
         # Legacy templar
         # TODO: Remove this once 2.19 is our minimal supported ansible-core version.
         from ansible.module_utils._text import to_text  # noqa: PLC0415
 
-        j2template, _ = dataloader._get_file_contents(template_file_path)
+        j2template, _ = templar.loader._get_file_contents(template_file_path)
         j2template = to_text(j2template)  # pyright: ignore [reportCallIssue] because of the redirection in ansible-core newer versions
 
-        with templar.set_temporary_context(available_variables=template_vars):
-            output = templar.template(j2template, convert_data=True, escape_backslashes=False)
+        with templar.templar.set_temporary_context(available_variables=template_vars):
+            output = templar.templar.template(j2template, convert_data=True, escape_backslashes=False)
 
     return output
diff --git a/python-avd/pyavd/_utils/template_var.py b/python-avd/pyavd/_utils/template_var.py
@@ -10,10 +10,10 @@
 if TYPE_CHECKING:
     from typing import Any
 
-    from ansible.template import Templar
+    from .avd_templar import AVDTemplar
 
 
-def template_var(template_file: str, template_vars: Any, templar: Templar | None) -> str:
+def template_var(template_file: str, template_vars: Any, templar: AVDTemplar | None) -> str:
     """
     Wrap "template" for single values like IP addresses.
 
@@ -25,8 +25,7 @@ def template_var(template_file: str, template_vars: Any, templar: Templar | None
     Args:
         template_file: Path to Jinja2 template file
         template_vars: Variables to use when rendering template
-        templar: Instance of Ansible Templar class
-        searchpath: List of Paths
+        templar: Instance of AVDTemplar wrapper
 
     Returns:
         The rendered template
diff --git a/python-avd/tests/pyavd/utils/test_template.py b/python-avd/tests/pyavd/utils/test_template.py
diff --git a/python-avd/tests/pyavd/utils/test_template_var.py b/python-avd/tests/pyavd/utils/test_template_var.py
