bear-utils 0.7.11__py3-none-any.whl

bear_utils/logging/logger_manager/loggers/_console_logger.py

@@ -0,0 +1,249 @@
+# region Imports
+from functools import cached_property
+from logging import DEBUG, Formatter, Handler, Logger
+from logging.handlers import QueueHandler, QueueListener, RotatingFileHandler
+from queue import Queue
+from typing import override
+
+from prompt_toolkit import PromptSession
+from rich.text import Text
+from rich.theme import Theme
+from rich.traceback import Traceback
+
+from bear_utils.constants.date_related import DATE_TIME_FORMAT
+
+from .._common import FIVE_MEGABYTES, VERBOSE_CONSOLE_FORMAT, VERBOSE_FORMAT, ExecValues
+from .._console_junk import ConsoleBuffering, ConsoleFormatter, ConsoleHandler
+from ._base_logger import BaseLogger
+
+# endregion Imports
+
+
+class ConsoleLogger(Logger, BaseLogger):
+    """
+    A comprehensive console logger that combines Python's logging framework with Rich console styling.
+
+    This logger provides styled console output with configurable file logging, queue handling,
+    buffering, and interactive input capabilities. It dynamically creates logging methods
+    (info, error, debug, etc.) that forward to Rich's styled console printing.
+
+    Features:
+    - Rich styled console output with themes
+    - Optional file logging with rotation
+    - Queue-based async logging
+    - Message buffering capabilities
+    - Interactive prompt integration
+    - Exception tracebacks with local variables
+
+    Example:
+        logger = ConsoleLogger.get_instance(init=True, verbose=True, name="MyLogger", level=DEBUG)
+        logger.info("This is styled info")
+        logger.error("This is styled error")
+        logger.success("This is styled success")
+    """
+
+    # region Setup
+    def __init__(
+        self,
+        theme: Theme | None = None,
+        name: str = "ConsoleLogger",
+        level: int = DEBUG,
+        disabled: bool = True,
+        console: bool = True,
+        file: bool = False,
+        queue_handler: bool = False,
+        buffering: bool = False,
+        *args,
+        **kwargs,
+    ) -> None:
+        Logger.__init__(self, name=name, level=level)
+        BaseLogger.__init__(
+            self,
+            output_handler=self._console_output,
+            theme=theme,
+            style_disabled=kwargs.get("style_disabled", False),
+            logger_mode=kwargs.get("logger_mode", True),
+            level=level,
+        )
+        self.name = name
+        self.level = level
+        self.setLevel(level)
+        self.session = None
+        self.disabled = disabled
+        self._handlers: list[Handler] = []
+        self.logger_mode: bool = kwargs.pop("logger_mode", True)
+        if self.logger_mode:
+            self.disabled = False
+            self._handle_enable_booleans(
+                file=file,
+                console=console,
+                buffering=buffering,
+                queue_handler=queue_handler,
+                **kwargs,
+            )
+
+    def _handle_enable_booleans(self, file, console, buffering, queue_handler, **kwargs) -> None:
+        """Configure logging handlers based on initialization parameters."""
+        if console or buffering:
+            self.console_handler: ConsoleHandler = ConsoleHandler(self.print, self.output_buffer)
+            self.console_handler.setFormatter(ConsoleFormatter(fmt=VERBOSE_CONSOLE_FORMAT, datefmt=DATE_TIME_FORMAT))
+            self.console_handler.setLevel(self.level)
+            if console:
+                self._handlers.append(self.console_handler)
+            if buffering:
+                self.buffer_handler: ConsoleBuffering = ConsoleBuffering(console_handler=self.console_handler)
+                self.addHandler(self.buffer_handler)
+        if file:
+            self.file_handler: RotatingFileHandler = RotatingFileHandler(
+                filename=kwargs.get("file_path", "console.log"),
+                maxBytes=kwargs.get("max_bytes", FIVE_MEGABYTES),
+                backupCount=kwargs.get("backup_count", 5),
+            )
+            self.file_handler.setFormatter(Formatter(fmt=VERBOSE_FORMAT, datefmt=DATE_TIME_FORMAT))
+            self.file_handler.setLevel(self.level)
+            self._handlers.append(self.file_handler)
+        if queue_handler:
+            self.queue = Queue()
+            self.queue_handler = QueueHandler(self.queue)
+            self.addHandler(self.queue_handler)
+            self.listener = QueueListener(self.queue, *self._handlers)
+            self.listener.start()
+        else:
+            for handler in self._handlers:
+                self.addHandler(handler)
+
+    def stop_queue_listener(self) -> None:
+        """Stop the queue listener if it exists and clean up resources."""
+        if hasattr(self, "listener"):
+            self.verbose("ConsoleLogger: QueueListener stopped and cleaned up.")
+            self.listener.stop()
+            del self.listener
+            del self.queue
+            del self.queue_handler
+
+    def trigger_buffer_flush(self) -> Text:
+        """Flush buffered messages to console output."""
+        if hasattr(self, "buffer_handler"):
+            return self.buffer_handler.flush_to_output()
+        return Text("No buffering handler available.", style="bold red")
+
+    def set_base_level(self, level: int) -> None:
+        """Set the base logging level for the console logger."""
+        super().set_base_level(level)
+        self.setLevel(level)
+        if hasattr(self, "console_handler"):
+            self.console_handler.setLevel(level)
+        if hasattr(self, "buffer_handler"):
+            self.buffer_handler.setLevel(level)
+        if hasattr(self, "queue_handler"):
+            self.queue_handler.setLevel(level)
+
+    def _console_output(self, msg: object, extra, *args, **kwargs) -> None:
+        """Console-specific output handler that integrates with logging module."""
+        if not self.logger_mode:
+            self.print(msg, *args, **kwargs)
+        else:
+            kwargs.pop("style", None)
+            self.log(
+                level=extra.get("log_level", DEBUG),
+                msg=msg,
+                extra=extra,
+                *args,
+                **kwargs,
+            )
+
+    # endregion Setup
+
+    # region Utility Methods
+
+    async def input(self, msg: str, style="info", **kwargs) -> str:
+        """Display a styled prompt and return user input asynchronously."""
+        if not self.session:
+            self.session = PromptSession(**kwargs)
+        self.print(msg, style=style)
+        return await self.session.prompt_async()
+
+    def output_buffer(
+        self, msg: object, end="\n", exc_info=None, exec_values: ExecValues | None = None, *args, **kwargs
+    ) -> str:
+        """Capture console output to a string buffer without printing to terminal."""
+        if exc_info and exec_values:
+            exception: Traceback = self._get_exception(manual=True, exec_values=exec_values)
+            self.console.print(exception, end=end)
+        self.console.print(msg, end="", style=kwargs.get("style", "info"))
+        output = self.console_buffer.getvalue()
+        self._reset_buffer()
+        return output
+
+    # endregion Utility Methods
+
+    # region Enhanced Print Methods
+
+    def print(self, msg: object, end="\n", exc_info=None, extra: dict | None = None, *args, **kwargs) -> None | str:
+        """
+        Print styled messages with enhanced exception handling and JSON support.
+
+        Extends the base print method with proper exception tracebacks and
+        integrated JSON printing for structured data output.
+        """
+        if exc_info is not None:
+            try:
+                self._print(self._get_exception(), end=end, width=100, show_locals=True, **kwargs)
+            except ValueError:
+                ...
+
+        self._print(msg, end=end, *args, **kwargs)
+
+        if extra:
+            self._print(msg=extra, end=end, json=True, indent=4)
+
+    @cached_property
+    def stack_level(self) -> int:
+        """Cached property to retrieve the current stack level."""
+        return self.stack_tracker.record_end()
+
+    @override
+    def _log(self, level, msg, args, exc_info=None, extra=None, stack_info=False, stacklevel=None):
+        """
+        Custom logging implementation with enhanced exception handling.
+
+        Overrides the standard logging._log method to provide better exception
+        value extraction for Rich traceback integration while respecting log levels.
+        """
+        stacklevel = stacklevel or self.stack_level
+        try:
+            fn, lno, func, sinfo = self.findCaller(stack_info, stacklevel)
+        except ValueError:
+            fn, lno, func, sinfo = "(unknown file)", 0, "(unknown function)", None
+
+        final_extra = extra or {}
+
+        if exc_info is not None:
+            exec_values = self._extract_exception_values(exc_info)
+            if exec_values:
+                final_extra = {**final_extra, "exec_values": exec_values}
+
+        record = self.makeRecord(
+            name=self.name,
+            level=level,
+            fn=fn,
+            lno=lno,
+            msg=msg,
+            args=args,
+            exc_info=None,
+            func=func,
+            extra=final_extra,
+            sinfo=sinfo,
+        )
+
+        self.handle(record)
+
+    def exit(self) -> None:
+        """Clean up resources including queue listeners and console buffers."""
+        if hasattr(self, "queue_handler"):
+            self.queue_handler.flush()
+            self.stop_queue_listener()
+
+        self.console_buffer.close()
+
+    # endregion Enhanced Print Methods

bear_utils/logging/logger_manager/loggers/_console_logger.pyi

@@ -0,0 +1,64 @@
+from logging import DEBUG, Logger
+from logging.handlers import QueueHandler, RotatingFileHandler
+from typing import Any
+
+from rich.text import Text
+from rich.theme import Theme
+
+from .._console_junk import ConsoleBuffering, ConsoleHandler
+from ._base_logger import BaseLogger
+from ._sub_logger import SubConsoleLogger
+
+class ConsoleLogger(Logger, BaseLogger):
+
+    name: str
+    level: int
+    file: bool
+    queue_handler: QueueHandler
+    buffer_handler: ConsoleBuffering
+    console_handler: ConsoleHandler
+    file_handler: RotatingFileHandler
+    sub_logger: dict[str, "SubConsoleLogger[ConsoleLogger]"]
+
+    def __init__(
+        self,
+        theme: Theme | None = None,
+        name: str = "ConsoleLogger",
+        level: int = DEBUG,
+        disabled: bool = True,
+        queue_handler: bool = False,
+        buffering: bool = False,
+        file: bool = False,
+        console: bool = True,
+        style_disabled: bool = False,
+        logger_mode: bool = True,
+        *args,
+        **kwargs,
+    ) -> None:
+        """
+        A general purpose console logger that that by default is a wrapper around both Rich and Python's logging module.
+
+        Args:
+            theme (Theme | None): The theme for the logger.
+            name (str): The name of the logger.
+            level (int): The logging level.
+            disabled (bool): Whether the logger is disabled.
+            queue_handler (bool): Whether to use a queue handler.
+            buffering (bool): Whether to use buffering.
+            file (bool): Whether to log to a file.
+            style_disabled (bool): Whether to disable styling.
+            logger_mode (bool): Whether to enable logger mode.
+        """
+    # fmt: off
+    def debug(self, msg: object, *args, **kwargs: Any) -> None: ...
+    def info(self, msg: object, *args, **kwargs: Any) -> None: ...
+    def warning(self, msg: object, *args, **kwargs: Any) -> None: ...
+    def error(self, msg: object, *args, **kwargs: Any) -> None: ...
+    def success(self, msg: str, *args, **kwargs: Any) -> None: ...
+    def failure(self, msg: str, *args, **kwargs: Any) -> None: ...
+    def verbose(self, msg: str, *args, **kwargs: Any) -> None: ...
+    def set_base_level(self, level: int) -> None: ...
+    def input(self, msg: str, style: str = "info") -> str: ...
+    def trigger_buffer_flush(self) -> str | Text: ...
+    def print(self, msg: object, end: str="\n", exc_info=None, extra: dict | None = None, *args, **kwargs) -> None | str: ...
+    def exit(self) -> None: ...

bear_utils/logging/logger_manager/loggers/_file_logger.py

@@ -0,0 +1,141 @@
+from logging import DEBUG
+from pathlib import Path
+from typing import Any, override
+
+from rich.theme import Theme
+
+from bear_utils.constants.date_related import DATE_TIME_FORMAT
+
+from .._common import FIVE_MEGABYTES
+from .._styles import LoggerExtraInfo
+from ._console_logger import ConsoleLogger
+from ._sub_logger import SubConsoleLogger
+
+
+class FileLogger(ConsoleLogger):
+    """
+    A file-based logger that writes styled log messages to files.
+
+    Combines Python's logging framework with Rich console styling, but outputs
+    to files instead of console. Supports file rotation, custom formatting,
+    and maintains the same interface as other loggers.
+
+    Features:
+    - File logging with rotation
+    - Rich-style method generation (info, error, debug, etc.)
+    - Consistent print() interface
+    - Exception tracebacks in file format
+    - JSON logging support
+
+    Example:
+        logger = FileLogger.get_instance(
+            init=True,
+            name="FileLogger",
+            file_path="app.log",
+            max_bytes=10*1024*1024,
+            backup_count=5
+        )
+        logger.info("This goes to the file")
+        logger.error("This error is logged to file")
+    """
+
+    def __init__(
+        self,
+        theme: Theme | None = None,
+        name: str = "FileLogger",
+        level: int = DEBUG,
+        file_path: str = "app.log",
+        max_bytes: int = FIVE_MEGABYTES,
+        backup_count: int = 5,
+        *args,
+        **kwargs,
+    ) -> None:
+        self.file_path = Path(file_path)  # TODO: Add more options for filename patterns (timestamps, process IDs, etc.)
+        self.max_bytes = max_bytes
+        self.backup_count = backup_count
+        ConsoleLogger.__init__(
+            self,
+            name=name,
+            level=level,
+            file=True,
+            console=False,
+            queue_handler=kwargs.pop("queue_handler", False),
+            file_path=self.file_path,
+            max_bytes=self.max_bytes,
+            backup_count=self.backup_count,
+            theme=theme,
+            style_disabled=True,
+            logger_mode=True,
+            **kwargs,
+        )
+
+    @override
+    def get_sub_logger(self, namespace: str, **kwargs: Any) -> SubConsoleLogger:
+        return SubConsoleLogger(self, namespace, **kwargs)
+
+    @override
+    def replacement_method(self, msg: object, *args, **kwargs) -> None:
+        """Handle logging method calls with proper file logging integration."""
+        extra: LoggerExtraInfo = kwargs.pop("injected_extra")
+        if kwargs.get("extra"):
+            extra.update(kwargs.pop("extra"))
+        if extra.get("namespace"):
+            msg = f"<{extra.get('namespace')}> {msg}"
+        if self.stack_tracker.not_set:
+            self.stack_tracker.record_start()
+
+        self.log(
+            level=extra.get("log_level", DEBUG),
+            msg=msg,
+            extra=extra,
+            *args,
+            **kwargs,
+        )
+
+    def print(self, msg: object, end: str = "\n", exc_info=None, extra: dict | None = None, *args, **kwargs) -> None:
+        """
+        Print a message to the file with proper formatting.
+
+        Maintains the same interface as other loggers but writes to file instead of console.
+        """
+        try:
+            # For file logging, we want to use the logging system rather than direct file writing
+            # This ensures proper formatting, rotation, etc.
+            if exc_info is not None:
+                # Log with exception info
+                self.error(f"{msg}", exc_info=exc_info, extra=extra)
+            else:
+                # Regular info log
+                self.info(f"{msg}", extra=extra)
+
+            if extra:
+                # Log extra data as JSON-like format
+                self.info(f"Extra data: {extra}")
+        except Exception as e:
+            print(f"FileLogger: Failed to write to log file. Message: {msg}, Error: {e}")
+
+    def get_file_size(self) -> int:
+        """Get current size of the log file in bytes."""
+        if self.file_path.exists():
+            return self.file_path.stat().st_size
+        return 0
+
+    def get_file_path(self) -> Path:
+        """Get the current log file path."""
+        return self.file_path
+
+    def rotate_file(self) -> None:
+        """Manually trigger file rotation."""
+        if hasattr(self.file_handler, "doRollover"):
+            self.file_handler.doRollover()
+
+    @override
+    def exit(self) -> None:
+        """Clean up file resources."""
+        if hasattr(self, "file_handler"):
+            self.file_handler.flush()
+            self.file_handler.close()
+            self.removeHandler(self.file_handler)
+
+        # Call parent exit
+        super().exit()

bear_utils/logging/logger_manager/loggers/_level_sin.py

@@ -0,0 +1,58 @@
+import threading
+from logging import addLevelName
+from typing import Literal
+
+ERROR: Literal[40] = 40
+WARNING: Literal[30] = 30
+WARN: Literal[30] = WARNING
+INFO: Literal[20] = 20
+DEBUG: Literal[10] = 10
+NOTSET: Literal[0] = 0
+
+_levelToName = {
+    ERROR: "ERROR",
+    WARNING: "WARNING",
+    INFO: "INFO",
+    DEBUG: "DEBUG",
+    NOTSET: "NOTSET",
+}
+_nameToLevel = {
+    "ERROR": ERROR,
+    "WARN": WARNING,
+    "WARNING": WARNING,
+    "INFO": INFO,
+    "DEBUG": DEBUG,
+    "NOTSET": NOTSET,
+}
+
+_lock = threading.RLock()
+
+
+def lvl_exists(level: int | str) -> bool:
+    """Check if a logging level already exists."""
+    with _lock:
+        level = check_level(level, fail=False)
+        return level in _levelToName
+
+
+def add_level_name(level: int, name: str) -> None:
+    """Add a custom logging level name."""
+    with _lock:
+        if level in _levelToName:
+            raise ValueError(f"Level {level} already exists with name {_levelToName[level]}")
+        _levelToName[level] = name.upper()
+        _nameToLevel[name.upper()] = level
+        addLevelName(level, name)
+
+
+def check_level(level: int | str, fail: bool = True) -> int:
+    """Validate and normalize logging level to integer."""
+    if isinstance(level, str) and level.upper() in _nameToLevel:
+        return _nameToLevel[level.upper()]
+    if isinstance(level, int) and level in _levelToName:
+        return level
+    if fail:
+        if not isinstance(level, (int, str)):
+            raise TypeError(f"Level must be int or str, got {type(level).__name__}: {level!r}")
+        raise ValueError(f"Invalid logging level: {level!r}. Valid levels are: {list(_nameToLevel.keys())}")
+    return 999  # Return a high value to indicate invalid level

bear_utils/logging/logger_manager/loggers/_logger.py

@@ -0,0 +1,18 @@
+from logging import Logger
+
+from ._base_logger import BaseLogger
+
+
+class ExtraBaseLogger(Logger, BaseLogger):
+    """
+    Base logger class that extends the standard logging.Logger and BaseLogger.
+    This class is intended to be used as a base for custom loggers that require
+    additional functionality or attributes.
+    """
+
+    def __init__(self, name, level=0, **kwargs):
+        """
+        Initialize the ExtraBaseLogger with a name and level.
+        """
+        super().__init__(name, level)
+        BaseLogger.__init__(self, **kwargs)

bear_utils/logging/logger_manager/loggers/_sub_logger.py

@@ -0,0 +1,110 @@
+"""
+Logger adapter module that provides an alternative to SubLogger using standard library tools.
+
+This implementation shows how to use LoggerAdapter and contextvars to maintain
+all the functionality of the existing SubLogger while reducing complexity.
+"""
+
+from functools import partial
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from rich.text import Text
+
+from .._styles import LOGGER_METHODS, LoggerExtraInfo
+from ._level_sin import check_level
+
+if TYPE_CHECKING:
+    from ._base_logger import BaseLogger
+
+T = TypeVar("T", bound="BaseLogger")
+
+
+class SubConsoleLogger(Generic[T]):
+    def __init__(self, logger: T, namespace: str, **kwargs) -> None:
+        """
+        Initialize the SubConsoleLogger with a logger and a namespace.
+
+        Args:
+            logger: The underlying logger to wrap with a namespace.
+            namespace: The namespace to prefix log messages with
+        """
+        self.logger: T = logger
+        self._level: int = kwargs.get("level", None) or logger._level
+        self.logger_mode = logger.logger_mode
+        self.namespace: str = namespace
+        self._setup(self.namespace)
+
+    def print(
+        self,
+        msg: object,
+        end: str = "\n",
+        exc_info: Any = None,
+        extra: dict | None = None,
+        *args,
+        **kwargs,
+    ) -> None | str:
+        """
+        Print a message to the console with the specified formatting.
+
+        This method allows for printing messages with additional context and formatting.
+        """
+        return self.logger.print(msg, end=end, exc_info=exc_info, extra=extra, **kwargs)
+
+    def set_sub_level(self, level: int) -> None:
+        """
+        Set the logging level for the logger.
+
+        This method allows changing the logging level dynamically.
+        """
+        self._level = level
+
+    def filter_by_level(self, level: int | str) -> bool:
+        """
+        Filter method to determine if a message should be logged based on its level.
+
+        This method checks if the provided level is greater than or equal to the logger's level.
+
+        Args:
+            level (int | str): The logging level of the message.
+
+        Returns:
+            bool: True if the message should be logged, False otherwise.
+        """
+        level = check_level(level)
+        bool_check = level >= self._level
+        return bool_check
+
+    def trigger_buffer_flush(self) -> str | Text:
+        """
+        Flush buffered messages to console output.
+
+        This method is used to ensure that any buffered log messages are printed
+        to the console, similar to the SubLogger's buffer flush functionality.
+        """
+        return self.logger.trigger_buffer_flush()
+
+    def _setup(self, name: str) -> None:
+        """
+        Get an attribute from the logger.
+
+        This allows for accessing logger methods directly.
+        """
+        filter_func = self.filter_by_level
+        for style_name, og_extra in LOGGER_METHODS.items():
+            extra: LoggerExtraInfo = og_extra.copy()
+
+            extra["namespace"] = name
+
+            setattr(
+                self,
+                style_name,
+                partial(
+                    self.logger.replacement_method,
+                    injected_extra=extra,
+                    filter_func=filter_func,
+                ),
+            )
+
+    def __repr__(self) -> str:
+        """String representation of the adapter."""
+        return f"ConsoleAdapter(namespace={self.namespace}"

bear_utils/logging/logger_manager/loggers/_sub_logger.pyi

@@ -0,0 +1,38 @@
+"""
+Logger adapter module that provides an alternative to SubLogger using standard library tools.
+
+This implementation shows how to use LoggerAdapter and contextvars to maintain
+all the functionality of the existing SubLogger while reducing complexity.
+"""
+
+from typing import Any, Generic, TypeVar
+
+from ._base_logger import BaseLogger
+
+T = TypeVar("T", bound=BaseLogger)
+
+class SubConsoleLogger(Generic[T]):
+    """
+    Enhanced logger adapter that supports style-based logging and namespace prefixing.
+
+    This class provides an alternative to the SubLogger implementation while
+    maintaining compatibility with the existing ConsoleLogger.
+    """
+
+    logger: T
+    _level: int
+    namespace: str
+    extra: dict[str, Any] | None
+    log_level: int
+    # fmt: off
+    def __init__(self, logger: T, namespace: str, **kwargs) -> None: ...
+    def set_sub_level(self, level: int) -> None: ...
+    def success(self, msg: object, *args, **kwargs) -> None: ...
+    def failure(self, msg: object, *args, **kwargs) -> None: ...
+    def verbose(self, msg: object, *args, **kwargs) -> None: ...
+    def info(self, msg: object, *args, **kwargs) -> None: ...
+    def debug(self, msg: object, *args, **kwargs) -> None: ...
+    def warning(self, msg: object, *args, **kwargs) -> None: ...
+    def error(self, msg: object, *args, **kwargs) -> None: ...
+    def print(self, msg: object, end: str = "\n", exc_info: Any = None, extra: dict | None = None, *args, **kwargs: Any) -> None | str: ...
+    def __repr__(self) -> str: ...