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

build/lib/build/lib/clitt/core/tui/menu/tui_menu_factory.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib
+   @package: clitt.core.tui.menu
+      @file: tui_menu_factory.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.menu.tui_menu import TUIMenu
+from clitt.core.tui.menu.tui_menu_action import OnTrigger_Cb, TUIMenuAction
+from clitt.core.tui.menu.tui_menu_item import TUIMenuItem
+from clitt.core.tui.menu.tui_menu_view import TUIMenuView
+from hspylib.core.preconditions import check_not_none
+from typing import List, TypeAlias, Union
+
+MenuBuilder: TypeAlias = Union[
+    "TUIMenuFactory.TUIMenuBuilder", "TUIMenuFactory.TUIMenuItemBuilder", "TUIMenuFactory.TUIMenuViewBuilder"
+]
+
+
+class TUIMenuFactory:
+    """TODO"""
+
+    _main_menu = None
+
+    class TUIMenuBuilder:
+        """TODO"""
+
+        def __init__(self, parent: "TUIMenuFactory", main_menu: TUIMenuItem):
+            check_not_none((parent, main_menu))
+            self._parent = parent
+            self._main_menu: TUIMenuItem = main_menu
+
+        def with_item(self, title: str, tooltip: str | None = None) -> "TUIMenuFactory.TUIMenuItemBuilder":
+            return TUIMenuFactory.TUIMenuItemBuilder(self, self._main_menu, title, tooltip)
+
+        def with_action(self, title: str, tooltip: str | None = None) -> "TUIMenuFactory.TUIMenuActionBuilder":
+            return TUIMenuFactory.TUIMenuActionBuilder(self, self._main_menu, title, tooltip)
+
+        def with_view(self, title: str, tooltip: str | None = None) -> "TUIMenuFactory.TUIMenuViewBuilder":
+            return TUIMenuFactory.TUIMenuViewBuilder(self, self._main_menu, title, tooltip)
+
+        def then(self) -> "TUIMenuFactory":
+            return self._parent
+
+    class TUIMenuItemBuilder:
+        """TODO"""
+
+        def __init__(
+            self, parent: MenuBuilder, parent_item: TUIMenuItem, title: str = None, tooltip: str | None = None
+        ):
+            check_not_none((parent, parent_item))
+            self._parent = parent
+            self._menu_item = TUIMenuItem(parent_item, title, tooltip)
+            self._items: List[TUIMenu] = []
+            parent_item.add_items(self._menu_item)
+
+        def with_item(self, title: str, tooltip: str | None = None) -> "TUIMenuFactory.TUIMenuItemBuilder":
+            return TUIMenuFactory.TUIMenuItemBuilder(self, self._menu_item, title, tooltip)
+
+        def with_action(self, title: str, tooltip: str | None = None) -> "TUIMenuFactory.TUIMenuActionBuilder":
+            return TUIMenuFactory.TUIMenuActionBuilder(self, self._menu_item, title, tooltip)
+
+        def with_view(self, title: str, tooltip: str | None = None) -> "TUIMenuFactory.TUIMenuViewBuilder":
+            return TUIMenuFactory.TUIMenuViewBuilder(self, self._menu_item, title, tooltip)
+
+        def then(self) -> MenuBuilder:
+            return self._parent
+
+    class TUIMenuViewBuilder:
+        """TODO"""
+
+        def __init__(
+            self, parent: MenuBuilder, parent_item: TUIMenuItem, title: str = None, tooltip: str | None = None
+        ):
+            check_not_none((parent, parent_item))
+            self._parent = parent
+            self._menu_view = TUIMenuView(parent_item, title, tooltip)
+            parent_item.add_items(self._menu_view)
+
+        def on_render(self, on_render: str | OnTrigger_Cb) -> "TUIMenuFactory.TUIMenuItemBuilder":
+            self._menu_view.on_render(on_render)
+            return self._parent
+
+    class TUIMenuActionBuilder:
+        """TODO"""
+
+        def __init__(
+            self, parent: MenuBuilder, parent_item: TUIMenuItem, title: str = None, tooltip: str | None = None
+        ):
+            check_not_none((parent, parent_item))
+            self._parent = parent
+            self._menu_action = TUIMenuAction(parent_item, title, tooltip)
+            self._parent_item = parent_item
+            parent_item.add_items(self._menu_action)
+
+        def on_trigger(self, action: OnTrigger_Cb) -> "TUIMenuFactory.TUIMenuItemBuilder":
+            check_not_none(action)
+            self._menu_action.on_trigger(action)
+            return self._parent
+
+    @classmethod
+    def create_main_menu(cls, title: str = None, tooltip: str | None = None) -> "TUIMenuBuilder":
+        cls._main_menu = TUIMenuItem(title=title, tooltip=tooltip)
+        factory = TUIMenuFactory()
+
+        return cls.TUIMenuBuilder(factory, cls._main_menu)
+
+    def build(self) -> TUIMenuItem:
+        return self._main_menu

build/lib/build/lib/clitt/core/tui/menu/tui_menu_item.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib
+   @package: clitt.core.tui.menu
+      @file: tui_menu_item.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.icons.font_awesome.nav_icons import NavIcons
+from clitt.core.term.commons import Direction, Portion
+from clitt.core.tui.menu.tui_menu import TUIMenu
+from clitt.core.tui.menu.tui_menu_ui import TUIMenuUi
+from functools import cached_property
+from hspylib.core.tools.dict_tools import get_or_default
+from hspylib.modules.cli.keyboard import Keyboard
+from typing import List, Optional
+
+
+class TUIMenuItem(TUIMenu):
+    """Represent a menu item with submenus. Each sub-item must belong to the TUIMenu class and can be an instance of
+    TUIMenuItem, TUIMenuAction or TUIMenuView.
+    """
+
+    ROW_OFFSET = 5
+
+    NAV_ICONS = NavIcons.compose(NavIcons.UP, NavIcons.DOWN)
+
+    def __init__(
+        self,
+        parent: Optional[TUIMenu] = None,
+        title: str = "Sub Menu",
+        tooltip: str = None,
+        items: List[TUIMenu] = None,
+    ):
+        super().__init__(parent, title, tooltip or f"Access the '{title}' menu")
+        self._show_from: int = 0
+        self._show_to: int = self.screen.lines - self.ROW_OFFSET
+        self._diff_index: int = self._show_to - self._show_from
+        self._sel_index: int = 0
+        self._items: List[TUIMenu] = items or []
+        self._max_line_length = max(len(str(menu)) for menu in self._items) if self._items else len(str(self))
+
+    @property
+    def items(self) -> List[TUIMenu]:
+        return self._items
+
+    def add_items(self, *items: TUIMenu) -> None:
+        """Add submenu items to the menu."""
+        list(map(self._items.append, items))
+
+    def execute(self) -> Optional[TUIMenu]:
+        # Wait for user interaction
+        while not self._done:
+            if not self._items:
+                return self._on_trigger(self._parent)
+
+            # Menu Renderization
+            if self._re_render:
+                self.render()
+
+            # Navigation input
+            if self.handle_keypress() == Keyboard.VK_ENTER:
+                return self._on_trigger(self._parent)
+
+        return None
+
+    def render(self) -> None:
+        length = len(self._items)
+        self.cursor.restore()
+        TUIMenuUi.render_app_title()
+
+        if length > 0:
+            for idx in range(self._show_from, self._show_to):
+                if idx >= length:
+                    break  # When the number of items is lower than the max_rows, skip the other lines
+                option_line = str(self._items[idx])
+                self.cursor.erase(Portion.LINE)
+                # Print the selector if the index is currently selected
+                selector = self.draw_selector(is_selected=(idx == self._sel_index), has_bg_color=False)
+                # fmt: off
+                line_fmt = (
+                    "  {:>" + f"{len(str(length))}" + "}  "
+                    + "{:>" + f"{len(selector)}" + "}  "
+                    + "{:<" + f"{self._max_line_length}" + "}  "
+                )
+                # fmt: on
+                self.draw_line(line_fmt, idx + 1, selector, option_line)
+
+        self.draw_navbar(self.navbar(to=length))
+        self._re_render = False
+
+    def navbar(self, **kwargs) -> str:
+        menu = get_or_default(self.items, self._sel_index, None)
+        tooltip = menu.tooltip if menu else None
+        return (
+            f"%EOL%%GREEN%{self.breadcrumb()} "
+            f"{tooltip + ' ' if tooltip else ''}%ED0%%NC%"
+            f"%EOL%{self.prefs.navbar_color.placeholder}%EOL%"
+            f"[Enter] Select  Navigate  [{self.NAV_ICONS}]  "
+            f"[Esc] Quit  [1..{kwargs['to']}] Goto: %NC%%EL0%%EOL%%EOL%"
+        )
+
+    def handle_keypress(self) -> Keyboard:
+        """Handle a keyboard press."""
+        if keypress := Keyboard.wait_keystroke():
+            match keypress:
+                case Keyboard.VK_ESC:
+                    self._done = True
+                case Keyboard.VK_UP:
+                    self._handle_key_up()
+                case Keyboard.VK_DOWN:
+                    self._handle_key_down()
+                case Keyboard.VK_TAB:
+                    self._handle_tab()
+                case Keyboard.VK_SHIFT_TAB:
+                    self._handle_shift_tab()
+                case _ as key if key in self._digits:
+                    self._handle_digit(keypress)
+            self._re_render = True
+
+        return keypress
+
+    def _handle_key_up(self) -> None:
+        """Handle a key up (arrow up) press."""
+        if self._sel_index == self._show_from and self._show_from > 0:
+            self._show_from -= 1
+            self._show_to -= 1
+        if self._sel_index - 1 >= 0:
+            self._sel_index -= 1
+            self._re_render = True
+
+    def _handle_key_down(self) -> None:
+        """Handle a key down (arrow down) press."""
+        length = len(self.items)
+        if self._sel_index + 1 == self._show_to and self._show_to < length:
+            self._show_from += 1
+            self._show_to += 1
+        if self._sel_index + 1 < length:
+            self._sel_index += 1
+            self._re_render = True
+
+    def _handle_tab(self) -> None:
+        """Handle a tab keypress."""
+        length = len(self.items)
+        page_index = min(self._show_to + self._diff_index, length)
+        self._show_to = max(page_index, self._diff_index)
+        self._show_from = self._show_to - self._diff_index
+        self._sel_index = self._show_from
+        self._re_render = True
+
+    def _handle_shift_tab(self) -> None:
+        """Handle a shift tab keypress."""
+        page_index = max(self._show_from - self._diff_index, 0)
+        self._show_from = min(page_index, self._diff_index)
+        self._show_to = self._show_from + self._diff_index
+        self._sel_index = self._show_from
+        self._re_render = True
+
+    def _handle_digit(self, digit: Keyboard) -> None:
+        """Handle a digit keypress.
+        :param digit: the digit pressed.
+        """
+        length = len(self._items)
+        typed_index = digit.value
+        self.write(digit.value)  # echo the digit typed
+        index_len = 1
+        while len(typed_index) < len(str(length)):
+            keystroke = Keyboard.wait_keystroke()
+            if not keystroke or not keystroke.isdigit():
+                typed_index = None if keystroke != Keyboard.VK_ENTER else typed_index
+                break
+            typed_index = f"{typed_index}{keystroke.value if keystroke else ''}"
+            self.write(f"{keystroke.value if keystroke else ''}")
+            index_len += 1
+        # Erase the index typed by the user
+        self.cursor.move(index_len, Direction.LEFT)
+        self.cursor.erase(Direction.RIGHT)
+        if typed_index and 1 <= int(typed_index) <= length:
+            self._show_to = max(int(typed_index), self._diff_index)
+            self._show_from = self._show_to - self._diff_index
+            self._sel_index = int(typed_index) - 1
+            self._re_render = True
+
+    def _default_trigger_cb(self, source: TUIMenu) -> Optional["TUIMenu"]:
+        return get_or_default(self._items, self._sel_index, self._parent)
+
+    @cached_property
+    def _digits(self) -> List[Keyboard]:
+        return Keyboard.digits()

build/lib/build/lib/clitt/core/tui/menu/tui_menu_ui.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib
+   @package: clitt.core.tui.menu
+      @file: tui_menu_ui.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.term.terminal import Terminal
+from clitt.core.tui.menu.tui_menu import TUIMenu
+from clitt.core.tui.tui_preferences import TUIPreferences
+from hspylib.core.metaclass.singleton import Singleton
+from hspylib.core.preconditions import check_not_none
+
+
+class TUIMenuUi(metaclass=Singleton):
+    """Provide a menu for terminal UIs. Each sub-item must belong to the TUIMenu class and can be an instance of
+    TUIMenuItem, TUIMenuAction or TUIMenuView.
+    """
+
+    APP_TITLE = "Main Menu"
+
+    # fmt: off
+    PREFS = TUIPreferences.INSTANCE
+
+    SCREEN = Terminal.INSTANCE.screen
+
+    MENU_LINE = f"{'--' * PREFS.title_line_length}"
+
+    MENU_TITLE_FMT = (
+        f"{PREFS.title_color}"
+        f"+{MENU_LINE}+%EOL%"
+        "|{title:^" + str(2 * PREFS.title_line_length) + "s}|%EOL%"
+        f"+{MENU_LINE}+%EOL%%NC%"
+    )
+    # fmt: on
+
+    @classmethod
+    def render_app_title(cls, app_title: str = None) -> None:
+        """Render the application title."""
+        cls.SCREEN.clear()
+        cls.SCREEN.cursor.writeln(cls.MENU_TITLE_FMT.format(title=app_title or cls.APP_TITLE))
+
+    @staticmethod
+    def back(source: TUIMenu) -> TUIMenu:
+        """Return the parent menu from the source of the event.
+        :param source: the source menu of the event.
+        """
+        return source.parent
+
+    def __init__(self, main_menu: TUIMenu, title: str = "Main Menu"):
+        check_not_none(main_menu)
+        super().__init__()
+        TUIMenuUi.APP_TITLE = title
+        self._done: bool = False
+        self._curr_menu: TUIMenu = main_menu
+        self._prev_menu = None
+        self._next_menu = None
+
+    def execute(self) -> None:
+        """Execute the terminal menu UI flow."""
+
+        self._prepare_render()
+
+        while not self._done:
+            if self._curr_menu:
+                self._next_menu = self._curr_menu.execute()
+                if self._next_menu:
+                    self._change_menu(
+                        self._next_menu
+                        if isinstance(self._next_menu, TUIMenu)
+                        else next((menu for menu in self._next_menu if menu), None)
+                    )
+                else:
+                    self._done = True
+            else:
+                self._done = True
+
+    def _prepare_render(self, auto_wrap: bool = True, show_cursor: bool = False, clear_screen: bool = True) -> None:
+        """Prepare the screen for renderization."""
+        Terminal.set_auto_wrap(auto_wrap)
+        Terminal.set_show_cursor(show_cursor)
+        if clear_screen:
+            self.SCREEN.clear()
+        self.SCREEN.cursor.save()
+
+    def _change_menu(self, new_menu: TUIMenu) -> None:
+        """Change the current menu and keep track about the previous one.
+        :param new_menu: the menu to be changed to.
+        """
+        self._prev_menu = self._curr_menu
+        self._curr_menu = new_menu

build/lib/build/lib/clitt/core/tui/menu/tui_menu_view.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib
+   @package: clitt.core.tui.menu
+      @file: tui_menu_view.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.term.commons import Direction
+from clitt.core.tui.menu.tui_menu import OnTrigger_Cb, TUIMenu
+from clitt.core.tui.menu.tui_menu_ui import TUIMenuUi
+from typing import Callable, Optional
+
+
+class TUIMenuView(TUIMenu):
+    """Represent a menu view without submenus. Each view can have a view to be displayed. If no view is provided, it
+    will behave like an action.
+    """
+
+    def __init__(
+        self,
+        parent: TUIMenu,
+        title: Optional[str] = None,
+        tooltip: Optional[str] = None,
+        display_text: Optional[str] = None,
+    ):
+        super().__init__(parent, title or "Menu View", tooltip or f"Access the '{title}' view")
+        self._on_render: OnTrigger_Cb = self._display_content
+        self._content: str = display_text or f"%ED0%This is a view: {self.title}"
+
+    def on_render(self, on_render: str | OnTrigger_Cb) -> None:
+        if isinstance(on_render, str):
+            self._content = on_render
+            self._on_render = self._display_content
+        elif isinstance(on_render, Callable):
+            self._on_render = on_render
+            self._content = f"This is a view: {self.title}"
+
+    def execute(self) -> Optional[TUIMenu]:
+        self.render()
+        return self._on_trigger(self)
+
+    def render(self) -> None:
+        TUIMenuUi.render_app_title()
+        self._on_render()
+        self.draw_navbar(self.navbar())
+
+    def _display_content(self) -> None:
+        self.cursor.erase(Direction.DOWN)
+        self.writeln(self._content)
+        self.wait_keystroke()

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

@@ -0,0 +1,19 @@
+# _*_ coding: utf-8 _*_
+#
+# hspylib-clitt v0.9.120
+#
+# Package: main.build.lib.build.lib.build.lib.clitt.core.tui.minput
+"""Package initialization."""
+
+__all__ = [
+    'access_type', 
+    'field_builder', 
+    'form_builder', 
+    'form_field', 
+    'input_type', 
+    'input_validator', 
+    'menu_input', 
+    'minput', 
+    'minput_utils'
+]
+__version__ = '0.9.120'

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

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib
+   @package: clitt.core.tui.minput
+      @file: access_type.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
+
+
+class AccessType(Enumeration):
+    """MenuInput input field access types."""
+
+    # fmt: off
+    NO_ACCESS   = "no-access"
+    READ_ONLY   = "read-only"
+    READ_WRITE  = "read-write"
+    # fmt: on

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

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib
+   @package: clitt.core.tui.minput
+      @file: field_builder.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.tui.minput.access_type import AccessType
+from clitt.core.tui.minput.form_field import FieldValidator_Fn, FormField
+from clitt.core.tui.minput.input_type import InputType
+from clitt.core.tui.minput.input_validator import InputValidator
+from clitt.core.tui.minput.minput_utils import get_selected, MASK_SYMBOLS, unpack_masked, VALUE_SEPARATORS
+from functools import reduce
+from hspylib.core.preconditions import check_argument
+from hspylib.core.tools.commons import to_bool
+from hspylib.core.tools.text_tools import snakecase
+from operator import add
+from typing import Any
+
+import re
+
+
+class FieldBuilder:
+    """MenuInput form field builder."""
+
+    @staticmethod
+    def _validate_field(field: FormField) -> bool:
+        match field.itype:
+            case InputType.MASKED:
+                value, mask = unpack_masked(field.value)
+                valid = reduce(add, list(map(mask[len(value) :].count, MASK_SYMBOLS))) == 0
+            case InputType.CHECKBOX:
+                valid = isinstance(field.value, bool)
+            case InputType.SELECT:
+                _, value = get_selected(field.value)
+                length = len(str(value or ""))
+                valid = field.min_length <= length <= field.max_length
+            case _:
+                length = len(str(field.value or ""))
+                valid = field.min_length <= length <= field.max_length
+        return valid
+
+    def __init__(self, parent: Any):
+        self._parent = parent
+        self._label = "Label"
+        self._dest = None
+        self._itype = InputType.TEXT
+        self._access_type = AccessType.READ_WRITE
+        self._min_max_length = 5, 30
+        self._value = ""
+        self._validator = InputValidator.anything(), self._validate_field
+
+    def label(self, label: str) -> "FieldBuilder":
+        self._label = label
+        return self
+
+    def dest(self, dest: str) -> "FieldBuilder":
+        self._dest = dest
+        return self
+
+    def itype(self, itype: str) -> "FieldBuilder":
+        self._itype = InputType.of_value(itype)
+        return self
+
+    def min_max_length(self, min_length: int, max_length: int) -> "FieldBuilder":
+        check_argument(max_length >= min_length, "Invalid field length: ({}-{})", min_length, max_length)
+        check_argument(max_length > 0 and min_length >= 0, "Invalid field length: ({}-{})", min_length, max_length)
+        self._min_max_length = min_length, max_length
+        return self
+
+    def access_type(self, access_type: str) -> "FieldBuilder":
+        self._access_type = AccessType.of_value(access_type)
+        return self
+
+    def value(self, value: Any | None) -> "FieldBuilder":
+        self._value = value
+        return self
+
+    def validator(
+        self, input_validator: InputValidator = None, field_validator: FieldValidator_Fn = None
+    ) -> "FieldBuilder":
+        self._validator = input_validator, field_validator or self._validate_field
+        return self
+
+    def build(self) -> Any:
+        if self._itype == InputType.CHECKBOX:
+            self._value = to_bool(str(self._value))
+        elif self._itype == InputType.SELECT:
+            parts = re.split(VALUE_SEPARATORS, re.sub("[<>]", "", str(self._value or "")))
+            self._min_max_length = len(min(parts, key=len)), len(max(parts, key=len))
+        elif self._itype == InputType.MASKED:
+            _, mask = unpack_masked(str(self._value))
+            min_max = reduce(add, list(map(mask.count, MASK_SYMBOLS)))
+            self._min_max_length = min_max, min_max
+        self._dest = self._dest or snakecase(self._label)
+        self._parent.fields.append(
+            FormField(
+                self._label,
+                self._dest,
+                self._itype,
+                self._min_max_length[0],
+                self._min_max_length[1],
+                self._access_type,
+                self._value,
+                self._validator[0],
+                self._validator[1],
+            )
+        )
+
+        return self._parent