ansys.dyna.core.pre.dynalogging =============================== .. py:module:: ansys.dyna.core.pre.dynalogging .. autoapi-nested-parse:: 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 !! Attributes ---------- .. autoapisummary:: ansys.dyna.core.pre.dynalogging.LOG_LEVEL ansys.dyna.core.pre.dynalogging.FILE_NAME ansys.dyna.core.pre.dynalogging.DEBUG ansys.dyna.core.pre.dynalogging.INFO ansys.dyna.core.pre.dynalogging.WARN ansys.dyna.core.pre.dynalogging.ERROR ansys.dyna.core.pre.dynalogging.CRITICAL ansys.dyna.core.pre.dynalogging.STDOUT_MSG_FORMAT ansys.dyna.core.pre.dynalogging.FILE_MSG_FORMAT ansys.dyna.core.pre.dynalogging.DEFAULT_STDOUT_HEADER ansys.dyna.core.pre.dynalogging.DEFAULT_FILE_HEADER ansys.dyna.core.pre.dynalogging.NEW_SESSION_HEADER ansys.dyna.core.pre.dynalogging.string_to_loglevel ansys.dyna.core.pre.dynalogging.LOG Classes ------- .. autoapisummary:: ansys.dyna.core.pre.dynalogging.PymapdlCustomAdapter ansys.dyna.core.pre.dynalogging.PymapdlPercentStyle ansys.dyna.core.pre.dynalogging.PymapdlFormatter ansys.dyna.core.pre.dynalogging.InstanceFilter ansys.dyna.core.pre.dynalogging.Logger Functions --------- .. autoapisummary:: ansys.dyna.core.pre.dynalogging.addfile_handler ansys.dyna.core.pre.dynalogging.add_stdout_handler Module Contents --------------- .. py:data:: LOG_LEVEL .. py:data:: FILE_NAME :value: 'pydyna.log' .. py:data:: DEBUG .. py:data:: INFO .. py:data:: WARN .. py:data:: ERROR .. py:data:: CRITICAL .. py:data:: STDOUT_MSG_FORMAT :value: '%(levelname)s - %(instance_name)s - %(module)s - %(funcName)s - %(message)s' .. py:data:: FILE_MSG_FORMAT .. py:data:: DEFAULT_STDOUT_HEADER :value: Multiline-String .. raw:: html
Show Value .. code-block:: python """ LEVEL - INSTANCE NAME - MODULE - FUNCTION - MESSAGE """ .. raw:: html
.. py:data:: DEFAULT_FILE_HEADER .. py:data:: NEW_SESSION_HEADER .. py:data:: string_to_loglevel .. py:class:: PymapdlCustomAdapter(logger, extra=None) Bases: :py:obj:`logging.LoggerAdapter` Adapter for keeping the reference to an MAPDL instance name dynamic. Using the standard approach, extra parameters must be supplied to the logger to indicate the MAPDL instance for which messages must be logged. With this class, you only have to specify the MAPDL instance that you are referring to once. .. !! processed by numpydoc !! .. py:attribute:: level :value: None .. py:attribute:: file_handler :value: None .. py:attribute:: stdout_handler :value: None .. py:attribute:: logger .. py:attribute:: std_out_handler .. py:method:: process(msg, kwargs) Process the logging message and keyword arguments passed in to a logging call to insert contextual information. You can either manipulate the message itself, the keyword args or both. Return the message and kwargs modified (or not) to suit your needs. Normally, you'll only need to override this one method in a LoggerAdapter subclass for your specific needs. .. !! processed by numpydoc !! .. py:method:: log_to_file(filename=FILE_NAME, level=LOG_LEVEL) Add a file handler to the logger. :Parameters: **filename** : :class:`python:str`, :obj:`optional` Name of the file where logs are recorded. The default is ``FILE_NAME``. **level** : :class:`python:str`, :obj:`optional` Level of logging. The default is ``LOG_LEVEL``, which causes all messages to be recorded. For example, you can set the level of logging to ``DEBUG``. .. !! processed by numpydoc !! .. py:method:: log_to_stdout(level=LOG_LEVEL) Add a standard output handler to the logger. :Parameters: **level** : :class:`python:str`, :obj:`optional` Level of logging record. The default is ``LOG_LEVEL``, which causes all messages to be recorded. For example, you can set the level of logging to ``"DEBUG"``. .. !! processed by numpydoc !! .. py:method:: setLevel(level='DEBUG') Change the log level of the object and the attached handlers. :Parameters: **level** : :class:`python:str`, :obj:`optional` Level of logging record. The default is ``"DEBUG``. .. !! processed by numpydoc !! .. py:class:: PymapdlPercentStyle(fmt, *, defaults=None) Bases: :py:obj:`logging.PercentStyle` .. py:class:: PymapdlFormatter(fmt=STDOUT_MSG_FORMAT, datefmt=None, style='%', validate=True, defaults=None) Bases: :py:obj:`logging.Formatter` Provides a customized ``Formatter`` class for overwriting the default format styles. .. !! processed by numpydoc !! .. py:class:: InstanceFilter(name='') Bases: :py:obj:`logging.Filter` Ensures that the ``instance_name`` record always exists. .. !! processed by numpydoc !! .. py:method:: filter(record) Determine if the specified record is to be logged. Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place. .. !! processed by numpydoc !! .. py:class:: Logger(level=logging.DEBUG, to_file=False, to_stdout=True, filename=FILE_NAME) Provides the logger used for each PyDyna ``pre`` session. This class allows you to add handlers to the logger to output to a file or standard output. :Parameters: **level** : :class:`python:int`, :obj:`optional` Logging level to filter the message severity allowed in the logger. The default is ``logging.DEBUG``. **to_file** : :ref:`bool `, :obj:`optional` Whether to write log messages to a file. The default is ``False``. **to_stdout** : :ref:`bool `, :obj:`optional` Whether to write log messages to the standard output. The default is ``True``. **filename** : :class:`python:str`, :obj:`optional` Name of the file to write log messages to if ``to_file=True``. The default is ``FILE_NAME``. .. rubric:: Examples Demonstrate logger usage from an MAPDL instance mapdl. This logger is automatically created when an MAPDL instance is created. >>> from ansys.mapdl.core import launch_mapdl >>> mapdl = launch_mapdl(loglevel='DEBUG') >>> mapdl._log.info('This is a useful message') INFO - - - - This is LOG debug message. Import the global PYMAPDL logger and add a file output handler. >>> import os >>> from ansys.mapdl.core import LOG >>> file_path = os.path.join(os.getcwd(), 'pymapdl.log') >>> LOG.log_to_file(file_path) .. !! processed by numpydoc !! .. py:attribute:: file_handler :value: None .. py:attribute:: std_out_handler :value: None .. py:attribute:: logger .. py:attribute:: propagate :value: True .. py:attribute:: level .. py:attribute:: debug .. py:attribute:: info .. py:attribute:: warning .. py:attribute:: error .. py:attribute:: critical .. py:attribute:: log .. py:method:: log_to_file(filename=FILE_NAME, level=LOG_LEVEL) Add a file handler to logger. :Parameters: **filename** : :class:`python:str`, :obj:`optional` Name of the file where the logs are recorded. The default is ``FILE_NAME``, in which case they are recorded in the ``'pymapdl.log'`` file. **level** : :class:`python:str`, :obj:`optional` Level of logging. The default is ``LOG_LEVEL``, in which case ``'DEBUG'`` is used. .. rubric:: Examples Write to the ``pymapdl.log`` file in the current working directory. >>> from ansys.mapdl.core import LOG >>> import os >>> file_path = os.path.join(os.getcwd(), 'pymapdl.log') >>> LOG.log_to_file(file_path) .. !! processed by numpydoc !! .. py:method:: log_to_stdout(level=LOG_LEVEL) Add a standard output handler to the logger. :Parameters: **filename** : :class:`python:str`, :obj:`optional` Name of the file where the logs are recorded. The default is ``FILE_NAME``, in which case they are recorded in the ``'pymapdl.log'`` file. **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 ``True``. .. !! processed by numpydoc !! .. py:method:: setLevel(level='DEBUG') Change the log level of the object and the attached handlers. :Parameters: **level** : :class:`python:str`, :obj:`optional` Level of logging. The default is ``'DEBUG'``. .. !! processed by numpydoc !! .. py:method:: add_child_logger(sufix, level=None) Add a child logger to the main logger. This child logger is more general than an instance logger, which is designed to track the state of MAPDL instances. If the logging level is in the arguments, a new logger with a reference to the ``_global`` logger handlers is created instead of a child logger. :Parameters: **sufix** : :class:`python:str` Name of the logger. **level** : :class:`python:str`, :obj:`optional` Level of logging. The default is ``None``. :Returns: :obj:`logging.logger` Logger class. .. !! processed by numpydoc !! .. py:method:: add_instance_logger(name, mapdl_instance, level=None) Create a logger for an MAPDL instance. The MAPDL instance logger is a logger with an adapter that adds contextual information, such as the MAPDL instance name. This logger is returned, and you can use it to log events as a normal logger. It is also stored in the ``_instances`` field. :Parameters: **name** : :class:`python:str` Name for the new logger. **mapdl_instance** : :obj:`ansys.mapdl.core.mapdl._MapdlCore` MAPDL instance object. This should contain the ``name`` attribute. :Returns: :obj:`ansys.mapdl.core.logging.PymapdlCustomAdapter` Logger adapter customized to add MAPDL information to the logs. You can use this class to log events in the same way you use the ``logger`` class. :Raises: :obj:`Exception` You can only input strings as ``name`` to this method. .. !! processed by numpydoc !! .. py:method:: __getitem__(key) .. py:method:: add_handling_uncaught_expections(logger) Redirect the output of an exception to the logger. .. !! processed by numpydoc !! .. 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