bear-utils 0.0.1__py3-none-any.whl

bear_utils/extras/_async_helpers.py

@@ -0,0 +1,67 @@
+import asyncio
+from asyncio import AbstractEventLoop, Task
+from collections.abc import Callable
+from contextlib import suppress
+import inspect
+
+from pydantic import BaseModel, Field
+
+
+class AsyncResponseModel(BaseModel):
+    """A model to handle asynchronous operations with a function and its arguments."""
+
+    loop: AbstractEventLoop | None = Field(default=None, description="The event loop to run the function in.")
+    task: Task | None = Field(default=None, description="The task created for the asynchronous function.")
+    before_loop: bool = Field(default=False, description="If the function was called from a running loop.")
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    def conditional_run(self) -> None:
+        """Run the event loop until the task is complete if not in a running loop."""
+        if self.loop and self.task and not self.before_loop:
+            self.loop.run_until_complete(self.task)
+
+
+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)
+
+
+def in_async_loop() -> bool:
+    """Check if the current context is already in an async loop.
+
+    Returns:
+        bool: True if an async loop is running, False otherwise.
+    """
+    loop: AbstractEventLoop | None = None
+    with suppress(RuntimeError):
+        loop = asyncio.get_running_loop()
+    return loop.is_running() if loop else False
+
+
+def gimmie_async_loop() -> AbstractEventLoop:
+    """Get the current event loop, creating one if it doesn't exist."""
+    if in_async_loop():
+        return asyncio.get_event_loop()
+    loop: AbstractEventLoop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    return loop
+
+
+def create_async_task(
+    func: Callable,
+    *args,
+    **kwargs,
+) -> AsyncResponseModel:
+    """Create an asyncio task for a given function."""
+    before_loop: bool = in_async_loop()
+    loop: AbstractEventLoop = gimmie_async_loop()
+    task = loop.create_task(func(*args, **kwargs))
+    return AsyncResponseModel(loop=loop, task=task, before_loop=before_loop)

bear_utils/extras/_tools.py

@@ -0,0 +1,185 @@
+import asyncio
+from asyncio.subprocess import PIPE
+from collections import deque
+import shutil
+from typing import TYPE_CHECKING
+
+from bear_utils.cli.shell._base_command import BaseShellCommand as ShellCommand
+from bear_utils.cli.shell._base_shell import AsyncShellSession
+from bear_utils.extras.platform_utils import OS, get_platform
+from bear_utils.graphics.font._utils import ascii_header
+
+if TYPE_CHECKING:
+    from subprocess import CompletedProcess
+
+
+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:
+        """Initialize the ClipboardManager with a maximum history length."""
+        self.clipboard_history: deque[str] = 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(name="pbcopy")
+                self._paste = ShellCommand.adhoc(name="pbpaste")
+            case OS.LINUX:
+                if shutil.which(cmd="wl-copy") and shutil.which(cmd="wl-paste"):
+                    self._copy = ShellCommand.adhoc(name="wl-copy")
+                    self._paste = ShellCommand.adhoc(name="wl-paste")
+                elif shutil.which(cmd="xclip"):
+                    self._copy = ShellCommand.adhoc(name="xclip").sub("-selection", "clipboard")
+                    self._paste = ShellCommand.adhoc(name="xclip").sub("-selection", "clipboard").value("-o")
+                else:
+                    raise RuntimeError("No clipboard command found on Linux")
+            case OS.WINDOWS:
+                self._copy = ShellCommand.adhoc(name="clip")
+                self._paste = ShellCommand.adhoc(name="powershell").sub("Get-Clipboard")
+            case _:
+                raise RuntimeError(f"Unsupported platform: {platform}")
+
+    def _copy_cmd(self) -> ShellCommand[str]:
+        """Get the copy command based on the platform."""
+        return self._copy
+
+    def _paste_cmd(self) -> ShellCommand[str]:
+        """Get the paste command based on the platform."""
+        return self._paste
+
+    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(cmd=self._copy, stdin=PIPE)
+        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(cmd=self._paste)
+            result: CompletedProcess[str] = await self.shell.communicate()
+        except Exception as e:
+            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(output="")
+
+
+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.AbstractEventLoop = asyncio.get_event_loop()
+    return loop.run_until_complete(future=clipboard_manager.copy(output))
+
+
+async def copy_to_clipboard_async(output: str) -> int:
+    """Asynchronously 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()
+    return await clipboard_manager.copy(output=output)
+
+
+def paste_from_clipboard() -> str:
+    """Paste the output from the clipboard.
+
+    Returns:
+        str: The content of the clipboard.
+    """
+    clipboard_manager = ClipboardManager()
+    loop: asyncio.AbstractEventLoop = asyncio.get_event_loop()
+    return loop.run_until_complete(future=clipboard_manager.paste())
+
+
+async def paste_from_clipboard_async() -> str:
+    """Asynchronously paste the output from the clipboard.
+
+    Returns:
+        str: The content of the clipboard.
+    """
+    clipboard_manager = ClipboardManager()
+    return await clipboard_manager.paste()
+
+
+def clear_clipboard() -> int:
+    """Clear the clipboard.
+
+    Returns:
+        int: The return code of the command.
+    """
+    clipboard_manager = ClipboardManager()
+    loop: asyncio.AbstractEventLoop = asyncio.get_event_loop()
+    return loop.run_until_complete(clipboard_manager.clear())
+
+
+async def clear_clipboard_async() -> int:
+    """Asynchronously clear the clipboard.
+
+    Returns:
+        int: The return code of the command.
+    """
+    clipboard_manager = ClipboardManager()
+    return await clipboard_manager.clear()
+
+
+__all__ = [
+    "ClipboardManager",
+    "ascii_header",
+    "clear_clipboard",
+    "clear_clipboard_async",
+    "copy_to_clipboard",
+    "copy_to_clipboard_async",
+    "paste_from_clipboard",
+    "paste_from_clipboard_async",
+]

bear_utils/extras/_zapper.py

@@ -0,0 +1,399 @@
+from collections.abc import Callable
+import re
+from typing import Any, Literal, Self
+
+
+class Zapper[T]:
+    """A class to remove specified symbols from a source string."""
+
+    def __init__(
+        self,
+        str_input: str | tuple[str, ...],
+        src: str,
+        replace: str = "",
+        expected_unpack: int = 0,
+        sep: str = ".",
+        atomic: bool = False,
+        unpack_strict: bool = True,
+        regex: bool = False,
+        filter_start: bool = False,  # Will filter out any separators at the start of the string
+        filter_end: bool = False,  # Will filter out any separators at the end of the string
+        sorting: Literal["length", "order"] = "length",
+        func: Callable[[str], T] = str,
+    ) -> None:
+        """Initialize the Zapper with symbols, source string, and optional parameters."""
+        self.src: str = src
+        self.replace: str = replace
+        self.expected_unpack: int = expected_unpack
+        self.sep: str = sep
+        self.func: Callable[[str], T] = func
+        self.atomic: bool = atomic
+        self.unpack_strict: bool = unpack_strict
+        self.regex_enabled: bool = regex
+        self.filter_start: bool = filter_start
+        self.filter_end: bool = filter_end
+        self.sorting: Literal["length", "order"] = sorting
+        self.input: list[str] = self._process_input(str_input)
+        self.dst: str = ""
+        self.result: tuple[Any, ...] | None = None
+
+    @staticmethod
+    def _get_chars(str_input: str) -> list[str]:
+        """Get a list of characters from the input string."""
+        return [char for char in str_input if char if char != ""]
+
+    @staticmethod
+    def _get_strs(str_input: tuple[str, ...]) -> list[str]:
+        """Get a list of strings from the input tuple."""
+        return [item for item in str_input if item if item != ""]
+
+    @staticmethod
+    def _de_dupe(strings: list[str], atomic: bool, sorting: Literal["length", "order"]) -> list[str]:
+        """Remove duplicates from the input list based on the sorting method."""
+        if atomic and sorting == "length":
+            return sorted(set(strings), key=lambda x: len(x), reverse=True)
+        seen = set()
+        ordered_result = []
+        for item in strings:
+            if item not in seen:
+                seen.add(item)
+                ordered_result.append(item)
+        return ordered_result
+
+    def _process_input(self, str_input: str | tuple[str, ...]) -> list[str]:
+        """Process the input symbols based on whether they are multi-input or single."""
+        is_tuple = isinstance(str_input, tuple)
+        is_string = isinstance(str_input, str)
+        if str_input == "":
+            return []
+        strings_to_replace = []
+        if is_string and not self.atomic:
+            # If a single string is passed, treat each char as a string to replace
+            chars: list[str] = self._get_chars(str_input)
+            strings_to_replace.extend(chars)
+        elif is_string and self.atomic:
+            # If a single string is passed and self.atomic is True, treat it as a single string to replace
+            strings_to_replace.append(str_input)
+        elif is_tuple and not self.atomic:
+            # If a tuple is passed while atomic is false, treat each char as a string to replace
+            for item in str_input:
+                chars = self._get_chars(item)
+                strings_to_replace.extend(chars)
+        elif is_tuple and self.atomic:
+            # If a tuple is passed and atomic is True, treat each string as a thing to replace
+            strings: list[str] = self._get_strs(str_input)
+            strings_to_replace.extend(strings)
+        return self._de_dupe(strings_to_replace, self.atomic, self.sorting)
+
+    # region Zap Related
+
+    @staticmethod
+    def _re_sub(src: str, pattern: str, replacement: str) -> str:
+        """Perform a regex substitution on the source string."""
+        return re.sub(pattern, replacement, src)
+
+    @property
+    def value(self) -> str:
+        """Return the modified source string."""
+        return self.dst
+
+    def _zap(self) -> str:
+        """Remove specified symbols from the source string."""
+        temp_str = self.src
+        for to_replace in self.input:
+            if self.regex_enabled:
+                temp_str = self._re_sub(temp_str, to_replace, self.replace)
+            else:
+                temp_str = temp_str.replace(to_replace, self.replace)
+        if self.filter_start and temp_str.startswith(self.sep):
+            temp_str = temp_str[len(self.sep) :]
+        if self.filter_end and temp_str.endswith(self.sep):
+            temp_str = temp_str[: -len(self.sep)]
+        if self.unpack_strict:
+            temp_str = temp_str.replace(self.sep * 2, self.sep)  # Remove double separators
+        self.dst = temp_str
+        return self.dst
+
+    def zap(self) -> Self:
+        """Remove specified symbols from the source string."""
+        self.dst = self._zap()
+        return self
+
+    # endregion
+    # region Zap Get Related
+
+    def _zap_get(self) -> tuple[str, ...]:
+        """Remove specified symbols and return a tuple of unpacked values."""
+        result: list[str] = self._zap().split(self.sep)[: self.expected_unpack]
+        if self.unpack_strict and len(result) != self.expected_unpack:
+            raise ValueError(f"Expected {self.expected_unpack} items, got {len(result)}: {result}")
+        self.result = tuple(result)
+        return self.result
+
+    def zap_get(self) -> Self:
+        """Remove specified symbols and return a tuple of unpacked values."""
+        self.result = self._zap_get()
+        if self.unpack_strict and len(self.result) != self.expected_unpack:
+            raise ValueError(f"Expected {self.expected_unpack} items, got {len(self.result)}: {self.result}")
+        return self
+
+    @property
+    def unpacked(self) -> tuple[Any, ...]:
+        """Return the unpacked values as a tuple."""
+        if isinstance(self.result, tuple):
+            return self.result
+        raise ValueError("Result is not unpacked yet. Call zap_get() first.")
+
+    # endregion
+    # region Zap As Related
+
+    def _zap_as(self) -> tuple[T, ...]:
+        """Convert the result in self.result to the specified type."""
+        temp_list: list[Any] = []
+        if self.result is None:
+            raise ValueError("No result to convert. Call zap_get() first.")
+        for item in self.result:
+            temp_list.append(self.func(item))
+        self.result = tuple(temp_list)
+        return self.result
+
+    def zap_as(self) -> Self:
+        """Convert the result in self.result to the specified type."""
+        if not self.result:
+            raise ValueError("No result to convert. Call zap_get() first.")
+        self._zap_as()
+        return self
+
+    # endregion
+
+
+def zap_multi(
+    *sym: str,
+    src: str,
+    replace: str = "",
+    atomic: bool = True,
+) -> str:
+    """Remove specified symbols from the source string.
+
+    Args:
+        *sym: A variable number of strings containing symbols to remove from src (e.g., "?!" or "!?")
+        src (str): The source string from which to remove the symbols
+        replace (str, optional): The string to replace the removed symbols with (default is an empty string).
+
+    Returns:
+        str: The modified source string with specified symbols removed.
+
+    Example:
+        >>> zap_multi("!?*", "Hello!? World! *", "")
+        'Hello World '
+        >>> zap_multi("!?*", "Hello!? World! *", "-")
+        'Hello- World- -'
+    """
+    zapper = Zapper(sym, src, replace, atomic=atomic)
+    return zapper.zap().value
+
+
+def zap(sym: str, src: str, replace: str = "") -> str:
+    """Remove specified symbols from the source string.
+
+    Args:
+        sym (str): A string containing symbols to remove from src (e.g., "?!" or "!?")
+        src (str): The source string from which to remove the symbols
+        replace (str, optional): The string to replace the removed symbols with (default is an empty string).
+
+    Returns:
+        str: The modified source string with specified symbols removed.
+
+    Example:
+        >>> zap("!?*", "Hello!? World! *", "")
+        'Hello World '
+        >>> zap("!?*", "Hello!? World! *", "-")
+        'Hello- World- -'
+    """
+    zapper = Zapper(sym, src, replace, unpack_strict=False)
+    return zapper.zap().value
+
+
+def zap_get_multi(
+    *sym: str,
+    src: str,
+    unpack_val: int,
+    replace: str = "",
+    sep: str = ".",
+) -> tuple[str, ...]:
+    """Remove specified symbols from the source string and return a tuple of unpacked values.
+
+    Args:
+        *sym: A variable number of strings containing symbols to remove from src (e.g., "?!" or "!?")
+        src (str): The source string from which to remove the symbols
+        unpack_val (int): The expected number of items to unpack from the result
+        replace (str, optional): The string to replace the removed symbols with (default is an empty string).
+        sep (str, optional): The separator used to split the modified source string (default is ".").
+
+    Returns:
+        tuple[str, ...]: A tuple of unpacked values from the modified source string.
+
+    Raises:
+        ValueError: If the number of items in the result does not match unpack_val.
+    """
+    zapper = Zapper(sym, src, replace, expected_unpack=unpack_val, sep=sep, unpack_strict=True)
+    try:
+        return zapper.zap_get().unpacked
+    except Exception as e:
+        raise ValueError(f"Error unpacking values: {e}") from e
+
+
+def zap_get(sym: str, src: str, unpack_val: int, replace: str = "", sep: str = ".") -> tuple[str, ...]:
+    """Remove specified symbols from the source string and return a tuple of unpacked values.
+
+    Args:
+        sym (str): A string containing symbols to remove from src (e.g., "?!" or "!?")
+        src (str): The source string from which to remove the symbols
+        unpack_val (int): The expected number of items to unpack from the result
+        replace (str, optional): The string to replace the removed symbols with (default is an empty string).
+        sep (str, optional): The separator used to split the modified source string (default is ".").
+
+    Returns:
+        tuple[str, ...]: A tuple of unpacked values from the modified source string.
+
+    Raises:
+        ValueError: If the number of items in the result does not match unpack_val.
+    """
+    zapper = Zapper(sym, src, replace, expected_unpack=unpack_val, sep=sep, unpack_strict=True)
+    try:
+        return zapper.zap_get().unpacked
+    except Exception as e:
+        raise ValueError(f"Error unpacking values: {e}") from e
+
+
+def zap_take(sym: str, src: str, unpack_val: int, replace: str = "", sep: str = ".") -> tuple[str, ...]:
+    """Remove specified symbols from the source string and return a tuple of unpacked values.
+
+    This function is similar to zap_get but does not raise an error if the number of items does not match unpack_val.
+    Instead, it returns as many items as possible.
+
+    Args:
+        sym (str): A string containing symbols to remove from src (e.g., "?!" or "!?")
+        src (str): The source string from which to remove the symbols
+        unpack_val (int): The expected number of items to unpack from the result
+        replace (str, optional): The string to replace the removed symbols with (default is an empty string).
+        sep (str, optional): The separator used to split the modified source string (default is ".").
+
+    Returns:
+        tuple[str, ...]: A tuple of unpacked values from the modified source string.
+    """
+    zapper = Zapper(sym, src, replace, expected_unpack=unpack_val, sep=sep, unpack_strict=False)
+    return zapper.zap_get().unpacked
+
+
+def zap_as_multi[T](
+    *sym,
+    src: str,
+    unpack_val: int,
+    replace: str = "",
+    sep: str | None = None,
+    func: Callable[[str], T] = str,
+    strict: bool = True,
+    regex: bool = False,
+    atomic: bool = True,
+    filter_start: bool = False,  # Will filter out any separators at the start of the string
+    filter_end: bool = False,  # Will filter out any separators at the end of the string
+    sorting: Literal["length", "order"] = "length",  # Will sort the input symbols by length in descending order
+) -> tuple[T, ...]:
+    """Remove specified symbols from the source string, unpack the result, and convert it to a specified type.
+
+    Args:
+        *sym: A variable number of strings containing symbols to remove from src (e.g., "?!" or "!?")
+        src (str): The source string from which to remove the symbols
+        unpack_val (int): The expected number of items to unpack from the result
+        replace (str, optional): The string to replace the removed symbols with (default is an empty string).
+        sep (str, optional): The separator used to split the modified source string (default is ".").
+        func (type, optional): The type of the result to cast/convert to (default is str).
+
+    Returns:
+        Zapper: An instance of the Zapper class configured with the provided parameters.
+    """
+    if sep is None:
+        sep = replace
+
+    zapper: Zapper[T] = Zapper(
+        str_input=sym,
+        src=src,
+        replace=replace,
+        expected_unpack=unpack_val,
+        sep=sep,
+        func=func,
+        unpack_strict=strict,
+        regex=regex,
+        atomic=atomic,
+        filter_start=filter_start,
+        filter_end=filter_end,
+        sorting=sorting,
+    )
+    try:
+        return zapper.zap_get().zap_as().unpacked
+    except Exception as e:
+        raise ValueError(f"Error converting values: {e}") from e
+
+
+def zap_as[T](
+    sym: str,
+    src: str,
+    unpack_val: int,
+    replace: str = "",
+    sep: str | None = None,
+    func: Callable[[str], T] = str,
+    strict: bool = True,
+    regex: bool = False,
+    filter_start: bool = False,  # Will filter out any separators at the start of the string
+    filter_end: bool = False,  # Will filter out any separators at the end of the string
+    atomic: bool = False,  # If True, treat the input symbols as a single string to replace
+    sorting: Literal["length", "order"] = "length",  # length ordering or by the order of input
+) -> tuple[T, ...]:
+    """Remove specified symbols from the source string, unpack the result, and convert it to a specified type.
+
+    Args:
+        sym (str): A string containing symbols to remove from src (e.g., "?!" or "!?")
+        src (str): The source string from which to remove the symbols
+        unpack_val (int): The expected number of items to unpack from the result
+        replace (str, optional): The string to replace the removed symbols with (default is an empty string).
+        sep (str, optional): The separator used to split the modified source string (default is ".").
+        func (type, optional): The type of the result to cast/convert to (default is str).
+
+    Returns:
+        Zapper: An instance of the Zapper class configured with the provided parameters.
+    """
+    if sep is None:
+        sep = replace
+
+    zapper: Zapper[T] = Zapper(
+        str_input=sym,
+        src=src,
+        replace=replace,
+        expected_unpack=unpack_val,
+        sep=sep,
+        func=func,
+        unpack_strict=strict,
+        regex=regex,
+        filter_start=filter_start,
+        filter_end=filter_end,
+        atomic=atomic,
+        sorting=sorting,
+    )
+    try:
+        return zapper.zap_get().zap_as().unpacked
+    except Exception as e:
+        raise ValueError(f"Error converting values: {e}") from e
+
+
+if __name__ == "__main__":
+    # # Example usage
+    # result = zap_as_multi("()", "(", ")", src="(a)(b)(c)", unpack_val=3, replace="|", atomic=False)
+    # print(result)
+    # assert result == ("a", "b", "c")
+
+    version_string = "v1.2.3-beta+build"
+    result = zap_as_multi(
+        "v", "-", "+", src=version_string, unpack_val=3, replace=".", func=int, strict=True, filter_start=True
+    )
+    print(result)