Logger implementation and tests

.github/workflows/ci_cd.yml

@@ -172,6 +172,8 @@ jobs:
           ANSYSCL232_DIR: /install/ansys_inc/v232/licensingclient
           ANSYSLMD_LICENSE_FILE: 1055@${{ secrets.LICENSE_SERVER }}
           ANSYS_WORKBENCH_LOGGING_CONSOLE: 0
+          ANSYS_WORKBENCH_LOGGING: 0
+          ANSYS_WORKBENCH_LOGGING_FILTER_LEVEL: 2
           NUM_CORES: 1
         run: |
           /install/ansys_inc/v232/aisol/.workbench_lite pytest -m embedding > pytest_output.txt || true

doc/source/examples/pymechanical_examples_repo/index.rst

@@ -1,19 +1,19 @@
 .. _ref_pymechanical_examples_repository:
 
-PyMechanical remote sessions examples repository
+PyMechanical remote session examples repository
 ================================================
 
-Remote sessions examples are hosted in the `PyMechanical Examples repository <pymechanical_remote_ex_repo_>`_.
+Remote session examples are hosted in the `PyMechanical Examples repository <pymechanical_remote_ex_repo_>`_.
 
 The documentation for these examples can be found in the
 `PyMechanical Examples documentation <pymechanical_remote_ex_doc_>`_.
 
 .. === REMOTE SESSIONS EXAMPLES ===
 
-Remote Sessions examples
+Remote session examples
 ------------------------
 
-Remote sessions examples demonstrate the basic simulation  capabilities of Mechanical using remote sessions.
+Remote session examples demonstrate the basic simulation  capabilities of Mechanical using remote sessions.
 
 The documentation to these examples can be found in the
 `Remote sessions examples <pymechanical_remote_ex_all_>`_ section.

doc/source/user_guide_embedding/index.rst

@@ -17,6 +17,7 @@ an instance of Mechanical in Python.
 
    configuration
    globals
+   logging
 
 
 Overview
@@ -50,6 +51,11 @@ By default, an instance of the :class:`Application <ansys.mechanical.core.embedd
 is configured in the same way as Mechanical. To customize an instance, see
 :ref:`ref_embedding_user_guide_configuration`.
 
+Diagnosing problems with embedding
+----------------------------------
+In some cases, debugging why the embedded Mechanical instance is not working requires additional logging.
+See the :ref:`ref_embedding_user_guide_logging` for instructions on how to configure logging.
+
 Running PyMechanical embedding scripts inside Mechanical with IronPython
 ------------------------------------------------------------------------
 If your PyMechanical embedding script does not use any other third-party Python package, such as `NumPy`,

doc/source/user_guide_embedding/logging.rst

@@ -0,0 +1,31 @@
+.. _ref_embedding_user_guide_logging:
+
+*******
+Logging
+*******
+
+Mechanical has a logging system that is useful when debugging issues. Normally, it is
+enabled by setting environment variables before starting Mechanical. With PyMechanical,
+it is possible to configure logging at any time, whether it is before or after creating
+the embedded Application, using the same Python API.
+
+Use the :class:`Configuration <ansys.mechanical.core.embedding.logger.Configuration>` to
+configure logging to the stdout for all warning messages and above(that is error and fatal).
+For example:
+
+.. code:: python
+
+    import ansys.mechanical.core as mech
+    from ansys.mechanical.core.embedding.logger import Configuration, Logger
+
+    Configuration.configure(level=logging.WARNING, to_stdout=True)
+    _ = mech.App()
+
+After the embedded application has been created, you can write messages to the this same
+log using the :class:`Logger <ansys.mechanical.core.embedding.logger.Logger>` like this:
+
+.. code:: python
+
+    from ansys.mechanical.core.embedding.logger import Logger
+
+    Logger.error("message")

doc/styles/Vocab/ANSYS/accept.txt

@@ -26,6 +26,7 @@ Windows
 windows
 WSL
 wsl
+stdout
 CPython
 namespaces
 Globals

src/ansys/mechanical/core/embedding/__init__.py

@@ -2,4 +2,3 @@
 from .app import App
 from .config import Configuration
 from .imports import global_variables
-from .logging import Logging

src/ansys/mechanical/core/embedding/app.py

@@ -55,8 +55,7 @@ def __init__(self, db_file=None, **kwargs):
         self._app = Ansys.Mechanical.Embedding.Application(db_file)
         runtime.initialize(self._version)
         self._disposed = False
-        if len(INSTANCES) == 0:
-            atexit.register(_dispose_embedded_app, INSTANCES)
+        atexit.register(_dispose_embedded_app, INSTANCES)
         INSTANCES.append(self)
 
     def __repr__(self):

src/ansys/mechanical/core/embedding/initializer.py

@@ -74,11 +74,12 @@ def initialize(version=None):
     if INITIALIZED_VERSION != None:
         assert INITIALIZED_VERSION == version
         return
-    INITIALIZED_VERSION = version
 
     if version == None:
         version = _get_default_version()
 
+    INITIALIZED_VERSION = version
+
     __disable_sec()
 
     # need to add system path in order to import the assembly with the resolver

src/ansys/mechanical/core/embedding/logger/__init__.py

@@ -0,0 +1,193 @@
+"""Embedding logger.
+
+Module to interact with the built-in logging system of Mechanical.
+
+Usage
+-----
+
+Configuring logger
+~~~~~~~~~~~~~~~~~~
+
+Configuring the logger can be done using the Configuration class, for instance:
+
+.. code:: python
+  import ansys.mechanical.core as mech
+  from ansys.mechanical.core.embedding.logger import Configuration, Logger
+
+  Configuration.configure(level=logging.INFO, to_stdout=True, base_directory=None)
+  app = mech.App(version=241)
+
+Then, the Logger class can be used to write messages to the log, for instance:
+
+.. code:: python
+
+   Logger.error("message")
+
+
+"""
+
+import logging
+import os
+import typing
+
+from ansys.mechanical.core.embedding import initializer
+from ansys.mechanical.core.embedding.logger import environ, linux_api, sinks, windows_api
+
+LOGGING_SINKS: typing.Set[int] = set()
+LOGGING_CONTEXT: str = "PYMECHANICAL"
+
+
+def _get_backend() -> (
+    typing.Union[windows_api.APIBackend, linux_api.APIBackend, environ.EnvironBackend]
+):
+    """Get the appropriate logger backend.
+
+    Before embedding is initialized, logging is configured via environment variables
+    After embedding is initialized, logging is configured by making API calls into the
+    mechanical logging system.
+
+    However, the API is mostly the same in both cases, though some methods only work
+    in one of the two backends.
+
+    Setting the base directory only works before initializing
+    Actually logging a message or flushing the log only works after initializing
+    """
+    # TODO - use abc instead of a union type?
+    embedding_initialized = initializer.INITIALIZED_VERSION != None
+    if not embedding_initialized:
+        return environ.EnvironBackend()
+    if os.name == "nt":
+        return windows_api.APIBackend()
+    return linux_api.APIBackend()
+
+
+class Configuration:
+    """Logger configuration for Mechanical embedding."""
+
+    @classmethod
+    def configure(cls, level=logging.WARNING, directory=None, base_directory=None, to_stdout=True):
+        """Configure the logger for PyMechanical embedding.
+
+        Parameters
+        ----------
+        level : int, optional
+            Level of logging that is defined in the ``logging`` package. The default is 'DEBUG'.
+            Options are ``"DEBUG"``, ``"INFO"``, ``"WARNING"``, and ``"ERROR"``.
+        directory : str, optional
+            Directory to write log file to. The default is ``None``, but by default the logs
+            will appear somewhere in the system temp folder.
+        base_directory: str, optional
+            Base directory to write log files to. This is only possible to set before the
+            Mechanical application is initialized.
+        to_stdout : bool, optional
+            Whether to write log messages to the standard output, which is the
+            command line. The default is ``True``.
+        """
+        # Setup the global log configuration.
+        cls.set_log_directory(directory)
+        cls.set_log_base_directory(base_directory)
+
+        # Setup the sink-specific log configuration, store to global state.
+        cls._store_stdout_sink_enabled(to_stdout)
+        file_sink_enabled = directory != None or base_directory != None
+        cls._store_file_sink_enabled(file_sink_enabled)
+
+        # Commit the sink-specific log configuration global state to the backend.
+        cls._commit_enabled_configuration()
+        cls.set_log_level(level)
+
+    @classmethod
+    def set_log_to_stdout(cls, value: bool) -> None:
+        """Configure logging to write to the stdout."""
+        cls._store_stdout_sink_enabled(value)
+        cls._commit_enabled_configuration()
+
+    @classmethod
+    def set_log_to_file(cls, value: bool) -> None:
+        """Configure logging to write to a file."""
+        cls._store_file_sink_enabled(value)
+        cls._commit_enabled_configuration()
+
+    @classmethod
+    def set_log_level(cls, level: int) -> None:
+        """Set the log level for all configured sinks."""
+        if len(LOGGING_SINKS) == 0:
+            raise Exception("No logging backend configured!")
+        cls._commit_level_configuration(level)
+
+    @classmethod
+    def set_log_directory(cls, value: str) -> None:
+        """Configure logging to write to a directory."""
+        if value == None:
+            return
+        _get_backend().set_directory(value)
+
+    @classmethod
+    def set_log_base_directory(cls, value: str) -> None:
+        """Configure logging to write in a time-stamped subfolder in the given directory."""
+        if value == None:
+            return
+        _get_backend().set_base_directory(value)
+
+    @classmethod
+    def _commit_level_configuration(cls, level: int) -> None:
+        for sink in LOGGING_SINKS:
+            _get_backend().set_log_level(level, sink)
+
+    @classmethod
+    def _commit_enabled_configuration(cls) -> None:
+        for sink in LOGGING_SINKS:
+            _get_backend().enable(sink)
+
+    @classmethod
+    def _store_stdout_sink_enabled(cls, value: bool) -> None:
+        if value:
+            LOGGING_SINKS.add(sinks.StandardSinks.CONSOLE)
+        else:
+            LOGGING_SINKS.discard(sinks.StandardSinks.CONSOLE)
+
+    @classmethod
+    def _store_file_sink_enabled(cls, value: bool) -> None:
+        if value:
+            LOGGING_SINKS.add(sinks.StandardSinks.STANDARD_LOG_FILE)
+        else:
+            LOGGING_SINKS.discard(sinks.StandardSinks.STANDARD_LOG_FILE)
+
+
+class Logger:
+    """Logger class for embedding."""
+
+    @classmethod
+    def flush(cls):
+        """Flush the log."""
+        _get_backend().flush()
+
+    @classmethod
+    def can_log_message(cls, level: int) -> bool:
+        """Get whether a message at the given level can be logged."""
+        return _get_backend().can_log_message(level)
+
+    @classmethod
+    def debug(cls, msg: str):
+        """Write a debug message to the log."""
+        _get_backend().log_message(logging.DEBUG, LOGGING_CONTEXT, msg)
+
+    @classmethod
+    def error(cls, msg: str):
+        """Write a error message to the log."""
+        _get_backend().log_message(logging.ERROR, LOGGING_CONTEXT, msg)
+
+    @classmethod
+    def info(cls, msg: str):
+        """Write a info message to the log."""
+        _get_backend().log_message(logging.INFO, LOGGING_CONTEXT, msg)
+
+    @classmethod
+    def warning(cls, msg: str):
+        """Write a warning message to the log."""
+        _get_backend().log_message(logging.WARNING, LOGGING_CONTEXT, msg)
+
+    @classmethod
+    def fatal(cls, msg: str):
+        """Write a fatal message to the log."""
+        _get_backend().log_message(logging.FATAL, LOGGING_CONTEXT, msg)