termcore 0.2.0__py3-none-any.whl

termcore/io/errors.py

@@ -0,0 +1,71 @@
+"""Domain exceptions raised by the `termcore.io` modules."""
+
+__all__ = [
+    "AppStateError",
+    "DatabaseError",
+    "EmptyConditionsError",
+    "StateFileError",
+    "UnknownIdentifierError",
+]
+
+
+class DatabaseError(Exception):
+    """Base class for every error raised while talking to a database."""
+
+
+class UnknownIdentifierError(DatabaseError):
+    """
+    Raised when a table or column name is not part of the schema.
+
+    Identifiers cannot be passed as query parameters, so they are checked
+    against the schema before they are put into a statement. Rejecting an
+    unknown name here means a typo is reported as a typo, and a name that
+    was never a column cannot become a fragment of SQL.
+    """
+
+    name: str
+    known: tuple[str, ...]
+
+    def __init__(self, name: str, known: tuple[str, ...]) -> None:
+        """Stores the rejected name and what would have been accepted."""
+        super().__init__(
+            f"Unknown identifier {name!r}. "
+            f"Known identifiers: {', '.join(known) or '(none)'}"
+        )
+        self.name = name
+        self.known = known
+
+
+class EmptyConditionsError(DatabaseError):
+    """
+    Raised when an update or a delete is asked to run without conditions.
+
+    An empty condition list almost always means the caller built it from
+    something that turned out to be empty, and carrying on would rewrite or
+    delete every row in the table.
+    """
+
+    operation: str
+
+    def __init__(self, operation: str) -> None:
+        """Stores the operation that was refused."""
+        super().__init__(
+            f"Refusing to {operation} every row of the table: no conditions "
+            f"were given. Use query() if that is genuinely intended."
+        )
+        self.operation = operation
+
+
+class AppStateError(Exception):
+    """Base class for every error raised while handling the app state."""
+
+
+class StateFileError(AppStateError):
+    """
+    Raised when the state file cannot be read, created or written.
+
+    The storage used to print a message and call `sys.exit()` here, which
+    takes the whole application down from inside a library and leaves the
+    caller no way to react. Losing the state is worth reporting, but it is
+    the application's decision what to do about it.
+    """

termcore/io/file.py

@@ -0,0 +1,263 @@
+
+"""
+Reading, writing and managing files and folders.
+
+It offers a simple and lightweight interface for handling
+text-based file operations.
+
+This module includes functions and classes to work with text files, such as
+reading content, writing data, appending text and performing basic file
+manipulations. It is designed to simplify text file handling in Python projects
+by providing an easy-to-use API.
+
+Features:
+
+- Read content from text files.
+- Write content to text files.
+- Append data to existing files.
+- Handle file encoding issues.
+- Support for line-by-line reading to optimize memory usage.
+
+This module is particularly useful for applications requiring efficient and
+straightforward text file operations, such as logging systems, data processing
+and configuration management.
+"""
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+__all__ = [
+    "File",
+    "FolderItem",
+]
+
+
+@dataclass(slots=True)
+class FolderItem:
+    """
+    Internal class: Represents an item (file or folder) within a directory.
+
+    Attributes
+    ----------
+    type : str
+        Type of the item, either 'file' or 'folder'.
+    name : str
+        Name of the file or folder (without extension for files).
+    level : int
+        Depth level of the item in the directory tree
+        (0 for root items, 1 for sub-items, etc.).
+        Items in a sub folder level 1 etc.
+    extension : str or None, optional
+        File extension without leading dot (None for folders).
+
+    Notes
+    -----
+    TODO: Support more pieces of information like size, modified, etc.
+    TODO: Method to copy/move/delete a file (one method "copy" that copies
+          folders and files)
+    """
+
+    type: str
+    name: str
+    level: int
+    extension: str | None = None
+
+
+class File:
+    """
+    A collection of static methods for performing file and folder operations.
+
+    Provides functionalities to list folder contents, copy files and folders,
+    retrieve file extensions, modify file extensions, and extract folder paths
+    from file paths.
+    """
+
+    @staticmethod
+    def folder_content(
+        path: str, extfilter: str | None = None
+    ) -> dict[str, FolderItem]:
+        """
+        Retrieves the contents of a given folder, without its subfolders.
+
+        Parameters
+        ----------
+        path : str
+            The directory path to list contents from.
+        extfilter : str or None, optional
+            A specific file extension to filter results
+            (e.g., "txt").
+
+        Returns
+        -------
+        dict[str, FolderItem]
+            A dictionary where the keys are item paths and the values are
+            FolderItem instances containing metadata about each item.
+        """
+        return File._folder_content(path, extfilter, with_subfolders=False)
+
+    @staticmethod
+    def folder_content_recursive(
+        path: str, extfilter: str | None = None
+    ) -> dict[str, FolderItem]:
+        """
+        Retrieves the contents of a given folder and of every subfolder.
+
+        Each `FolderItem` carries its depth below `path` in `level`.
+
+        Parameters
+        ----------
+        path : str
+            The directory path to list contents from.
+        extfilter : str or None, optional
+            A specific file extension to filter results
+            (e.g., "txt").
+
+        Returns
+        -------
+        dict[str, FolderItem]
+            A dictionary where the keys are item paths and the values are
+            FolderItem instances containing metadata about each item.
+        """
+        return File._folder_content(path, extfilter, with_subfolders=True)
+
+    @staticmethod
+    def _folder_content(  # noqa: PLR0913 - level is carried by recursion
+        path: str, extfilter: str | None = None, level: int = 0,
+        *, with_subfolders: bool
+    ) -> dict[str, FolderItem]:
+        """
+        Lists a folder, descending into subfolders when asked to.
+
+        Notes
+        -----
+        TODO: also return a sorted list of the keys of the dictionary
+        """
+        # Get all items of the folder and create a dictionary
+        items_list: list[str] = [p.name for p in Path(path).iterdir()]
+        items_dict: dict[str, FolderItem] = {}
+
+        # Loop folder items
+        for item in items_list:
+            item_path = path + "/" + item
+
+            # Recursion if the item is a folder
+            if Path(item_path).is_dir() and with_subfolders:
+                items_dict = {**items_dict, **File._folder_content(
+                    item_path + "/", extfilter, level + 1,
+                    with_subfolders=with_subfolders)}
+                item_type = "folder"
+            else:
+                item_type = "file"
+
+            # Add item to dictionary
+            if File.extension(item) == extfilter or extfilter is None:
+                # Create FolderItem instance
+                items_dict[item_path] = FolderItem(
+                    type=item_type,
+                    name=item,
+                    extension=File.extension(item),
+                    level=level
+                )
+
+        # TODO: also return a sorted list of the keys of the dictionary
+
+        return items_dict
+
+    @staticmethod
+    def copy_folder(source: str, target: str) -> None:
+        """
+        Copies a folder and its contents to a new location.
+
+        Creates the target folder if it does not exist.
+
+        Parameters
+        ----------
+        source : str
+            The path of the source folder to copy.
+        target : str
+            The destination path where the folder should be copied.
+
+        Notes
+        -----
+        TODO: Add functionality for moving or deleting folders.
+        """
+        # Create target folder if it doesn't exist
+        Path(target).mkdir(parents=True, exist_ok=True)
+
+        # Copy each file
+        # TODO: Also copy sub folder (-> recursion)
+        for entry in Path(source).iterdir():
+            shutil.copyfile(entry, Path(target) / entry.name)
+
+    @staticmethod
+    def extension(file_name: str) -> str | None:
+        """
+        Extracts and returns the file extension from a given file name.
+
+        Parameters
+        ----------
+        file_name : str
+            The name of the file (including extension).
+
+        Returns
+        -------
+        str or None
+            The file extension (without a leading dot) or None if the file has
+            no extension.
+        """
+        # Dateiname anhand von . in Liste splitten
+        file_name_split = file_name.split(".")
+        count = len(file_name_split)
+
+        # Das letzte Element der Liste (= Dateiendung) zurückgeben
+        if count > 1:
+            return file_name.split(".")[count - 1]
+        return None
+
+    @staticmethod
+    def change_extension(file_name: str, extension: str) -> str:
+        """
+        Replaces the extension of a given file name with a new extension.
+
+        Parameters
+        ----------
+        file_name : str
+            The original file name.
+        extension : str
+            The new file extension (without a leading dot).
+
+        Returns
+        -------
+        str
+            The file name with the updated extension.
+        """
+        # Split file name into list by "."
+        file_name_split = file_name.split(".")
+        count = len(file_name_split)
+
+        # Replace the last element of the list (old extension) and replace it
+        # with the new extension
+        if count > 1:
+            file_name_split[count-1] = extension
+            file_name = ".".join(file_name_split)
+
+        return file_name
+
+    @staticmethod
+    def path(file_path: str) -> str:
+        """
+        Extracts and returns the folder path from a full file path.
+
+        Parameters
+        ----------
+        file_path : str
+            The full file path.
+
+        Returns
+        -------
+        str
+            The folder path without the file name.
+        """
+        file_path_list: list[str] = file_path.split("/")
+        file_path_list.remove(file_path_list[len(file_path_list) - 1])
+        return "/".join(file_path_list)

termcore/io/textfile.py

@@ -0,0 +1,92 @@
+"""
+Reading and writing text files.
+
+This module provides a convenient interface for working with text files,
+allowing users to read entire file contents, retrieve lines as a list,
+and write new content efficiently.
+
+It is designed to simplify file operations by providing a class-based
+approach for handling text files. It ensures proper file handling using context
+managers and includes essential methods to perform common file operations.
+
+Features:
+
+- Read the entire content of a text file as a string.
+- Read a text file line by line, returning a list of lines.
+- Write new content to a text file, replacing any existing content.
+- Uses UTF-8 encoding for compatibility with various text formats.
+- Ensures proper file handling by automatically closing files after operations.
+"""
+
+from pathlib import Path
+
+__all__ = [
+    "Textfile",
+]
+
+
+class Textfile:
+    """
+    Reads and writes text files.
+
+    This class provides methods to read the entire content of a text file,
+    read individual lines, and write new content to the file. It is designed for
+    simple file manipulation tasks and ensures that file streams are properly
+    handled using context managers.
+    """
+
+    @staticmethod
+    def readlines(path: str) -> list[str]:
+        """
+        Reads the text file and returns its lines as a list.
+
+        Parameters
+        ----------
+        path : str
+            The path to the text file that will be read.
+
+        Returns
+        -------
+        list[str]
+            A list containing all lines from the text file.
+        """
+        with Path(path).open("r+", encoding="utf-8") as f:
+            return f.readlines()
+
+    @staticmethod
+    def read(path: str) -> str:
+        """
+        Reads the whole text file into a single string.
+
+        Parameters
+        ----------
+        path : str
+            The path to the text file that will be read.
+
+        Returns
+        -------
+        str
+            The complete content of the text file as a string.
+        """
+        with Path(path).open("r+", encoding="utf-8") as f:
+            return f.read()
+
+    @staticmethod
+    def write(path: str, text: str) -> None:
+        """
+        Writes the given text to the file, overwriting any existing content.
+
+        The file is truncated before writing, ensuring that any previous content
+        is removed.
+
+        Parameters
+        ----------
+        path : str
+            The path to the text file that will be written.
+        text : str
+            Content of the text file.
+        """
+        with Path(path).open("w", encoding="utf-8") as f:
+            f.seek(0)               # Set stream to the beginning of the file
+            f.write("".join(text))  # Write text to file
+            f.truncate()            # Remove old text

termcore/tui/__init__.py

@@ -0,0 +1,9 @@
+"""Textual helpers: theme loading, key bindings and widgets."""
+
+from .custom_bindings import *
+from .custom_widgets.custom_checkbox import *
+from .custom_widgets.custom_data_table import *
+from .custom_widgets.custom_selection import *
+from .custom_widgets.multiline_footer import *
+from .question_screen import *
+from .theme_loader import *