termcore 0.2.0__py3-none-any.whl

termcore/__init__.py

@@ -0,0 +1,6 @@
+"""Terminal utilities for CLI, TUI, IO and general use."""
+
+from .cli import *
+from .io import *
+from .tui import *
+from .util import *

termcore/cli/__init__.py

@@ -0,0 +1,3 @@
+"""Styled console output for command line applications."""
+
+from .output import *

termcore/cli/output.py

@@ -0,0 +1,70 @@
+"""
+Provides utility functions for styled CLI output using Rich.
+
+Includes helpers for printing color-coded panels (error, warning, success and
+info) and a function to clear previously printed lines from the terminal.
+"""
+import sys
+
+from rich.console import Console
+from rich.panel import Panel
+
+__all__ = [
+    "clear_lines",
+    "console",
+    "get_console",
+    "print_custom_panel",
+    "print_error",
+    "print_info",
+    "print_panel",
+    "print_success",
+    "print_warning",
+]
+
+console = Console()
+
+
+def get_console() -> Console:
+    """Returns the Rich Console instance."""
+    return console
+
+
+def print_error(message: str) -> None:
+    """Prints an error message in a red panel using Rich."""
+    print_panel(f"✗ {message}", "red")
+
+
+def print_warning(message: str) -> None:
+    """Prints a warning message in a yellow panel using Rich."""
+    print_panel(f"⚠ {message}", "yellow")
+
+
+def print_success(message: str) -> None:
+    """Prints a success message in a green panel using Rich."""
+    print_panel(f"✓ {message}", "green")
+
+
+def print_info(message: str) -> None:
+    """Prints an info message in a cyan panel using Rich."""
+    print_panel(f"ℹ {message}", "cyan")  # noqa: RUF001 - the glyph is the icon
+
+
+def print_panel(message: str, color: str) -> None:
+    """Prints a message in a red panel with the given color using Rich."""
+    formatted_message = f"[{color} bold]{message}[/{color} bold]"
+    print_custom_panel(formatted_message, color)
+
+
+def print_custom_panel(formatted_message: str, panel_color: str) -> None:
+    """Prints a pre-formatted message in a coloured Rich panel."""
+    console.print(Panel(
+        formatted_message,
+        border_style=panel_color,
+        padding=(1, 2)
+    ))
+
+
+def clear_lines(count: int) -> None:
+    """Move cursor up `count` lines and clear everything below."""
+    _ = sys.stdout.write(f"\033[{count}A\033[0J")
+    _ = sys.stdout.flush()

termcore/io/__init__.py

@@ -0,0 +1,7 @@
+"""Storage adapters: SQLite, JSON app state and text files."""
+
+from .app_state_storage import *
+from .database import *
+from .errors import *
+from .file import *
+from .textfile import *

termcore/io/app_state_storage.py

@@ -0,0 +1,185 @@
+"""
+A JSON-backed store for key-value pairs of application state.
+
+Useful for persisting things like the last scroll position or the command
+history. `AppStateStorage` follows the singleton pattern, so one instance
+serves the whole application.
+
+Features:
+
+- Reads a JSON file and loads its content into a dictionary.
+- Provides methods to retrieve (`get`) and update (`set`) key-value pairs.
+- Supports modifying lists within the JSON file, including:
+  - Inserting elements at a specific index (`list_insert`)
+  - Editing individual elements within a list (`edit_list_item`)
+  - Deleting elements from a list (`delete_list_item`)
+  - Moving elements within a list (`move_list_item`)
+- Ensures data persistence by saving changes to the JSON file automatically.
+- Manages file creation and error handling for missing or corrupted JSON files.
+"""
+import json
+from pathlib import Path
+from typing import cast
+
+from termcore.io.errors import StateFileError
+from termcore.util.singleton import Singleton
+
+__all__ = [
+    "AppStateStorage",
+]
+
+
+class AppStateStorage(metaclass=Singleton):
+    """
+    Keeps the content of a JSON file in a dictionary.
+
+    The values are reachable with `get()`.
+
+    Changed values or new key-value pairs can be stored within the Dictionary
+    and the JSON file with the method `set()`.
+
+    Attributes
+    ----------
+    _json_file : Path or str or None
+        Path to the JSON file.
+    _json_dict : dict[str, object]
+        Content of the JSON file as a dictionary.
+    """
+
+    _json_file_path: Path | str | None
+    _json_dict: dict[str, object]
+
+
+    def __init__(
+        self,
+        package_name: str | None = None,
+        state_file_path: Path | str | None = None
+    ) -> None:
+        """
+        Opens the JSON file and stores the key-value pairs in `self.json_dict`.
+
+        Raises
+        ------
+        Exception
+            If no JSON file is given and the class instance is None.
+        """
+        if state_file_path is None and package_name is not None:
+            state_dir = Path.home() / ".local" / "state" / package_name
+            state_dir.mkdir(parents=True, exist_ok=True)
+            state_file_path = state_dir / "state.json"
+        elif state_file_path is None and AppStateStorage.instance is None:
+            raise StateFileError(
+                "Either state_file_path or package_name must be given."
+            )
+        self._json_file_path = state_file_path
+        self._json_dict = {}
+        self._read_json_file()
+
+    def _read_json_file(self) -> None:
+        """
+        Opens the JSON file and stores the content in `self.json_dict`.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the JSON file cannot be found and cannot be created.
+        json.JSONDecodeError
+            If the JSON file contains invalid JSON.
+        """
+        if self._json_file_path is None:
+            raise StateFileError("No JSON file given.")
+        json_path = Path(self._json_file_path)
+        abs_path = json_path.resolve()
+
+        try:
+            with json_path.open(encoding="utf-8") as file:
+                self._json_dict = json.load(file)
+        except FileNotFoundError:
+            # File not found -> try to create a new one
+            try:
+                with json_path.open("w", encoding="utf-8") as file:
+                    _ = file.write("{}")
+            except OSError as error:
+                raise StateFileError(
+                    f"Could not find or create \"{abs_path}\"."
+                ) from error
+        except json.JSONDecodeError as error:
+            raise StateFileError(
+                f"File \"{abs_path}\" contains invalid JSON."
+            ) from error
+
+    def _save_json_file(self) -> None:
+        """Stores the content of self.json_dict in the JSON file."""
+        if self._json_file_path is None:
+            raise StateFileError("No JSON file given.")
+        json_path = Path(self._json_file_path)
+
+        try:
+            with json_path.open("w", encoding="utf-8") as file:
+                json.dump(self._json_dict, file, indent=4)
+        except OSError as error:
+            raise StateFileError(
+                f"File \"{json_path.resolve()}\" could not be written."
+            ) from error
+
+    def get(self, key: str, default_value: object = None) -> object | None:
+        """
+        Returns a value from the JSON file.
+
+        If the key cannot be found, the given default value is returned.
+        """
+        if key in self._json_dict:
+            return self._json_dict[key]
+        return default_value  # type: ignore
+
+    def set(self, key: str, value: object) -> None:
+        """Saves a key-value pair in the JSON file."""
+        self._json_dict.update({key: value})
+        self._save_json_file()
+
+    def list_insert(
+        self, list_name: str, list_index: int, value: object
+    ) -> None:
+        """Adds a new entry to a list at the given index."""
+        # Create list if it doesn't exist
+        if list_name not in self._json_dict:
+            self._json_dict.update({list_name: []})
+
+        # Create empty list if value is empty
+        if self._json_dict[list_name] is None:
+            self._json_dict[list_name] = []
+
+        # Add given data to dict and write to JSON file
+        lst = self._json_dict[list_name]
+        if isinstance(lst, list):
+            cast("list[object]", lst).insert(list_index, value)
+            self._json_dict[list_name] = lst
+            self._save_json_file()
+        else:
+            raise TypeError(f"Value of \"{list_name}\" is not a list.")
+
+    def edit_list_item(  # noqa: PLR0913 - addressing one cell needs all four
+        self, list_name: str, list_index: int, dict_key: str, value: object
+    ) -> None:
+        """Changes the value of a list item."""
+        lst = cast("list[dict[str, object]]", self._json_dict[list_name])
+        lst[list_index][dict_key] = value
+        self._json_dict[list_name] = lst
+        self._save_json_file()
+
+    def delete_list_item(self, list_name: str, list_index: int) -> None:
+        """Deletes an element of a list."""
+        lst = cast("list[dict[str, object]]", self._json_dict[list_name])
+        del lst[list_index]
+        self._save_json_file()
+
+    def move_list_item(
+        self, list_name: str, list_index: int, list_index_new: int
+    ) -> None:
+        """Moves a list item by deleting and re-inserting it elsewhere."""
+        lst = cast("list[object]", self._json_dict[list_name])
+        list_element: object = lst[list_index]
+        del lst[list_index]
+        lst.insert(list_index_new, list_element)
+        self._json_dict[list_name] = lst
+        self._save_json_file()