.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "generated/tutorials/99_logging.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_generated_tutorials_99_logging.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_generated_tutorials_99_logging.py:


Logging
=======

This package uses the logging module.

.. GENERATED FROM PYTHON SOURCE LINES 9-10

The logger and its utilities can be imported from the ``bsl`` package namespace.

.. GENERATED FROM PYTHON SOURCE LINES 10-18

.. code-block:: Python


    import logging
    from pathlib import Path
    from tempfile import TemporaryDirectory

    from bsl import add_file_handler, logger, set_log_level









.. GENERATED FROM PYTHON SOURCE LINES 20-25

The logger can be used to send logs at different levels: ``DEBUG``, ``INFO``,
``WARNING``, ``ERROR`` and ``CRITICAL``. Each of this level is equal to an integer
value. If the logger level is at least equal to the emitted report level, the log is
displayed. Else, it is omitted. By default, the logger is set to the ``WARNING``
level.

.. GENERATED FROM PYTHON SOURCE LINES 25-31

.. code-block:: Python


    print(f"The level 'INFO' corresponds to the value {logging.INFO}.")
    print(f"The level 'ERROR' corresponds to the value {logging.ERROR}.")
    logger.debug("Log that will not be displayed.")
    logger.warning("Log that will be displayed.")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    The level 'INFO' corresponds to the value 20.
    The level 'ERROR' corresponds to the value 40.
    [99_logging.<module>] WARNING: Log that will be displayed.




.. GENERATED FROM PYTHON SOURCE LINES 32-33

The function `~bsl.set_log_level` can be used to edit the level of the logger.

.. GENERATED FROM PYTHON SOURCE LINES 33-37

.. code-block:: Python


    set_log_level("DEBUG")
    logger.debug("Log that will now be displayed.")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    [99_logging:<module>:35] DEBUG: Log that will now be displayed. (2024-09-11 13:34:08,012)




.. GENERATED FROM PYTHON SOURCE LINES 38-47

By default, the logger has one `~logging.StreamHandler` which outputs to
``sys.stdout``. The level of both the logger and of this first handler can be changed
with `~bsl.set_log_level`. Additional file handlers can be added with
`~bsl.add_file_handler`. Each handler can be set to a different level than the logger.

.. note::

    For the purpose of this example, a temporary file is used. Logs can be saved to
    any text file, e.g. a ``.txt`` or ``.log`` file.

.. GENERATED FROM PYTHON SOURCE LINES 47-54

.. code-block:: Python


    directory = TemporaryDirectory()
    file = Path(directory.name) / "mylogs.log"
    add_file_handler(file, verbose="INFO")  # different level than the logger
    logger.debug("Log displayed but not saved to file.")
    logger.info("Log displayed and saved to file.")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    [99_logging:<module>:51] DEBUG: Log displayed but not saved to file. (2024-09-11 13:34:08,083)
    [99_logging.<module>] INFO: Log displayed and saved to file.




.. GENERATED FROM PYTHON SOURCE LINES 55-57

Since the file handler we added is set to the ``INFO`` level, it should capture only
the second log.

.. GENERATED FROM PYTHON SOURCE LINES 57-63

.. code-block:: Python


    with open(file, "r") as f:
        lines = f.readlines()
    for line in lines:
        print(line)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    [99_logging.<module>] INFO: Log displayed and saved to file.





.. GENERATED FROM PYTHON SOURCE LINES 64-75

A message level must be equal or above both the logger and the handler level to be
emitted on a specific handler. More information on the
`Python logging documentation <pyLogging_>`_ and on the flowchart below:

.. figure:: ../../_static/logging/flowchart-light.png
    :class: only-light

.. figure:: ../../_static/logging/flowchart-dark.png
    :class: only-dark

.. _pyLogging: https://docs.python.org/3/library/logging.html

.. GENERATED FROM PYTHON SOURCE LINES 77-80

Finally, the handlers are listed in ``logger.handlers``. When an handler is not used
anymore, it can be closed. This step is optional on Unix systems while it might be
mantadory depending on the situation on Windows.

.. GENERATED FROM PYTHON SOURCE LINES 80-83

.. code-block:: Python


    print(logger.handlers)
    logger.handlers[-1].close()




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    [<StreamHandler (NOTSET)>, <FileHandler /tmp/tmpg0ccw1ce/mylogs.log (INFO)>]





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.687 seconds)

**Estimated memory usage:**  204 MB


.. _sphx_glr_download_generated_tutorials_99_logging.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: 99_logging.ipynb <99_logging.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: 99_logging.py <99_logging.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: 99_logging.zip <99_logging.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_