The ``dynalogging.py`` module
=============================
.. py:module:: ansys.dyna.core.solver.dynalogging
Summary
-------
.. py:currentmodule:: dynalogging
.. tab-set::
.. tab-item:: Classes
.. list-table::
:header-rows: 0
:widths: auto
* - :py:obj:`~ansys.dyna.core.solver.dynalogging.PymapdlCustomAdapter`
- Adapter for keeping the reference to an MAPDL instance name dynamic.
* - :py:obj:`~ansys.dyna.core.solver.dynalogging.PymapdlPercentStyle`
-
* - :py:obj:`~ansys.dyna.core.solver.dynalogging.PymapdlFormatter`
- Provides a customized ``Formatter`` class for overwriting the default format styles.
* - :py:obj:`~ansys.dyna.core.solver.dynalogging.InstanceFilter`
- Ensures that the ``instance_name`` record always exists.
* - :py:obj:`~ansys.dyna.core.solver.dynalogging.Logger`
- Provides the logger used for each PyDyna ``pre`` 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 file 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:
PymapdlCustomAdapter
PymapdlPercentStyle
PymapdlFormatter
InstanceFilter
Logger
Description
-----------
Logging module supplying a general framework for logging in the PyDYNA
``pre`` service.
This module is built upon the `Python logging `_
module. It is not intended to replace this Python module but rather to provide a way
for it and the PyDyna ``pre`` service to interact.
The loggers used in this PyDyna logging mdoule include the name of the instance,
which is intended to be unique. This name is printed in all the active
outputs and is used to track the different instances of the PyDyNA ``pre``
service.
Global logger
-------------
The global logger, named ``pydyna_global``, is created at
``ansys.dyna.core.__init__``. If you want to use the global logger,
you must call it at the top of your module:
.. code:: python
from ansys.dyna.core.pre import LOG
You can rename the global logger to avoid conflicts with other loggers (if any):
.. code:: python
from ansys.dyna.core.pre import LOG as logger
The default logging level of ``LOG`` is ``ERROR``. To change this to output
lower-level messages, you can use this code:
.. code:: python
LOG.logger.setLevel("DEBUG")
LOG.file_handler.setLevel("DEBUG") # If present.
LOG.stdout_handler.setLevel("DEBUG") # If present.
Alternatively, you can set the logging level of ``LOG`` to ``DEBUG``
with one line of code::
.. code:: python
LOG.setLevel("DEBUG")
Using the preceding line ensures that all the handlers are set to the input log level.
By default, this logger does not log to a file. If you want to log to a file,
you can add a file handler:
.. code:: python
import os
file_path = os.path.join(os.getcwd(), "pydyna.log")
LOG.log_to_file(file_path)
The preceding code sets the logger to also redirect to a file. If you want
to change the characteristics of the global logger from the beginning
of the execution, you must edit the ``__init__`` file in the
``ansys.dyna.core.pre`` directory.
To log using this logger, call the desired method as a normal logger.
Instance loggers
----------------
Every time an instance of the :class:`Mapdl `
class is created, a logger is created and stored in two places:
* ``_MapdlCore._log``: For backward compatibility.
* ``LOG._instances``: This field is a dictionary where the key is the name
of the created logger.
Instance loggers inheritate the ``pydyna_global`` output handlers and
logging level unless otherwise specified. Instance loggers work in a
similar way to the global logger. You can use the
:func:`log_to_file() ` method to add
a file handler or the :func:`logger.Logging.setLevel` method to change
the log level.
Other loggers
~~~~~~~~~~~~~
You can create your own loggers using the Python ``logging`` module as
you would do in any other script. No conflicts between these loggers exist.
..
!! 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`
Logger to add the file handler to.
**filename** : :class:`python:str`, :obj:`optional`
Name of the output file. The default is ``FILE_NAME``.
**level** : :class:`python:str`, :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 file handler to the logger.
:Parameters:
**logger** : :obj:`logging.Logger` or :obj:`logging.Logger`
Logger to add the file handler to.
**level** : :class:`python:str`, :obj:`optional`
Level of logging. The default is ``LOG_LEVEL``, in which
case ``""DEBUG" is used``.
**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:data:: LOG_LEVEL
:value: 10
.. py:data:: FILE_NAME
:value: 'pydyna.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