Logging
=======

Since version 0.18.0 :program:`rebase-helper` uses standard module-level loggers.

There are also 3 loggers with a special purpose:

=============================== =============================================================================
Logger name                     Purpose
=============================== =============================================================================
:samp:`rebasehelper.traceback`  traceback generated by unhandled exceptions
:samp:`rebasehelper.summary`    messages forming the rebase summary
:samp:`rebasehelper.report`     messages forming the textual rebase report (used by :samp:`text` output tool)
=============================== =============================================================================


:program:`rebase-helper` uses :class:`rebasehelper.logger.CustomLogger` logger class which provides
extra logging levels.

:class:`rebasehelper.logger.LoggerHelper` class provides 3 utility methods to manage default handlers:

* :meth:`rebasehelper.logger.LoggerHelper.create_stream_handlers` sets up the default console handlers
  for :samp:`rebasehelper` and :samp:`rebasehelper.summary` loggers.

* :meth:`rebasehelper.logger.LoggerHelper.create_file_handlers` sets up the default file handlers
  for :samp:`rebasehelper` logger, with INFO, VERBOSE and DEBUG levels.
  The respective log files are located in :file:`rebase-helper-results/logs/`.

* :meth:`rebasehelper.logger.LoggerHelper.remove_file_handlers` removes specified file handlers
  from :samp:`rebasehelper` logger.


Examples
--------

.. code-block:: python

    # use a single module and get logs from it

    import logging

    from rebasehelper.specfile import SpecFile

    logger = logging.getLogger('rebasehelper.specfile')
    logger.addHandler(logging.StreamHandler())

    spec = SpecFile('test.spec')
    spec.set_release_number(2)

.. code-block:: python

    # run a complete rebase with default log handlers

    from rebasehelper.logger import LoggerHelper
    from rebasehelper.config import Config
    from rebasehelper.cli import CLI
    from rebasehelper.application import Application

    LoggerHelper.create_stream_handlers()
    config = Config()
    cli = CLI()
    config.merge(cli)
    exec_dir, res_dir = Application.setup(config)
    # default file handlers are automatically created and removed by Application instance,
    # unless disabled by passing create_logs=False
    app = Application(config, exec_dir, res_dir)
    app.run()