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

ansible/executor/module_common.py

@@ -37,6 +37,8 @@ from ast import AST, Import, ImportFrom
 from io import BytesIO
 
 from ansible._internal import _locking
+from ansible._internal._ansiballz import _builder
+from ansible._internal import _ansiballz
 from ansible._internal._datatag import _utils
 from ansible.module_utils._internal import _dataclass_validation
 from ansible.module_utils.common.yaml import yaml_load
@@ -54,7 +56,8 @@ from ansible.plugins.loader import module_utils_loader
 from ansible._internal._templating._engine import TemplateOptions, TemplateEngine
 from ansible.template import Templar
 from ansible.utils.collection_loader._collection_finder import _get_collection_metadata, _nested_dict_get
-from ansible.module_utils._internal import _json, _ansiballz
+from ansible.module_utils._internal import _json
+from ansible.module_utils._internal._ansiballz import _loader
 from ansible.module_utils import basic as _basic
 
 if t.TYPE_CHECKING:
@@ -117,7 +120,7 @@ def _strip_comments(source: str) -> str:
 
 
 def _read_ansiballz_code() -> str:
-    code = (pathlib.Path(__file__).parent.parent / '_internal/_ansiballz.py').read_text()
+    code = (pathlib.Path(_ansiballz.__file__).parent / '_wrapper.py').read_text()
 
     if not C.DEFAULT_KEEP_REMOTE_FILES:
         # Keep comments when KEEP_REMOTE_FILES is set.  That way users will see
@@ -709,7 +712,14 @@ def _get_module_metadata(module: ast.Module) -> ModuleMetadata:
     return metadata
 
 
-def recursive_finder(name: str, module_fqn: str, module_data: str | bytes, zf: zipfile.ZipFile, date_time: datetime.datetime) -> ModuleMetadata:
+def recursive_finder(
+    name: str,
+    module_fqn: str,
+    module_data: str | bytes,
+    zf: zipfile.ZipFile,
+    date_time: datetime.datetime,
+    extension_manager: _builder.ExtensionManager,
+) -> ModuleMetadata:
     """
     Using ModuleDepFinder, make sure we have all of the module_utils files that
     the module and its module_utils files needs. (no longer actually recursive)
@@ -755,12 +765,14 @@ def recursive_finder(name: str, module_fqn: str, module_data: str | bytes, zf: z
 
     # include module_utils that are always required
     modules_to_process.extend((
-        _ModuleUtilsProcessEntry.from_module(_ansiballz),
+        _ModuleUtilsProcessEntry.from_module(_loader),
         _ModuleUtilsProcessEntry.from_module(_basic),
         _ModuleUtilsProcessEntry.from_module_name(_json.get_module_serialization_profile_module_name(profile, True)),
         _ModuleUtilsProcessEntry.from_module_name(_json.get_module_serialization_profile_module_name(profile, False)),
     ))
 
+    modules_to_process.extend(_ModuleUtilsProcessEntry.from_module_name(name) for name in extension_manager.module_names)
+
     module_info: ModuleUtilLocatorBase
 
     # we'll be adding new modules inline as we discover them, so just keep going til we've processed them all
@@ -815,12 +827,13 @@ def recursive_finder(name: str, module_fqn: str, module_data: str | bytes, zf: z
                 modules_to_process.append(_ModuleUtilsProcessEntry(normalized_name, False, module_info.redirected, is_optional=entry.is_optional))
 
     for py_module_name in py_module_cache:
-        py_module_file_name = py_module_cache[py_module_name][1]
+        source_code, py_module_file_name = py_module_cache[py_module_name]
+
+        zf.writestr(_make_zinfo(py_module_file_name, date_time, zf=zf), source_code)
+
+        if extension_manager.debugger_enabled and (origin := Origin.get_tag(source_code)) and origin.path:
+            extension_manager.source_mapping[origin.path] = py_module_file_name
 
-        zf.writestr(
-            _make_zinfo(py_module_file_name, date_time, zf=zf),
-            py_module_cache[py_module_name][0]
-        )
         mu_file = to_text(py_module_file_name, errors='surrogate_or_strict')
         display.vvvvv("Including module_utils file %s" % mu_file)
 
@@ -879,17 +892,27 @@ def _get_ansible_module_fqn(module_path):
     return remote_module_fqn
 
 
-def _add_module_to_zip(zf: zipfile.ZipFile, date_time: datetime.datetime, remote_module_fqn: str, b_module_data: bytes) -> None:
+def _add_module_to_zip(
+    zf: zipfile.ZipFile,
+    date_time: datetime.datetime,
+    remote_module_fqn: str,
+    b_module_data: bytes,
+    module_path: str,
+    extension_manager: _builder.ExtensionManager,
+) -> None:
     """Add a module from ansible or from an ansible collection into the module zip"""
     module_path_parts = remote_module_fqn.split('.')
 
     # Write the module
-    module_path = '/'.join(module_path_parts) + '.py'
+    zip_module_path = '/'.join(module_path_parts) + '.py'
     zf.writestr(
-        _make_zinfo(module_path, date_time, zf=zf),
+        _make_zinfo(zip_module_path, date_time, zf=zf),
         b_module_data
     )
 
+    if extension_manager.debugger_enabled:
+        extension_manager.source_mapping[module_path] = zip_module_path
+
     existing_paths: frozenset[str]
 
     # Write the __init__.py's necessary to get there
@@ -932,6 +955,8 @@ class _CachedModule:
 
     zip_data: bytes
     metadata: ModuleMetadata
+    source_mapping: dict[str, str]
+    """A mapping of controller absolute source locations to target relative source locations within the AnsiballZ payload."""
 
     def dump(self, path: str) -> None:
         temp_path = pathlib.Path(path + '-part')
@@ -1029,6 +1054,7 @@ def _find_module_utils(
 
     if module_substyle == 'python':
         date_time = datetime.datetime.now(datetime.timezone.utc)
+
         if date_time.year < 1980:
             raise AnsibleError(f'Cannot create zipfile due to pre-1980 configured date: {date_time}')
 
@@ -1038,19 +1064,19 @@ def _find_module_utils(
             display.warning(u'Bad module compression string specified: %s.  Using ZIP_STORED (no compression)' % module_compression)
             compression_method = zipfile.ZIP_STORED
 
+        extension_manager = _builder.ExtensionManager.create(task_vars=task_vars)
+        extension_key = '~'.join(extension_manager.extension_names) if extension_manager.extension_names else 'none'
         lookup_path = os.path.join(C.DEFAULT_LOCAL_TMP, 'ansiballz_cache')  # type: ignore[attr-defined]
-        cached_module_filename = os.path.join(lookup_path, "%s-%s" % (remote_module_fqn, module_compression))
+        cached_module_filename = os.path.join(lookup_path, '-'.join((remote_module_fqn, module_compression, extension_key)))
 
         os.makedirs(os.path.dirname(cached_module_filename), exist_ok=True)
 
-        zipdata: bytes | None = None
-        module_metadata: ModuleMetadata | None = None
+        cached_module: _CachedModule | None = None
 
         # Optimization -- don't lock if the module has already been cached
         if os.path.exists(cached_module_filename):
             display.debug('ANSIBALLZ: using cached module: %s' % cached_module_filename)
             cached_module = _CachedModule.load(cached_module_filename)
-            zipdata, module_metadata = cached_module.zip_data, cached_module.metadata
         else:
             display.debug('ANSIBALLZ: Acquiring lock')
             lock_path = f'{cached_module_filename}.lock'
@@ -1065,35 +1091,40 @@ def _find_module_utils(
                     zf = zipfile.ZipFile(zipoutput, mode='w', compression=compression_method)
 
                     # walk the module imports, looking for module_utils to send- they'll be added to the zipfile
-                    module_metadata = recursive_finder(module_name, remote_module_fqn, Origin(path=module_path).tag(b_module_data), zf, date_time)
+                    module_metadata = recursive_finder(
+                        module_name,
+                        remote_module_fqn,
+                        Origin(path=module_path).tag(b_module_data),
+                        zf,
+                        date_time,
+                        extension_manager,
+                    )
 
                     display.debug('ANSIBALLZ: Writing module into payload')
-                    _add_module_to_zip(zf, date_time, remote_module_fqn, b_module_data)
+                    _add_module_to_zip(zf, date_time, remote_module_fqn, b_module_data, module_path, extension_manager)
 
                     zf.close()
-                    zipdata = base64.b64encode(zipoutput.getvalue())
+                    zip_data = base64.b64encode(zipoutput.getvalue())
 
                     # Write the assembled module to a temp file (write to temp
                     # so that no one looking for the file reads a partially
                     # written file)
                     os.makedirs(lookup_path, exist_ok=True)
                     display.debug('ANSIBALLZ: Writing module')
-                    cached_module = _CachedModule(zip_data=zipdata, metadata=module_metadata)
+                    cached_module = _CachedModule(zip_data=zip_data, metadata=module_metadata, source_mapping=extension_manager.source_mapping)
                     cached_module.dump(cached_module_filename)
                     display.debug('ANSIBALLZ: Done creating module')
 
-            if not zipdata:
+            if not cached_module:
                 display.debug('ANSIBALLZ: Reading module after lock')
                 # Another process wrote the file while we were waiting for
                 # the write lock.  Go ahead and read the data from disk
                 # instead of re-creating it.
                 try:
                     cached_module = _CachedModule.load(cached_module_filename)
-                except IOError:
+                except OSError as ex:
                     raise AnsibleError('A different worker process failed to create module file. '
-                                       'Look at traceback for that process for debugging information.')
-
-                zipdata, module_metadata = cached_module.zip_data, cached_module.metadata
+                                       'Look at traceback for that process for debugging information.') from ex
 
         o_interpreter, o_args = _extract_interpreter(b_module_data)
         if o_interpreter is None:
@@ -1107,40 +1138,36 @@ def _find_module_utils(
         if not isinstance(rlimit_nofile, int):
             rlimit_nofile = int(templar._engine.template(rlimit_nofile, options=TemplateOptions(value_for_omit=0)))
 
-        coverage_config = os.environ.get('_ANSIBLE_COVERAGE_CONFIG')
-
-        if coverage_config:
-            coverage_output = os.environ['_ANSIBLE_COVERAGE_OUTPUT']
-        else:
-            coverage_output = None
-
-        if not isinstance(module_metadata, ModuleMetadataV1):
+        if not isinstance(cached_module.metadata, ModuleMetadataV1):
             raise NotImplementedError()
 
         params = dict(ANSIBLE_MODULE_ARGS=module_args,)
-        encoder = get_module_encoder(module_metadata.serialization_profile, Direction.CONTROLLER_TO_MODULE)
+        encoder = get_module_encoder(cached_module.metadata.serialization_profile, Direction.CONTROLLER_TO_MODULE)
+
         try:
             encoded_params = json.dumps(params, cls=encoder)
         except TypeError as ex:
             raise AnsibleError(f'Failed to serialize arguments for the {module_name!r} module.') from ex
 
+        extension_manager.source_mapping = cached_module.source_mapping
+
         code = _get_ansiballz_code(shebang)
         args = dict(
-            zipdata=to_text(zipdata),
             ansible_module=module_name,
             module_fqn=remote_module_fqn,
-            params=encoded_params,
-            profile=module_metadata.serialization_profile,
+            profile=cached_module.metadata.serialization_profile,
             date_time=date_time,
-            coverage_config=coverage_config,
-            coverage_output=coverage_output,
             rlimit_nofile=rlimit_nofile,
+            params=encoded_params,
+            extensions=extension_manager.get_extensions(),
+            zip_data=to_text(cached_module.zip_data),
         )
 
         args_string = '\n'.join(f'{key}={value!r},' for key, value in args.items())
 
         wrapper = f"""{code}
 
+
 if __name__ == "__main__":
     _ansiballz_main(
 {args_string}
@@ -1149,6 +1176,7 @@ if __name__ == "__main__":
 
         output.write(to_bytes(wrapper))
 
+        module_metadata = cached_module.metadata
         b_module_data = output.getvalue()
 
     elif module_substyle == 'powershell':

ansible/executor/process/worker.py

@@ -138,8 +138,8 @@ class WorkerProcess(multiprocessing_context.Process):  # type: ignore[name-defin
         try:
             display.debug(u"WORKER HARD EXIT: %s" % to_text(e))
         except BaseException:
-            # If the cause of the fault is IOError being generated by stdio,
-            # attempting to log a debug message may trigger another IOError.
+            # If the cause of the fault is OSError being generated by stdio,
+            # attempting to log a debug message may trigger another OSError.
             # Try printing once then give up.
             pass
 

ansible/galaxy/api.py

@@ -337,10 +337,7 @@ class GalaxyAPI:
         if not isinstance(other_galaxy_api, self.__class__):
             return NotImplemented
 
-        return (
-            self._priority > other_galaxy_api._priority or
-            self.name < self.name
-        )
+        return self._priority > other_galaxy_api._priority
 
     @property  # type: ignore[misc]  # https://github.com/python/mypy/issues/1362
     @g_connect(['v1', 'v2', 'v3'])

ansible/galaxy/collection/__init__.py

@@ -5,7 +5,6 @@
 
 from __future__ import annotations
 
-import errno
 import fnmatch
 import functools
 import glob
@@ -1689,11 +1688,7 @@ def _extract_tar_dir(tar, dirname, b_dest):
     b_dir_path = os.path.join(b_dest, to_bytes(dirname, errors='surrogate_or_strict'))
 
     b_parent_path = os.path.dirname(b_dir_path)
-    try:
-        os.makedirs(b_parent_path, mode=S_IRWXU_RXG_RXO)
-    except OSError as e:
-        if e.errno != errno.EEXIST:
-            raise
+    os.makedirs(b_parent_path, mode=S_IRWXU_RXG_RXO, exist_ok=True)
 
     if tar_member.type == tarfile.SYMTYPE:
         b_link_path = to_bytes(tar_member.linkname, errors='surrogate_or_strict')

ansible/galaxy/collection/concrete_artifact_manager.py

@@ -656,14 +656,8 @@ def _get_json_from_installed_dir(
     try:
         with open(b_json_filepath, 'rb') as manifest_fd:
             b_json_text = manifest_fd.read()
-    except (IOError, OSError):
-        raise LookupError(
-            "The collection {manifest!s} path '{path!s}' does not exist.".
-            format(
-                manifest=filename,
-                path=to_native(b_json_filepath),
-            )
-        )
+    except OSError as ex:
+        raise LookupError(f"The collection {filename!r} path {to_text(b_json_filepath)!r} does not exist.") from ex
 
     manifest_txt = to_text(b_json_text, errors='surrogate_or_strict')
 

ansible/galaxy/role.py

@@ -438,8 +438,8 @@ class GalaxyRole(object):
                 if not (self.src and os.path.isfile(self.src)):
                     try:
                         os.unlink(tmp_file)
-                    except (OSError, IOError) as e:
-                        display.warning(u"Unable to remove tmp file (%s): %s" % (tmp_file, to_text(e)))
+                    except OSError as ex:
+                        display.error_as_warning(f"Unable to remove tmp file {tmp_file!r}.", exception=ex)
                 return True
 
         return False

ansible/module_utils/_internal/__init__.py

@@ -4,6 +4,9 @@ import collections.abc as c
 
 import typing as t
 
+if t.TYPE_CHECKING:
+    from ansible.module_utils.compat.typing import TypeGuard
+
 
 INTERMEDIATE_MAPPING_TYPES = (c.Mapping,)
 """
@@ -18,18 +21,18 @@ These will be converted to a simple Python `list` before serialization or storag
 CAUTION: Scalar types which are sequences should be excluded when using this.
 """
 
-ITERABLE_SCALARS_NOT_TO_ITERATE_FIXME = (str, bytes)
+ITERABLE_SCALARS_NOT_TO_ITERATE = (str, bytes)
 """Scalars which are also iterable, and should thus be excluded from iterable checks."""
 
 
-def is_intermediate_mapping(value: object) -> bool:
+def is_intermediate_mapping(value: object) -> TypeGuard[c.Mapping]:
     """Returns `True` if `value` is a type supported for projection to a Python `dict`, otherwise returns `False`."""
     return isinstance(value, INTERMEDIATE_MAPPING_TYPES)
 
 
-def is_intermediate_iterable(value: object) -> bool:
+def is_intermediate_iterable(value: object) -> TypeGuard[c.Iterable]:
     """Returns `True` if `value` is a type supported for projection to a Python `list`, otherwise returns `False`."""
-    return isinstance(value, INTERMEDIATE_ITERABLE_TYPES) and not isinstance(value, ITERABLE_SCALARS_NOT_TO_ITERATE_FIXME)
+    return isinstance(value, INTERMEDIATE_ITERABLE_TYPES) and not isinstance(value, ITERABLE_SCALARS_NOT_TO_ITERATE)
 
 
 is_controller: bool = False

ansible/module_utils/_internal/_ansiballz/_extensions/_coverage.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import atexit
+import dataclasses
+import importlib.util
+import os
+import sys
+
+import typing as t
+
+
+@dataclasses.dataclass(frozen=True)
+class Options:
+    """Code coverage options."""
+
+    config: str
+    output: str | None
+
+
+def run(args: dict[str, t.Any]) -> None:  # pragma: nocover
+    """Bootstrap `coverage` for the current Ansible module invocation."""
+    options = Options(**args)
+
+    if options.output:
+        # Enable code coverage analysis of the module.
+        # This feature is for internal testing and may change without notice.
+        python_version_string = '.'.join(str(v) for v in sys.version_info[:2])
+        os.environ['COVERAGE_FILE'] = f'{options.output}=python-{python_version_string}=coverage'
+
+        import coverage
+
+        cov = coverage.Coverage(config_file=options.config)
+
+        def atexit_coverage() -> None:
+            cov.stop()
+            cov.save()
+
+        atexit.register(atexit_coverage)
+
+        cov.start()
+    else:
+        # Verify coverage is available without importing it.
+        # This will detect when a module would fail with coverage enabled with minimal overhead.
+        if importlib.util.find_spec('coverage') is None:
+            raise RuntimeError('Could not find the `coverage` Python module.')

ansible/module_utils/_internal/_ansiballz/_extensions/_pydevd.py

@@ -0,0 +1,62 @@
+"""
+Remote debugging support for AnsiballZ modules.
+
+To use with PyCharm:
+
+1) Choose an available port for PyCharm to listen on (e.g. 5678).
+2) Create a Python Debug Server using that port.
+3) Start the Python Debug Server.
+4) Ensure the correct version of `pydevd-pycharm` is installed for the interpreter(s) which will run the code being debugged.
+5) Configure Ansible with the `_ANSIBALLZ_DEBUGGER_CONFIG` option.
+   See `Options` below for the structure of the debugger configuration.
+   Example configuration using an environment variable:
+     export _ANSIBLE_ANSIBALLZ_DEBUGGER_CONFIG='{"module": "pydevd_pycharm", "settrace": {"host": "localhost", "port": 5678, "suspend": false}}'
+6) Set any desired breakpoints.
+7) Run Ansible commands.
+
+A similar process should work for other pydevd based debuggers, such as Visual Studio Code, but they have not been tested.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import importlib
+import json
+import os
+import pathlib
+
+import typing as t
+
+
+@dataclasses.dataclass(frozen=True)
+class Options:
+    """Debugger options for pydevd and its derivatives."""
+
+    module: str = 'pydevd'
+    """The Python module which will be imported and which provides the `settrace` method."""
+    settrace: dict[str, object] = dataclasses.field(default_factory=dict)
+    """The options to pass to the `{module}.settrace` method."""
+    source_mapping: dict[str, str] = dataclasses.field(default_factory=dict)
+    """
+    A mapping of source paths to provide to pydevd.
+    This setting is used internally by AnsiballZ and is not required unless Ansible CLI commands are run from a different system than your IDE.
+    In that scenario, use this setting instead of configuring source mapping in your IDE.
+    The key is a path known to the IDE.
+    The value is the same path as known to the Ansible CLI.
+    Both file paths and directories are supported.
+    """
+
+
+def run(args: dict[str, t.Any]) -> None:  # pragma: nocover
+    """Enable remote debugging."""
+
+    options = Options(**args)
+    temp_dir = pathlib.Path(__file__).parent.parent.parent.parent.parent.parent
+    path_mapping = [[key, str(temp_dir / value)] for key, value in options.source_mapping.items()]
+
+    os.environ['PATHS_FROM_ECLIPSE_TO_PYTHON'] = json.dumps(path_mapping)
+
+    debugging_module = importlib.import_module(options.module)
+    debugging_module.settrace(**options.settrace)
+
+    pass  # when suspend is True, execution pauses here -- it's also a convenient place to put a breakpoint

ansible/module_utils/_internal/{_ansiballz.py → _ansiballz/_loader.py}

@@ -5,17 +5,15 @@
 
 from __future__ import annotations
 
-import atexit
-import importlib.util
+import importlib
 import json
-import os
 import runpy
 import sys
 import typing as t
 
-from . import _errors, _traceback, _messages
-from .. import basic
-from ..common.json import get_module_encoder, Direction
+from ansible.module_utils import basic
+from ansible.module_utils._internal import _errors, _traceback, _messages, _ansiballz
+from ansible.module_utils.common.json import get_module_encoder, Direction
 
 
 def run_module(
@@ -24,13 +22,16 @@ def run_module(
     profile: str,
     module_fqn: str,
     modlib_path: str,
+    extensions: dict[str, dict[str, object]],
     init_globals: dict[str, t.Any] | None = None,
-    coverage_config: str | None = None,
-    coverage_output: str | None = None,
 ) -> None:  # pragma: nocover
     """Used internally by the AnsiballZ wrapper to run an Ansible module."""
     try:
-        _enable_coverage(coverage_config, coverage_output)
+        for extension, args in extensions.items():
+            # importing _ansiballz instead of _extensions avoids an unnecessary import when extensions are not in use
+            extension_module = importlib.import_module(f'{_ansiballz.__name__}._extensions.{extension}')
+            extension_module.run(args)
+
         _run_module(
             json_params=json_params,
             profile=profile,
@@ -42,35 +43,6 @@ def run_module(
         _handle_exception(ex, profile)
 
 
-def _enable_coverage(coverage_config: str | None, coverage_output: str | None) -> None:  # pragma: nocover
-    """Bootstrap `coverage` for the current Ansible module invocation."""
-    if not coverage_config:
-        return
-
-    if coverage_output:
-        # Enable code coverage analysis of the module.
-        # This feature is for internal testing and may change without notice.
-        python_version_string = '.'.join(str(v) for v in sys.version_info[:2])
-        os.environ['COVERAGE_FILE'] = f'{coverage_output}=python-{python_version_string}=coverage'
-
-        import coverage
-
-        cov = coverage.Coverage(config_file=coverage_config)
-
-        def atexit_coverage():
-            cov.stop()
-            cov.save()
-
-        atexit.register(atexit_coverage)
-
-        cov.start()
-    else:
-        # Verify coverage is available without importing it.
-        # This will detect when a module would fail with coverage enabled with minimal overhead.
-        if importlib.util.find_spec('coverage') is None:
-            raise RuntimeError('Could not find the `coverage` Python module.')
-
-
 def _run_module(
     *,
     json_params: bytes,

ansible/module_utils/_internal/_ansiballz/_respawn.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import inspect
+import sys
+
+from ... import basic
+from . import _respawn_wrapper
+
+
+def create_payload() -> str:
+    """Create and return an AnsiballZ payload for respawning a module."""
+    main = sys.modules['__main__']
+    code = inspect.getsource(_respawn_wrapper)
+
+    args = dict(
+        module_fqn=main._module_fqn,
+        modlib_path=main._modlib_path,
+        profile=basic._ANSIBLE_PROFILE,
+        json_params=basic._ANSIBLE_ARGS,
+    )
+
+    args_string = '\n'.join(f'{key}={value!r},' for key, value in args.items())
+
+    wrapper = f"""{code}
+
+if __name__ == "__main__":
+    _respawn_main(
+{args_string}
+)
+"""
+
+    return wrapper

ansible/module_utils/_internal/_ansiballz/_respawn_wrapper.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+
+def _respawn_main(
+    json_params: bytes,
+    profile: str,
+    module_fqn: str,
+    modlib_path: str,
+) -> None:
+    import sys
+
+    sys.path.insert(0, modlib_path)
+
+    from ansible.module_utils._internal._ansiballz import _loader
+
+    _loader.run_module(
+        json_params=json_params,
+        profile=profile,
+        module_fqn=module_fqn,
+        modlib_path=modlib_path,
+        extensions={},
+        init_globals=dict(_respawned=True),
+    )

ansible/module_utils/_internal/_datatag/__init__.py

@@ -5,6 +5,7 @@ import collections.abc as c
 import copy
 import dataclasses
 import datetime
+import enum
 import inspect
 import sys
 
@@ -216,7 +217,7 @@ class AnsibleTagHelper:
             return value
 
 
-class AnsibleSerializable(metaclass=abc.ABCMeta):
+class AnsibleSerializable:
     __slots__ = _NO_INSTANCE_STORAGE
 
     _known_type_map: t.ClassVar[t.Dict[str, t.Type['AnsibleSerializable']]] = {}
@@ -274,6 +275,27 @@ class AnsibleSerializable(metaclass=abc.ABCMeta):
         return f'{name}({arg_string})'
 
 
+class AnsibleSerializableEnum(AnsibleSerializable, enum.Enum):
+    """Base class for serializable enumerations."""
+
+    def _as_dict(self) -> t.Dict[str, t.Any]:
+        return dict(value=self.value)
+
+    @classmethod
+    def _from_dict(cls, d: t.Dict[str, t.Any]) -> t.Self:
+        return cls(d['value'].lower())
+
+    def __str__(self) -> str:
+        return self.value
+
+    def __repr__(self) -> str:
+        return f'<{self.__class__.__name__}.{self.name}>'
+
+    @staticmethod
+    def _generate_next_value_(name, start, count, last_values):
+        return name.lower()
+
+
 class AnsibleSerializableWrapper(AnsibleSerializable, t.Generic[_T], metaclass=abc.ABCMeta):
     __slots__ = ('_value',)