logseg.log_setup
================

.. py:module:: logseg.log_setup


Classes
-------

.. autoapisummary::

   logseg.log_setup.LoggerManager
   logseg.log_setup.RedirectToLogger
   logseg.log_setup.CreateFileHandlerHandler


Functions
---------

.. autoapisummary::

   logseg.log_setup._add_file_handler
   logseg.log_setup._get_log_formatter
   logseg.log_setup._get_root_logger
   logseg.log_setup._redirect_stdout_stderr
   logseg.log_setup._configure_logging_handlers
   logseg.log_setup._lt
   logseg.log_setup.logger_init
   logseg.log_setup.get_logger


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

.. py:class:: LoggerManager(logger_thread: threading.Thread)

   This class manages the logger thread.

   :param logger_thread: The logger thread to manage.

   Returns:



   .. py:attribute:: logger_thread


   .. py:method:: terminate_logger()

      This method terminates the logger thread. It should be called when log is complete during program cleanup.

      Returns:




.. py:class:: RedirectToLogger(logger, log_level=logging.INFO)

   Bases: :py:obj:`object`


   Used to redirect stdout and stderr to logger in _redirect_stdout_stderr

   :param logger: The logger instance to redirect to.
   :param log_level: The log level to use for the logger.

   Returns:



   .. py:attribute:: logger


   .. py:attribute:: log_level
      :value: 20



   .. py:attribute:: value
      :value: None



   .. py:method:: write(message)

      This method writes a message to the logger instance.

      :param message: The message to write to the logger instance.

      Returns:




   .. py:method:: flush()


   .. py:method:: getvalue()


.. py:class:: CreateFileHandlerHandler(config: configparser.ConfigParser)

   Bases: :py:obj:`logging.Handler`


   This class creates a file handler for a logger instance.

   :param config: A ConfigParser containing the logger configuration.

   Returns:



   .. py:attribute:: config


   .. py:attribute:: segregate_regex


   .. py:attribute:: seg_name_regex


   .. py:method:: _process_logseg(log_str: str) -> Tuple[str, str]

      This method processes a logseg log record.

      :param log_str: The log string to be processed.

      :returns: A Tuple containing the final message and the segregate folder name for the log string.



   .. py:method:: emit(record)

      This method emits a log record to the logger instance.

      :param record: The log record to emit.

      Returns:




.. py:function:: _add_file_handler(config: configparser.ConfigParser, instance: logging.Logger, log_formatter: logging.Formatter, folder_name: Optional[str] = None) -> None

   This function adds a file handler to a logger instance.

   :param config: A ConfigParser containing the logger configuration.
   :param instance: The logger instance to add the file handler to.
   :param log_formatter: The log formatter to use for the file handler.
   :param folder_name: The name of the folder to segregate logs into.

   Returns:



.. py:function:: _get_log_formatter(config: configparser.ConfigParser)

   This function gets the log formatter with timezone support.

   :param config: A ConfigParser containing the logger configuration.

   :returns: A logging.Formatter instance with timezone support.


.. py:function:: _get_root_logger(config: configparser.ConfigParser = None)

   This function gets the root logger and sets its level based on configuration.

   :param config: A ConfigParser containing the logger configuration. If None, the default config will be used.

   :returns: The root logger with the configured log level.


.. py:function:: _redirect_stdout_stderr(logger: logging.Logger) -> None

   This function redirects the standard out and standard error to logger instances.

   :param logger: The logger instance to redirect stdout and stderr to.

   Returns:



.. py:function:: _configure_logging_handlers(config: configparser.ConfigParser) -> logging.Logger

   This function configures the logging handlers for the logger instance.

   :param config: A ConfigParser containing the logger configuration.

   :returns: A Logger instance.


.. py:function:: _lt(queue: multiprocessing.queues.Queue)

   This function acts as the thread that listens to the logger queue and sends queued logs to the logger instance.

   :param queue: A multiprocessing Queue, managed by a multiprocessing Manager.

   Returns:



.. py:function:: logger_init(config_file: Union[pathlib.Path, str] = None) -> LoggerManager

   This function initializes a logger as well as a thread to process logs produced by concurrent processes. Logs
   from concurrent processes should be passed through the multiprocessing queue stored in log.globals.logger_queue.

   :param config_file: A path to a configuration file containing a LOGSEG section. If not provided, the default
   :param configuration will be used. See the documentation for an example configuration file.:

   :returns: A LoggerManager instance which can be used to terminate the logger thread at cleanup time.


.. py:function:: get_logger(name: str, queue: Optional[multiprocessing.queues.Queue] = None) -> logging.Logger

   This function gets a logger instance.

   Setup ::

       from logseg import LoggerManager
       from logseg import logger_init

       logger_manager: LoggerManager = logger_init()

   Without multiprocessing ::

       from logseg import get_logger

       logger = get_logger(__name__)
       logger.info('your message')

   With multiprocessing ::

       import multiprocessing as mp
       import log.globals

       def my_function(queue: mp.Queue, parameter: str):
           logger = get_logger(__name__, queue)
           logger.info(f'Your message: {parameter}')

       pool = mp.Pool(processes=mp.cpu_count())
       pool.imap_unordered(func=partial(
           my_function,
           queue=log.globals.logger_queue,
           parameter='example'
       ))
       pool.close()
       pool.join()

   Shutdown ::

       logger_manager.terminate_logger()

   :param name: The name for the logger.
   :param queue: A Queue instance generated by logger_init(), held in the variable log.globals.logger_queue

   :returns: A logseg logger instance.