:py:mod:`FELiCS.Misc.logging`
=============================

.. py:module:: FELiCS.Misc.logging


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   FELiCS.Misc.logging.CustomFormatter
   FELiCS.Misc.logging.Logger



Functions
~~~~~~~~~

.. autoapisummary::

   FELiCS.Misc.logging.in_notebook



.. py:function:: in_notebook()


.. py:class:: CustomFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)


   Bases: :py:obj:`logging.Formatter`

   Custom log formatter with colored output for different log levels.

   Provides colored formatting for log messages in the terminal, making it easier to distinguish between log levels such as DEBUG, INFO,
   WARNING, ERROR, and CRITICAL.

   **Initialize the CustomFormatter object**

   No parameters are required for initialization.

   :ivar grey: ANSI escape code for grey color.
   :vartype grey: :py:class:`str`
   :ivar yellow: ANSI escape code for yellow color.
   :vartype yellow: :py:class:`str`
   :ivar red: ANSI escape code for red color.
   :vartype red: :py:class:`str`
   :ivar bold_red: ANSI escape code for bold red color.
   :vartype bold_red: :py:class:`str`
   :ivar reset: ANSI escape code to reset color.
   :vartype reset: :py:class:`str`
   :ivar format: Log message format string.
   :vartype format: :py:class:`str`
   :ivar FORMATS: Mapping of log levels to their respective colored format strings.

   :vartype FORMATS: :py:class:`dict`

   .. py:attribute:: grey
      :value: '\x1b[38;20m'

      

   .. py:attribute:: yellow
      :value: '\x1b[33;20m'

      

   .. py:attribute:: red
      :value: '\x1b[31;20m'

      

   .. py:attribute:: bold_red
      :value: '\x1b[31;1m'

      

   .. py:attribute:: reset
      :value: '\x1b[0m'

      

   .. py:attribute:: format_str
      :value: '%(levelname)-8s | %(filename)-22s | %(funcName)-26s (line %(lineno)-4s) : %(message)s'

      

   .. py:attribute:: FORMATS

      

   .. py:method:: format(record)

      Format the specified log record as text with color based on log level.

      Applies color formatting to the log message depending on the log level.

      :param record: The log record to be formatted.
      :type record: :py:class:`logging.LogRecord`

      :returns: The formatted log message string.
      :rtype: :py:class:`str`



.. py:class:: Logger(debug_mode=False, test_mode=False, logger_name='log')


   Logger class for flexible and colored logging to file and console.

   Provides a singleton logger with support for colored console output, file logging, dynamic log file location changes, and debug/test modes.

   **Initialize the Logger object**

   :param debug_mode: If True, enables debug logging (default is False).
   :type debug_mode: :py:class:`bool`, *optional*
   :param test_mode: If True, enables test mode logging (default is False).
   :type test_mode: :py:class:`bool`, *optional*
   :param logger_name: Name of the logger and log file prefix (default is "log").
   :type logger_name: :py:class:`str`, *optional*

   :ivar debug_mode: Indicates if debug mode is enabled.
   :vartype debug_mode: :py:class:`bool`
   :ivar test_mode: Indicates if test mode is enabled.
   :vartype test_mode: :py:class:`bool`
   :ivar logger_name: Name of the logger.
   :vartype logger_name: :py:class:`str`
   :ivar _logger: The underlying Python logger instance.

   :vartype _logger: :py:class:`logging.Logger`

   .. py:property:: logger

      Get the underlying logger instance.

      :returns: The configured logger instance.
      :rtype: :py:class:`logging.Logger`

      :raises RuntimeError: If the logger has not been properly initialized.

   .. py:method:: get_logger(name=None)
      :classmethod:

      Retrieve the singleton logger instance.

      If the logger has not been initialized, creates a new instance with the specified name.

      :param name: Name for the logger if it needs to be created.
      :type name: :py:class:`str`, *optional*

      :returns: The singleton logger instance.
      :rtype: :py:class:`logging.Logger`

      :raises RuntimeError: If the logger is not initialized and no name is provided.


   .. py:method:: change_log_location(new_log_path)
      :classmethod:

      Move log files to a new directory and update file handlers.

      Moves all current log files to the specified new directory and updates the logger's file handlers to write to the new location.

      :param new_log_path: The new directory path for log files.
      :type new_log_path: :py:class:`str`

      :raises RuntimeError: If the logger is not initialized.


   .. py:method:: close_logger(logger)

      Remove all handlers from the given logger.

      Clears all handlers from the specified logger instance.

      :param logger: The logger instance to close.
      :type logger: :py:class:`logging.Logger`