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

build/lib/clitt/core/icons/font_awesome/nav_icons.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib-Clitt
+   @package: clitt.core.icons.font_awesome
+      @file: nav_icons.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.awesome import Awesome
+from enum import auto
+
+
+# @composable
+class NavIcons(Awesome):
+    """
+    Navigation icons.
+    Codes can be found here:
+    - https://fontawesome.com/cheatsheet?from=io
+    """
+
+    # fmt: off
+    _CUSTOM         = auto()
+    UP              = '\u2191'  # ↑
+    RIGHT           = '\u2192'  # →
+    DOWN            = '\u2193'  # ↓
+    LEFT            = '\u2190'  # ←
+    UP_DOWN         = '\uF9E1'  # 李
+    LEFT_RIGHT      = '\uF9E0'  # 易
+    ENTER           = '\u21B5'  # ↵
+    TAB             = '\u21B9'  # ↹
+    BACKSPACE       = '\u232B'  # ⌫
+    POINTER         = '\uF432'  # 
+    SELECTED        = '\uF814'  # 
+    UNSELECTED      = '\uF815'  # 
+    BREADCRUMB      = '\uF44A'  # 
+    # fmt: on

build/lib/clitt/core/icons/font_awesome/trickplay_icons.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib-Clitt
+   @package: clitt.core.icons.font_awesome
+      @file: trickplay_icons.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.awesome import Awesome
+from enum import auto
+
+
+# @composable
+class TrickplayIcons(Awesome):
+    """
+    Navigation icons.
+    Codes can be found here:
+    - https://fontawesome.com/cheatsheet?from=io
+    """
+
+    # fmt: off
+    _CUSTOM         = auto()
+    PREVIOUS        = '\uF048'  # 
+    REWIND          = '\uF049'  # 
+    BACKWARD        = '\uF04A'  # 
+    PLAY            = '\uF04B'  # 
+    PAUSE           = '\uF04C'  # 
+    STOP            = '\uF04D'  # 
+    NEXT            = '\uF051'  # 
+    ADVANCE         = '\uF050'  # 
+    FORWARD         = '\uF04E'  # 
+    EJECT           = '\uF052'  # 
+    # fmt: on

build/lib/clitt/core/icons/font_awesome/widget_icons.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib-Clitt
+   @package: clitt.core.icons.font_awesome
+      @file: widget_icons.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.icons.font_awesome.awesome import Awesome
+from enum import auto
+
+
+class WidgetIcons(Awesome):
+    """
+    Dashboard UI icons.
+    Codes can be found here:
+    - https://fontawesome.com/cheatsheet?from=io
+    """
+
+    # fmt: off
+    _CUSTOM         = auto()
+    CHART_2         = '\uF200'  # 
+    CHART_1         = '\uF1FE'  # 
+    CLOCK           = '\uF651'  # 
+    CHIP            = '\uFB19'  # ﬙
+    MUSIC           = '\uF3B5'  # 
+    NETWORK         = '\uF819'  # 
+    PUNCH           = '\uF255'  # 
+    SIGN            = '\uF45D'  # 
+    WIDGET          = '\uF198'  # 
+    # fmt: on

build/lib/clitt/core/preferences.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: HsPyLib-Clitt
+   @package: clitt.core
+      @file: preferences.py
+   @created: Fri, 7 Jul 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 enum import Enum
+from hspylib.core.metaclass.singleton import AbstractSingleton
+from hspylib.core.preconditions import check_argument, check_not_none
+from hspylib.core.tools.dict_tools import get_or_default_by_key
+from hspylib.core.tools.text_tools import ensure_startswith, environ_name
+from typing import Any
+
+import os
+
+
+class Preferences(metaclass=AbstractSingleton):
+    """General purpose bas class to provide preference management."""
+
+    def __init__(self, prefix: str = ""):
+        self._prefix = prefix
+        self._overrides = {}
+
+    def __str__(self):
+        # fmt: off
+        return (
+            f"Terminal UI Preferences{os.linesep}"
+            f"{'-=' * 20}{os.linesep}"
+            + os.linesep.join([f"|-{p[1:]:<16}: {getattr(self, p)}" for p in vars(self)])
+            + f"{os.linesep}{'-=' * 20}{os.linesep}"
+        )
+        # fmt: on
+
+    def __repr__(self):
+        return str(self)
+
+    def __getitem__(self, name: str):
+        attr_name = name.replace(self._prefix + ".", "").replace(".", "_")
+        return getattr(self, attr_name)
+
+    def __setitem__(self, name: str, value: Any):
+        attr_name = name.replace(self._prefix + ".", "").replace(".", "_")
+        curr_val = getattr(self, attr_name)
+        t1, t2 = type(curr_val), type(value)
+        check_not_none(curr_val, f"Preference '{name}' does not exist")
+        check_argument(t1 == t2, f"Preference '{name}' value must be of type '{t1}', not '{t2}'")
+        self._overrides[self._get_name(name)] = value
+
+    def __iter__(self):
+        return self._overrides.__iter__()
+
+    def __len__(self):
+        return len(self._overrides)
+
+    def get_preference(self, name: str, default: Any = None) -> Any:
+        """Retrieve preference for the given specified name. If not found, return the default value.
+        :param name: the preference name.
+        :param default: the preference default value.
+        :return the preference value.
+        """
+        pref_name = self._get_name(name)
+        value = get_or_default_by_key(self._overrides, pref_name, default)
+        if str_value := os.environ.get(environ_name(pref_name)):
+            type_attr = type(value)
+            try:
+                if isinstance(value, Enum):
+                    value = type_attr[str_value.upper()]
+                else:
+                    value = type_attr(str_value)
+            except (KeyError, TypeError, ValueError):
+                pass
+        return value
+
+    def _get_name(self, name: str) -> str:
+        """Retrieve the preference name based. It uses the specified prefix to compose the actual name.
+        :param name: the preference name.
+        :return the prefixed preference name.
+        """
+        return ensure_startswith(name, self._prefix + ".")

build/lib/clitt/core/term/__init__.py

@@ -0,0 +1,14 @@
+# _*_ coding: utf-8 _*_
+#
+# hspylib-clitt v0.9.119
+#
+# Package: main.build.lib.build.lib.clitt.core.term
+"""Package initialization."""
+
+__all__ = [
+    'commons', 
+    'cursor', 
+    'screen', 
+    'terminal'
+]
+__version__ = '0.9.119'

build/lib/clitt/core/term/commons.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: hspylib-clitt
+   @package: hspylib-clitt.main.clitt.core.term
+      @file: commons.py
+   @created: Wed, 20 Mar 2024
+    @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 2024, HSPyLib team
+"""
+
+import re
+import sys
+import termios
+import tty
+from shutil import get_terminal_size
+from typing import Callable, Tuple, TypeAlias, Union
+
+from hspylib.core.enums.enumeration import Enumeration
+from hspylib.core.tools.commons import is_debugging
+from hspylib.modules.cli.vt100.vt_100 import Vt100
+
+# fmt: off
+Dimension       : TypeAlias = Tuple[int, int]
+Position        : TypeAlias = Tuple[int, int]
+Resize_Cb       : TypeAlias = Callable[[], None]
+MoveDirection   : TypeAlias = "Direction"
+EraseDirection  : TypeAlias = Union["Direction", "Portion"]
+# fmt: on
+
+
+def is_a_tty() -> bool:
+    """Checks whether we are under a tty environment."""
+    try:
+        return sys.stdout.isatty() and sys.stdin.isatty()
+    except ValueError:
+        return sys.stdout.isatty()
+
+
+class Direction(Enumeration):
+    """Provide a base class for the cursor direction."""
+
+    # fmt: off
+    UP          = '%ED1%', '%CUU({n})%'   # Cursor up (line)
+    RIGHT       = '%EL0%', '%CUF({n})%'   # Cursor right (forward)
+    DOWN        = '%ED0%', '%CUD({n})%'   # Cursor down (line)
+    LEFT        = '%EL1%', '%CUB({n})%'   # Cursor left (backward)
+    # fmt: on
+
+
+class Portion(Enumeration):
+    """Provide a base class for the portions of the screen."""
+
+    # fmt: off
+    SCREEN      = '%ED2%', ''   # Entire screen (screen)
+    LINE        = '%EL2%', ''   # Entire line (line)
+    # fmt: on
+
+
+def get_dimensions(fallback: Tuple[int, int] = (24, 80)) -> Tuple[int, int]:
+    """Retrieve the size of the terminal.
+    :return lines, columns
+    """
+    if not is_a_tty():
+        return fallback
+    dim = get_terminal_size((fallback[1], fallback[0]))
+    return dim.lines, dim.columns
+
+
+def get_cursor_position(fallback: Tuple[int, int] = (0, 0)) -> Tuple[int, int]:
+    """Get the terminal cursor position.
+    :return line, column
+    """
+    pos = fallback
+
+    if is_debugging():
+        return pos
+
+    if not is_a_tty():
+        return pos
+
+    buf, re_query_resp = "", r"^\x1b\[(\d*);(\d*)R"
+    stdin, attrs = None, None
+
+    try:
+        stdin = sys.stdin.fileno()  # Get the stdin file descriptor.
+        attrs = termios.tcgetattr(stdin)  # Save terminal attributes.
+        tty.setcbreak(stdin, termios.TCSANOW)
+        sys.stdout.write(Vt100.get_cursor_pos())
+        sys.stdout.flush()
+        while not buf or buf[-1] != "R":
+            buf += sys.stdin.read(1)
+        if matches := re.match(re_query_resp, buf):  # If the response is 'Esc[r;cR'
+            groups = matches.groups()
+            pos = int(groups[0]), int(groups[1])
+    except termios.error:
+        pass
+    finally:
+        if stdin and attrs:
+            termios.tcsetattr(stdin, termios.TCSANOW, attrs)  # Reset terminal attributes
+
+    return pos

build/lib/clitt/core/term/cursor.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: hspylib-clitt
+   @package: hspylib-clitt.main.clitt.core.term
+      @file: cursor.py
+   @created: Wed, 20 Mar 2024
+    @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 2024, HSPyLib team
+"""
+
+from clitt.core.term.commons import Direction, EraseDirection, get_cursor_position, MoveDirection, Portion, Position
+from hspylib.core.metaclass.singleton import Singleton
+from hspylib.core.tools.commons import sysout
+from hspylib.core.tools.text_tools import last_index_of
+from hspylib.modules.cli.vt100.vt_100 import Vt100
+from hspylib.modules.cli.vt100.vt_code import VtCode
+from hspylib.modules.cli.vt100.vt_color import VtColor
+from typing import Any
+
+import os
+
+
+class Cursor(metaclass=Singleton):
+    """Provide a base class for the screen cursor."""
+
+    INSTANCE = None
+
+    CURSOR_HOME = 1, 1
+
+    def __init__(self):
+        self._position: Position = get_cursor_position() or self.CURSOR_HOME
+        self._bottom: Position = self.CURSOR_HOME
+        self._saved_attrs = self._position, self._bottom
+
+    def __str__(self):
+        return f"({', '.join(list(map(str, self._position)))})"
+
+    def __repr__(self):
+        return str(self)
+
+    @property
+    def position(self) -> Position:
+        return self._position
+
+    @position.setter
+    def position(self, new_position: Position) -> None:
+        self._bottom = (new_position[0], new_position[1]) if new_position >= self._bottom else self._bottom
+        self._position = new_position
+
+    @property
+    def bottom(self) -> Position:
+        return self._bottom
+
+    def home(self) -> None:
+        """Move the cursor to home position.
+        :return None
+        """
+        self.move_to(self.CURSOR_HOME[0], self.CURSOR_HOME[1])
+
+    def end(self) -> None:
+        """Move the cursor to the bottom most position on the screen.
+        :return None
+        """
+        self.move_to(self.bottom[0], self.bottom[1])
+
+    def move_to(self, row: int = None, column: int = None) -> Position:
+        """Move the cursor to the specified position.
+        :param row the specified row to move.
+        :param column the specified column to move.
+        :return the cursor position after moving.
+        """
+        row_pos = max(self.CURSOR_HOME[0], row if row is not None else self.position[0])
+        col_pos = max(self.CURSOR_HOME[1], column if column is not None else self.position[1])
+        sysout(f"%CUP({row_pos};{col_pos})%", end="")
+        self.position = row_pos, col_pos
+        return self.position
+
+    def move(self, amount: int, direction: MoveDirection) -> Position:
+        """Move the cursor towards the specified direction.
+        :param amount the amount of columns to move.
+        :param direction the direction to move.
+        :return the cursor position after moving.
+        """
+        if amount > 0:
+            sysout(direction.value[1].format(n=amount), end="")
+            row_pos, col_pos = self.position
+            match direction:
+                case Direction.UP:
+                    row_pos -= max(0, amount)
+                case Direction.DOWN:
+                    row_pos += max(0, amount)
+                case Direction.LEFT:
+                    col_pos -= max(0, amount)
+                case Direction.RIGHT:
+                    col_pos += max(0, amount)
+            self.position = row_pos, col_pos
+        return self.position
+
+    def erase(self, direction: EraseDirection) -> Position:
+        """Erase the screen following the specified direction.
+           Note: It does not move the cursor along the way.
+        :param direction the direction to erase the screen.
+        :return the cursor position after erasing.
+        """
+        sysout(direction.value[0], end="")
+        return self.position
+
+    def erase_line(self) -> Position:
+        """Erase the previous line of the screen."""
+        row_pos, col_pos = self.position
+        self.move(1, Direction.UP)
+        self.erase(Portion.LINE)
+        self.move(col_pos, Direction.LEFT)
+        self.position = row_pos, 0
+        return self.position
+
+    def track(self) -> Position:
+        """Track the cursor position.
+        :return the tracked cursor position.
+        """
+        self.position = get_cursor_position() or self.position
+        return self.position
+
+    def write(self, obj: Any, end: str = "") -> Position:
+        """Write the string representation of the object to the screen.
+        :param obj the object to be written.
+        :param end string appended after the last value, default a newline.
+        :return the cursor position after writing.
+        """
+        sysout(obj, end=end)
+        text = (str(obj) + end).replace("%EOL%", os.linesep)
+        text = VtColor.strip_colors(VtCode.strip_codes(text))
+        text_offset = len(text[max(0, last_index_of(text, os.linesep)) :])
+        self.position = self.position[0] + text.count(os.linesep), text_offset + (
+            self.position[1] if text.count(os.linesep) == 0 else 0
+        )
+        return self.position
+
+    def writeln(self, obj: Any) -> Position:
+        """Write the string representation of the object to the screen, appending a new line.
+        :param obj the object to be written.
+        :return the cursor position after writing.
+        """
+        return self.write(obj, end=os.linesep)
+
+    def save(self) -> Position:
+        """Save the current cursor position and attributes.
+        :return the actual cursor position.
+        """
+        sysout(Vt100.save_cursor(), end="")
+        self._saved_attrs = self._position, self._bottom
+        return self.position
+
+    def restore(self) -> Position:
+        """Restore the saved cursor position and attributes.
+        :return the cursor position after restoration.
+        """
+        sysout(Vt100.restore_cursor(), end="")
+        self._position = self._saved_attrs[0]
+        self._bottom = self._saved_attrs[1]
+        return self.position
+
+    def reset_mode(self, end="") -> Position:
+        """Reset cursor modifiers."""
+        sysout(Vt100.mode(0), end=end)
+        return self.position
+
+
+assert (cursor := Cursor().INSTANCE) is not None, "Failed to create Cursor instance"

build/lib/clitt/core/term/screen.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+   @project: hspylib-clitt
+   @package: hspylib-clitt.main.clitt.core.term
+      @file: screen.py
+   @created: Wed, 20 Mar 2024
+    @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 2024, HSPyLib team
+"""
+
+from clitt.core.term.commons import Dimension, get_dimensions, Portion, Resize_Cb
+from clitt.core.term.cursor import Cursor
+from clitt.core.tui.tui_preferences import TUIPreferences
+from hspylib.core.metaclass.singleton import Singleton
+from hspylib.core.tools.commons import sysout
+from threading import Timer
+from typing import List, Optional
+
+import threading
+
+
+class Screen(metaclass=Singleton):
+    """Provide a base class for terminal UI components."""
+
+    INSTANCE = None
+
+    RESIZE_WATCH_INTERVAL = 0.5
+
+    def __init__(self):
+        self._preferences: TUIPreferences = TUIPreferences.INSTANCE
+        self._dimension: Dimension = get_dimensions()
+        self._cursor: Cursor = Cursor.INSTANCE or Cursor()
+        self._resize_timer: Optional[Timer] = None
+        self._cb_watchers: List[Resize_Cb] = []
+        self._alternate: bool = False
+        self._resize_watcher()
+
+    def __str__(self):
+        return f"Terminal.Screen(rows={self.lines}, columns={self.columns}, cursor={self.cursor})"
+
+    def __repr__(self):
+        return str(self)
+
+    @property
+    def preferences(self) -> TUIPreferences:
+        return self._preferences
+
+    @property
+    def dimension(self) -> Dimension:
+        return self._dimension
+
+    @property
+    def lines(self) -> int:
+        return self._dimension[0]
+
+    @property
+    def columns(self) -> int:
+        return self._dimension[1]
+
+    @property
+    def cursor(self) -> Cursor:
+        return self._cursor
+
+    @property
+    def alternate(self) -> bool:
+        return self._alternate
+
+    @alternate.setter
+    def alternate(self, enable: bool) -> None:
+        """Switch to the alternate screen buffer.
+        :param enable: alternate enable on/off.
+        """
+        if enable != self._alternate:
+            self._alternate = enable
+            sysout(f"%SC{'A' if enable else 'M'}%", end="")
+            self.cursor.track()
+
+    def clear(self) -> None:
+        """Clear terminal and move the cursor to HOME position (0, 0)."""
+        self.cursor.home()
+        self.cursor.erase(Portion.SCREEN)
+
+    def add_watcher(self, watcher: Resize_Cb) -> None:
+        """Add a resize watcher."""
+        self._cb_watchers.append(watcher)
+        if not self._resize_timer:
+            self._resize_watcher()
+
+    def _resize_watcher(self) -> None:
+        """Add a watcher for screen resizes. If a resize is detected, the callback is called with the
+        new dimension."""
+        if self._cb_watchers and threading.main_thread().is_alive():
+            dimension: Dimension = get_dimensions()
+            self._resize_timer = Timer(self.RESIZE_WATCH_INTERVAL, self._resize_watcher)
+            if dimension != self._dimension:
+                list(map(lambda cb_w: cb_w(), self._cb_watchers))
+                self._dimension = dimension
+            self._resize_timer.start()
+
+
+assert (screen := Screen().INSTANCE) is not None, "Failed to create Screen instance"