hspylib-clitt 0.9.118__py3-none-any.whl → 0.9.120__py3-none-any.whl

build/lib/clitt/core/tui/minput/input_validator.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib
+   @package: clitt.core.tui.minput
+      @file: input_validator.py
+   @created: Thu, 20 May 2021
+    @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior"
+      @site: https://github.com/yorevs/hspylib
+   @license: MIT - Please refer to <https://opensource.org/licenses/MIT>
+
+   Copyright·(c)·2024,·HSPyLib
+"""
+
+from hspylib.core.enums.enumeration import Enumeration
+from hspylib.core.tools.validator import Validator
+
+import re
+
+
+class InputValidator(Validator):
+    """MenuInput 'input' validator."""
+
+    class PatternType(Enumeration):
+        # fmt: off
+        CUSTOM      = r''  # It will be set later
+        ANYTHING    = r'.'
+        LETTERS     = r'[a-zA-Z]'
+        WORDS       = r'[a-zA-Z0-9 _]'
+        NUMBERS     = r'[0-9\.\,]'
+        MASKED      = r'[a-zA-Z0-9]'
+        # fmt: on
+
+    @classmethod
+    def custom(cls, pattern: str) -> "InputValidator":
+        """Return a custom validator that allows customize the input rules.
+        :param pattern: the custom validator pattern.
+        """
+        pattern_type = cls.PatternType.CUSTOM
+        validator = InputValidator(pattern_type=pattern_type)
+        validator.pattern = pattern
+        return validator
+
+    @classmethod
+    def letters(cls) -> "InputValidator":
+        """Return a validator that allows only letters."""
+        return InputValidator(cls.PatternType.LETTERS)
+
+    @classmethod
+    def numbers(cls) -> "InputValidator":
+        """Return a validator that allows only numbers."""
+        return InputValidator(cls.PatternType.NUMBERS)
+
+    @classmethod
+    def words(cls) -> "InputValidator":
+        """Return a validator that allows only words (space, numbers or letters)."""
+        return InputValidator(cls.PatternType.WORDS)
+
+    @classmethod
+    def anything(cls) -> "InputValidator":
+        """Return a validator that allows any input value."""
+        return InputValidator(cls.PatternType.ANYTHING)
+
+    @classmethod
+    def masked(cls) -> "InputValidator":
+        """Return a validator that allows masked inputs."""
+        return InputValidator(cls.PatternType.MASKED)
+
+    def __init__(self, pattern_type: PatternType = PatternType.ANYTHING):
+        self._pattern_type = pattern_type
+        self._pattern = pattern_type.value
+
+    def __str__(self) -> str:
+        return f'r"{self.pattern}"' if self.pattern_type == self.PatternType.CUSTOM else self.pattern_type.name
+
+    def __repr__(self):
+        return str(self)
+
+    def __call__(self, *args, **kwargs) -> bool:
+        return all(self.validate(value) for value in args)
+
+    def validate(self, value: str) -> bool:
+        """Validate the value against the validator pattern."""
+        unmasked_value = re.split("[|,;]", value)[0] if value else ""
+        return bool(re.match(self.pattern, unmasked_value))
+
+    @property
+    def pattern(self) -> str:
+        return str(self._pattern)
+
+    @pattern.setter
+    def pattern(self, pattern: str) -> None:
+        self._pattern = rf"{pattern}"
+
+    @property
+    def pattern_type(self) -> PatternType:
+        return self._pattern_type

build/lib/clitt/core/tui/minput/menu_input.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib
+   @package: clitt.core.tui.minput
+      @file: menu_input.py
+   @created: Wed, 17 May 2023
+    @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior"
+      @site: https://github.com/yorevs/hspylib
+   @license: MIT - Please refer to <https://opensource.org/licenses/MIT>
+
+   Copyright·(c)·2024,·HSPyLib
+"""
+from clitt.core.icons.font_awesome.form_icons import FormIcons
+from clitt.core.icons.font_awesome.nav_icons import NavIcons
+from clitt.core.term.commons import Direction, get_cursor_position
+from clitt.core.term.terminal import Terminal
+from clitt.core.tui.minput import minput_utils as mu
+from clitt.core.tui.minput.form_builder import FormBuilder
+from clitt.core.tui.minput.form_field import FormField
+from clitt.core.tui.minput.input_type import InputType
+from clitt.core.tui.minput.minput_utils import MASK_SYMBOLS, VALUE_SEPARATORS
+from clitt.core.tui.tui_component import TUIComponent
+from functools import reduce
+from hspylib.core.exception.exceptions import InvalidInputError, InvalidStateError
+from hspylib.core.namespace import Namespace
+from hspylib.core.tools.text_tools import xstr
+from hspylib.modules.cli.keyboard import Keyboard
+from operator import add
+from time import sleep
+from typing import List, Optional
+
+import pyperclip
+import re
+
+
+class MenuInput(TUIComponent):
+    """Provide a form input for terminal UIs."""
+
+    NAV_ICONS = NavIcons.compose(NavIcons.UP, NavIcons.DOWN)
+
+    @classmethod
+    def builder(cls) -> FormBuilder:
+        return FormBuilder()
+
+    def __init__(self, title: str, fields: List[FormField]):
+        super().__init__(title)
+        self.fields = fields
+        self.positions = [(0, 0) for _ in fields]
+        self.cur_field = self._done = None
+        self.cur_row = self.cur_col = self.tab_index = 0
+        self.max_label_length = max(len(field.label) for field in fields)
+        self.max_value_length = max(field.max_length for field in fields)
+        self.max_detail_length = max(mu.detail_len(field) for field in fields)
+
+    def execute(self) -> Optional[Namespace]:
+        if len(self.fields) == 0:
+            return None
+
+        self._prepare_render()
+        keypress = self._loop()
+
+        if keypress == Keyboard.VK_ENTER:
+            form_fields = Namespace("FormFields")
+            for field in self.fields:
+                form_fields.setattr(field.dest, field.value)
+            return form_fields
+
+        return None
+
+    def render(self) -> None:
+
+        Terminal.set_show_cursor(False)
+        self.cursor.restore()
+        self.writeln(f"{self.prefs.title_color.placeholder}{self.title}%EOL%%NC%")
+
+        for idx, field in enumerate(self.fields):
+            field_length = field.length
+            if self.tab_index == idx:
+                mu.mi_print(
+                    self.screen, f"  {field.label}", self.prefs.sel_bg_color.placeholder, self.max_label_length + 2
+                )
+                self.cur_field = field
+            else:
+                mu.mi_print(self.screen, f"  {field.label}", field_len=self.max_label_length + 2)
+            self._buffer_positions(idx, field_length)
+            self._render_field(field)
+            self._render_details(field, field_length)
+
+        self.cursor.erase(Direction.DOWN)
+        self.draw_navbar(self.navbar())
+        self._set_cursor_pos()
+        self._re_render = False
+        Terminal.set_show_cursor()
+
+    def navbar(self, **kwargs) -> str:
+
+        return (
+            f"%EOL%{NavIcons.POINTER} %GREEN%{self.cur_field.tooltip or f'the {self.cur_field.label.lower()}'}%NC%"
+            f"%EOL%{self.prefs.navbar_color.placeholder}%EOL%"
+            f"[Enter] Submit  [{self.NAV_ICONS}] "
+            f"Navigate  [{NavIcons.TAB}] Next  [Space] Toggle  [^P] Paste  [Esc] Quit %NC%"
+        )
+
+    def handle_keypress(self) -> Keyboard:
+        length = len(self.fields)
+
+        if keypress := Keyboard.wait_keystroke():
+            match keypress:
+                case Keyboard.VK_ESC:
+                    self._done = True
+                case _ as key if key in [Keyboard.VK_TAB, Keyboard.VK_DOWN]:
+                    self.tab_index = min(length - 1, self.tab_index + 1)
+                case _ as key if key in [Keyboard.VK_SHIFT_TAB, Keyboard.VK_UP]:
+                    self.tab_index = max(0, self.tab_index - 1)
+                case Keyboard.VK_BACKSPACE:
+                    if not self.cur_field.can_write():
+                        self._display_error("This field is read only !")
+                    else:
+                        self._handle_backspace()
+                case Keyboard.VK_CTRL_P:
+                    self._handle_ctrl_p()
+                case Keyboard.VK_ENTER:
+                    return self._handle_enter()
+                case _ as key if key.isalnum() or key.ispunct() or key == Keyboard.VK_SPACE:
+                    if not self.cur_field.can_write():
+                        self._display_error("This field is read only !")
+                    else:
+                        self._handle_input(keypress)
+
+        self._re_render = True
+
+        return keypress
+
+    def _handle_enter(self) -> Optional[Keyboard]:
+        """Handle 'enter' press. Validate & Save form and exit."""
+        invalid = next((field for field in self.fields if not field.validate_field()), None)
+        if invalid:
+            idx = self.fields.index(invalid)
+            pos = self.positions[idx]
+            self.cur_row = pos[0]
+            self.tab_index = idx
+            self._display_error("Form field is not valid: " + str(invalid))
+            return None
+
+        for idx, field in enumerate(self.fields):
+            match field.itype:
+                case InputType.MASKED:
+                    field.value = re.split(VALUE_SEPARATORS, field.value)[0]
+                case InputType.CHECKBOX:
+                    field.value = bool(field.value)
+                case InputType.SELECT:
+                    _, field.value = mu.get_selected(field.value)
+        self._done = True
+        return Keyboard.VK_ENTER
+
+    def _handle_input(self, keypress: Keyboard) -> None:
+        """Handle a form input.
+        :param keypress: the input provided by the keypress.
+        """
+
+        match self.cur_field.itype:
+            case InputType.CHECKBOX:
+                if keypress == Keyboard.VK_SPACE:
+                    self.cur_field.value = not self.cur_field.value
+            case InputType.SELECT:
+                if keypress == Keyboard.VK_SPACE:
+                    if self.cur_field.value:
+                        self.cur_field.value = mu.toggle_selected(xstr(self.cur_field.value))
+            case InputType.MASKED:
+                value, mask = mu.unpack_masked(xstr(self.cur_field.value))
+                try:
+                    self.cur_field.value = mu.append_masked(value, mask, keypress.value)
+                except InvalidInputError as err:
+                    self._display_error(str(err))
+            case _:
+                if len(xstr(self.cur_field.value)) < self.cur_field.max_length:
+                    if self.cur_field.validate_input(keypress.value):
+                        self.cur_field.value = (str(self.cur_field.value) if self.cur_field.value else "") + str(
+                            keypress.value
+                        )
+                    else:
+                        self._display_error(
+                            f"Input '{keypress.value}' is invalid. "
+                            f"This field takes only {self.cur_field.input_validator}!"
+                        )
+
+    def _handle_backspace(self) -> None:
+        """Handle 'backspace' press. Delete previous input."""
+
+        if self.cur_field.itype == InputType.MASKED:
+            value, mask = mu.unpack_masked(str(self.cur_field.value))
+            value = value[:-1]
+            while mask[len(value) - 1] not in MASK_SYMBOLS:
+                value = value[:-1]
+            self.cur_field.value = f"{value}|{mask}"
+        elif self.cur_field.itype not in [InputType.CHECKBOX, InputType.SELECT]:
+            if self.cur_field.can_write() and len(str(self.cur_field.value)) >= 1:
+                self.cur_field.value = str(self.cur_field.value)[:-1]
+            elif not self.cur_field.can_write():
+                self._display_error("This field is read only !")
+
+    def _handle_ctrl_p(self) -> None:
+        """Handle 'ctrl + p' press. Paste content from clipboard."""
+        for c in pyperclip.paste():
+            self._handle_input(Keyboard.of_value(c))
+
+    def _set_cursor_pos(self) -> None:
+        """Set the cursor at the right position according to the ATB index."""
+        pos = self.positions[self.tab_index]
+        self.screen.cursor.move_to(pos[0], pos[1] + self.cur_field.length)
+
+    def _render_field(self, field: FormField) -> None:
+        """Render the specified form field.
+        :param field: the form field to render.
+        """
+        match field.itype:
+            case InputType.TEXT:
+                mu.mi_print(self.screen, xstr(field.value), field_len=self.max_value_length)
+            case InputType.PASSWORD:
+                mu.mi_print(self.screen, "*" * field.length, field_len=self.max_value_length)
+            case InputType.CHECKBOX:
+                mu.mi_print(
+                    self.screen,
+                    " ",
+                    FormIcons.CHECK_SQUARE.unicode if field.value else FormIcons.UNCHECK_SQUARE.unicode,
+                    field_len=self.max_value_length - 1,
+                )
+            case InputType.SELECT:
+                if field.value:
+                    mat = re.search(rf".*({VALUE_SEPARATORS})?<(.+)>({VALUE_SEPARATORS})?.*", str(field.value))
+                    sel_value = mat.group(2) if mat else re.split(VALUE_SEPARATORS, str(field.value))[0]
+                    mu.mi_print(self.screen, f"{sel_value}", field_len=self.max_value_length)
+            case InputType.MASKED:
+                value, mask = mu.unpack_masked(str(field.value))
+                mu.mi_print(self.screen, mu.over_masked(value, mask), field_len=self.max_value_length)
+            case _:
+                raise InvalidStateError(f"Invalid form field type: {field.itype}")
+
+    def _render_details(self, field: FormField, field_details: int) -> None:
+        """Render details about total/remaining field characters.
+        :param field: the form field to render.
+        :param field_details: details about the form field (total / remaining) size.
+        """
+        padding = 1 - len(str(self.max_detail_length / 2))
+        fmt = "{:<3}{:>" + str(padding) + "}/{:<" + str(padding) + "}  %NC%"
+        if field.itype == InputType.SELECT:
+            idx, _ = mu.get_selected(field.value)
+            count = len(re.split(VALUE_SEPARATORS, field.value))
+            self.writeln(fmt.format(field.icon, idx + 1 if idx >= 0 else 1, count))
+        elif field.itype == InputType.MASKED:
+            value, mask = mu.unpack_masked(xstr(field.value))
+            self.writeln(
+                fmt.format(
+                    field.icon,
+                    reduce(add, list(map(mask[: len(value)].count, MASK_SYMBOLS))),
+                    reduce(add, list(map(mask.count, MASK_SYMBOLS))),
+                )
+            )
+        else:
+            self.writeln(fmt.format(field.icon, field_details, field.max_length))
+
+    def _buffer_positions(self, field_index: int, field_size: int) -> None:
+        """Buffer all cursor positions to avoid calling get_cursor_pos over and over because it is a very
+        expensive call.
+        :param field_index: the current form field index.
+        :param field_size: the form field length.
+        """
+        if f_pos := get_cursor_position() if self.positions[field_index] == (0, 0) else self.positions[field_index]:
+            self.positions[field_index] = f_pos
+            if self.tab_index == field_index:
+                self.cur_row, self.cur_col = f_pos[0], f_pos[1] + field_size
+
+    def _display_error(self, err_msg: str) -> None:
+        """Display a form filling or submitting error.
+        :param err_msg: the error message.
+        """
+        Terminal.set_enable_echo(False)
+        Terminal.set_show_cursor(False)
+        offset = 15  # Sum of minput used characters that are not related to the field.
+        err_pos = offset + self.max_label_length + self.max_value_length + self.max_detail_length
+        self.cursor.move_to(self.cur_row, err_pos)
+        mu.mi_print_err(self.screen, f"{FormIcons.ARROW_LEFT} {err_msg}")
+        # This calculation gives a good delay amount based on the size of the message.
+        sleep(max(2.0, int(len(err_msg) / 21)))
+        Terminal.set_enable_echo()
+        # Erase the message after the timeout
+        self.cursor.move_to(self.cur_row, err_pos)
+        self.cursor.erase(Direction.RIGHT)
+        Terminal.set_show_cursor()
+        self._re_render = True

build/lib/clitt/core/tui/minput/minput.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib
+   @package: clitt.core.tui.minput
+      @file: minput.py
+   @created: Tue, 4 May 2021
+    @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior"
+      @site: https://github.com/yorevs/hspylib
+   @license: MIT - Please refer to <https://opensource.org/licenses/MIT>
+
+   Copyright·(c)·2024,·HSPyLib
+"""
+from clitt.core.tui.minput.form_field import FormField
+from clitt.core.tui.minput.menu_input import MenuInput
+from hspylib.core.enums.charset import Charset
+from hspylib.core.namespace import Namespace
+from hspylib.core.preconditions import check_argument
+from hspylib.core.tools.text_tools import quote, snakecase
+from typing import List, Optional
+
+import os
+
+
+def minput(
+    form_fields: List[FormField], title: str = "Please fill all fields of the form fields below", output: str = None
+) -> Optional[Namespace]:
+    """
+    Terminal UI menu form input method.
+    :param form_fields: the provided form items to input from.
+    :param title: the title to be displayed before the form.
+    :param output: optional output file containing the marked items.
+    :return: a namespace containing all form values.
+    """
+    check_argument(len(form_fields) > 0, "Must provide at least one form field!")
+    result = MenuInput(title, form_fields).execute()
+
+    if result and output:
+        with open(output, "w", encoding=Charset.UTF_8.val) as f_out:
+            for name, value in zip(result.attributes, result.values):
+                f_out.write(f"{snakecase(name, screaming=True)}={quote(value)}" + os.linesep)
+
+    return result

build/lib/clitt/core/tui/minput/minput_utils.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib
+   @package: clitt.core.tui.minput
+      @file: minput_utils.py
+   @created: Thu, 20 May 2021
+    @author: <B>H</B>ugo <B>S</B>aporetti <B>J</B>unior"
+      @site: https://github.com/yorevs/hspylib
+   @license: MIT - Please refer to <https://opensource.org/licenses/MIT>
+
+   Copyright·(c)·2024,·HSPyLib
+"""
+from clitt.core.term.screen import Screen
+from hspylib.core.exception.exceptions import InvalidInputError
+from typing import Any, Optional, Tuple
+
+import re
+
+MASK_SYMBOLS = ["#", "@", "%", "*"]
+
+VALUE_SEPARATORS = r"[|,;]"
+
+VALUE_SELECTORS = r"[<>]"
+
+
+def detail_len(field: Any) -> int:
+    """Return the length of the details, according to the form field.
+    :param field: the form field to get details.
+    """
+    max_len = len(str(field.max_length))
+    return 1 + (2 * max_len)
+
+
+def mi_print(screen: Screen, text: str, prefix: str = None, field_len: int = 0, end: str = "") -> None:
+    """Special menu input print.
+    :param screen: the component's screen.
+    :param text: the text to be printed.
+    :param prefix the text to print before the text.
+    :param field_len: the length of the field.
+    :param end: string appended after the last value, default an empty string.
+    """
+    fmt = ("{}" if prefix else "") + "{:<" + str(field_len) + "} : "
+    if prefix:
+        screen.cursor.write(fmt.format(prefix, text), end=end)
+    else:
+        screen.cursor.write(fmt.format(text or ""), end=end)
+
+
+def mi_print_err(screen: Screen, text: str) -> None:
+    """Special menu input print error message.
+    :param screen: the component's screen.
+    :param text: the text to be printed.
+    """
+    screen.cursor.write(f"%RED%{text}%NC%")
+
+
+def toggle_selected(tokenized_values: str) -> str:
+    """Toggle the 'select' component value. Selects the next value on the token sequence.
+    :param tokenized_values: the 'select' component tokenized values.
+    """
+    values = re.split(VALUE_SEPARATORS, tokenized_values)
+    cur_idx = next((idx for idx, val in enumerate(values) if val.find("<") >= 0), -1)
+    if cur_idx < 0:
+        if len(values) > 1:
+            values[1] = f"<{values[1]}>"
+        else:
+            values[0] = f"<{values[0]}>"
+        return "|".join(values)
+    unselected = list(map(lambda x: re.sub(VALUE_SELECTORS, "", x), values))
+    # fmt: off
+    return '|'.join([
+        f'<{val}>'
+        if idx == (cur_idx + 1) or ((cur_idx + 1) >= len(unselected) and idx == 0)
+        else val for idx, val in enumerate(unselected)
+    ])
+    # fmt: on
+
+
+def get_selected(tokenized_values: str) -> Optional[Tuple[int, str]]:
+    """Get the selected value from the 'select' component tokens.
+    :param tokenized_values: the 'select' component tokenized values.
+    """
+    values = re.split(VALUE_SEPARATORS, tokenized_values)
+    # fmt: off
+    sel_item = next((
+        re.sub(VALUE_SELECTORS, '', val)
+        for val in values if val.startswith('<') and val.endswith('>')
+    ), values[0])
+    # fmt: on
+    try:
+        return values.index(sel_item), sel_item
+    except ValueError:
+        try:
+            return values.index(f"<{sel_item}>"), sel_item
+        except ValueError:
+            return -1, sel_item
+
+
+def unpack_masked(value: str) -> Tuple[str, str]:
+    """Unpack all values of the 'masked' component.
+    :param value: the masked values to unpack.
+    """
+    if value:
+        parts = re.split(VALUE_SEPARATORS, value)
+        return parts[0], parts[1] if len(parts) == 2 else ""
+
+    return "", ""
+
+
+def append_masked(value: str, mask: str, keypress_value: chr) -> str:
+    """Append a value to the masked field.
+    :param value: the masked field current value.
+    :param mask: the masked field's mask.
+    :param keypress_value: the value to append (it can be a part of the mask itself).
+    """
+    idx = len(value)
+    masked_value = value
+    if idx < len(mask):
+        if keypress_value == mask[idx]:
+            return f"{value}{keypress_value}|{mask}"
+        while idx < len(mask) and mask[idx] not in MASK_SYMBOLS:
+            masked_value += mask[idx]
+            idx += 1
+        if mask and idx < len(mask):
+            mask_re = mask_regex(mask, idx)
+            if re.search(mask_re, keypress_value):
+                masked_value += keypress_value
+            else:
+                raise InvalidInputError(f"Value '{keypress_value}' is invalid. Expecting: {mask_re}")
+
+    return f"{masked_value}|{mask}"
+
+
+def over_masked(value: str, mask: str) -> str:
+    """
+    Return the value to be printed by a 'masked' input field. A placeholder value will be used for unfilled values.
+    :param value: the masked field current value.
+    :param mask: the masked field's mask.
+    """
+    if value:
+        over_masked_val = ""
+        for idx, element in enumerate(mask):
+            if element in MASK_SYMBOLS:
+                over_masked_val += value[idx] if idx < len(value) else mask[idx]
+            else:
+                over_masked_val += element
+        return over_masked_val
+
+    return mask
+
+
+def mask_regex(mask: str, idx: int) -> str:
+    """Return a regex matching the index of the mask."""
+    return mask[idx].replace("#", "[0-9]").replace("@", "[a-zA-Z]").replace("%", "[a-zA-Z0-9]").replace("*", ".")

build/lib/clitt/core/tui/mselect/__init__.py

@@ -0,0 +1,12 @@
+# _*_ coding: utf-8 _*_
+#
+# hspylib-clitt v0.9.120
+#
+# Package: main.build.lib.build.lib.clitt.core.tui.mselect
+"""Package initialization."""
+
+__all__ = [
+    'menu_select', 
+    'mselect'
+]
+__version__ = '0.9.120'