bear-utils 0.8.26__py3-none-any.whl → 0.9.0__py3-none-any.whl

bear_utils/__init__.py

@@ -2,11 +2,12 @@
 
 from bear_utils.cache import CacheWrapper, cache, cache_factory
 from bear_utils.config.settings_manager import SettingsManager, get_settings_manager
+from bear_utils.constants import DEVNULL, STDERR, STDOUT, ExitCode, HTTPStatusCode
 from bear_utils.database import DatabaseManager
 from bear_utils.events import Events
-from bear_utils.extras.responses import FAILURE, SUCCESS, FunctionResponse
+from bear_utils.extras.responses import FunctionResponse
 from bear_utils.files.file_handlers.file_handler_factory import FileHandlerFactory
-from bear_utils.logger_manager import BaseLogger, BufferLogger, ConsoleLogger, FileLogger
+from bear_utils.logger_manager import BaseLogger, BufferLogger, ConsoleLogger, FileLogger, LoggingClient, LoggingServer
 from bear_utils.logger_manager._common import VERBOSE_CONSOLE_FORMAT
 from bear_utils.logger_manager._styles import VERBOSE
 from bear_utils.time import (
@@ -21,8 +22,9 @@ from bear_utils.time import (
 __all__ = [
     "DATE_FORMAT",
     "DATE_TIME_FORMAT",
-    "FAILURE",
-    "SUCCESS",
+    "DEVNULL",
+    "STDERR",
+    "STDOUT",
     "VERBOSE",
     "VERBOSE_CONSOLE_FORMAT",
     "BaseLogger",
@@ -32,9 +34,13 @@ __all__ = [
     "DatabaseManager",
     "EpochTimestamp",
     "Events",
+    "ExitCode",
     "FileHandlerFactory",
     "FileLogger",
     "FunctionResponse",
+    "HTTPStatusCode",
+    "LoggingClient",
+    "LoggingServer",
     "SettingsManager",
     "TimeTools",
     "cache",

bear_utils/cli/__init__.py

@@ -1,5 +1,6 @@
 """A set of command-line interface (CLI) utilities for bear_utils."""
 
+from ._args import FAILURE, SUCCESS, ExitCode, args_process
 from .commands import GitCommand, MaskShellCommand, OPShellCommand, UVShellCommand
 from .shell._base_command import BaseShellCommand
 from .shell._base_shell import SimpleShellSession, shell_session
@@ -7,11 +8,15 @@ from .shell._common import DEFAULT_SHELL
 
 __all__ = [
     "DEFAULT_SHELL",
+    "FAILURE",
+    "SUCCESS",
     "BaseShellCommand",
+    "ExitCode",
     "GitCommand",
     "MaskShellCommand",
     "OPShellCommand",
     "SimpleShellSession",
     "UVShellCommand",
+    "args_process",
     "shell_session",
 ]

bear_utils/cli/_args.py

@@ -0,0 +1,12 @@
+import sys
+
+from bear_utils.constants._exit_code import FAILURE, SUCCESS, ExitCode
+
+
+def args_process(args: list[str] | None = None) -> tuple[list[str], ExitCode]:
+    args = sys.argv[1:] if args is None else args
+
+    if not args:
+        return [], FAILURE
+
+    return args, SUCCESS

bear_utils/cli/shell/_base_shell.py

@@ -13,26 +13,13 @@ import subprocess
 from subprocess import CompletedProcess
 from typing import Self, override
 
+from bear_utils.constants import ExitCode
 from bear_utils.logger_manager import VERBOSE, BaseLogger, SubConsoleLogger
 from bear_utils.logger_manager.logger_protocol import LoggerProtocol
 
 from ._base_command import BaseShellCommand
 from ._common import DEFAULT_SHELL
 
-EXIT_CODES: dict[int, str] = {
-    0: "Success",
-    1: "General error",
-    2: "Misuse of shell command",
-    126: "Command invoked cannot execute",
-    127: "Command not found",
-    128: "Invalid argument to exit",
-    130: "Script terminated by Control-C",
-    137: "Process killed by SIGKILL (9)",
-    139: "Segmentation fault (core dumped)",
-    143: "Process terminated by SIGTERM (15)",
-    255: "Exit status out of range",
-}
-
 
 class FancyCompletedProcess(CompletedProcess[str]):
     def __init__(self, args: list[str], returncode: int, stdout: str | None = None, stderr: str | None = None) -> None:
@@ -53,7 +40,7 @@ class FancyCompletedProcess(CompletedProcess[str]):
     @property
     def exit_message(self) -> str:
         """Get a human-readable message for the exit code"""
-        return EXIT_CODES.get(self.returncode, EXIT_CODES.get(1, "Unknown error"))
+        return ExitCode.from_int(self.returncode).text
 
 
 class CommandList(deque[CompletedProcess[str]]):
@@ -149,7 +136,7 @@ class SimpleShellSession:
 
     def _run(self, command: str) -> CompletedProcess[str]:
         """Internal method to run the accumulated command"""
-        self.logger.verbose(f"Executing: {command}")
+        self.logger.debug(f"Executing: {command}")
         self.next_cmd()
 
         if self.use_shell:
@@ -311,7 +298,7 @@ class AsyncShellSession(SimpleShellSession):
     @override
     async def _run(self, command: str, **kwargs) -> Process:  # type: ignore[override]
         """Run the command using Popen for better control"""
-        self.logger.verbose(f"Executing: {command}")
+        self.logger.debug(f"Executing: {command}")
         self.next_cmd()
 
         if self.use_shell:

bear_utils/constants/__init__.py

@@ -1,8 +1,34 @@
 """Constants Module for Bear Utils."""
 
 from pathlib import Path
+import sys
+from typing import TextIO
 
-from .server import BAD_REQUEST, CONFLICT, FORBIDDEN, PAGE_NOT_FOUND, SERVER_ERROR, SERVER_OK, UNAUTHORIZED
+from bear_utils.constants._exit_code import (
+    COMMAND_CANNOT_EXECUTE,
+    COMMAND_NOT_FOUND,
+    EXIT_STATUS_OUT_OF_RANGE,
+    FAIL,
+    INVALID_ARGUMENT_TO_EXIT,
+    MISUSE_OF_SHELL_COMMAND,
+    PROCESS_KILLED_BY_SIGKILL,
+    PROCESS_TERMINATED_BY_SIGTERM,
+    SCRIPT_TERMINATED_BY_CONTROL_C,
+    SEGMENTATION_FAULT,
+    SUCCESS,
+    ExitCode,
+)
+from bear_utils.constants._http_status_code import (
+    BAD_REQUEST,
+    CONFLICT,
+    FORBIDDEN,
+    PAGE_NOT_FOUND,
+    SERVER_ERROR,
+    SERVER_OK,
+    UNAUTHORIZED,
+    HTTPStatusCode,
+)
+from bear_utils.constants._meta import NullFile, RichIntEnum, Value
 
 VIDEO_EXTS = [".mp4", ".mov", ".avi", ".mkv"]
 """Extensions for video files."""
@@ -18,18 +44,43 @@ PATH_TO_PICTURES = Path.home() / "Pictures"
 GLOBAL_VENV = Path.home() / ".global_venv"
 """Path to the global virtual environment."""
 
+STDOUT: TextIO = sys.stdout
+"""Standard output stream."""
+STDERR: TextIO = sys.stderr
+"""Standard error stream."""
+DEVNULL: TextIO = NullFile()
+"""A null file that discards all writes."""
+
 __all__ = [
     "BAD_REQUEST",
+    "COMMAND_CANNOT_EXECUTE",
+    "COMMAND_NOT_FOUND",
     "CONFLICT",
+    "EXIT_STATUS_OUT_OF_RANGE",
+    "FAIL",
     "FILE_EXTS",
     "FORBIDDEN",
     "GLOBAL_VENV",
     "IMAGE_EXTS",
+    "INVALID_ARGUMENT_TO_EXIT",
+    "MISUSE_OF_SHELL_COMMAND",
     "PAGE_NOT_FOUND",
     "PATH_TO_DOWNLOADS",
     "PATH_TO_PICTURES",
+    "PROCESS_KILLED_BY_SIGKILL",
+    "PROCESS_TERMINATED_BY_SIGTERM",
+    "SCRIPT_TERMINATED_BY_CONTROL_C",
+    "SEGMENTATION_FAULT",
     "SERVER_ERROR",
     "SERVER_OK",
+    "STDERR",
+    "STDOUT",
+    "SUCCESS",
     "UNAUTHORIZED",
     "VIDEO_EXTS",
+    "ExitCode",
+    "HTTPStatusCode",
+    "NullFile",
+    "RichIntEnum",
+    "Value",
 ]

bear_utils/constants/_exit_code.py

@@ -0,0 +1,60 @@
+from bear_utils.constants._meta import RichIntEnum, Value
+
+
+class ExitCode(RichIntEnum):
+    """An enumeration of common exit codes used in shell commands."""
+
+    SUCCESS = Value(0, "Success")
+    FAILURE = Value(1, "General error")
+    MISUSE_OF_SHELL_COMMAND = Value(2, "Misuse of shell command")
+    COMMAND_CANNOT_EXECUTE = Value(126, "Command invoked cannot execute")
+    COMMAND_NOT_FOUND = Value(127, "Command not found")
+    INVALID_ARGUMENT_TO_EXIT = Value(128, "Invalid argument to exit")
+    SCRIPT_TERMINATED_BY_CONTROL_C = Value(130, "Script terminated by Control-C")
+    PROCESS_KILLED_BY_SIGKILL = Value(137, "Process killed by SIGKILL (9)")
+    SEGMENTATION_FAULT = Value(139, "Segmentation fault (core dumped)")
+    PROCESS_TERMINATED_BY_SIGTERM = Value(143, "Process terminated by SIGTERM (15)")
+    EXIT_STATUS_OUT_OF_RANGE = Value(255, "Exit status out of range")
+
+
+SUCCESS = ExitCode.SUCCESS
+"""An exit code indicating success."""
+FAIL = ExitCode.FAILURE
+"""Deprecated alias for ExitCode.FAILURE."""
+FAILURE = ExitCode.FAILURE
+"""An exit code indicating a general error."""
+MISUSE_OF_SHELL_COMMAND = ExitCode.MISUSE_OF_SHELL_COMMAND
+"""An exit code indicating misuse of a shell command."""
+COMMAND_CANNOT_EXECUTE = ExitCode.COMMAND_CANNOT_EXECUTE
+"""An exit code indicating that the command invoked cannot execute."""
+COMMAND_NOT_FOUND = ExitCode.COMMAND_NOT_FOUND
+"""An exit code indicating that the command was not found."""
+INVALID_ARGUMENT_TO_EXIT = ExitCode.INVALID_ARGUMENT_TO_EXIT
+"""An exit code indicating an invalid argument to exit."""
+SCRIPT_TERMINATED_BY_CONTROL_C = ExitCode.SCRIPT_TERMINATED_BY_CONTROL_C
+"""An exit code indicating that the script was terminated by Control-C."""
+PROCESS_KILLED_BY_SIGKILL = ExitCode.PROCESS_KILLED_BY_SIGKILL
+"""An exit code indicating that the process was killed by SIGKILL (9)."""
+SEGMENTATION_FAULT = ExitCode.SEGMENTATION_FAULT
+"""An exit code indicating a segmentation fault (core dumped)."""
+PROCESS_TERMINATED_BY_SIGTERM = ExitCode.PROCESS_TERMINATED_BY_SIGTERM
+"""An exit code indicating that the process was terminated by SIGTERM (15)."""
+EXIT_STATUS_OUT_OF_RANGE = ExitCode.EXIT_STATUS_OUT_OF_RANGE
+"""An exit code indicating that the exit status is out of range."""
+
+
+__all__ = [
+    "COMMAND_CANNOT_EXECUTE",
+    "COMMAND_NOT_FOUND",
+    "EXIT_STATUS_OUT_OF_RANGE",
+    "FAIL",
+    "FAILURE",
+    "INVALID_ARGUMENT_TO_EXIT",
+    "MISUSE_OF_SHELL_COMMAND",
+    "PROCESS_KILLED_BY_SIGKILL",
+    "PROCESS_TERMINATED_BY_SIGTERM",
+    "SCRIPT_TERMINATED_BY_CONTROL_C",
+    "SEGMENTATION_FAULT",
+    "SUCCESS",
+    "ExitCode",
+]

bear_utils/constants/_http_status_code.py

@@ -0,0 +1,37 @@
+"""HTTP status codes."""
+
+from bear_utils.constants._meta import RichIntEnum, Value
+
+
+class HTTPStatusCode(RichIntEnum):
+    """An enumeration of common HTTP status codes."""
+
+    SERVER_ERROR = Value(500, "Internal Server Error")
+    SERVER_OK = Value(200, "OK")
+    PAGE_NOT_FOUND = Value(404, "Not Found")
+    BAD_REQUEST = Value(400, "Bad Request")
+    UNPROCESSABLE_CONTENT = Value(422, "Unprocessable Content")
+    UNAUTHORIZED = Value(401, "Unauthorized")
+    FORBIDDEN = Value(403, "Forbidden")
+    CONFLICT = Value(409, "Conflict")
+    METHOD_NOT_ALLOWED = Value(405, "Method Not Allowed")
+
+
+SERVER_ERROR = HTTPStatusCode.SERVER_ERROR
+"""Internal Server Error"""
+SERVER_OK = HTTPStatusCode.SERVER_OK
+"""OK"""
+PAGE_NOT_FOUND = HTTPStatusCode.PAGE_NOT_FOUND
+"""Not Found"""
+BAD_REQUEST = HTTPStatusCode.BAD_REQUEST
+"""Bad Request"""
+UNPROCESSABLE_CONTENT = HTTPStatusCode.UNPROCESSABLE_CONTENT
+"""Unprocessable Content"""
+UNAUTHORIZED = HTTPStatusCode.UNAUTHORIZED
+"""Unauthorized"""
+FORBIDDEN = HTTPStatusCode.FORBIDDEN
+"""Forbidden"""
+CONFLICT = HTTPStatusCode.CONFLICT
+"""Conflict"""
+METHOD_NOT_ALLOWED = HTTPStatusCode.METHOD_NOT_ALLOWED
+"""Method Not Allowed"""

bear_utils/constants/_meta.py

@@ -0,0 +1,107 @@
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Any, Self, TextIO
+
+
+@dataclass(frozen=True)
+class Value:
+    """A frozen dataclass for holding constant values."""
+
+    value: int
+    text: str
+
+
+class RichIntEnum(IntEnum):
+    """Base class for IntEnums with rich metadata."""
+
+    text: str
+
+    def __new__(cls, value: Value) -> Self:
+        _value: int = value.value
+        text: str = value.text
+        obj: Self = int.__new__(cls, _value)
+        obj._value_ = _value
+        obj.text = text
+        return obj
+
+    def __int__(self) -> int:
+        """Return the integer value of the enum."""
+        return self.value
+
+    def __str__(self) -> str:
+        return f"{self.name} ({self.value}): {self.text}"
+
+    @classmethod
+    def get(cls, value: Any) -> Self:
+        """Try to get an enum member by its value, name, or text."""
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, int):
+            return cls.from_int(value)
+        if isinstance(value, str):
+            return cls.from_name(value)
+        raise ValueError(f"Cannot convert {value} to {cls.__name__}")
+
+    @classmethod
+    def from_name(cls, name: str) -> Self:
+        """Convert a string name to its corresponding enum member."""
+        try:
+            return cls[name.upper()]
+        except KeyError as e:
+            raise ValueError(f"Name {name} not found in {cls.__name__}") from e
+
+    @classmethod
+    def from_int(cls, code: int) -> Self:
+        for item in cls:
+            if item.value == code:
+                return item
+        raise ValueError(f"Value {code} not found in {cls.__name__}")
+
+    @classmethod
+    def int_to_text(cls, code: int) -> str:
+        """Convert an integer to its text representation."""
+        try:
+            return cls.from_int(code).text
+        except ValueError:
+            return "Unknown value"
+
+
+class MockTextIO(TextIO):
+    """A mock TextIO class that does nothing."""
+
+    def __init__(self) -> None:
+        """Initialize the mock TextIO."""
+        self._buffer = []
+
+    def write(self, _s: str, *_) -> None:  # type: ignore[override]
+        """Mock write method that appends to the buffer."""
+        if _s == "\n":
+            return
+        self._buffer.append(_s)
+
+    def output_buffer(self) -> list[str]:
+        """Get the output buffer."""
+        return self._buffer
+
+    def clear(self) -> None:
+        """Clear the output buffer."""
+        self._buffer.clear()
+
+    def flush(self) -> None:
+        """Mock flush method that does nothing."""
+
+
+class NullFile(TextIO):
+    """A class that acts as a null file, discarding all writes."""
+
+    def write(self, _s: str, *_: Any) -> None:  # type: ignore[override]
+        """Discard the string written to this null file."""
+
+    def flush(self) -> None:
+        """Flush the null file (no operation)."""
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        """Exit context manager (no operation)."""

bear_utils/extras/responses/__init__.py

@@ -1,9 +1,5 @@
 """A module for handling responses for functions, methods, and classes in Bear Utils."""
 
-from .function_response import FAILURE, SUCCESS, FunctionResponse
+from .function_response import FunctionResponse, fail, success
 
-__all__ = [
-    "FAILURE",
-    "SUCCESS",
-    "FunctionResponse",
-]
+__all__ = ["FunctionResponse", "fail", "success"]

bear_utils/extras/responses/function_response.py

@@ -18,10 +18,6 @@ if TYPE_CHECKING:
     from collections.abc import Callable
 
 
-SUCCESS: list[str] = ["name", "success", "number_of_tasks"]
-FAILURE: list[str] = ["name", "number_of_tasks"]
-
-
 class FunctionResponse(BaseModel):
     """A class to represent the response of a function call, including success status, content, and error messages."""
 

bear_utils/graphics/font/__init__.py

@@ -0,0 +1,11 @@
+"""A set of command-line interface (CLI) utilities for creating font outputs."""
+
+from .block_font import BLOCK_LETTERS, char_to_block, print_block_font, word_to_block
+
+__all__ = [
+    "BLOCK_LETTERS",
+    "char_to_block",
+    "char_to_block",
+    "print_block_font",
+    "word_to_block",
+]