question.py

""" This module represents the questions to ask to the user to fulfill the cookiecutter context. """
from abc import ABC, abstractmethod
from enum import Enum
from typing import Any, Dict, List, Optional, Type, Union

import click


class QuestionKind(Enum):
    """An Enum of possible question types."""

    info = "info"
    confirm = "confirm"
    choice = "choice"
    question = "question"


class Promptable(ABC):
    """
    Abstract class Question, Info, Choice, Confirm implement.
    These classes need to implement their own prompt() method to prompt differently.
    """

    @abstractmethod
    def prompt(self, text: str, default_answer: Optional[Any]) -> Any:
        pass


class Question(Promptable):
    """
    A question to be prompt to the user in an interactive flow where the response is used to fulfill
    the cookiecutter context.

    Attributes
    ----------
    _key: str
        The key of the cookiecutter config to associate the answer with.
    _text: str
        The text to prompt to the user
    _required: bool
        Whether the user must provide an answer for this question or not.
    _default_answer: Optional[Union[str, Dict]]
        A default answer that is suggested to the user,
        it can be directly provided (a string)
        or resolved from cookiecutter context (a Dict, in the form of {"keyPath": [...,]})
    _next_question_map: Optional[Dict[str, str]]
        A simple branching mechanism, it refers to what is the next question to ask the user if he answered
        a particular answer to this question. this map is in the form of {answer: next-question-key}. this
        can be used in a flow like:
            supposed we are prompting the user for two resources r1 & r2 such that if the resource already
            exist then the user provide it otherwise we created it on his behave. the questions may look like:
                Question(key="r1" text="do you already have resource1?",
                         _next_question_map={"True": "r2", "False": "r1-creation"}
                Question(key="r1-creation" text="What do you like to name resource1?"}
                Question(key="r2" text="do you already have resource2?",
                         _next_question_map={"True": "r3", "False": "r2-creation"}
    _default_next_question_key: str
        The key of the next question that is not based on user's answer, i.e., if there is no matching in
        the _next_question_map
    """

    def __init__(
        self,
        key: str,
        text: str,
        default: Optional[Union[str, Dict]] = None,
        is_required: Optional[bool] = None,
        allow_autofill: Optional[bool] = None,
        next_question_map: Optional[Dict[str, str]] = None,
        default_next_question_key: Optional[str] = None,
    ):
        self._key = key
        self._text = text
        self._required = is_required
        self._allow_autofill = allow_autofill
        self._default_answer = default
        # if it is an optional question, set an empty default answer to prevent click from keep asking for an answer
        if not self._required and self._default_answer is None:
            self._default_answer = ""
        self._next_question_map: Dict[str, str] = next_question_map or {}
        self._default_next_question_key = default_next_question_key

    @property
    def key(self) -> str:
        return self._key

    @property
    def text(self) -> str:
        return self._text

    @property
    def default_answer(self) -> Optional[Any]:
        return self._resolve_default_answer()

    @property
    def required(self) -> Optional[bool]:
        return self._required

    @property
    def next_question_map(self) -> Dict[str, str]:
        return self._next_question_map

    @property
    def default_next_question_key(self) -> Optional[str]:
        return self._default_next_question_key

    def ask(self, context: Optional[Dict] = None) -> Any:
        """
        prompt the user this question

        Parameters
        ----------
        context
            The cookiecutter context dictionary containing previous questions' answers and default values

        Returns
        -------
        The user provided answer.
        """
        resolved_default_answer = self._resolve_default_answer(context)

        # skip the question and directly use the default value if autofill is allowed.
        if resolved_default_answer is not None and self._allow_autofill:
            return resolved_default_answer

        # if it is an optional question with no default answer,
        # set an empty default answer to prevent click from keep asking for an answer
        if not self._required and resolved_default_answer is None:
            resolved_default_answer = ""

        return self.prompt(self._resolve_text(context), resolved_default_answer)

    def prompt(self, text: str, default_answer: Optional[Any]) -> Any:
        return click.prompt(text=text, default=default_answer)

    def get_next_question_key(self, answer: Any) -> Optional[str]:
        # _next_question_map is a Dict[str(answer), str(next question key)]
        # so we need to parse the passed argument(answer) to str
        answer = str(answer)
        return self._next_question_map.get(answer, self._default_next_question_key)

    def set_default_next_question_key(self, next_question_key: str) -> None:
        self._default_next_question_key = next_question_key

    def _resolve_key_path(self, key_path: List, context: Dict) -> List[str]:
        """
        key_path element is a list of str and Dict.
        When the element is a dict, in the form of { "valueOf": question_key },
        it means it refers to the answer to another questions.
        _resolve_key_path() will replace such dict with the actual question answer

        Parameters
        ----------
        key_path
            The key_path list containing str and dict
        context
            The cookiecutter context containing answers to previous answered questions
        Returns
        -------
            The key_path list containing only str
        """
        resolved_key_path: List[str] = []
        for unresolved_key in key_path:
            if isinstance(unresolved_key, str):
                resolved_key_path.append(unresolved_key)
            elif isinstance(unresolved_key, dict):
                if "valueOf" not in unresolved_key:
                    raise KeyError(f'Missing key "valueOf" in question default keyPath element "{unresolved_key}".')
                query_question_key: str = unresolved_key.get("valueOf", "")
                if query_question_key not in context:
                    raise KeyError(
                        f'Invalid question key "{query_question_key}" referenced '
                        f"in default answer of question {self.key}"
                    )
                resolved_key_path.append(context[query_question_key])
            else:
                raise ValueError(f'Invalid value "{unresolved_key}" in key path')
        return resolved_key_path

    def _resolve_value_from_expression(self, expression: Any, context: Optional[Dict] = None) -> Optional[Any]:
        """
        a question may have a value provided directly as string or number value
        or indirectly from cookiecutter context using a key path

        Parameters
        ----------
        context
            Cookiecutter context used to resolve values.

        Raises
        ------
        KeyError
            When an expression depends on the answer to a non-existent question
        ValueError
            The expression is malformed

        Returns
        -------
        Optional value, it might be resolved from cookiecutter context using specified key path.

        """
        if isinstance(expression, dict):
            context = context if context else {}

            # load value using key path from cookiecutter
            if "keyPath" not in expression:
                raise KeyError(f'Missing key "keyPath" in "{expression}".')
            unresolved_key_path = expression.get("keyPath", [])
            if not isinstance(unresolved_key_path, list):
                raise ValueError(f'Invalid expression "{expression}" in question {self.key}')

            return context.get(str(self._resolve_key_path(unresolved_key_path, context)))
        return expression

    def _resolve_text(self, context: Optional[Dict] = None) -> str:
        resolved_text = self._resolve_value_from_expression(self._text, context)
        if resolved_text is None:
            raise ValueError(f"Cannot resolve value from expression: {self._text}")
        return str(resolved_text)

    def _resolve_default_answer(self, context: Optional[Dict] = None) -> Optional[Any]:
        return self._resolve_value_from_expression(self._default_answer, context)


class Info(Question):
    def prompt(self, text: str, default_answer: Optional[Any]) -> Any:
        return click.echo(message=text)


class Confirm(Question):
    def prompt(self, text: str, default_answer: Optional[Any]) -> Any:
        return click.confirm(text=text)


class Choice(Question):
    def __init__(
        self,
        key: str,
        text: str,
        options: List[str],
        default: Optional[str] = None,
        is_required: Optional[bool] = None,
        allow_autofill: Optional[bool] = None,
        next_question_map: Optional[Dict[str, str]] = None,
        default_next_question_key: Optional[str] = None,
    ):
        if not options:
            raise ValueError("No defined options")
        self._options = options
        super().__init__(key, text, default, is_required, allow_autofill, next_question_map, default_next_question_key)

    def prompt(self, text: str, default_answer: Optional[Any]) -> Any:
        click.echo(text)
        for index, option in enumerate(self._options):
            click.echo(f"\t{index + 1} - {option}")
        options_indexes = self._get_options_indexes(base=1)
        choices = list(map(str, options_indexes))
        choice = click.prompt(
            text="Choice",
            default=default_answer,
            show_choices=False,
            type=click.Choice(choices),
            show_default=default_answer is not None,
        )
        return self._options[int(choice) - 1]

    def _get_options_indexes(self, base: int = 0) -> List[int]:
        return list(range(base, len(self._options) + base))


class QuestionFactory:
    question_classes: Dict[QuestionKind, Type[Question]] = {
        QuestionKind.info: Info,
        QuestionKind.choice: Choice,
        QuestionKind.confirm: Confirm,
        QuestionKind.question: Question,
    }

    @staticmethod
    def create_question_from_json(question_json: Dict) -> Question:
        key = question_json["key"]
        text = question_json["question"]
        options = question_json.get("options")
        default = question_json.get("default")
        is_required = question_json.get("isRequired")
        allow_autofill = question_json.get("allowAutofill")
        next_question_map = question_json.get("nextQuestion")
        default_next_question = question_json.get("defaultNextQuestion")
        kind_str = question_json.get("kind")
        kind = QuestionKind(kind_str) if kind_str else QuestionKind.choice if options else QuestionKind.question

        klass = QuestionFactory.question_classes[kind]
        args = {
            "key": key,
            "text": text,
            "default": default,
            "is_required": is_required,
            "allow_autofill": allow_autofill,
            "next_question_map": next_question_map,
            "default_next_question_key": default_next_question,
        }
        if klass == Choice:
            args["options"] = options

        return klass(**args)