The ``logger.py`` module
========================
.. py:module:: ansys.speos.core.logger
Summary
-------
.. py:currentmodule:: logger
.. tab-set::
.. tab-item:: Classes
.. list-table::
:header-rows: 0
:widths: auto
* - :py:obj:`~ansys.speos.core.logger.PySpeosCustomAdapter`
- Keeps the reference to the speos instance name dynamic.
* - :py:obj:`~ansys.speos.core.logger.PySpeosPercentStyle`
- Customized ``PercentStyle`` class for overwriting default format styles.
* - :py:obj:`~ansys.speos.core.logger.PySpeosFormatter`
- Provides the customized ``Formatter`` class for overwriting default format styles.
* - :py:obj:`~ansys.speos.core.logger.InstanceFilter`
- Ensures that the ``instance_name`` record always exists.
* - :py:obj:`~ansys.speos.core.logger.Logger`
- Provides the logger used for each PySpeos session.
.. tab-item:: Functions
.. list-table::
:header-rows: 0
:widths: auto
* - :py:obj:`~addfile_handler`
- Add a file handler to the input.
* - :py:obj:`~add_stdout_handler`
- Add a standout handler to the logger.
.. tab-item:: Attributes
.. list-table::
:header-rows: 0
:widths: auto
* - :py:obj:`~string_to_loglevel`
-
.. tab-item:: Constants
.. list-table::
:header-rows: 0
:widths: auto
* - :py:obj:`~LOG_LEVEL`
-
* - :py:obj:`~FILE_NAME`
-
* - :py:obj:`~DEBUG`
-
* - :py:obj:`~INFO`
-
* - :py:obj:`~WARN`
-
* - :py:obj:`~ERROR`
-
* - :py:obj:`~CRITICAL`
-
* - :py:obj:`~STDOUT_MSG_FORMAT`
-
* - :py:obj:`~FILE_MSG_FORMAT`
-
* - :py:obj:`~DEFAULT_STDOUT_HEADER`
-
* - :py:obj:`~DEFAULT_FILE_HEADER`
-
* - :py:obj:`~NEW_SESSION_HEADER`
-
* - :py:obj:`~LOG`
-
.. toctree::
:titlesonly:
:maxdepth: 1
:hidden:
PySpeosCustomAdapter
PySpeosPercentStyle
PySpeosFormatter
InstanceFilter
Logger
Description
-----------
Logging module.
This module supplies a general framework for logging in PySpeos. This module is
built upon `logging `_ library
and it does not intend to replace it but rather provide a way to interact between
``logging`` and pyspeos.
The loggers used in the module include the name of the instance, which
is intended to be unique. This name is printed in all active
outputs and is used to track the different PySpeos instances.
Usage
-----
Global logger
~~~~~~~~~~~~~
There is a global logger named ``pyspeos_global`` that is created at
``ansys.speos.core.__init__``. If you want to use this global logger,
you must call it at the top of your module:
.. code:: python
from ansys.speos.core import LOG
You can also rename it to avoid conflicts with other loggers (if any):
.. code:: python
from ansys.speos.core import LOG as logger
It should be noticed that the default logging level of ``LOG`` is ``ERROR``.
You can change this and output lower-level messages with:
.. code:: python
LOG.logger.setLevel("DEBUG")
LOG.file_handler.setLevel("DEBUG") # If present.
LOG.stdout_handler.setLevel("DEBUG") # If present.
Alternatively, you can ensure all the handlers are set to the input log
level with:
.. code:: python
LOG.setLevel("DEBUG")
By default, this logger does not log to a file. If you want to do so,
you can add a file handler with:
.. code:: python
import os
file_path = os.path.join(os.getcwd(), "pyspeos.log")
LOG.log_to_file(file_path)
This sets the logger to be redirected also to this file. If you want
to change the characteristics of this global logger from the beginning
of the execution, you must edit the ``__init__`` file in the directory
``ansys.speos.core``.
To log using this logger, call the desired method as a normal logger with:
.. code:: pycon
>>> import logging
>>> from ansys.speos.core.logger import Logger
>>> LOG = Logger(level=logging.DEBUG, to_file=False, to_stdout=True)
>>> LOG.debug("This is LOG debug message.")
DEBUG - - - - This is LOG debug message.
Instance Logger
~~~~~~~~~~~~~~~
Every time an instance of :class:`ansys.speos.core.speos.Speos`
is created, a logger is created and stored in ``LOG._instances``. This field is a
dictionary where the key is the name of the created logger.
These instance loggers inherit the ``pyspeos_global`` output handlers and
logging level unless otherwise specified. The way this logger works is very
similar to the global logger. If you want to add a file handler, you can use
the :func:`log_to_file() ` method. If you want
to change the log level, you can use the :func:`logger.Logging.setLevel` method.
You can use this logger like this:
.. code:: pycon
>>> from ansys.speos.core import SpeosClient
>>> speos = SpeosClient()
>>> speos._log.info("This is a useful message")
INFO - GRPC_127.0.0.1:50056 - <...> - - This is a useful message
Other loggers
~~~~~~~~~~~~~
You can create your own loggers using a Python ``logging`` library as
you would do in any other script. There would be no conflicts between
these loggers.
..
!! processed by numpydoc !!
Module detail
-------------
.. py:function:: addfile_handler(logger, filename=FILE_NAME, level=LOG_LEVEL, write_headers=False)
Add a file handler to the input.
:Parameters:
**logger** : :obj:`logging.Logger` or :obj:`logging.Logger`, :obj:`optional`
Logger to add the file handler to.
**filename** : :class:`python:str`, :obj:`optional`
Name of the output file. The default is ``"pyspeos.log"``.
**level** : :class:`python:int`, :obj:`optional`
Level of logging. The default is ``LOG_LEVEL``.
**write_headers** : :ref:`bool `, :obj:`optional`
Whether to write the headers to the file. The default is ``False``.
:Returns:
:obj:`logger`
Logger or Logger object.
..
!! processed by numpydoc !!
.. py:function:: add_stdout_handler(logger, level=LOG_LEVEL, write_headers=False)
Add a standout handler to the logger.
:Parameters:
**logger** : :obj:`logging.Logger` or :obj:`logging.Logger`
Logger to add the file handler to.
**level** : :obj:`in`, :obj:`optional`
Level of logging. The default is ``10``, in which case the
``logging.DEBUG`` level is used.
**write_headers** : :ref:`bool `, :obj:`optional`
Whether to write headers to the file. The default is ``False``.
:Returns:
:obj:`logger`
Logger or Logger object.
..
!! processed by numpydoc !!
.. py:data:: LOG_LEVEL
:value: 10
.. py:data:: FILE_NAME
:value: 'pyspeos.log'
.. py:data:: DEBUG
:value: 10
.. py:data:: INFO
:value: 20
.. py:data:: WARN
:value: 30
.. py:data:: ERROR
:value: 40
.. py:data:: CRITICAL
:value: 50
.. py:data:: STDOUT_MSG_FORMAT
:value: '%(levelname)s - %(instance_name)s - %(module)s - %(funcName)s - %(message)s'
.. py:data:: FILE_MSG_FORMAT
:value: '%(levelname)s - %(instance_name)s - %(module)s - %(funcName)s - %(message)s'
.. py:data:: DEFAULT_STDOUT_HEADER
:value: Multiline-String
.. raw:: html
Show Value
.. code-block:: python
"""
LEVEL - INSTANCE NAME - MODULE - FUNCTION - MESSAGE
"""
.. raw:: html
Show Value
.. code-block:: python
"""
LEVEL - INSTANCE NAME - MODULE - FUNCTION - MESSAGE
"""
.. raw:: html
Show Value
.. code-block:: python
"""
===============================================================================
NEW SESSION - Uninferable
==============================================================================="""
.. raw:: html