bear-utils 0.7.11__py3-none-any.whl

bear_utils/events/events_module.py

@@ -0,0 +1,65 @@
+import asyncio
+import weakref
+from collections import defaultdict
+from collections.abc import Callable
+from functools import wraps
+from types import MethodType
+from typing import Any, TypeAlias
+from weakref import WeakMethod, ref
+
+from ..extras._async_helpers import is_async_function
+
+Callback: TypeAlias = Callable[..., Any]
+
+_event_registry: dict[str, weakref.WeakSet[Callback]] = defaultdict(weakref.WeakSet)
+
+
+def clear_handlers_for_event(event_name: str) -> None:
+    _event_registry.pop(event_name, None)
+
+
+def clear_all() -> None:
+    _event_registry.clear()
+
+
+def _make_callback(name: str) -> Callable[[Any], None]:
+    """Create an internal callback to remove dead handlers."""
+
+    def callback(weak_method: Any) -> None:
+        _event_registry[name].remove(weak_method)
+        if not _event_registry[name]:
+            del _event_registry[name]
+
+    return callback
+
+
+def set_handler(name: str, func: Callback) -> None:
+    if isinstance(func, MethodType):
+        _event_registry[name].add(WeakMethod(func, _make_callback(name)))
+    else:
+        _event_registry[name].add(ref(func, _make_callback(name)))
+
+
+def dispatch_event(name: str, *args, **kwargs) -> Any | None:
+    results = list()
+    for func in _event_registry.get(name, []):
+        if is_async_function(func):
+            result = asyncio.run(func(*args, **kwargs))
+        else:
+            result = func(*args, **kwargs)
+            results.append(result)
+    if not results:
+        return None
+    return results[0] if len(results) == 1 else results
+
+
+def event_handler(event_name: str) -> Callable[[Callback], Callback]:
+    def decorator(callback: Callback) -> Callback:
+        @wraps(callback)
+        def wrapper(*args, **kwargs):
+            return callback(*args, **kwargs)
+
+        set_handler(event_name, wrapper)
+        return wrapper
+
+    return decorator

bear_utils/extras/__init__.py

@@ -0,0 +1,17 @@
+from ._tools import ClipboardManager, clear_clipboard, copy_to_clipboard, fmt_header, paste_from_clipboard
+from .platform_utils import OS, get_platform, is_linux, is_macos, is_windows
+from .wrappers.add_methods import add_comparison_methods
+
+__all__ = [
+    "OS",
+    "get_platform",
+    "is_linux",
+    "is_macos",
+    "is_windows",
+    "ClipboardManager",
+    "copy_to_clipboard",
+    "paste_from_clipboard",
+    "clear_clipboard",
+    "fmt_header",
+    "add_comparison_methods",
+]

bear_utils/extras/_async_helpers.py

@@ -0,0 +1,15 @@
+import inspect
+from collections.abc import Callable
+
+
+def is_async_function(func: Callable) -> bool:
+    """
+    Check if a function is asynchronous.
+
+    Args:
+        func (Callable): The function/method to check.
+
+    Returns:
+        bool: True if the function is asynchronous, False otherwise.
+    """
+    return inspect.iscoroutinefunction(func) or inspect.isasyncgenfunction(func) or inspect.isasyncgen(func)

bear_utils/extras/_tools.py

@@ -0,0 +1,178 @@
+import asyncio
+import shutil
+from collections import deque
+from functools import cached_property
+from subprocess import CompletedProcess
+
+from ..cli.shell._base_command import BaseShellCommand as ShellCommand
+from ..cli.shell._base_shell import AsyncShellSession
+from ..logging.logger_manager.loggers._base_logger import BaseLogger
+from .platform_utils import OS, get_platform
+
+
+class TextHelper:
+    @cached_property
+    def local_console(self) -> BaseLogger:
+        from ..logging.loggers import BaseLogger
+
+        init: bool = not BaseLogger.has_instance()
+        return BaseLogger.get_instance(init=init)
+
+    def print_header(self, title: str, sep="#", len=60, s1="bold red", s2="bold blue", return_txt: bool = False) -> str:
+        """Generate a header string"""
+        # FIXME: There are probably better ways to do this, but this is OK.
+        fill: str = sep * len
+        title = f" {title} ".center(len, sep).replace(title, f"[{s1}]{title}[/{s1}]")
+        output_text: str = f"\n{fill}\n{title}\n{fill}\n"
+        if not return_txt:
+            self.local_console.print(output_text, style=s2)
+        return output_text
+
+
+class ClipboardManager:
+    """
+    A class to manage clipboard operations such as copying, pasting, and clearing.
+    This class provides methods to interact with the system clipboard.
+    """
+
+    def __init__(self, maxlen: int = 10) -> None:
+        self.clipboard_history = deque(maxlen=maxlen)
+        self.shell = AsyncShellSession(env={"LANG": "en_US.UTF-8"}, verbose=False)
+        self._copy: ShellCommand[str]
+        self._paste: ShellCommand[str]
+
+        platform: OS = get_platform()
+        match platform:
+            case OS.DARWIN:
+                self._copy = ShellCommand.adhoc("pbcopy")
+                self._paste = ShellCommand.adhoc("pbpaste")
+            case OS.LINUX:
+                if shutil.which("wl-copy") and shutil.which("wl-paste"):
+                    self._copy = ShellCommand.adhoc("wl-copy")
+                    self._paste = ShellCommand.adhoc("wl-paste")
+                elif shutil.which("xclip"):
+                    self._copy = ShellCommand.adhoc("xclip").sub("-selection", "clipboard")
+                    self._paste = ShellCommand.adhoc("xclip").sub("-selection", "clipboard").value("-o")
+                else:
+                    raise RuntimeError("No clipboard command found on Linux")
+            case OS.WINDOWS:
+                self._copy = ShellCommand.adhoc("clip")
+                self._paste = ShellCommand.adhoc("powershell").sub("Get-Clipboard")
+            case _:
+                raise RuntimeError(f"Unsupported platform: {platform}")
+
+    def get_history(self) -> deque:
+        """Get the clipboard history.
+
+        Returns:
+            deque: The history of clipboard entries.
+        """
+        return self.clipboard_history
+
+    async def copy(self, output: str) -> int:
+        """
+        A function that copies the output to the clipboard.
+
+        Args:
+            output (str): The output to copy to the clipboard.
+
+        Returns:
+            int: The return code of the command.
+        """
+        await self.shell.run(self._copy)
+        result: CompletedProcess[str] = await self.shell.communicate(stdin=output)
+        if result.returncode == 0:
+            self.clipboard_history.append(output)  # Only append to history if the copy was successful
+        return result.returncode
+
+    async def paste(self) -> str:
+        """
+        Paste the output from the clipboard.
+
+        Returns:
+            str: The content of the clipboard.
+
+        Raises:
+            RuntimeError: If the paste command fails.
+        """
+        try:
+            await self.shell.run(self._paste)
+            result: CompletedProcess[str] = await self.shell.communicate()
+        except Exception as e:  # pragma: no cover - safety net for unforeseen shell errors
+            raise RuntimeError(f"Error pasting from clipboard: {e}") from e
+        if result.returncode != 0:
+            raise RuntimeError(f"{self._paste.cmd} failed with return code {result.returncode}")
+        return result.stdout
+
+    async def clear(self) -> int:
+        """
+        A function that clears the clipboard.
+
+        Returns:
+            int: The return code of the command.
+        """
+        return await self.copy("")
+
+
+def copy_to_clipboard(output: str) -> int:
+    """
+    Copy the output to the clipboard.
+
+    Args:
+        output (str): The output to copy to the clipboard.
+
+    Returns:
+        int: The return code of the command.
+    """
+    clipboard_manager = ClipboardManager()
+    loop = asyncio.get_event_loop()
+    return loop.run_until_complete(clipboard_manager.copy(output))
+
+
+def paste_from_clipboard() -> str:
+    """
+    Paste the output from the clipboard.
+
+    Returns:
+        str: The content of the clipboard.
+    """
+    clipboard_manager = ClipboardManager()
+    loop = asyncio.get_event_loop()
+    return loop.run_until_complete(clipboard_manager.paste())
+
+
+def clear_clipboard() -> int:
+    """
+    Clear the clipboard.
+
+    Returns:
+        int: The return code of the command.
+    """
+    clipboard_manager = ClipboardManager()
+    loop = asyncio.get_event_loop()
+    return loop.run_until_complete(clipboard_manager.clear())
+
+
+def fmt_header(
+    title: str,
+    sep: str = "#",
+    length: int = 60,
+    style1: str = "bold red",
+    style2: str = "bold blue",
+    print_out: bool = True,
+) -> str:
+    """
+    Generate a header string for visual tests.
+
+    Args:
+        title (str): The title to display in the header.
+        sep (str): The character to use for the separator. Defaults to '#'.
+        length (int): The total length of the header line. Defaults to 60.
+        style1 (str): The style for the title text. Defaults to 'bold red'.
+        style2 (str): The style for the separator text. Defaults to 'bold blue'.
+    """
+    text_helper = TextHelper()
+    if print_out:
+        text_helper.print_header(title, sep, length, style1, style2, return_txt=False)
+        return ""
+    return text_helper.print_header(title, sep, length, style1, style2, return_txt=True)

bear_utils/extras/platform_utils.py

@@ -0,0 +1,53 @@
+import platform
+from enum import StrEnum
+
+
+class OS(StrEnum):
+    DARWIN = "Darwin"
+    LINUX = "Linux"
+    WINDOWS = "Windows"
+    OTHER = "Other"
+
+
+DARWIN = OS.DARWIN
+LINUX = OS.LINUX
+WINDOWS = OS.WINDOWS
+OTHER = OS.OTHER
+
+
+def get_platform() -> OS:
+    """Return the current operating system as an :class:`OS` enum.
+
+    Returns:
+        OS: The current operating system as an enum member, or `OS.OTHER` if the platform is not recognized.
+    """
+    system = platform.system()
+    return OS(system) if system in OS.__members__.values() else OS.OTHER
+
+
+def is_macos() -> bool:
+    """Return ``True`` if running on macOS."""
+    return get_platform() == DARWIN
+
+
+def is_windows() -> bool:
+    """Return ``True`` if running on Windows."""
+    return get_platform() == WINDOWS
+
+
+def is_linux() -> bool:
+    """Return ``True`` if running on Linux."""
+    return get_platform() == LINUX
+
+
+if __name__ == "__main__":
+    detected_platform: OS = get_platform()
+    match detected_platform:
+        case OS.DARWIN:
+            print("Detected macOS")
+        case OS.LINUX:
+            print("Detected Linux")
+        case OS.WINDOWS:
+            print("Detected Windows")
+        case _:
+            print(f"Detected unsupported platform: {detected_platform}")

bear_utils/extras/wrappers/add_methods.py

@@ -0,0 +1,98 @@
+from collections.abc import Callable
+from types import NotImplementedType
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+PRIMITIVE_TYPES: tuple[type[str], type[int], type[float], type[bool]] = (str, int, float, bool)
+
+
+def add_comparison_methods(attribute: str) -> Callable[[type[T]], type[T]]:
+    """Class decorator that adds rich comparison methods based on a specific attribute.
+
+    This decorator adds __eq__, __ne__, __lt__, __gt__, __le__, __ge__, and __hash__ methods
+    to a class, all of which delegate to the specified attribute. This allows instances
+    of the decorated class to be compared with each other, as well as with primitive values
+    that the attribute can be compared with.
+
+    Args:
+        attribute: Name of the instance attribute to use for comparisons
+
+    Returns:
+        Class decorator function that adds comparison methods to a class
+
+    Example:
+        @add_comparison_methods('name')
+        class Person:
+            def __init__(self, name):
+                self.name = name
+    """
+
+    def decorator(cls: type[T]) -> type[T]:
+        def extract_comparable_value(self, other: Any) -> NotImplementedType | Any:
+            """Helper to extract the comparable value from the other object."""
+            if isinstance(other, PRIMITIVE_TYPES):
+                return other
+
+            if hasattr(other, attribute):
+                return getattr(other, attribute)
+
+            return NotImplemented
+
+        def equals_method(self, other: Any) -> NotImplementedType | bool:
+            """Equal comparison method (__eq__)."""
+            other_val: NotImplementedType | Any = extract_comparable_value(self, other)
+            if other_val is NotImplemented:
+                return NotImplemented
+            return getattr(self, attribute) == other_val
+
+        def not_equals_method(self, other: Any) -> NotImplementedType | bool:
+            """Not equal comparison method (__ne__)."""
+            other_val: NotImplementedType | Any = extract_comparable_value(self, other)
+            if other_val is NotImplemented:
+                return NotImplemented
+            return getattr(self, attribute) != other_val
+
+        def less_than_method(self, other: Any) -> NotImplementedType | bool:
+            """Less than comparison method (__lt__)."""
+            other_val: NotImplementedType | Any = extract_comparable_value(self, other)
+            if other_val is NotImplemented:
+                return NotImplemented
+            return getattr(self, attribute) < other_val
+
+        def greater_than_method(self, other: Any) -> NotImplementedType | bool:
+            """Greater than comparison method (__gt__)."""
+            other_val: NotImplementedType | Any = extract_comparable_value(self, other)
+            if other_val is NotImplemented:
+                return NotImplemented
+            return getattr(self, attribute) > other_val
+
+        def less_than_or_equal_method(self, other: Any) -> NotImplementedType | bool:
+            """Less than or equal comparison method (__le__)."""
+            other_val: NotImplementedType | Any = extract_comparable_value(self, other)
+            if other_val is NotImplemented:
+                return NotImplemented
+            return getattr(self, attribute) <= other_val
+
+        def greater_than_or_equal_method(self, other: Any) -> NotImplementedType | bool:
+            """Greater than or equal comparison method (__ge__)."""
+            other_val: NotImplementedType | Any = extract_comparable_value(self, other)
+            if other_val is NotImplemented:
+                return NotImplemented
+            return getattr(self, attribute) >= other_val
+
+        def hash_method(self) -> int:
+            """Generate hash based on the attribute used for equality."""
+            return hash(getattr(self, attribute))
+
+        setattr(cls, "__eq__", equals_method)
+        setattr(cls, "__ne__", not_equals_method)
+        setattr(cls, "__lt__", less_than_method)
+        setattr(cls, "__gt__", greater_than_method)
+        setattr(cls, "__le__", less_than_or_equal_method)
+        setattr(cls, "__ge__", greater_than_or_equal_method)
+        setattr(cls, "__hash__", hash_method)
+
+        return cls
+
+    return decorator

bear_utils/files/__init__.py

@@ -0,0 +1,4 @@
+from .file_handlers import FileHandlerFactory
+from .ignore_parser import IGNORE_PATTERNS
+
+__all__ = ["FileHandlerFactory", "IGNORE_PATTERNS"]

bear_utils/files/file_handlers/__init__.py

@@ -0,0 +1,3 @@
+from .file_handler_factory import FileHandlerFactory
+
+__all__ = ["FileHandlerFactory"]

bear_utils/files/file_handlers/_base_file_handler.py

@@ -0,0 +1,93 @@
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from functools import wraps
+from pathlib import Path
+from typing import Any, ClassVar, ParamSpec, TypeVar, cast
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class FileHandler(ABC):
+    """Abstract class for file handling with read, write, and present methods
+
+    :attr ext str: File extension to check for.
+    :method file_checker: Class method to check if file is of correct type.
+    :method read_file: Read file method.
+    :method write_file: Write file method.
+    :method present_file: Present file method.
+    """
+
+    valid_extensions: ClassVar[list[str]] = []
+
+    @classmethod
+    def file_checker(cls, file_path: Path) -> bool:
+        """Check if the file is of the correct type.
+
+        Args:
+            file_path: Path to the file
+
+        Returns:
+            bool: True if the file is of the correct type, False otherwise
+        """
+        return file_path.suffix.lstrip(".") in cls.valid_extensions
+
+    @classmethod
+    def ValidateFileType(cls, method: Callable[P, R]) -> Callable[P, R]:
+        """Decorator to validate file type before executing a method.
+
+        This decorator checks if the file is of the correct type before
+        executing the method. If not, it raises a ValueError.
+
+        Args:
+            method: Method to decorate
+
+        Returns:
+            Decorated method
+        """
+
+        @wraps(method)
+        def wrapper(self: "FileHandler", file_path: Path, *args: Any, **kwargs: Any) -> R:
+            if not self.file_checker(file_path):
+                raise ValueError(f"Invalid file type. Expected {self.valid_extensions}")
+            return method(self, file_path, *args, **kwargs)  # type: ignore
+
+        return cast(Callable[P, R], wrapper)
+
+    @abstractmethod
+    def read_file(self, file_path: Path) -> dict[str, Any] | str:
+        if not file_path.exists():
+            raise ValueError(f"File does not exist: {file_path}")
+
+    @abstractmethod
+    def write_file(self, file_path: Path, data: dict[str, Any] | str, **kwargs) -> None:
+        if not file_path.parent.exists():
+            if kwargs.get("mkdir", False):
+                file_path.parent.mkdir(parents=True, exist_ok=True)
+            else:
+                raise ValueError(f"Directory does not exist: {file_path.parent}. Set mkdir=True to create it.")
+
+    @abstractmethod
+    def present_file(self, data: dict[str, Any] | str) -> str: ...
+
+    @staticmethod
+    def get_file_info(file_path: Path) -> dict[str, Any]:
+        """Get information about a file.
+
+        Args:
+            file_path: Path to the file
+
+        Returns:
+            Dictionary with file information
+        """
+        if not file_path.exists():
+            raise ValueError(f"File does not exist: {file_path}")
+
+        return {
+            "path": file_path,
+            "name": file_path.name,
+            "extension": file_path.suffix,
+            "size": file_path.stat().st_size if file_path.exists() else 0,
+            "is_file": file_path.is_file() if file_path.exists() else False,
+            "modified": file_path.stat().st_mtime if file_path.exists() else None,
+        }