logseg
======

.. py:module:: logseg


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/logseg/configurations/index
   /autoapi/logseg/globals/index
   /autoapi/logseg/log_setup/index
   /autoapi/logseg/project_metadata/index
   /autoapi/logseg/utils/index


Attributes
----------

.. autoapisummary::

   logseg.__version__


Classes
-------

.. autoapisummary::

   logseg.LoggerManager


Functions
---------

.. autoapisummary::

   logseg.logger_init
   logseg.get_logger


Package Contents
----------------

.. 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.


.. 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:data:: __version__
   :value: '0.3.1'