ansible-core 2.19.0b3__py3-none-any.whl → 2.19.0b5__py3-none-any.whl

ansible/module_utils/_internal/_datatag/__init__.py

@@ -37,15 +37,16 @@ _ANSIBLE_TAGGED_OBJECT_SLOTS = tuple(('_ansible_tags_mapping',))
 # shared empty frozenset for default values
 _empty_frozenset: t.FrozenSet = frozenset()
 
+# Technical Notes
+#
+# Tagged values compare (and thus hash) the same as their base types, so a value that differs only by its tags will appear identical to non-tag-aware code.
+# This will affect storage and update of tagged values in dictionary keys, sets, etc. While tagged values can be used as keys in hashable collections,
+# updating a key usually requires removal and re-addition.
+
 
 class AnsibleTagHelper:
     """Utility methods for working with Ansible data tags."""
 
-    # DTFIX-RELEASE: bikeshed the name and location of this class, also, related, how much more of it should be exposed as public API?
-    #        it may make sense to move this into another module, but the implementations should remain here (so they can be used without circular imports here)
-    #        if they're in a separate module, is a class even needed, or should they be globals?
-    # DTFIX-RELEASE: add docstrings to all non-override methods in this class
-
     @staticmethod
     def untag(value: _T, *tag_types: t.Type[AnsibleDatatagBase]) -> _T:
         """
@@ -105,7 +106,7 @@ class AnsibleTagHelper:
         if issubclass(the_type, AnsibleTaggedObject):
             the_type = type_or_value._native_type
 
-        # DTFIX-RELEASE: provide a way to report the real type for debugging purposes
+        # DTFIX-FUTURE: provide a knob to optionally report the real type for debugging purposes
         return the_type
 
     @staticmethod
@@ -339,10 +340,11 @@ class AnsibleSerializableDateTime(AnsibleSerializableWrapper[datetime.datetime])
 @dataclasses.dataclass(**_tag_dataclass_kwargs)
 class AnsibleSerializableDataclass(AnsibleSerializable, metaclass=abc.ABCMeta):
     _validation_allow_subclasses = True
+    _validation_auto_enabled = True
 
     def _as_dict(self) -> t.Dict[str, t.Any]:
         # omit None values when None is the field default
-        # DTFIX-RELEASE: this implementation means we can never change the default on fields which have None for their default
+        # DTFIX-FUTURE: this implementation means we can never change the default on fields which have None for their default
         #          other defaults can be changed -- but there's no way to override this behavior either way for other default types
         #          it's a trip hazard to have the default logic here, rather than per field (or not at all)
         #          consider either removing the filtering or requiring it to be explicitly set per field using dataclass metadata
@@ -351,7 +353,7 @@ class AnsibleSerializableDataclass(AnsibleSerializable, metaclass=abc.ABCMeta):
 
     @classmethod
     def _from_dict(cls, d: t.Dict[str, t.Any]) -> t.Self:
-        # DTFIX-RELEASE: optimize this to avoid the dataclasses fields metadata and get_origin stuff at runtime
+        # DTFIX-FUTURE: optimize this to avoid the dataclasses fields metadata and get_origin stuff at runtime
         type_hints = t.get_type_hints(cls)
         mutated_dict: dict[str, t.Any] | None = None
 
@@ -368,7 +370,11 @@ class AnsibleSerializableDataclass(AnsibleSerializable, metaclass=abc.ABCMeta):
     def __init_subclass__(cls, **kwargs) -> None:
         super(AnsibleSerializableDataclass, cls).__init_subclass__(**kwargs)  # cannot use super() without arguments when using slots
 
-        _dataclass_validation.inject_post_init_validation(cls, cls._validation_allow_subclasses)  # code gen a real __post_init__ method
+        if cls._validation_auto_enabled:
+            try:
+                _dataclass_validation.inject_post_init_validation(cls, cls._validation_allow_subclasses)  # code gen a real __post_init__ method
+            except Exception as ex:
+                raise Exception(f'Validation code generation failed on {cls}.') from ex
 
 
 class Tripwire:
@@ -524,7 +530,6 @@ class CollectionWithMro(c.Collection, t.Protocol):
     __mro__: tuple[type, ...]
 
 
-# DTFIX-RELEASE: This should probably reside elsewhere.
 def is_non_scalar_collection_type(value: type) -> t.TypeGuard[type[CollectionWithMro]]:
     """Returns True if the value is a non-scalar collection type, otherwise returns False."""
     return issubclass(value, c.Collection) and not issubclass(value, str) and not issubclass(value, bytes)
@@ -878,7 +883,6 @@ class _AnsibleTaggedList(list, AnsibleTaggedObject):
     # Propagation of tags in these cases is left to the caller, based on needs specific to their use case.
 
 
-# DTFIX-RELEASE: do we want frozenset too?
 class _AnsibleTaggedSet(set, AnsibleTaggedObject):
     __slots__ = _ANSIBLE_TAGGED_OBJECT_SLOTS
 
@@ -914,10 +918,12 @@ class _AnsibleTaggedTuple(tuple, AnsibleTaggedObject):
         return super()._copy_collection()
 
 
-# This set gets augmented with additional types when some controller-only types are imported.
-# While we could proxy or subclass builtin singletons, they're idiomatically compared with "is" reference
-# equality, which we can't customize.
 _untaggable_types = {type(None), bool}
+"""
+Attempts to apply tags to values of these types will be silently ignored.
+While we could proxy or subclass builtin singletons, they're idiomatically compared with "is" reference equality, which we can't customize.
+This set gets augmented with additional types when some controller-only types are imported.
+"""
 
 # noinspection PyProtectedMember
 _ANSIBLE_ALLOWED_VAR_TYPES = frozenset({type(None), bool}) | set(AnsibleTaggedObject._tagged_type_map) | set(AnsibleTaggedObject._tagged_type_map.values())

ansible/module_utils/_internal/_datatag/_tags.py

@@ -3,8 +3,7 @@ from __future__ import annotations
 import dataclasses
 import typing as t
 
-from ansible.module_utils.common import messages as _messages
-from ansible.module_utils._internal import _datatag
+from ansible.module_utils._internal import _datatag, _messages
 
 
 @dataclasses.dataclass(**_datatag._tag_dataclass_kwargs)
@@ -14,3 +13,4 @@ class Deprecated(_datatag.AnsibleDatatagBase):
     date: t.Optional[str] = None
     version: t.Optional[str] = None
     deprecator: t.Optional[_messages.PluginInfo] = None
+    formatted_traceback: t.Optional[str] = None

ansible/module_utils/_internal/_deprecator.py

@@ -1,79 +1,52 @@
 from __future__ import annotations
 
-import inspect
 import re
 import pathlib
 import sys
 import typing as t
 
-from ansible.module_utils.common.messages import PluginInfo
+from ansible.module_utils._internal import _stack, _messages, _validation
 
-_ansible_module_base_path: t.Final = pathlib.Path(sys.modules['ansible'].__file__).parent
-"""Runtime-detected base path of the `ansible` Python package to distinguish between Ansible-owned and external code."""
 
-ANSIBLE_CORE_DEPRECATOR: t.Final = PluginInfo._from_collection_name('ansible.builtin')
-"""Singleton `PluginInfo` instance for ansible-core callers where the plugin can/should not be identified in messages."""
+def deprecator_from_collection_name(collection_name: str | None) -> _messages.PluginInfo | None:
+    """Returns an instance with the special `collection` type to refer to a non-plugin or ambiguous caller within a collection."""
+    # CAUTION: This function is exposed in public API as ansible.module_utils.datatag.deprecator_from_collection_name.
 
-INDETERMINATE_DEPRECATOR: t.Final = PluginInfo(resolved_name='indeterminate', type='indeterminate')
-"""Singleton `PluginInfo` instance for indeterminate deprecator."""
+    if not collection_name:
+        return None
 
-_DEPRECATOR_PLUGIN_TYPES = frozenset(
-    {
-        'action',
-        'become',
-        'cache',
-        'callback',
-        'cliconf',
-        'connection',
-        # doc_fragments - no code execution
-        # filter - basename inadequate to identify plugin
-        'httpapi',
-        'inventory',
-        'lookup',
-        'module',  # only for collections
-        'netconf',
-        'shell',
-        'strategy',
-        'terminal',
-        # test - basename inadequate to identify plugin
-        'vars',
-    }
-)
-"""Plugin types which are valid for identifying a deprecator for deprecation purposes."""
+    _validation.validate_collection_name(collection_name)
 
-_AMBIGUOUS_DEPRECATOR_PLUGIN_TYPES = frozenset(
-    {
-        'filter',
-        'test',
-    }
-)
-"""Plugin types for which basename cannot be used to identify the plugin name."""
+    return _messages.PluginInfo(
+        resolved_name=collection_name,
+        type=_COLLECTION_ONLY_TYPE,
+    )
 
 
-def get_best_deprecator(*, deprecator: PluginInfo | None = None, collection_name: str | None = None) -> PluginInfo:
+def get_best_deprecator(*, deprecator: _messages.PluginInfo | None = None, collection_name: str | None = None) -> _messages.PluginInfo:
     """Return the best-available `PluginInfo` for the caller of this method."""
     _skip_stackwalk = True
 
     if deprecator and collection_name:
         raise ValueError('Specify only one of `deprecator` or `collection_name`.')
 
-    return deprecator or PluginInfo._from_collection_name(collection_name) or get_caller_plugin_info() or INDETERMINATE_DEPRECATOR
+    return deprecator or deprecator_from_collection_name(collection_name) or get_caller_plugin_info() or INDETERMINATE_DEPRECATOR
 
 
-def get_caller_plugin_info() -> PluginInfo | None:
+def get_caller_plugin_info() -> _messages.PluginInfo | None:
     """Try to get `PluginInfo` for the caller of this method, ignoring marked infrastructure stack frames."""
     _skip_stackwalk = True
 
-    if frame_info := next((frame_info for frame_info in inspect.stack() if '_skip_stackwalk' not in frame_info.frame.f_locals), None):
+    if frame_info := _stack.caller_frame():
         return _path_as_core_plugininfo(frame_info.filename) or _path_as_collection_plugininfo(frame_info.filename)
 
     return None  # pragma: nocover
 
 
-def _path_as_core_plugininfo(path: str) -> PluginInfo | None:
+def _path_as_core_plugininfo(path: str) -> _messages.PluginInfo | None:
     """Return a `PluginInfo` instance if the provided `path` refers to a core plugin."""
     try:
-        relpath = str(pathlib.Path(path).relative_to(_ansible_module_base_path))
+        relpath = str(pathlib.Path(path).relative_to(_ANSIBLE_MODULE_BASE_PATH))
     except ValueError:
         return None  # not ansible-core
 
@@ -104,10 +77,10 @@ def _path_as_core_plugininfo(path: str) -> PluginInfo | None:
 
     name = f'{namespace}.{plugin_name}'
 
-    return PluginInfo(resolved_name=name, type=plugin_type)
+    return _messages.PluginInfo(resolved_name=name, type=plugin_type)
 
 
-def _path_as_collection_plugininfo(path: str) -> PluginInfo | None:
+def _path_as_collection_plugininfo(path: str) -> _messages.PluginInfo | None:
     """Return a `PluginInfo` instance if the provided `path` refers to a collection plugin."""
     if not (match := re.search(r'/ansible_collections/(?P<ns>\w+)/(?P<coll>\w+)/plugins/(?P<plugin_type>\w+)/(?P<plugin_name>\w+)', path)):
         return None
@@ -118,7 +91,7 @@ def _path_as_collection_plugininfo(path: str) -> PluginInfo | None:
         # We're able to detect the namespace, collection and plugin type -- but we have no way to identify the plugin name currently.
         # To keep things simple we'll fall back to just identifying the namespace and collection.
         # In the future we could improve the detection and/or make it easier for a caller to identify the plugin name.
-        return PluginInfo._from_collection_name('.'.join((match.group('ns'), match.group('coll'))))
+        return deprecator_from_collection_name('.'.join((match.group('ns'), match.group('coll'))))
 
     if plugin_type == 'modules':
         plugin_type = 'module'
@@ -131,4 +104,49 @@ def _path_as_collection_plugininfo(path: str) -> PluginInfo | None:
 
     name = '.'.join((match.group('ns'), match.group('coll'), match.group('plugin_name')))
 
-    return PluginInfo(resolved_name=name, type=plugin_type)
+    return _messages.PluginInfo(resolved_name=name, type=plugin_type)
+
+
+_COLLECTION_ONLY_TYPE: t.Final = 'collection'
+"""Ersatz placeholder plugin type for use by a `PluginInfo` instance that references only a collection."""
+
+_ANSIBLE_MODULE_BASE_PATH: t.Final = pathlib.Path(sys.modules['ansible'].__file__).parent
+"""Runtime-detected base path of the `ansible` Python package to distinguish between Ansible-owned and external code."""
+
+ANSIBLE_CORE_DEPRECATOR: t.Final = deprecator_from_collection_name('ansible.builtin')
+"""Singleton `PluginInfo` instance for ansible-core callers where the plugin can/should not be identified in messages."""
+
+INDETERMINATE_DEPRECATOR: t.Final = _messages.PluginInfo(resolved_name='indeterminate', type='indeterminate')
+"""Singleton `PluginInfo` instance for indeterminate deprecator."""
+
+_DEPRECATOR_PLUGIN_TYPES: t.Final = frozenset(
+    {
+        'action',
+        'become',
+        'cache',
+        'callback',
+        'cliconf',
+        'connection',
+        # doc_fragments - no code execution
+        # filter - basename inadequate to identify plugin
+        'httpapi',
+        'inventory',
+        'lookup',
+        'module',  # only for collections
+        'netconf',
+        'shell',
+        'strategy',
+        'terminal',
+        # test - basename inadequate to identify plugin
+        'vars',
+    }
+)
+"""Plugin types which are valid for identifying a deprecator for deprecation purposes."""
+
+_AMBIGUOUS_DEPRECATOR_PLUGIN_TYPES: t.Final = frozenset(
+    {
+        'filter',
+        'test',
+    }
+)
+"""Plugin types for which basename cannot be used to identify the plugin name."""

ansible/module_utils/_internal/_errors.py

@@ -3,28 +3,99 @@
 
 """Internal error handling logic for targets. Not for use on the controller."""
 
-from __future__ import annotations
+from __future__ import annotations as _annotations
 
-from . import _traceback
-from ..common.messages import Detail, ErrorSummary
+import traceback as _sys_traceback
+import typing as _t
 
+from . import _messages
 
-def create_error_summary(exception: BaseException) -> ErrorSummary:
-    """Return an `ErrorDetail` created from the given exception."""
-    return ErrorSummary(
-        details=_create_error_details(exception),
-        formatted_traceback=_traceback.maybe_extract_traceback(exception, _traceback.TracebackEvent.ERROR),
-    )
+MSG_REASON_DIRECT_CAUSE: _t.Final[str] = '<<< caused by >>>'
+MSG_REASON_HANDLING_CAUSE: _t.Final[str] = '<<< while handling >>>'
 
+TRACEBACK_REASON_EXCEPTION_DIRECT_WARNING: _t.Final[str] = 'The above exception was the direct cause of the following warning:'
 
-def _create_error_details(exception: BaseException) -> tuple[Detail, ...]:
-    """Return an `ErrorMessage` tuple created from the given exception."""
-    target_exception: BaseException | None = exception
-    error_details: list[Detail] = []
 
-    while target_exception:
-        error_details.append(Detail(msg=str(target_exception).strip()))
+class EventFactory:
+    """Factory for creating `Event` instances from `BaseException` instances on targets."""
 
-        target_exception = target_exception.__cause__
+    _MAX_DEPTH = 10
+    """Maximum exception chain depth. Exceptions beyond this depth will be omitted."""
 
-    return tuple(error_details)
+    @classmethod
+    def from_exception(cls, exception: BaseException, include_traceback: bool) -> _messages.Event:
+        return cls(include_traceback)._convert_exception(exception)
+
+    def __init__(self, include_traceback: bool) -> None:
+        self._include_traceback = include_traceback
+        self._depth = 0
+
+    def _convert_exception(self, exception: BaseException) -> _messages.Event:
+        if self._depth > self._MAX_DEPTH:
+            return _messages.Event(
+                msg="Maximum depth exceeded, omitting further events.",
+            )
+
+        self._depth += 1
+
+        try:
+            return _messages.Event(
+                msg=self._get_msg(exception),
+                formatted_traceback=self._get_formatted_traceback(exception),
+                formatted_source_context=self._get_formatted_source_context(exception),
+                help_text=self._get_help_text(exception),
+                chain=self._get_chain(exception),
+                events=self._get_events(exception),
+            )
+        finally:
+            self._depth -= 1
+
+    def _get_msg(self, exception: BaseException) -> str | None:
+        return str(exception).strip()
+
+    def _get_formatted_traceback(self, exception: BaseException) -> str | None:
+        if self._include_traceback:
+            return ''.join(_sys_traceback.format_exception(type(exception), exception, exception.__traceback__, chain=False))
+
+        return None
+
+    def _get_formatted_source_context(self, exception: BaseException) -> str | None:
+        return None
+
+    def _get_help_text(self, exception: BaseException) -> str | None:
+        return None
+
+    def _get_chain(self, exception: BaseException) -> _messages.EventChain | None:
+        if cause := self._get_cause(exception):
+            return _messages.EventChain(
+                msg_reason=MSG_REASON_DIRECT_CAUSE,
+                traceback_reason='The above exception was the direct cause of the following exception:',
+                event=self._convert_exception(cause),
+                follow=self._follow_cause(exception),
+            )
+
+        if context := self._get_context(exception):
+            return _messages.EventChain(
+                msg_reason=MSG_REASON_HANDLING_CAUSE,
+                traceback_reason='During handling of the above exception, another exception occurred:',
+                event=self._convert_exception(context),
+                follow=False,
+            )
+
+        return None
+
+    def _follow_cause(self, exception: BaseException) -> bool:
+        return True
+
+    def _get_cause(self, exception: BaseException) -> BaseException | None:
+        return exception.__cause__
+
+    def _get_context(self, exception: BaseException) -> BaseException | None:
+        if exception.__suppress_context__:
+            return None
+
+        return exception.__context__
+
+    def _get_events(self, exception: BaseException) -> tuple[_messages.Event, ...] | None:
+        # deprecated: description='move BaseExceptionGroup support here from ControllerEventFactory' python_version='3.10'
+        return None

ansible/module_utils/_internal/_event_utils.py

@@ -0,0 +1,61 @@
+from __future__ import annotations as _annotations
+
+import typing as _t
+
+from ansible.module_utils._internal import _text_utils, _messages
+
+
+def deduplicate_message_parts(message_parts: list[str]) -> str:
+    """Format the given list of messages into a brief message, while deduplicating repeated elements."""
+    message_parts = list(reversed(message_parts))
+
+    message = message_parts.pop(0)
+
+    for message_part in message_parts:
+        # avoid duplicate messages where the cause was already concatenated to the exception message
+        if message_part.endswith(message):
+            message = message_part
+        else:
+            message = _text_utils.concat_message(message_part, message)
+
+    return message
+
+
+def format_event_brief_message(event: _messages.Event) -> str:
+    """
+    Format an event into a brief message.
+    Help text, contextual information and sub-events will be omitted.
+    """
+    message_parts: list[str] = []
+
+    while True:
+        message_parts.append(event.msg)
+
+        if not event.chain or not event.chain.follow:
+            break
+
+        event = event.chain.event
+
+    return deduplicate_message_parts(message_parts)
+
+
+def deprecation_as_dict(deprecation: _messages.DeprecationSummary) -> _t.Dict[str, _t.Any]:
+    """Returns a dictionary representation of the deprecation object in the format exposed to playbooks."""
+    from ansible.module_utils._internal._deprecator import INDETERMINATE_DEPRECATOR  # circular import from messages
+
+    if deprecation.deprecator and deprecation.deprecator != INDETERMINATE_DEPRECATOR:
+        collection_name = '.'.join(deprecation.deprecator.resolved_name.split('.')[:2])
+    else:
+        collection_name = None
+
+    result = dict(
+        msg=format_event_brief_message(deprecation.event),
+        collection_name=collection_name,
+    )
+
+    if deprecation.date:
+        result.update(date=deprecation.date)
+    else:
+        result.update(version=deprecation.version)
+
+    return result

ansible/module_utils/_internal/_json/_profiles/__init__.py

@@ -6,7 +6,7 @@ import json
 import typing as t
 
 from ansible.module_utils import _internal
-from ansible.module_utils.common import messages as _messages
+from ansible.module_utils._internal import _messages
 from ansible.module_utils._internal._datatag import (
     AnsibleSerializable,
     AnsibleSerializableWrapper,
@@ -87,7 +87,8 @@ For controller-to-module, type behavior is profile dependent.
 _common_module_response_types: frozenset[type[AnsibleSerializable]] = frozenset(
     {
         _messages.PluginInfo,
-        _messages.Detail,
+        _messages.Event,
+        _messages.EventChain,
         _messages.ErrorSummary,
         _messages.WarningSummary,
         _messages.DeprecationSummary,
@@ -203,11 +204,27 @@ class _JSONSerializationProfile(t.Generic[_T_encoder, _T_decoder]):
 
     @classmethod
     def handle_key(cls, k: t.Any) -> t.Any:
+        """Validation/conversion hook before a dict key is serialized. The default implementation only accepts str-typed keys."""
+        # NOTE: Since JSON requires string keys, there is no support for preserving tags on dictionary keys during serialization.
+
         if not isinstance(k, str):  # DTFIX-FUTURE: optimize this to use all known str-derived types in type map / allowed types
             raise TypeError(f'Key of type {type(k).__name__!r} is not JSON serializable by the {cls.profile_name!r} profile.')
 
         return k
 
+    @classmethod
+    def _handle_key_str_fallback(cls, k: t.Any) -> t.Any:
+        """Legacy implementations should use this key handler for backward compatibility with stdlib JSON key conversion quirks."""
+        # DTFIX-FUTURE: optimized exact-type table lookup first
+
+        if isinstance(k, str):
+            return k
+
+        if k is None or isinstance(k, (int, float)):
+            return json.dumps(k)
+
+        raise TypeError(f'Key of type {type(k).__name__!r} is not JSON serializable by the {cls.profile_name!r} profile.')
+
     @classmethod
     def default(cls, o: t.Any) -> t.Any:
         # Preserve the built-in JSON encoder support for subclasses of scalar types.
@@ -373,8 +390,8 @@ Future code changes should further restrict bytes to string conversions to elimi
 Additional warnings at other boundaries may be needed to give users an opportunity to resolve the issues before they become errors.
 """
 # DTFIX-FUTURE: add strict UTF8 string encoding checking to serialization profiles (to match the checks performed during deserialization)
-# DTFIX-RELEASE: the surrogateescape note above isn't quite right, for encoding use surrogatepass, which does work
-# DTFIX-RELEASE: this config setting should probably be deprecated
+# DTFIX3: the surrogateescape note above isn't quite right, for encoding use surrogatepass, which does work
+# DTFIX-FUTURE: this config setting should probably be deprecated
 
 
 def _create_encoding_check_error() -> Exception:

ansible/module_utils/_internal/_json/_profiles/_module_legacy_c2m.py

@@ -22,6 +22,8 @@ class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
             }
         )
 
+        cls.handle_key = cls._handle_key_str_fallback  # type: ignore[method-assign]  # legacy stdlib-compatible key behavior
+
 
 class Encoder(_profiles.AnsibleProfileJSONEncoder):
     _profile = _Profile

ansible/module_utils/_internal/_json/_profiles/_module_legacy_m2c.py

@@ -26,6 +26,8 @@ class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
             _datetime.datetime: cls.serialize_as_isoformat,  # legacy _json_encode_fallback behavior *and* legacy parameters.py does this before serialization
         }
 
+        cls.handle_key = cls._handle_key_str_fallback  # type: ignore[method-assign]  # legacy stdlib-compatible key behavior
+
 
 class Encoder(_profiles.AnsibleProfileJSONEncoder):
     _profile = _Profile

ansible/module_utils/_internal/_json/_profiles/_tagless.py

@@ -17,7 +17,7 @@ class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
     @classmethod
     def post_init(cls) -> None:
         cls.serialize_map = {
-            # DTFIX-RELEASE: support serialization of every type that is supported in the Ansible variable type system
+            # DTFIX5: support serialization of every type that is supported in the Ansible variable type system
             set: cls.serialize_as_list,
             tuple: cls.serialize_as_list,
             _datetime.date: cls.serialize_as_isoformat,
@@ -41,6 +41,8 @@ class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
             '__ansible_vault': _functools.partial(cls.unsupported_target_type_error, '__ansible_vault'),
         }
 
+        cls.handle_key = cls._handle_key_str_fallback  # type: ignore[method-assign]  # legacy stdlib-compatible key behavior
+
 
 class Encoder(_profiles.AnsibleProfileJSONEncoder):
     _profile = _Profile