Renamed specific log flag to specific_log_level (#1768)

* Renamed specific log flag to specific_log_level for clarity

* [build docs]

docs/io/optional/logging_configuration.ipynb

@@ -72,7 +72,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sim = run_tardis(\"tardis_config_logger.yml\")"
+    "sim = run_tardis(\"tardis_config_logger.yml\", show_cplots=False)"
    ]
   },
   {
@@ -96,7 +96,7 @@
    "id": "ac8d5088",
    "metadata": {},
    "source": [
-    "The `run_tardis()` function from the `tardis module` has two functional arguments:`log_level` & `specific`."
+    "The `run_tardis()` function from the `tardis module` has two functional arguments:`log_level` & `specific_log_level`."
    ]
   },
   {
@@ -105,7 +105,7 @@
    "metadata": {},
    "source": [
     "<div class=\"alert alert-info\" role=\"alert\">\n",
-    "    Both <strong>log_level</strong> & <strong>specific</strong> are optional arguments for the <strong>run_tardis()</strong> function, however, if <strong>specific</strong> argument is used then, <strong>log_level</strong> must be set to a particular level.\n",
+    "    Both <strong>log_level</strong> & <strong>specific_log_level</strong> are optional arguments for the <strong>run_tardis()</strong> function, however, if <strong>specific_log_level</strong> argument is used then, <strong>log_level</strong> must be set to a particular level.\n",
     "</div>"
    ]
   },
@@ -134,7 +134,7 @@
    },
    "outputs": [],
    "source": [
-    "sim = run_tardis(\"tardis_config_logger.yml\", log_level=\"Info\")"
+    "sim = run_tardis(\"tardis_config_logger.yml\", log_level=\"Info\", show_cplots=False)"
    ]
   },
   {
@@ -150,15 +150,15 @@
    "id": "25277fe8",
    "metadata": {},
    "source": [
-    "### `specific`"
+    "### `specific_log_level`"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "56a5ef36",
    "metadata": {},
    "source": [
-    "The `specific` argument tells the logger to capture log messages set by the `log_level` parameter. It can only take *Boolean* values for input, which are `True` or `False`. Take for example the following:"
+    "The `specific_log_level` argument tells the logger to capture log messages set by the `log_level` parameter. It can only take *Boolean* values for input, which are `True` or `False`. Take for example the following:"
    ]
   },
   {
@@ -170,23 +170,23 @@
    },
    "outputs": [],
    "source": [
-    "sim = run_tardis(\"tardis_config_logger.yml\", log_level=\"Debug\", specific=True)"
+    "sim = run_tardis(\"tardis_config_logger.yml\", log_level=\"Debug\", specific_log_level=True, show_cplots=False)"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "5c6ff57c",
    "metadata": {},
    "source": [
-    "It can be examined that, when we set `specific` to `True`, the log messages captured were only at the `DEBUG` log level.<br> This allows for logging only specified logging messages for inspection."
+    "It can be examined that, when we set `specific_log_level` to `True`, the log messages captured were only at the `DEBUG` log level.<br> This allows for logging only specified logging messages for inspection."
    ]
   },
   {
    "cell_type": "markdown",
    "id": "5083321b",
    "metadata": {},
    "source": [
-    "The changes in the captured log messages can be seen when we set `specific` to `False`."
+    "The changes in the captured log messages can be seen when we set `specific_log_level` to `False`."
    ]
   },
   {
@@ -198,15 +198,15 @@
    },
    "outputs": [],
    "source": [
-    "sim = run_tardis(\"tardis_config_logger.yml\", log_level=\"Debug\", specific=False)"
+    "sim = run_tardis(\"tardis_config_logger.yml\", log_level=\"Debug\", specific_log_level=False, show_cplots=False)"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "42ddc98b",
    "metadata": {},
    "source": [
-    "It can be examined in this example that when we kept `specific` to `False`, the captured log output includes all log messages from `DEBUG` and higher logging levels, which is the default behavior of the logger."
+    "It can be examined in this example that when we kept `specific_log_level` to `False`, the captured log output includes all log messages from `DEBUG` and higher logging levels, which is the default behavior of the logger."
    ]
   },
   {
@@ -234,7 +234,7 @@
     "...\n",
     "debug:\n",
     "  log_level: \"Info\"\n",
-    "  specific : False\n",
+    "  specific_log_level : False\n",
     "```"
    ]
   },
@@ -243,7 +243,7 @@
    "id": "85ea7ae2",
    "metadata": {},
    "source": [
-    "The `debug` schema includes the `log_level` & `specific` parameters."
+    "The `debug` schema includes the `log_level` & `specific_log_level` parameters."
    ]
   },
   {
@@ -252,7 +252,7 @@
    "metadata": {},
    "source": [
     "<div class=\"alert alert-info\" role=\"alert\">\n",
-    "    The <strong>debug</strong> section of the <strong>YAML</strong> config file is <i>optional</i>. The <strong>log_level</strong> and the <strong>specific</strong> arguments are <i>optional</i> as well. If none of the parameters are defined, then the values of these parameter fall back on the <strong>default values</strong>.\n",
+    "    The <strong>debug</strong> section of the <strong>YAML</strong> config file is <i>optional</i>. The <strong>log_level</strong> and the <strong>specific_log_level</strong> arguments are <i>optional</i> as well. If none of the parameters are defined, then the values of these parameter fall back on the <strong>default values</strong>.\n",
     "</div>"
    ]
   },
@@ -332,31 +332,31 @@
    "outputs": [],
    "source": [
     "# Running the simulation by passing the config dictionary to `run_tardis()` function\n",
-    "sim = run_tardis(config)"
+    "sim = run_tardis(config, show_cplots=False)"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "3fadc651",
    "metadata": {},
    "source": [
-    "### `specific`"
+    "### `specific_log_level`"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "df50d2e1",
    "metadata": {},
    "source": [
-    "The `specific` parameter in the `debug` section of the schema is similar in functionality to the `specific` functional argument. It takes **Boolean** values, i.e., `True` or `False`. It is an optional parameter. "
+    "The `specific_log_level` parameter in the `debug` section of the schema is similar in functionality to the `specific_log_level` functional argument. It takes **Boolean** values, i.e., `True` or `False`. It is an optional parameter. "
    ]
   },
   {
    "cell_type": "markdown",
    "id": "b71946ad",
    "metadata": {},
    "source": [
-    "Let us see an example when we set `specific` to `True` at the `Debug` level."
+    "Let us see an example when we set `specific_log_level` to `True` at the `Debug` level."
    ]
   },
   {
@@ -367,7 +367,7 @@
    "outputs": [],
    "source": [
     "config[\"debug\"][\"log_level\"] = \"Debug\"\n",
-    "config[\"debug\"][\"specific\"] = True"
+    "config[\"debug\"][\"specific_log_level\"] = True"
    ]
   },
   {
@@ -377,15 +377,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sim = run_tardis(config)"
+    "sim = run_tardis(config, show_cplots=False)"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "3e895aec",
    "metadata": {},
    "source": [
-    "Setting `specific` to `False` to check the actual output at the `DEBUG` level for the simulation logs."
+    "Setting `specific_log_level` to `False` to check the actual output at the `DEBUG` level for the simulation logs."
    ]
   },
   {
@@ -395,7 +395,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "config[\"debug\"][\"specific\"] = False"
+    "config[\"debug\"][\"specific_log_level\"] = False"
    ]
   },
   {
@@ -407,7 +407,7 @@
    },
    "outputs": [],
    "source": [
-    "sim = run_tardis(config)"
+    "sim = run_tardis(config,show_cplots=False)"
    ]
   },
   {
@@ -451,7 +451,7 @@
    },
    "outputs": [],
    "source": [
-    "sim = run_tardis(config, log_level = \"Info\")"
+    "sim = run_tardis(config, log_level = \"Info\", show_cplots=False)"
    ]
   },
   {
@@ -472,7 +472,7 @@
    "id": "9ff806bd",
    "metadata": {},
    "source": [
-    "In regards to the `specific` parameter, if any of the config input value is `True`, then `specific` will be set to `True` for the simulation output."
+    "In regards to the `specific_log_level` parameter, if any of the config input value is `True`, then `specific_log_level` will be set to `True` for the simulation output."
    ]
   },
   {
@@ -484,7 +484,7 @@
    },
    "outputs": [],
    "source": [
-    "sim = run_tardis(config, log_level = \"Info\", specific = True)"
+    "sim = run_tardis(config, log_level = \"Info\", specific_log_level = True, show_cplots=False)"
    ]
   }
  ],

docs/io/optional/tardis_config_logger.yml

@@ -57,4 +57,4 @@ spectrum:
   num: 10000
 
 debug:
-  specific: False
+  specific_log_level: False

tardis/base.py

@@ -14,7 +14,7 @@ def run_tardis(
     virtual_packet_logging=False,
     show_cplots=True,
     log_level=None,
-    specific=None,
+    specific_log_level=None,
     **kwargs,
 ):
     """
@@ -45,11 +45,11 @@ def run_tardis(
         Set the level of the TARDIS logger (follows native python logging framework log levels).
         Use this parameter to override the `log_level` specified in the configuration file.
         The default value `None` means that the `log_level` specified in the configuration file will be used.
-    specific : bool, default: None, optional
+    specific_log_level : bool, default: None, optional
         Allows to set specific logging levels, overriding the value in the configuration file.
         If True, only show the log messages from a particular log level, set by `log_level`.
         If False, the logger shows log messages belonging to the level set and all levels above it in severity.
-        The default value None means that the `specific` specified in the configuration file will be used.
+        The default value None means that the `specific_log_level` specified in the configuration file will be used.
     show_cplots : bool, default: True, optional
         Option to enable tardis convergence plots.
     **kwargs : dict, optional
@@ -84,7 +84,7 @@ def run_tardis(
     if not isinstance(show_cplots, bool):
         raise TypeError("Expected bool in show_cplots argument")
 
-    logging_state(log_level, tardis_config, specific)
+    logging_state(log_level, tardis_config, specific_log_level)
 
     if atom_data is not None:
         try:

tardis/io/logger/logger.py

@@ -69,25 +69,27 @@ def filter(self, log_record):
         return log_record.levelno == self.log_level
 
 
-def logging_state(log_level, tardis_config, specific):
+def logging_state(log_level, tardis_config, specific_log_level):
     """
     Function to set the logging configuration for the simulation output
     Called from within run_tardis()
-    Configured via functional arguments passed through run_tardis() - log_level & specific
-    Configured via YAML parameters under `debug` section - logging_level & specific_logging
+    Configured via functional arguments passed through run_tardis() - log_level & specific_log_level
+    Configured via YAML parameters under `debug` section - log_level & specific_log_level
 
     Parameters
     ----------
     log_level: str
         Allows to input the log level for the simulation
         Uses Python logging framework to determine the messages that will be output
-    specific: boolean
+    specific_log_level: boolean
         Allows to set specific logging levels. Logs of the `log_level` level would be output.
     """
 
     if "debug" in tardis_config:
-        specific = (
-            tardis_config["debug"]["specific"] if specific is None else specific
+        specific_log_level = (
+            tardis_config["debug"]["specific_log_level"]
+            if specific_log_level is None
+            else specific_log_level
         )
 
         logging_level = (
@@ -110,8 +112,8 @@ def logging_state(log_level, tardis_config, specific):
             tardis_config["debug"] = {"log_level": DEFAULT_LOG_LEVEL}
             logging_level = tardis_config["debug"]["log_level"]
 
-        if specific:
-            specific = specific
+        if specific_log_level:
+            specific_log_level = specific_log_level
 
     logging_level = logging_level.upper()
     if not logging_level in LOGGING_LEVELS:
@@ -134,7 +136,7 @@ def logging_state(log_level, tardis_config, specific):
             for logger in tardis_loggers:
                 logger.removeFilter(filter)
 
-    if specific:
+    if specific_log_level:
         filter_log = FilterLog(LOGGING_LEVELS[logging_level])
         for logger in tardis_loggers:
             logger.addFilter(filter_log)