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

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

@@ -1,106 +0,0 @@
-#!/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

@@ -1,174 +0,0 @@
-#!/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

@@ -1,106 +0,0 @@
-#!/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"

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

@@ -1,202 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-   @project: HsPyLib
-   @package: hspylib.modules.cli.vt100
-      @file: terminal.py
-   @created: Tue, 11 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.exception.exceptions import NotATerminalError
-from clitt.core.term.commons import is_a_tty
-from clitt.core.term.cursor import Cursor
-from clitt.core.term.screen import Screen
-from hspylib.core.enums.charset import Charset
-from hspylib.core.metaclass.singleton import Singleton
-from hspylib.core.tools.commons import sysout
-from hspylib.modules.application.exit_status import ExitStatus
-from hspylib.modules.cli.keyboard import Keyboard
-from hspylib.modules.cli.vt100.vt_100 import Vt100
-from subprocess import CalledProcessError, PIPE, Popen
-from typing import Any, Iterable, List, Optional, Tuple
-
-import atexit
-import logging as log
-import os
-import platform
-import select
-import shlex
-import signal
-
-
-class Terminal(metaclass=Singleton):
-    """Utility class to provide terminal features."""
-
-    INSTANCE = None
-
-    @staticmethod
-    def is_a_tty() -> bool:
-        return is_a_tty()
-
-    @staticmethod
-    def _chain_pipes(cmd_list: Iterable, **kwargs) -> Popen:
-        """Run commands in PIPE, return the last process in chain.
-        :param cmd_list: the command list to be executed.
-        """
-        if "stdout" in kwargs:
-            del kwargs["stdout"]
-        if "stderr" in kwargs:
-            del kwargs["stderr"]
-        if "stdin" in kwargs:
-            del kwargs["stdin"]
-        commands = map(shlex.split, cmd_list) if "shell" not in kwargs else cmd_list
-        first_cmd, *rest_cmds = commands
-        if len(rest_cmds) > 0:
-            procs: List[Popen] = [Popen(first_cmd, stdout=PIPE, stderr=PIPE, **kwargs)]
-            for cmd in rest_cmds:
-                last_stdout = procs[-1].stdout
-                procs.append(Popen(cmd, stdin=last_stdout, stdout=PIPE, stderr=PIPE, **kwargs))
-            return procs[-1]
-        return Popen(first_cmd, stdout=PIPE, stderr=PIPE, **kwargs)
-
-    @staticmethod
-    def shell_exec(cmd_line: str, **kwargs) -> Tuple[Optional[str], ExitStatus]:
-        """Execute command with arguments and return it's run status.
-        :param cmd_line: the command line to be executed.
-        """
-        proc = Terminal._chain_pipes(cmd_line.split("|"), **kwargs)
-        log.info("Executing shell command: %s", cmd_line)
-        output, err_out = proc.communicate()
-        ret_code = ExitStatus.FAILED if err_out else ExitStatus.SUCCESS
-        log.info("Execution result: %s", ret_code)
-        return output.decode(Charset.UTF_8.val) if output else err_out.decode(Charset.UTF_8.val), ret_code
-
-    @staticmethod
-    def shell_poll(cmd_line: str, **kwargs) -> None:
-        """Execute command with arguments and continuously poll it's output.
-        :param cmd_line: the command line to be executed.
-        """
-        if "stdout" in kwargs:
-            del kwargs["stdout"]  # Deleted because it's forbidden
-        if "stderr" in kwargs:
-            del kwargs["stderr"]  # Deleted because it's forbidden
-        if "shell" in kwargs:
-            del kwargs["shell"]  # Deleted because we don't want to use it
-        try:
-            log.info("Polling shell command: %s", cmd_line)
-            cmd_args = list(filter(None, shlex.split(cmd_line)))
-            with Popen(cmd_args, stdout=PIPE, stderr=PIPE, **kwargs) as proc:
-                process = select.poll()
-                process.register(proc.stdout)
-                process.register(proc.stderr)
-                while not Keyboard.kbhit():
-                    if poll_obj := process.poll(0.5):
-                        line = proc.stdout.readline()
-                        sysout(line.decode(Charset.UTF_8.val) if isinstance(line, bytes) else line.strip(), end="")
-                        log.debug("Polling returned: %s", str(poll_obj))
-                os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
-        except (InterruptedError, KeyboardInterrupt):
-            log.warning("Polling process has been interrupted command='%s'", cmd_line)
-        except CalledProcessError as err:
-            log.error("Command failed: %s => %s", cmd_line, err)
-
-    @staticmethod
-    def open(filename: str) -> None:
-        """Open the specified file using the default editor."""
-        my_os = os.environ.get("HHS_MY_OS", platform.system())
-        if "Darwin" == my_os:
-            Terminal.shell_exec(f"open {filename}")
-        elif "Linux" == my_os:
-            Terminal.shell_exec(f"xdg-open {filename}")
-        else:
-            raise NotImplementedError(f"OS '{my_os}' is not supported")
-
-    @classmethod
-    def restore(cls) -> None:
-        """Clear the terminal and restore default attributes [wrap,cursor,echo]."""
-        cls.set_attributes(show_cursor=True, auto_wrap=True, enable_echo=True)
-        cls.alternate_screen(False)
-        sysout("%MOD(0)%", end="")
-
-    @classmethod
-    def set_enable_echo(cls, enabled: bool = True) -> None:
-        """Enable echo in the terminal.
-        :param enabled: whether is enabled or not.
-        """
-        if not cls.is_a_tty():
-            log.warning(NotATerminalError("set_enable_echo:: Requires a terminal (TTY)"))
-            return
-
-        os.popen(f"stty {'echo -raw' if enabled else 'raw -echo min 0'}").read()
-
-    @classmethod
-    def set_auto_wrap(cls, auto_wrap: bool = True) -> None:
-        """Set auto-wrap mode in the terminal.
-        :param auto_wrap: whether auto_wrap is set or not.
-        """
-        if not cls.is_a_tty():
-            log.warning(NotATerminalError("set_auto_wrap:: Requires a terminal (TTY)"))
-            return
-
-        sysout(Vt100.set_auto_wrap(auto_wrap), end="")
-
-    @classmethod
-    def set_show_cursor(cls, show_cursor: bool = True) -> None:
-        """Show or hide cursor in the terminal.
-        :param show_cursor: whether to show or hide he cursor.
-        """
-        if not cls.is_a_tty():
-            log.warning(NotATerminalError("set_show_cursor:: Requires a terminal (TTY)"))
-            return
-
-        sysout(Vt100.set_show_cursor(show_cursor), end="")
-
-    @classmethod
-    def set_attributes(cls, **attrs) -> None:
-        """Wrapper to set all terminal attributes at once."""
-        # fmt: off
-        enable_echo = attrs['enable_echo']
-        auto_wrap = attrs['auto_wrap']
-        show_cursor = attrs['show_cursor']
-        # fmt: on
-        if enable_echo is not None:
-            cls.set_enable_echo(enable_echo)
-        if auto_wrap is not None:
-            cls.set_auto_wrap(auto_wrap)
-        if show_cursor is not None:
-            cls.set_show_cursor(show_cursor)
-
-    @classmethod
-    def clear(cls) -> None:
-        """Clear terminal and move the cursor to HOME position (0, 0)."""
-        cls.INSTANCE.screen.clear()
-
-    @classmethod
-    def echo(cls, obj: Any, end: str = os.linesep) -> None:
-        """Write the string representation of the object to the screen."""
-        cls.INSTANCE.screen.cursor.write(obj, end=end)
-
-    @classmethod
-    def alternate_screen(cls, enable: bool) -> None:
-        """Switch to the alternate screen buffer on/off."""
-        cls.INSTANCE.screen.alternate = enable
-
-    def __init__(self):
-        self._screen = Screen.INSTANCE or Screen()
-        atexit.register(self.restore)
-
-    @property
-    def screen(self) -> Screen:
-        return self._screen
-
-    @property
-    def cursor(self) -> Cursor:
-        return self.screen.cursor
-
-
-assert (terminal := Terminal().INSTANCE) is not None, "Failed to create Terminal instance"

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

@@ -1,20 +0,0 @@
-# _*_ coding: utf-8 _*_
-#
-# hspylib-clitt v0.9.120
-#
-# Package: main.build.lib.build.lib.clitt.core.tui
-"""Package initialization."""
-
-__all__ = [
-    'line_input', 
-    'mchoose', 
-    'mdashboard', 
-    'menu', 
-    'minput', 
-    'mselect', 
-    'table', 
-    'tui_application', 
-    'tui_component', 
-    'tui_preferences'
-]
-__version__ = '0.9.120'

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

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