edisgo.tools.logger
===================

.. py:module:: edisgo.tools.logger


Functions
---------

.. autoapisummary::

   edisgo.tools.logger.setup_logger


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

.. py:function:: setup_logger(file_name=None, log_dir=None, loggers=None, stream_output=sys.stdout, debug_message=False, reset_loggers=False)

   Setup different loggers with individual logging levels and where to write output.

   The following table from python 'Logging Howto' shows you when which logging level
   is used.

   .. tabularcolumns:: |l|L|

   +--------------+---------------------------------------------+
   | Level        | When it's used                              |
   +==============+=============================================+
   | ``DEBUG``    | Detailed information, typically of interest |
   |              | only when diagnosing problems.              |
   +--------------+---------------------------------------------+
   | ``INFO``     | Confirmation that things are working as     |
   |              | expected.                                   |
   +--------------+---------------------------------------------+
   | ``WARNING``  | An indication that something unexpected     |
   |              | happened, or indicative of some problem in  |
   |              | the near future (e.g. 'disk space low').    |
   |              | The software is still working as expected.  |
   +--------------+---------------------------------------------+
   | ``ERROR``    | Due to a more serious problem, the software |
   |              | has not been able to perform some function. |
   +--------------+---------------------------------------------+
   | ``CRITICAL`` | A serious error, indicating that the program|
   |              | itself may be unable to continue running.   |
   +--------------+---------------------------------------------+

   :param file_name: Specifies file name of file logging information is written to. Possible options
                     are:

                     * None (default)
                         Saves log file with standard name `%Y_%m_%d-%H:%M:%S_edisgo.log`.
                     * str
                         Saves log file with the specified file name.
   :type file_name: str or None
   :param log_dir: Specifies directory log file is saved to. Possible options are:

                   * None (default)
                       Saves log file in current working directory.
                   * "default"
                       Saves log file into directory configured in the configs.
                   * str
                       Saves log file into the specified directory.
   :type log_dir: str or None
   :param loggers:
                   * None
                       Configuration as shown in the example below is used. Configures root logger
                       with file and stream level warning and the edisgo logger with file and
                       stream level debug.
                   * list(dict)
                       List of dicts with the logger configuration. Each dictionary must contain
                       the following keys and corresponding values:

                       * 'name'
                           Specifies name of the logger as string, e.g. 'root' or 'edisgo'.
                       * 'file_level'
                           Specifies file logging level. Possible options are:

                           * "debug"
                               Logs logging messages with logging level logging.DEBUG and above.
                           * "info"
                               Logs logging messages with logging level logging.INFO and above.
                           * "warning"
                               Logs logging messages with logging level logging.WARNING and above.
                           * "error"
                               Logs logging messages with logging level logging.ERROR and above.
                           * "critical"
                               Logs logging messages with logging level logging.CRITICAL.
                           * None
                               No logging messages are logged.
                       * 'stream_level'
                           Specifies stream logging level. Possible options are the same as for
                           `file_level`.
   :type loggers: None or list(dict)
   :param stream_output: Default sys.stdout is used. sys.stderr is also possible.
   :type stream_output: stream
   :param debug_message: If True the handlers of every configured logger is printed.
   :type debug_message: bool
   :param reset_loggers: If True the handlers of all loggers are cleared before configuring the loggers.
                         Only use if you know what you do, it could be dangerous.
   :type reset_loggers: bool

   .. rubric:: Examples

   >>> setup_logger(
   >>>     loggers=[
   >>>         {"name": "root", "file_level": "warning", "stream_level": "warning"},
   >>>         {"name": "edisgo", "file_level": "info", "stream_level": "info"}
   >>>     ]
   >>> )