ansible-core 2.18.5rc1__py3-none-any.whl → 2.19.0b2__py3-none-any.whl

ansible/playbook/task.py

@@ -17,13 +17,18 @@
 
 from __future__ import annotations
 
+import typing as t
+
 from ansible import constants as C
-from ansible.errors import AnsibleError, AnsibleParserError, AnsibleUndefinedVariable, AnsibleAssertionError
+from ansible.module_utils.common.sentinel import Sentinel
+from ansible.errors import AnsibleError, AnsibleParserError, AnsibleUndefinedVariable, AnsibleAssertionError, AnsibleValueOmittedError
+from ansible.executor.module_common import _get_action_arg_defaults
 from ansible.module_utils.common.text.converters import to_native
+from ansible.module_utils._internal._datatag import AnsibleTagHelper
 from ansible.module_utils.six import string_types
-from ansible.parsing.mod_args import ModuleArgsParser
-from ansible.parsing.yaml.objects import AnsibleBaseYAMLObject, AnsibleMapping
-from ansible.plugins.loader import lookup_loader
+from ansible.parsing.mod_args import ModuleArgsParser, RAW_PARAM_MODULES
+from ansible.plugins.action import ActionBase
+from ansible.plugins.loader import action_loader, module_loader, lookup_loader
 from ansible.playbook.attribute import NonInheritableFieldAttribute
 from ansible.playbook.base import Base
 from ansible.playbook.block import Block
@@ -34,10 +39,14 @@ from ansible.playbook.loop_control import LoopControl
 from ansible.playbook.notifiable import Notifiable
 from ansible.playbook.role import Role
 from ansible.playbook.taggable import Taggable
+from ansible._internal import _task
+from ansible._internal._templating import _marker_behaviors
+from ansible._internal._templating._jinja_bits import is_possibly_all_template
+from ansible._internal._templating._engine import TemplateEngine, TemplateOptions
 from ansible.utils.collection_loader import AnsibleCollectionConfig
 from ansible.utils.display import Display
-from ansible.utils.sentinel import Sentinel
-from ansible.utils.vars import isidentifier
+
+from ansible.utils.vars import validate_variable_name
 
 __all__ = ['Task']
 
@@ -67,8 +76,8 @@ class Task(Base, Conditional, Taggable, CollectionSearch, Notifiable, Delegatabl
     # inheritance is only triggered if the 'current value' is Sentinel,
     # default can be set at play/top level object and inheritance will take it's course.
 
-    args = NonInheritableFieldAttribute(isa='dict', default=dict)
-    action = NonInheritableFieldAttribute(isa='string')
+    args = t.cast(dict, NonInheritableFieldAttribute(isa='dict', default=dict))
+    action = t.cast(str, NonInheritableFieldAttribute(isa='string'))
 
     async_val = NonInheritableFieldAttribute(isa='int', default=0, alias='async')
     changed_when = NonInheritableFieldAttribute(isa='list', default=list)
@@ -84,13 +93,13 @@ class Task(Base, Conditional, Taggable, CollectionSearch, Notifiable, Delegatabl
     # deprecated, used to be loop and loop_args but loop has been repurposed
     loop_with = NonInheritableFieldAttribute(isa='string', private=True)
 
-    def __init__(self, block=None, role=None, task_include=None):
-        ''' constructors a task, without the Task.load classmethod, it will be pretty blank '''
+    def __init__(self, block=None, role=None, task_include=None) -> None:
+        """ constructors a task, without the Task.load classmethod, it will be pretty blank """
 
         self._role = role
         self._parent = None
         self.implicit = False
-        self.resolved_action = None
+        self.resolved_action: str | None = None
 
         if task_include:
             self._parent = task_include
@@ -100,7 +109,7 @@ class Task(Base, Conditional, Taggable, CollectionSearch, Notifiable, Delegatabl
         super(Task, self).__init__()
 
     def get_name(self, include_role_fqcn=True):
-        ''' return the name of the task '''
+        """ return the name of the task """
 
         if self._role:
             role_name = self._role.get_name(include_role_fqcn=include_role_fqcn)
@@ -131,18 +140,85 @@ class Task(Base, Conditional, Taggable, CollectionSearch, Notifiable, Delegatabl
 
     @staticmethod
     def load(data, block=None, role=None, task_include=None, variable_manager=None, loader=None):
-        t = Task(block=block, role=role, task_include=task_include)
-        return t.load_data(data, variable_manager=variable_manager, loader=loader)
+        task = Task(block=block, role=role, task_include=task_include)
+        return task.load_data(data, variable_manager=variable_manager, loader=loader)
 
-    def __repr__(self):
-        ''' returns a human-readable representation of the task '''
+    def _post_validate_module_defaults(self, attr: str, value: t.Any, templar: TemplateEngine) -> t.Any:
+        """Override module_defaults post validation to disable templating, which is handled by args post validation."""
+        return value
+
+    def _post_validate_args(self, attr: str, value: t.Any, templar: TemplateEngine) -> dict[str, t.Any]:
+        try:
+            self.action = templar.template(self.action)
+        except AnsibleValueOmittedError:
+            # some strategies may trigger this error when templating task.action, but backstop here if not
+            raise AnsibleParserError("Omit is not valid for the `action` keyword.", obj=self.action) from None
+
+        action_context = action_loader.get_with_context(self.action, collection_list=self.collections, class_only=True)
+
+        if not action_context.plugin_load_context.resolved:
+            module_or_action_context = module_loader.find_plugin_with_context(self.action, collection_list=self.collections)
+
+            if not module_or_action_context.resolved:
+                raise AnsibleError(f"Cannot resolve {self.action!r} to an action or module.", obj=self.action)
+
+            action_context = action_loader.get_with_context('ansible.legacy.normal', collection_list=self.collections, class_only=True)
+        else:
+            module_or_action_context = action_context.plugin_load_context
+
+        self.resolved_action = module_or_action_context.resolved_fqcn
+
+        action_type: type[ActionBase] = action_context.object
+
+        vp = value.pop('_variable_params', None)
+
+        supports_raw_params = action_type.supports_raw_params or module_or_action_context.resolved_fqcn in RAW_PARAM_MODULES
+
+        if supports_raw_params:
+            raw_params_to_finalize = None
+        else:
+            raw_params_to_finalize = value.pop('_raw_params', None)  # always str or None
+
+            # TaskArgsFinalizer performs more thorough type checking, but this provides a friendlier error message for a subset of detected cases.
+            if raw_params_to_finalize and not is_possibly_all_template(raw_params_to_finalize):
+                raise AnsibleError(f'Action {module_or_action_context.resolved_fqcn!r} does not support raw params.', obj=self.action)
+
+        args_finalizer = _task.TaskArgsFinalizer(
+            _get_action_arg_defaults(module_or_action_context.resolved_fqcn, self, templar),
+            vp,
+            raw_params_to_finalize,
+            value,
+            templar=templar,
+        )
+
+        try:
+            with action_type.get_finalize_task_args_context() as finalize_context:
+                args = args_finalizer.finalize(action_type.finalize_task_arg, context=finalize_context)
+        except Exception as ex:
+            raise AnsibleError(f'Finalization of task args for {module_or_action_context.resolved_fqcn!r} failed.', obj=self.action) from ex
+
+        if self._origin:
+            args = self._origin.tag(args)
+
+        return args
+
+    def _get_meta(self) -> str | None:
+        # FUTURE: validate meta and return an enum instead of a str
+        # meta currently does not support being templated, so we can cheat
         if self.action in C._ACTION_META:
-            return "TASK: meta (%s)" % self.args['_raw_params']
+            return self.args.get('_raw_params')
+
+        return None
+
+    def __repr__(self):
+        """ returns a human-readable representation of the task """
+        if meta := self._get_meta():
+            return f"TASK: meta ({meta})"
         else:
             return "TASK: %s" % self.get_name()
 
     def _preprocess_with_loop(self, ds, new_ds, k, v):
-        ''' take a lookup plugin name and store it correctly '''
+        """ take a lookup plugin name and store it correctly """
 
         loop_name = k.removeprefix("with_")
         if new_ds.get('loop') is not None or new_ds.get('loop_with') is not None:
@@ -155,20 +231,17 @@ class Task(Base, Conditional, Taggable, CollectionSearch, Notifiable, Delegatabl
         #                    version="2.10", collection_name='ansible.builtin')
 
     def preprocess_data(self, ds):
-        '''
+        """
         tasks are especially complex arguments so need pre-processing.
         keep it short.
-        '''
+        """
 
         if not isinstance(ds, dict):
             raise AnsibleAssertionError('ds (%s) should be a dict but was a %s' % (ds, type(ds)))
 
-        # the new, cleaned datastructure, which will have legacy
-        # items reduced to a standard structure suitable for the
-        # attributes of the task class
-        new_ds = AnsibleMapping()
-        if isinstance(ds, AnsibleBaseYAMLObject):
-            new_ds.ansible_pos = ds.ansible_pos
+        # the new, cleaned datastructure, which will have legacy items reduced to a standard structure suitable for the
+        # attributes of the task class; copy any tagged data to preserve things like origin
+        new_ds = AnsibleTagHelper.tag_copy(ds, {})
 
         # since this affects the task action parsing, we have to resolve in preprocess instead of in typical validator
         default_collection = AnsibleCollectionConfig.default_collection
@@ -201,26 +274,13 @@ class Task(Base, Conditional, Taggable, CollectionSearch, Notifiable, Delegatabl
         args_parser = ModuleArgsParser(task_ds=ds, collection_list=collections_list)
         try:
             (action, args, delegate_to) = args_parser.parse()
-        except AnsibleParserError as e:
+        except AnsibleParserError as ex:
             # if the raises exception was created with obj=ds args, then it includes the detail
             # so we dont need to add it so we can just re raise.
-            if e.obj:
+            if ex.obj:
                 raise
             # But if it wasn't, we can add the yaml object now to get more detail
-            raise AnsibleParserError(to_native(e), obj=ds, orig_exc=e)
-        else:
-            # Set the resolved action plugin (or if it does not exist, module) for callbacks.
-            self.resolved_action = args_parser.resolved_action
-
-        # the command/shell/script modules used to support the `cmd` arg,
-        # which corresponds to what we now call _raw_params, so move that
-        # value over to _raw_params (assuming it is empty)
-        if action in C._ACTION_HAS_CMD:
-            if 'cmd' in args:
-                if args.get('_raw_params', '') != '':
-                    raise AnsibleError("The 'cmd' argument cannot be used when other raw parameters are specified."
-                                       " Please put everything in one or the other place.", obj=ds)
-                args['_raw_params'] = args.pop('cmd')
+            raise AnsibleParserError("Error parsing task arguments.", obj=ds) from ex
 
         new_ds['action'] = action
         new_ds['args'] = args
@@ -276,114 +336,99 @@ class Task(Base, Conditional, Taggable, CollectionSearch, Notifiable, Delegatabl
             setattr(self, name, [value])
 
     def _validate_register(self, attr, name, value):
-        if value is not None and not isidentifier(value):
-            raise AnsibleParserError(f"Invalid variable name in 'register' specified: '{value}'")
+        if value is not None:
+            try:
+                validate_variable_name(value)
+            except Exception as ex:
+                raise AnsibleParserError("Invalid 'register' specified.", obj=value) from ex
 
     def post_validate(self, templar):
-        '''
+        """
         Override of base class post_validate, to also do final validation on
         the block and task include (if any) to which this task belongs.
-        '''
+        """
 
         if self._parent:
             self._parent.post_validate(templar)
 
-        if AnsibleCollectionConfig.default_collection:
-            pass
-
         super(Task, self).post_validate(templar)
 
-    def _post_validate_args(self, attr, value, templar):
-        # smuggle an untemplated copy of the task args for actions that need more control over the templating of their
-        # input (eg, debug's var/msg, assert's "that" conditional expressions)
-        self.untemplated_args = value
-
-        # now recursively template the args dict
-        args = templar.template(value)
-
-        # FIXME: could we just nuke this entirely and/or wrap it up in ModuleArgsParser or something?
-        if '_variable_params' in args:
-            variable_params = args.pop('_variable_params')
-            if isinstance(variable_params, dict):
-                if C.INJECT_FACTS_AS_VARS:
-                    display.warning("Using a variable for a task's 'args' is unsafe in some situations "
-                                    "(see https://docs.ansible.com/ansible/devel/reference_appendices/faq.html#argsplat-unsafe)")
-                variable_params.update(args)
-                args = variable_params
-            else:
-                # if we didn't get a dict, it means there's garbage remaining after k=v parsing, just give up
-                # see https://github.com/ansible/ansible/issues/79862
-                raise AnsibleError(f"invalid or malformed argument: '{variable_params}'")
-
-        return args
-
     def _post_validate_loop(self, attr, value, templar):
-        '''
+        """
         Override post validation for the loop field, which is templated
         specially in the TaskExecutor class when evaluating loops.
-        '''
+        """
         return value
 
+    def _post_validate_name(self, attr, value, templar):
+        """
+        Override post-validation behavior for `name` to be best-effort for the vars available.
+        Direct access via `post_validate_attribute` writes the value back to provide a stable value.
+        This value is individually post-validated early by strategies for the benefit of callbacks.
+        """
+        with _marker_behaviors.ReplacingMarkerBehavior.warning_context() as replacing_behavior:
+            self.name = templar.extend(marker_behavior=replacing_behavior).template(value, options=TemplateOptions(value_for_omit=None))
+
+        return self.name
+
     def _post_validate_environment(self, attr, value, templar):
-        '''
+        """
         Override post validation of vars on the play, as we don't want to
         template these too early.
-        '''
+        """
         env = {}
-        if value is not None:
 
-            def _parse_env_kv(k, v):
-                try:
-                    env[k] = templar.template(v, convert_bare=False)
-                except AnsibleUndefinedVariable as e:
-                    error = to_native(e)
-                    if self.action in C._ACTION_FACT_GATHERING and 'ansible_facts.env' in error or 'ansible_env' in error:
-                        # ignore as fact gathering is required for 'env' facts
-                        return
-                    raise
-
-            if isinstance(value, list):
-                for env_item in value:
-                    if isinstance(env_item, dict):
-                        for k in env_item:
-                            _parse_env_kv(k, env_item[k])
-                    else:
-                        isdict = templar.template(env_item, convert_bare=False)
-                        if isinstance(isdict, dict):
-                            env |= isdict
-                        else:
-                            display.warning("could not parse environment value, skipping: %s" % value)
-
-            elif isinstance(value, dict):
-                # should not really happen
-                env = dict()
-                for env_item in value:
-                    _parse_env_kv(env_item, value[env_item])
+        # FUTURE: kill this with fire
+        def _parse_env_kv(k, v):
+            try:
+                env[k] = templar.template(v)
+            except AnsibleValueOmittedError:
+                # skip this value
+                return
+            except AnsibleUndefinedVariable as e:
+                error = to_native(e)
+                if self.action in C._ACTION_FACT_GATHERING and 'ansible_facts.env' in error or 'ansible_env' in error:
+                    # ignore as fact gathering is required for 'env' facts
+                    return
+                raise
+
+        # NB: the environment FieldAttribute definition ensures that value is always a list
+        for env_item in value:
+            if isinstance(env_item, dict):
+                for k in env_item:
+                    _parse_env_kv(k, env_item[k])
             else:
-                # at this point it should be a simple string, also should not happen
-                env = templar.template(value, convert_bare=False)
+                try:
+                    isdict = templar.template(env_item)
+                except AnsibleValueOmittedError:
+                    continue
+
+                if isinstance(isdict, dict):
+                    env |= isdict
+                else:
+                    display.warning("could not parse environment value, skipping: %s" % value)
 
         return env
 
     def _post_validate_changed_when(self, attr, value, templar):
-        '''
+        """
         changed_when is evaluated after the execution of the task is complete,
         and should not be templated during the regular post_validate step.
-        '''
+        """
         return value
 
     def _post_validate_failed_when(self, attr, value, templar):
-        '''
+        """
         failed_when is evaluated after the execution of the task is complete,
         and should not be templated during the regular post_validate step.
-        '''
+        """
         return value
 
     def _post_validate_until(self, attr, value, templar):
-        '''
+        """
         until is evaluated after the execution of the task is complete,
         and should not be templated during the regular post_validate step.
-        '''
+        """
         return value
 
     def get_vars(self):
@@ -408,7 +453,7 @@ class Task(Base, Conditional, Taggable, CollectionSearch, Notifiable, Delegatabl
             all_vars |= self.vars
         return all_vars
 
-    def copy(self, exclude_parent=False, exclude_tasks=False):
+    def copy(self, exclude_parent: bool = False, exclude_tasks: bool = False) -> Task:
         new_me = super(Task, self).copy()
 
         new_me._parent = None
@@ -473,11 +518,11 @@ class Task(Base, Conditional, Taggable, CollectionSearch, Notifiable, Delegatabl
         super(Task, self).deserialize(data)
 
     def set_loader(self, loader):
-        '''
+        """
         Sets the loader on this object and recursively on parent, child objects.
         This is used primarily after the Task has been serialized/deserialized, which
         does not preserve the loader.
-        '''
+        """
 
         self._loader = loader
 
@@ -485,9 +530,9 @@ class Task(Base, Conditional, Taggable, CollectionSearch, Notifiable, Delegatabl
             self._parent.set_loader(loader)
 
     def _get_parent_attribute(self, attr, omit=False):
-        '''
+        """
         Generic logic to get the attribute or parent attribute for a task value.
-        '''
+        """
         fattr = self.fattributes[attr]
 
         extend = fattr.extend
@@ -542,3 +587,28 @@ class Task(Base, Conditional, Taggable, CollectionSearch, Notifiable, Delegatabl
         while not isinstance(parent, Block):
             parent = parent._parent
         return parent._play
+
+    def dump_attrs(self):
+        """Override to smuggle important non-FieldAttribute values back to the controller."""
+        attrs = super().dump_attrs()
+        attrs.update(resolved_action=self.resolved_action)
+        return attrs
+
+    def _resolve_conditional(
+        self,
+        conditional: list[str | bool],
+        variables: dict[str, t.Any],
+        *,
+        result_context: dict[str, t.Any] | None = None,
+    ) -> bool:
+        """Loops through the conditionals set on this object, returning False if any of them evaluate as such, as well as the condition that was False."""
+        engine = TemplateEngine(self._loader, variables=variables)
+
+        for item in conditional:
+            if not engine.evaluate_conditional(item):
+                if result_context is not None:
+                    result_context.update(false_condition=item)
+
+                return False
+
+        return True

ansible/playbook/task_include.py

@@ -19,10 +19,10 @@ from __future__ import annotations
 
 import ansible.constants as C
 from ansible.errors import AnsibleParserError
+from ansible.module_utils.common.sentinel import Sentinel
 from ansible.playbook.block import Block
 from ansible.playbook.task import Task
 from ansible.utils.display import Display
-from ansible.utils.sentinel import Sentinel
 
 __all__ = ['TaskInclude']
 
@@ -58,12 +58,12 @@ class TaskInclude(Task):
         return task
 
     def check_options(self, task, data):
-        '''
+        """
         Method for options validation to use in 'load_data' for TaskInclude and HandlerTaskInclude
         since they share the same validations. It is not named 'validate_options' on purpose
         to prevent confusion with '_validate_*" methods. Note that the task passed might be changed
         as a side-effect of this method.
-        '''
+        """
         my_arg_names = frozenset(task.args.keys())
 
         # validate bad args, otherwise we silently ignore
@@ -104,10 +104,10 @@ class TaskInclude(Task):
         return new_me
 
     def build_parent_block(self):
-        '''
+        """
         This method is used to create the parent block for the included tasks
         when ``apply`` is specified
-        '''
+        """
         apply_attrs = self.args.pop('apply', {})
         if apply_attrs:
             apply_attrs['block'] = []

ansible/plugins/__init__.py

@@ -19,17 +19,16 @@
 
 from __future__ import annotations
 
-from abc import ABC
-
+import abc
 import types
 import typing as t
 
 from ansible import constants as C
 from ansible.errors import AnsibleError
-from ansible.module_utils.common.text.converters import to_native
-from ansible.module_utils.six import string_types
 from ansible.utils.display import Display
 
+from ansible.module_utils._internal import _plugin_exec_context
+
 display = Display()
 
 if t.TYPE_CHECKING:
@@ -42,13 +41,32 @@ PLUGIN_PATH_CACHE = {}  # type: dict[str, dict[str, dict[str, PluginPathContext]
 
 
 def get_plugin_class(obj):
-    if isinstance(obj, string_types):
+    if isinstance(obj, str):
         return obj.lower().replace('module', '')
     else:
         return obj.__class__.__name__.lower().replace('module', '')
 
 
-class AnsiblePlugin(ABC):
+class _ConfigurablePlugin(t.Protocol):
+    """Protocol to provide type-safe access to config for plugin-related mixins."""
+
+    def get_option(self, option: str, hostvars: dict[str, object] | None = None) -> object: ...
+
+
+class _AnsiblePluginInfoMixin(_plugin_exec_context.HasPluginInfo):
+    """Mixin to provide type annotations and default values for existing PluginLoader-set load-time attrs."""
+    _original_path: str | None = None
+    _load_name: str | None = None
+    _redirected_names: list[str] | None = None
+    ansible_aliases: list[str] | None = None
+    ansible_name: str | None = None
+
+    @property
+    def plugin_type(self) -> str:
+        return self.__class__.__name__.lower().replace('module', '')
+
+
+class AnsiblePlugin(_AnsiblePluginInfoMixin, _ConfigurablePlugin, metaclass=abc.ABCMeta):
 
     # Set by plugin loader
     _load_name: str
@@ -81,7 +99,7 @@ class AnsiblePlugin(ABC):
         try:
             option_value, origin = C.config.get_config_value_and_origin(option, plugin_type=self.plugin_type, plugin_name=self._load_name, variables=hostvars)
         except AnsibleError as e:
-            raise KeyError(to_native(e))
+            raise KeyError(str(e))
         return option_value, origin
 
     def get_option(self, option, hostvars=None):
@@ -102,13 +120,13 @@ class AnsiblePlugin(ABC):
         C.handle_config_noise(display)
 
     def set_options(self, task_keys=None, var_options=None, direct=None):
-        '''
+        """
         Sets the _options attribute with the configuration/keyword information for this plugin
 
         :arg task_keys: Dict with playbook keywords that affect this option
         :arg var_options: Dict with either 'connection variables'
         :arg direct: Dict with 'direct assignment'
-        '''
+        """
         self._options = C.config.get_plugin_options(self.plugin_type, self._load_name, keys=task_keys, variables=var_options, direct=direct)
 
         # allow extras/wildcards from vars that are not directly consumed in configuration
@@ -123,13 +141,9 @@ class AnsiblePlugin(ABC):
             self.set_options()
         return option in self._options
 
-    @property
-    def plugin_type(self):
-        return self.__class__.__name__.lower().replace('module', '')
-
     @property
     def option_definitions(self):
-        if self._defs is None:
+        if (not hasattr(self, "_defs")) or self._defs is None:
             self._defs = C.config.get_configuration_definitions(plugin_type=self.plugin_type, name=self._load_name)
         return self._defs
 
@@ -137,23 +151,56 @@ class AnsiblePlugin(ABC):
         # FIXME: standardize required check based on config
         pass
 
+    def __repr__(self):
+        ansible_name = getattr(self, 'ansible_name', '(unknown)')
+        load_name = getattr(self, '_load_name', '(unknown)')
+        return f'{type(self).__name__}(plugin_type={self.plugin_type!r}, {ansible_name=!r}, {load_name=!r})'
 
-class AnsibleJinja2Plugin(AnsiblePlugin):
-
-    def __init__(self, function):
 
+class AnsibleJinja2Plugin(AnsiblePlugin, metaclass=abc.ABCMeta):
+    def __init__(self, function: t.Callable) -> None:
         super(AnsibleJinja2Plugin, self).__init__()
         self._function = function
 
+        # Declare support for markers. Plugins with `False` here will never be invoked with markers for top-level arguments.
+        self.accept_args_markers = getattr(self._function, 'accept_args_markers', False)
+        self.accept_lazy_markers = getattr(self._function, 'accept_lazy_markers', False)
+
     @property
-    def plugin_type(self):
-        return self.__class__.__name__.lower().replace('ansiblejinja2', '')
+    @abc.abstractmethod
+    def plugin_type(self) -> str:
+        ...
 
-    def _no_options(self, *args, **kwargs):
+    def _no_options(self, *args, **kwargs) -> t.NoReturn:
         raise NotImplementedError()
 
     has_option = get_option = get_options = option_definitions = set_option = set_options = _no_options
 
     @property
-    def j2_function(self):
+    def j2_function(self) -> t.Callable:
         return self._function
+
+
+_TCallable = t.TypeVar('_TCallable', bound=t.Callable)
+
+
+def accept_args_markers(plugin: _TCallable) -> _TCallable:
+    """
+    A decorator to mark a Jinja plugin as capable of handling `Marker` values for its top-level arguments.
+    Non-decorated plugin invocation is skipped when a top-level argument is a `Marker`, with the first such value substituted as the plugin result.
+    This ensures that only plugins which understand `Marker` instances for top-level arguments will encounter them.
+    """
+    plugin.accept_args_markers = True
+
+    return plugin
+
+
+def accept_lazy_markers(plugin: _TCallable) -> _TCallable:
+    """
+    A decorator to mark a Jinja plugin as capable of handling `Marker` values retrieved from lazy containers.
+    Non-decorated plugins will trigger a `MarkerError` exception when attempting to retrieve a `Marker` from a lazy container.
+    This ensures that only plugins which understand lazy retrieval of `Marker` instances will encounter them.
+    """
+    plugin.accept_lazy_markers = True
+
+    return plugin