InquirerPrompt 0.3.0__tar.gz

inquirerprompt-0.3.0/InquirerPy/__init__.py

@@ -0,0 +1,4 @@
+__all__ = ["prompt", "prompt_async", "get_style"]
+
+from InquirerPy.resolver import prompt, prompt_async
+from InquirerPy.utils import get_style

inquirerprompt-0.3.0/InquirerPy/base/__init__.py

@@ -0,0 +1,24 @@
+"""Module contains base class for prompts.
+
+BaseSimplePrompt ← InputPrompt ← SecretPrompt ...
+        ↑
+BaseComplexPrompt
+        ↑
+BaseListPrompt ← FuzzyPrompt
+        ↑
+ListPrompt ← ExpandPrompt ...
+"""
+
+__all__ = [
+    "BaseComplexPrompt",
+    "FakeDocument",
+    "Choice",
+    "InquirerPyUIListControl",
+    "BaseSimplePrompt",
+    "BaseListPrompt",
+]
+
+from .complex import BaseComplexPrompt, FakeDocument
+from .control import Choice, InquirerPyUIListControl
+from .list import BaseListPrompt
+from .simple import BaseSimplePrompt

inquirerprompt-0.3.0/InquirerPy/base/complex.py

@@ -0,0 +1,295 @@
+"""Contains the interface class :class:`.BaseComplexPrompt` for more complex prompts and the mocked document class :class:`.FakeDocument`."""
+
+import shutil
+from dataclasses import dataclass
+from typing import Any, Callable, List, Optional, Tuple, Union
+
+from prompt_toolkit.application import Application
+from prompt_toolkit.enums import EditingMode
+from prompt_toolkit.filters.base import Condition, FilterOrBool
+from prompt_toolkit.key_binding.key_bindings import KeyHandlerCallable
+from prompt_toolkit.keys import Keys
+
+from InquirerPy.base.simple import BaseSimplePrompt
+from InquirerPy.enum import INQUIRERPY_KEYBOARD_INTERRUPT
+from InquirerPy.utils import (
+    InquirerPySessionResult,
+    InquirerPyStyle,
+    InquirerPyValidate,
+)
+
+
+@dataclass
+class FakeDocument:
+    """A fake `prompt_toolkit` document class.
+
+    Work around to allow non-buffer type :class:`~prompt_toolkit.layout.UIControl` to use
+    :class:`~prompt_toolkit.validation.Validator`.
+
+    Args:
+        text: Content to be validated.
+        cursor_position: Fake cursor position.
+    """
+
+    text: str
+    cursor_position: int = 0
+
+
+class BaseComplexPrompt(BaseSimplePrompt):
+    """A base class to create a more complex prompt that will involve :class:`~prompt_toolkit.application.Application`.
+
+    Note:
+        This class does not create :class:`~prompt_toolkit.layout.Layout` nor :class:`~prompt_toolkit.application.Application`,
+        it only contains the necessary attributes and helper functions to be consumed.
+
+    Note:
+        Use :class:`~InquirerPy.base.BaseListPrompt` to create a complex list prompt which involves multiple choices. It has
+        more methods and helper function implemented.
+
+    See Also:
+        :class:`~InquirerPy.base.BaseListPrompt`
+        :class:`~InquirerPy.prompts.fuzzy.FuzzyPrompt`
+    """
+
+    def __init__(
+        self,
+        message: Union[str, Callable[[InquirerPySessionResult], str]],
+        style: Optional[InquirerPyStyle] = None,
+        border: bool = False,
+        vi_mode: bool = False,
+        qmark: str = "?",
+        amark: str = "?",
+        instruction: str = "",
+        long_instruction: str = "",
+        transformer: Optional[Callable[[Any], Any]] = None,
+        filter: Optional[Callable[[Any], Any]] = None,
+        validate: Optional[InquirerPyValidate] = None,
+        invalid_message: str = "Invalid input",
+        wrap_lines: bool = True,
+        raise_keyboard_interrupt: bool = True,
+        mandatory: bool = True,
+        mandatory_message: str = "Mandatory prompt",
+        session_result: Optional[InquirerPySessionResult] = None,
+    ) -> None:
+        super().__init__(
+            message=message,
+            style=style,
+            vi_mode=vi_mode,
+            qmark=qmark,
+            amark=amark,
+            instruction=instruction,
+            transformer=transformer,
+            filter=filter,
+            invalid_message=invalid_message,
+            validate=validate,
+            wrap_lines=wrap_lines,
+            raise_keyboard_interrupt=raise_keyboard_interrupt,
+            mandatory=mandatory,
+            mandatory_message=mandatory_message,
+            session_result=session_result,
+        )
+        self._invalid_message = invalid_message
+        self._rendered = False
+        self._invalid = False
+        self._loading = False
+        self._application: Application
+        self._long_instruction = long_instruction
+        self._border = border
+        self._height_offset = 2  # prev prompt result + current prompt question
+        if self._border:
+            self._height_offset += 2
+        if self._long_instruction:
+            self._height_offset += 1
+        self._validation_window_bottom_offset = 0 if not self._long_instruction else 1
+        if self._wrap_lines:
+            self._validation_window_bottom_offset += (
+                self.extra_long_instruction_line_count
+            )
+
+        self._is_vim_edit = Condition(lambda: self._editing_mode == EditingMode.VI)
+        self._is_invalid = Condition(lambda: self._invalid)
+        self._is_displaying_long_instruction = Condition(
+            lambda: self._long_instruction != ""
+        )
+
+    def _redraw(self) -> None:
+        """Redraw the application UI."""
+        self._application.invalidate()
+
+    def register_kb(
+        self, *keys: Union[Keys, str], filter: FilterOrBool = True
+    ) -> Callable[[KeyHandlerCallable], KeyHandlerCallable]:
+        """Decorate keybinding registration function.
+
+        Ensure that the `invalid` state is cleared on next keybinding entered.
+        """
+        kb_dec = super().register_kb(*keys, filter=filter)
+
+        def decorator(func: KeyHandlerCallable) -> KeyHandlerCallable:
+            @kb_dec
+            def executable(event):
+                if self._invalid:
+                    self._invalid = False
+                func(event)
+
+            return executable
+
+        return decorator
+
+    def _exception_handler(self, _, context) -> None:
+        """Set exception handler for the event loop.
+
+        Skip the question and raise exception.
+
+        Args:
+            loop: Current event loop.
+            context: Exception context.
+        """
+        self._status["answered"] = True
+        self._status["result"] = INQUIRERPY_KEYBOARD_INTERRUPT
+        self._status["skipped"] = True
+        self._application.exit(exception=context["exception"])
+
+    def _after_render(self, app: Optional[Application]) -> None:
+        """Run after the :class:`~prompt_toolkit.application.Application` is rendered/updated.
+
+        Since this function is fired up on each render, adding a check on `self._rendered` to
+        process logics that should only run once.
+
+        Set event loop exception handler here, since its guaranteed that the event loop is running
+        in `_after_render`.
+        """
+        if not self._rendered:
+            self._rendered = True
+
+            self._keybinding_factory()
+            self._on_rendered(app)
+
+    def _set_error(self, message: str) -> None:
+        """Set error message and set invalid state.
+
+        Args:
+            message: Error message to display.
+        """
+        self._invalid_message = message
+        self._invalid = True
+
+    def _get_error_message(self) -> List[Tuple[str, str]]:
+        """Obtain the error message dynamically.
+
+        Returns:
+            FormattedText in list of tuple format.
+        """
+        return [
+            (
+                "class:validation-toolbar",
+                self._invalid_message,
+            )
+        ]
+
+    def _on_rendered(self, _: Optional[Application]) -> None:
+        """Run once after the UI is rendered. Acts like `ComponentDidMount`."""
+        pass
+
+    def _get_prompt_message(self) -> List[Tuple[str, str]]:
+        """Get the prompt message to display.
+
+        Returns:
+            Formatted text in list of tuple format.
+        """
+        pre_answer = (
+            "class:instruction",
+            " %s " % self.instruction if self.instruction else " ",
+        )
+        post_answer = ("class:answer", " %s" % self.status["result"])
+        return super()._get_prompt_message(pre_answer, post_answer)
+
+    def _run(self) -> Any:
+        """Run the application."""
+        return self.application.run()
+
+    async def _run_async(self) -> None:
+        """Run the application asynchronously."""
+        return await self.application.run_async()
+
+    @property
+    def application(self) -> Application:
+        """Get the application.
+
+        :class:`.BaseComplexPrompt` requires :attr:`.BaseComplexPrompt._application` to be defined since this class
+        doesn't implement :class:`~prompt_toolkit.layout.Layout` and :class:`~prompt_toolkit.application.Application`.
+
+        Raises:
+            NotImplementedError: When `self._application` is not defined.
+        """
+        if not self._application:
+            raise NotImplementedError
+        return self._application
+
+    @application.setter
+    def application(self, value: Application) -> None:
+        self._application = value
+
+    @property
+    def height_offset(self) -> int:
+        """int: Height offset to apply."""
+        if not self._wrap_lines:
+            return self._height_offset
+        return self.extra_line_count + self._height_offset
+
+    @property
+    def total_message_length(self) -> int:
+        """int: Total length of the message."""
+        total_message_length = 0
+        if self._qmark:
+            total_message_length += len(self._qmark)
+            total_message_length += 1  # Extra space if qmark is present
+        total_message_length += len(str(self._message))
+        total_message_length += 1  # Extra space between message and instruction
+        total_message_length += len(str(self._instruction))
+        if self._instruction:
+            total_message_length += 1  # Extra space behind the instruction
+        return total_message_length
+
+    @property
+    def extra_message_line_count(self) -> int:
+        """int: Get the extra lines created caused by line wrapping.
+
+        Minus 1 on the totoal message length as we only want the extra line.
+        24 // 24 will equal to 1 however we only want the value to be 1 when we have 25 char
+        which will create an extra line.
+        """
+        term_width, _ = shutil.get_terminal_size()
+        return (self.total_message_length - 1) // term_width
+
+    @property
+    def extra_long_instruction_line_count(self) -> int:
+        """int: Get the extra lines created caused by line wrapping.
+
+        See Also:
+            :attr:`.BaseComplexPrompt.extra_message_line_count`
+        """
+        if self._long_instruction:
+            term_width, _ = shutil.get_terminal_size()
+            return (len(self._long_instruction) - 1) // term_width
+        else:
+            return 0
+
+    @property
+    def extra_line_count(self) -> int:
+        """Get the extra lines created caused by line wrapping.
+
+        Used mainly to calculate how much additional offset should be applied when getting
+        the height.
+
+        Returns:
+            Total extra lines created due to line wrapping.
+        """
+        result = 0
+
+        # message wrap
+        result += self.extra_message_line_count
+        # long instruction wrap
+        result += self.extra_long_instruction_line_count
+
+        return result

inquirerprompt-0.3.0/InquirerPy/base/control.py

@@ -0,0 +1,230 @@
+"""Contains the content control class :class:`.InquirerPyUIListControl`."""
+
+from abc import abstractmethod
+from dataclasses import asdict, dataclass
+from typing import Any, Callable, Dict, List, Optional, Tuple, cast
+
+from prompt_toolkit.layout.controls import FormattedTextControl
+
+from InquirerPy.exceptions import InvalidArgument, RequiredKeyNotFound
+from InquirerPy.separator import Separator
+from InquirerPy.utils import InquirerPyListChoices, InquirerPySessionResult
+
+__all__ = ["Choice", "InquirerPyUIListControl"]
+
+
+@dataclass
+class Choice:
+    """Class to create choices for list type prompts.
+
+    A simple dataclass that can be used as an alternate to using :class:`dict`
+    when working with choices.
+
+    Args:
+        value: The value of the choice when user selects this choice.
+        name: The value that should be presented to the user prior/after selection of the choice.
+            This value is optional, if not provided, it will fallback to the string representation of `value`.
+        enabled: Indicates if the choice should be pre-selected.
+            This only has effects when the prompt has `multiselect` enabled.
+    """
+
+    value: Any
+    name: Optional[str] = None
+    enabled: bool = False
+
+    def __post_init__(self):
+        """Assign strinify value to name if not present."""
+        if self.name is None:
+            self.name = str(self.value)
+
+
+class InquirerPyUIListControl(FormattedTextControl):
+    """A base class to create :class:`~prompt_toolkit.layout.UIControl` to display list type contents.
+
+    Args:
+        choices(InquirerPyListChoices): List of choices to display as the content.
+            Can also be a callable or async callable that returns a list of choices.
+        default: Default value, this will affect the cursor position.
+        multiselect: Indicate if the current prompt has `multiselect` enabled.
+        session_result: Current session result.
+    """
+
+    def __init__(
+        self,
+        choices: InquirerPyListChoices,
+        default: Any = None,
+        multiselect: bool = False,
+        session_result: Optional[InquirerPySessionResult] = None,
+    ) -> None:
+        self._session_result = session_result or {}
+        self._selected_choice_index: int = 0
+        self._choice_func = None
+        self._multiselect = multiselect
+        self._default = (
+            default
+            if not isinstance(default, Callable)
+            else cast(Callable, default)(self._session_result)
+        )
+        self._raw_choices = (
+            choices
+            if not isinstance(choices, Callable)
+            else cast(Callable, choices)(self._session_result)
+        )
+        self._choices = self._get_choices(self._raw_choices, self._default)
+        self._safety_check()
+        self._format_choices()
+        super().__init__(self._get_formatted_choices)
+
+    def _get_choices(self, choices: List[Any], default: Any) -> List[Dict[str, Any]]:
+        """Process the raw user input choices and format it into dictionary.
+
+        Args:
+            choices: List of chices to display.
+            default: Default value, this will affect the :attr:`.InquirerPyUIListControl.selected_choice_index`
+
+        Returns:
+            List of choices.
+
+        Raises:
+            RequiredKeyNotFound: When the provided choice is missing the `name` or `value` key.
+        """
+        processed_choices: List[Dict[str, Any]] = []
+        try:
+            for index, choice in enumerate(choices, start=0):
+                if isinstance(choice, dict):
+                    if choice["value"] == default:
+                        self.selected_choice_index = index
+                    processed_choices.append(
+                        {
+                            "name": str(choice["name"]),
+                            "value": choice["value"],
+                            "enabled": (
+                                choice.get("enabled", False)
+                                if self._multiselect
+                                else False
+                            ),
+                        }
+                    )
+                elif isinstance(choice, Separator):
+                    if self.selected_choice_index == index:
+                        self.selected_choice_index = (
+                            self.selected_choice_index + 1
+                        ) % len(choices)
+                    processed_choices.append(
+                        {"name": str(choice), "value": choice, "enabled": False}
+                    )
+                elif isinstance(choice, Choice):
+                    dict_choice = asdict(choice)
+                    if dict_choice["value"] == default:
+                        self.selected_choice_index = index
+                    if not self._multiselect:
+                        dict_choice["enabled"] = False
+                    processed_choices.append(dict_choice)
+                else:
+                    if choice == default:
+                        self.selected_choice_index = index
+                    processed_choices.append(
+                        {"name": str(choice), "value": choice, "enabled": False}
+                    )
+        except KeyError:
+            raise RequiredKeyNotFound(
+                "dictionary type of choice require a 'name' key and a 'value' key"
+            )
+        return processed_choices
+
+    @property
+    def selected_choice_index(self) -> int:
+        """int: Current highlighted index."""
+        return self._selected_choice_index
+
+    @selected_choice_index.setter
+    def selected_choice_index(self, value: int) -> None:
+        self._selected_choice_index = value
+
+    @property
+    def choices(self) -> List[Dict[str, Any]]:
+        """List[Dict[str, Any]]: Get all processed choices."""
+        return self._choices
+
+    @choices.setter
+    def choices(self, value: List[Dict[str, Any]]) -> None:
+        self._choices = value
+
+    def _safety_check(self) -> None:
+        """Validate processed choices.
+
+        Check if the choices are empty or if it only contains :class:`~InquirerPy.separator.Separator`.
+        """
+        if not self.choices:
+            raise InvalidArgument("argument choices cannot be empty")
+        should_proceed: bool = False
+        for choice in self.choices:
+            if not isinstance(choice["value"], Separator):
+                should_proceed = True
+                break
+        if not should_proceed:
+            raise InvalidArgument(
+                "argument choices should contain choices other than separator"
+            )
+
+    def _get_formatted_choices(self) -> List[Tuple[str, str]]:
+        """Get all choices in formatted text format.
+
+        Returns:
+            List of choices in formatted text form.
+        """
+        display_choices = []
+
+        for index, choice in enumerate(self.choices):
+            if index == self.selected_choice_index:
+                display_choices += self._get_hover_text(choice)
+            else:
+                display_choices += self._get_normal_text(choice)
+            display_choices.append(("", "\n"))
+        if display_choices:
+            display_choices.pop()
+        return display_choices
+
+    def _format_choices(self) -> None:
+        """Perform post processing on the choices.
+
+        Additional customisation to the choices after :meth:`.InquirerPyUIListControl._get_choices` call.
+        """
+        pass
+
+    @abstractmethod
+    def _get_hover_text(self, choice) -> List[Tuple[str, str]]:
+        """Generate the formatted text for hovered choice.
+
+        Returns:
+            Formatted text in list of tuple format.
+        """
+        pass
+
+    @abstractmethod
+    def _get_normal_text(self, choice) -> List[Tuple[str, str]]:
+        """Generate the formatted text for non-hovered choices.
+
+        Returns:
+            Formatted text in list of tuple format.
+        """
+        pass
+
+    @property
+    def choice_count(self) -> int:
+        """int: Total count of choices."""
+        return len(self.choices)
+
+    @property
+    def selection(self) -> Dict[str, Any]:
+        """Dict[str, Any]: Current selected choice."""
+        return self.choices[self.selected_choice_index]
+
+    @property
+    def loading(self) -> bool:
+        """bool: Indicate if the content control is loading."""
+        return self._loading
+
+    @loading.setter
+    def loading(self, value: bool) -> None:
+        self._loading = value