polymerist.genutils.logutils.IOHandlers
=======================================

.. py:module:: polymerist.genutils.logutils.IOHandlers

.. autoapi-nested-parse::

   Tools for simplifying logging from multiple sources



Attributes
----------

.. autoapisummary::

   polymerist.genutils.logutils.IOHandlers.LOG_FORMATTER
   polymerist.genutils.logutils.IOHandlers.MSFHandler
   polymerist.genutils.logutils.IOHandlers.MSFHandlerFlex


Classes
-------

.. autoapisummary::

   polymerist.genutils.logutils.IOHandlers.MultiStreamFileHandler
   polymerist.genutils.logutils.IOHandlers.MultiStreamFileHandlerFlexible


Functions
---------

.. autoapisummary::

   polymerist.genutils.logutils.IOHandlers.get_logger_registry
   polymerist.genutils.logutils.IOHandlers.get_active_loggers
   polymerist.genutils.logutils.IOHandlers.submodule_loggers


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

.. py:data:: LOG_FORMATTER

.. py:function:: get_logger_registry() -> dict[str, logging.Logger]

   Gets all registered Loggers by module


.. py:function:: get_active_loggers() -> list[logging.Logger]

.. py:function:: submodule_loggers(module: types.ModuleType, recursive: bool = True, blacklist: Optional[Iterable[str]] = None, sparse: bool = True) -> dict[str, Optional[logging.Logger]]

   Produce a dict of any Logger objects present in each submodule. Can optionally generate recursively and blacklist certain modules

   :Parameters: * **module** (*ModuleType*) -- The "root" module to begin importing from
                  Represented in the Node object returned by this function
                * **recursive** (*bool, default=True*) -- Whether or not to recursively import modules from subpackages and add them to the tree
                * **blacklist** (*list[str] (optional), default None*) -- List of module names to exclude from tree building
                  If provided, will exclude any modules whose names occur in this list
                * **sparse** (*bool, default=True*) -- Whether to only include modules which have a Logger defined (i.e. exclude all NoneType entries from returned dict)

   :returns: **logger_registry** -- A dict keyed by module name whose values are the corresponding Logger bound to that module
   :rtype: dict[str, Optional[logging.Logger]]


.. py:class:: MultiStreamFileHandler(filename: Union[str, pathlib.Path], mode: str = 'a', encoding: Optional[str] = None, delay: bool = False, errors: Optional[str] = None, loggers: Optional[Union[str, logging.Logger, Iterable[logging.Logger]]] = 'ALL', formatter: logging.Formatter = LOG_FORMATTER, proc_name: str = 'Process')

   Bases: :py:obj:`logging.FileHandler`


   Class to simplify logging file I/O given multiple logger sources providing logging input
   Automatically reports process completion & runtime if process is successful, or detailed error traceback otherwise

   Can spawn child processes to have multiple nested levels of logging to many partitioned output files for layered processes


   .. py:attribute:: proc_name
      :type:  str
      :value: 'Process'



   .. py:attribute:: id
      :type:  int


   .. py:attribute:: personal_logger
      :type:  logging.Logger


   .. py:attribute:: parent
      :type:  Optional[MultiStreamFileHandler]
      :value: None



   .. py:attribute:: children
      :type:  dict[int, MultiStreamFileHandler]


   .. py:method:: register_logger(logger: logging.Logger) -> None

      Add an individual Logger to the File Stream



   .. py:method:: unregister_logger(logger: logging.Logger) -> None

      Remove an individual Logger from the collection of linked Loggers



   .. py:method:: register_loggers(*loggers: list[logging.Logger]) -> None

      Record a new Logger and add the File handler to it - enables support for multiple Logger streams to a single file



   .. py:method:: unregister_loggers() -> None

      Purge all currently registered Loggers



   .. py:method:: subhandler(*args, **kwargs) -> MultiStreamFileHandler

      Generate a subordinate "child" process which reports back up to the spawning "parent" process once complete



   .. py:method:: propogate_msg(level: int, msg: str) -> None

      Propogate a logged message up through the parent tree



.. py:class:: MultiStreamFileHandlerFlexible(filedir: Optional[pathlib.Path] = None, filename: Optional[Union[str, pathlib.Path]] = None, mode: str = 'a', encoding: Optional[str] = None, delay: bool = False, errors: Optional[str] = None, loggers: Optional[Union[str, logging.Logger, list[logging.Logger]]] = 'ALL', formatter: logging.Formatter = LOG_FORMATTER, proc_name: str = 'Process', write_timestamp: bool = True, timestamp: polymerist.genutils.logutils.timestamps.Timestamp = Timestamp())

   Bases: :py:obj:`MultiStreamFileHandler`


   MSFHandler which is a bit more flexible (and lazy) when it comes to log file naming and creation
   Can either pass a log file path (as normal) or a directory into which to output the logfile
   If the latter is chosen, will create a logfile based on the specified process name, optionally adding a timestamp if desired


.. py:data:: MSFHandler

.. py:data:: MSFHandlerFlex