Added function for getting log category descriotions; deprecated get_…

…categories in favor of get_log_categories

CHANGELOG

@@ -12,11 +12,11 @@
     * Added option to limit the size of the result ("result_max_size"), default set to 2GB.
     * Added method ResultDymolaBinary.get_variables_data. Included some minor refactorization.
       The new method allows for retrieving partial trajectories, and multiple trajectories at once.
-
---- PyFMI-2.14.x ---
-    * "FMUModelBase2.get_categories()" and "FMUModelBase2.set_debug_logging()" now operate on lists of strings instead of bytes.
+    * Deprecated "get_categories" function for "FMUModelBase2" and "CoupledFMUModelBase", use "get_log_categories" instead.
+    * Added function "get_log_category_descriptions" to "FMUModelBase2" and "CoupledFMUModelBase" for retreiving log category descriptions.
+    * "FMUModelBase2.get_log_categories()" and "FMUModelBase2.set_debug_logging()" now operate on lists of strings instead of bytes.
     * Calling "FMUModelBase2.set_debug_logging()" with "logging_on = True" will set the FMU log level to 7 (ALL).
-    * Removed error check that log categories set via "FMUModelBase2.set_debug_logging()" are in "FMUModelBase2.get_categories()".
+    * Removed error check that log categories set via "FMUModelBase2.set_debug_logging()" are exposed log categories.
 
 --- PyFMI-2.14.0 ---
     * Updated the error message displayed when loading FMUs with needsExecutionTool set to True.

src/pyfmi/fmi.pyx

@@ -30,6 +30,7 @@ import os
 import logging
 import fnmatch
 import re
+import warnings
 from collections import OrderedDict
 cimport cython
 from io import UnsupportedOperation
@@ -4980,7 +4981,7 @@ cdef class FMUModelBase2(ModelBase):
         for the specified categories, after checking they are valid.
         TODO: Do we want it that way?
         Automatically invokes .set_log_level() based on logging_on truth value:
-            - logging_on is True:  .set_log_level(7) -ALL
+            - logging_on is True:  .set_log_level(7) - ALL
             - logging_on is False: .set_log_level(0) - NOTHING
 
         Parameters::
@@ -4989,7 +4990,7 @@ cdef class FMUModelBase2(ModelBase):
                 Boolean value.
 
             categories --
-                List of categories to log, call get_categories() for list of categories.
+                List of categories to log, call get_log_categories() for list of categories.
                 Default: [] (all categories)
 
         Calls the low-level FMI function: fmi2SetDebugLogging
@@ -5023,9 +5024,10 @@ cdef class FMUModelBase2(ModelBase):
         if status != 0:
             raise FMUException('Failed to set the debugging option.')
 
-    def get_categories(self):
+    def get_log_categories(self):
         """
-        Method used to retrieve the logging categories.
+        Method used to retrieve the logging categories. 
+        Use 'get_log_category_descriptions' to get the corresponding descriptions.
 
         Returns::
 
@@ -5039,6 +5041,35 @@ cdef class FMUModelBase2(ModelBase):
 
         return categories
 
+    def get_categories(self):
+        """
+        [DEPRECATED] Method used to retrieve the logging categories.
+        Use 'get_log_categories' instead
+
+        Returns::
+
+            A list with the categories available for logging.
+        """
+        warnings.warn("'get_categories' is deprecated and will be replaced by 'get_log_categories' soon.", DeprecationWarning)
+        return self.get_log_categories()
+
+    def get_log_category_descriptions(self):
+        """
+        Method used to retrieve the logging category descriptions.
+        Use 'get_log_categories' to retreive the corresponding categories.
+
+        Returns::
+
+            A list with the category descriptions available for logging.
+        """
+        cdef FMIL.size_t i, nbr_categories = FMIL.fmi2_import_get_log_categories_num(self._fmu)
+        cdef list descriptions = []
+
+        for i in range(nbr_categories):
+            descriptions.append(str(FMIL.fmi2_import_get_log_category_description(self._fmu, i).decode()))
+
+        return descriptions
+
     def get_variable_nominal(self, variable_name=None, valueref=None, _override_erroneous_nominal=True):
         """
         Returns the nominal value from a real variable determined by

src/pyfmi/fmi_coupled.pyx

@@ -18,6 +18,7 @@
 # distutils: define_macros=NPY_NO_DEPRECATED_API=NPY_1_7_API_VERSION
 
 import time
+import warnings
 import numpy as np
 cimport numpy as np
 
@@ -1777,28 +1778,56 @@ cdef class CoupledFMUModelBase(CoupledModelBase):
                 Boolean value.
 
             categories --
-                List of categories to log, call get_categories() for list of categories.
+                List of categories to log, call get_log_categories() for list of categories.
                 Default: [] (all categories)
 
         Calls the low-level FMI function: fmi2SetDebuggLogging
         """
         for model in self.models:
             model.set_debug_logging(logging_on, categories)
 
-    def get_categories(self):
+    def get_log_categories(self):
         """
         Method used to retrieve the logging categories.
+        Use 'get_log_category_descriptions' to get the corresponding descriptions.
 
         Returns::
         
             A list with the categories available for logging.
         """
         categories = []
         for model in self.models:
-            categories.append(model.get_categories())
+            categories.append(model.get_log_categories())
 
         return categories
 
+    def get_categories(self):
+        """
+        [DEPRECATED] Method used to retrieve the logging categories.
+        Use 'get_log_categories' instead
+
+        Returns::
+        
+            A list with the categories available for logging.
+        """
+        warnings.warn("'get_categories' is deprecated and will be replaced by 'get_log_categories' soon.", DeprecationWarning)
+        return self.get_log_categories()
+
+    def get_log_category_descriptions(self):
+        """
+        Method used to retrieve the logging category descriptions.
+        Use 'get_log_categories' to retreive the corresponding categories.
+
+        Returns::
+
+            A list with the category descriptions available for logging.
+        """
+        descriptions = []
+        for model in self.models:
+            descriptions.append(model.get_log_category_descriptions())
+
+        return descriptions
+
 cdef class CoupledFMUModelME2(CoupledFMUModelBase):
     """
     A class for coupled ME models

src/pyfmi/fmil_import.pxd

@@ -827,6 +827,7 @@ cdef extern from 'fmilib.h':
     char * fmi2_import_get_variable_description(fmi2_import_variable_t *)
     char * fmi2_import_get_model_identifier_CS(fmi2_import_t *)
     char * fmi2_import_get_log_category(fmi2_import_t *, size_t)
+    char * fmi2_import_get_log_category_description(fmi2_import_t *, size_t)
     char * fmi2_import_get_last_error(fmi2_import_t *)
     char * fmi2_import_get_enum_type_item_description(fmi2_import_enumeration_typedef_t *, unsigned int)
     fmi2_value_reference_t fmi2_import_get_variable_vr(fmi2_import_variable_t *)