.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "generated/tutorials/00_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_00_logging.py>`
        to download the full example code.

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

.. _sphx_glr_generated_tutorials_00_logging.py:


Logging
=======

This package uses the logging module.

.. GENERATED FROM PYTHON SOURCE LINES 9-11

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

.. GENERATED FROM PYTHON SOURCE LINES 11-20

.. code-block:: Python


    import logging
    from pathlib import Path
    from tempfile import TemporaryDirectory

    from template import add_file_handler, set_log_level
    from template.utils.logs import logger









.. GENERATED FROM PYTHON SOURCE LINES 22-27

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 27-33

.. 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.
    [00_logging.<module>] WARNING: Log that will be displayed.




.. GENERATED FROM PYTHON SOURCE LINES 34-35

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

.. GENERATED FROM PYTHON SOURCE LINES 35-39

.. code-block:: Python


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





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

 .. code-block:: none

    [00_logging:<module>:37] DEBUG: Log that will now be displayed. (2024-09-19 08:38:57,178)




.. GENERATED FROM PYTHON SOURCE LINES 40-50

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 `~template.set_log_level`. Additional file handlers can be added with
`~template.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 50-57

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

    [00_logging:<module>:54] DEBUG: Log displayed but not saved to file. (2024-09-19 08:38:57,221)
    [00_logging.<module>] INFO: Log displayed and saved to file.




.. GENERATED FROM PYTHON SOURCE LINES 58-60

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

.. GENERATED FROM PYTHON SOURCE LINES 60-66

.. code-block:: Python


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





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

 .. code-block:: none

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





.. GENERATED FROM PYTHON SOURCE LINES 67-78

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 80-83

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 83-86

.. code-block:: Python


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




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

 .. code-block:: none

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





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

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

**Estimated memory usage:**  84 MB


.. _sphx_glr_download_generated_tutorials_00_logging.py:

.. only:: html

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

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

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

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

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

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

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


.. only:: html

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

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