ansible-module/plugins/module_utils/generic.py

import pathlib
import warnings
from typing import Any, Callable, Dict, Optional, Sequence, Tuple, Type, Union

__all__ = (
    "Types",
    "SYSTEMD_SERVICE_CONFIG",
    "SYSTEMD_NETWORK_CONFIG",
    "SYSTEMD_CONFIG_ROOT",
    "systemdbool",
    "AnsibleParameter",
)


SYSTEMD_CONFIG_ROOT = pathlib.Path("/etc/systemd")
SYSTEMD_NETWORK_CONFIG = SYSTEMD_CONFIG_ROOT / "network"
SYSTEMD_SERVICE_CONFIG = SYSTEMD_CONFIG_ROOT / "system"

AnsibleParameter = Dict[str, Any]


class _Type:
    def __dir__(self) -> tuple:  # pragma: nocover
        return (
            "str",
            "bool",
            "int",
            "float",
            "path",
            "raw",
            "jsonarg",
            "json",
            "bytes",
            "dict",
            "list",
            "bits",
            "__doc__",
        )

    def __repr__(self) -> str:  # pragma: nocover
        return "Types()"

    def __call__(self) -> "_Type":  # pragma: nocover
        return self

    def list(
        self,
        elements: Union[Type[object], str, AnsibleParameter],
        required: bool = False,
        help: Optional[str] = None,
    ) -> AnsibleParameter:
        option: AnsibleParameter = dict(type="list", required=required)
        if not isinstance(elements, (str, dict)):
            option["elements"] = elements.__name__
        elif isinstance(elements, dict):
            option["elements"] = elements["type"]
            if elements["type"] == "dict":
                option["options"] = dict()
                for name, value in elements["option"].items():
                    option["options"][name] = value
                    if "description" not in option["options"][name]:
                        warnings.warn(  # pragma: nocover
                            f"helptext of option {name} is unset."
                            " Ansible requires suboptions to have an documentation"
                        )
        if help is not None:
            option["description"] = help.split("\n")
        return option

    def dict(self, required: bool = False, help: Optional[str] = None, **options: dict) -> AnsibleParameter:
        option: AnsibleParameter = dict(type="dict", required=required)
        option["option"] = options
        if help is not None:
            option["description"] = help.split("\n")
        return option

    def __getattr__(self, name: str):
        def argument(
            required: bool = False,
            help: Optional[str] = None,
            choices: Optional[Sequence] = None,
            default: Optional[Any] = None,
        ) -> AnsibleParameter:
            option: AnsibleParameter = dict(type=name, required=required)
            if choices is not None:
                option["choices"] = choices
            if default is not None:
                option["default"] = default
            if help is not None:
                option["description"] = help.split("\n")
            return option

        argument.__name__ = name
        argument.__qualname__ = f"Types.{name}"
        argument.__doc__ = f"Simple wrapper for Ansible {name} argument dict"
        return argument


Types = _Type()


def systemdbool(b: Union[bool, str]) -> str:
    """Converts values into things systemd can parse"""
    if b is True:
        return "yes"
    elif b is False:
        return "no"
    return b


def modspec(
    argument_spec: Dict[str, Dict[str, Any]],
    mutually_exclusive: Sequence[Tuple[str, ...]] = (),
    required_together: Sequence[Tuple[str, ...]] = (),
    required_one_of: Sequence[Tuple[str, ...]] = (),
    required_if: Sequence[Union[Tuple[str, Any, Tuple[str, ...]], Tuple[str, Any, Tuple[str, ...], bool]]] = (),
    required_by: Dict[str, Union[str, Tuple[str, ...]]] = {},
) -> Dict[str, Any]:  # pragma: nocover
    return dict(
        argument_spec=argument_spec,
        mutually_exclusive=mutually_exclusive,
        required_together=required_together,
        required_one_of=required_one_of,
        required_if=required_if,
        required_by=required_by,
    )


def joindict(*items: dict) -> dict:
    """merges one or more dictionaries into one"""
    odict = dict()
    for item in items:
        for key, value in item.items():
            odict[key] = value
    return odict