Adding descriptions to two settings (#1733)

armi/bookkeeping/mainInterface.py

@@ -28,6 +28,8 @@
 from armi import runLog
 from armi import utils
 from armi.bookkeeping.db.database3 import Database3
+from armi.settings.fwSettings.globalSettings import CONF_COPY_FILES_FROM
+from armi.settings.fwSettings.globalSettings import CONF_COPY_FILES_TO
 from armi.utils import pathTools
 from armi.utils.customExceptions import InputError
 
@@ -46,9 +48,8 @@ class MainInterface(interfaces.Interface):
 
     Notes
     -----
-    Interacts early so that the database is accessible as soon as possible in the run.
-    The database interfaces interacts near the end of the interface stack, but the main
-    interface interacts first.
+    Interacts early so that the database is accessible as soon as possible in the run. The database
+    interfaces runs near the end of the interface stack, but the main interface interacts first.
     """
 
     name = "main"
@@ -64,10 +65,9 @@ def _activateDB(self):
 
         Notes
         -----
-        This happens here rather than on the database interface, as the database
-        interacts near the end of the stack. Some interactBOL methods may be
-        dependent on having data in the database, such as calls to history tracker
-        during a restart run.
+        This happens here rather than on the database interface, as the database interacts near the
+        end of the stack. Some interactBOL methods may be dependent on having data in the database,
+        such as calls to history tracker during a restart run.
         """
         dbi = self.o.getInterface("database")
         if not dbi.enabled():
@@ -80,30 +80,49 @@ def _activateDB(self):
             # load case before going forward with normal cycle
             runLog.important("MainInterface loading from DB")
 
-            # Load the database from the point just before start cycle and start node
-            # as the run will continue at the begining of start cycle and start node,
-            # and the database contains the values from the run at the end of the
-            # interface stack, which are what the start start cycle and start node
-            # should begin with.
+            # Load the database from the point just before start cycle and start node as the run
+            # will continue at the begining of start cycle and start node, and the database contains
+            # the values from the run at the end of the interface stack, which are what the start
+            # start cycle and start node should begin with.
 
-            # NOTE: this should be the responsibility of the database, but cannot
-            # because the Database is last in the stack and the MainInterface is
-            # first
+            # NOTE: this should be the responsibility of the database, but cannot because the
+            # database is last in the stack and the MainInterface is first
             dbi.prepRestartRun()
             self.r.p.cycle = self.cs["startCycle"]
             self.r.p.timeNode = self.cs["startNode"]
 
     def _moveFiles(self):
-        # check for orificed flow bounds files. These will often be named based on the
-        # case that this one is dependent upon, but not always. For example, testSassys
-        # is dependent on the safety case but requires physics bounds files.  now copy
-        # the files over
+        """
+        At the start of each run, arbitrary lists of user-defined files can be copied around.
+
+        This logic is controlled by the settings ``copyFilesFrom`` & ``copyFilesTo``.
+
+        ``copyFilesFrom`` :
+
+        - List of files to copy (cannot be directories).
+        - Can be of length zero (that just means no files will be copied).
+        - The file names listed can use the ``*`` glob syntax, to reference multiple files.
+
+
+        ``copyFilesTo`` :
+
+        - List of directories to copy the files into.
+        - Can be of length zero; all files will be copied to the local dir.
+        - Can be of length one; all files will be copied to that dir.
+        - The only other valid length for this list _must_ be the same length as the "from" list.
+
+        Notes
+        -----
+        If a provided "from" file is missing, this method will silently pass over that. It will only
+        check if the length of the "from" and "to" lists are valid in the end.
+        """
+        # handle a lot of asterisks and missing files
         copyFilesFrom = [
             filePath
-            for possiblePat in self.cs["copyFilesFrom"]
-            for filePath in glob.glob(possiblePat)
+            for possiblePath in self.cs[CONF_COPY_FILES_FROM]
+            for filePath in glob.glob(possiblePath)
         ]
-        copyFilesTo = self.cs["copyFilesTo"]
+        copyFilesTo = self.cs[CONF_COPY_FILES_TO]
 
         if len(copyFilesTo) in (len(copyFilesFrom), 0, 1):
             # if any files to copy, then use the first as the default, i.e. len() == 1,
@@ -112,15 +131,17 @@ def _moveFiles(self):
             for filename, dest in itertools.zip_longest(
                 copyFilesFrom, copyFilesTo, fillvalue=default
             ):
-                pathTools.copyOrWarn("copyFilesFrom", filename, dest)
+                pathTools.copyOrWarn(CONF_COPY_FILES_FROM, filename, dest)
         else:
             runLog.error(
-                "cs['copyFilesTo'] must either be length 1, 0, or have the same number of entries as "
-                "cs['copyFilesFrom']. Actual values:\n"
-                "    copyFilesTo   : {}\n"
-                "    copyFilesFrom : {}".format(copyFilesTo, copyFilesFrom)
+                f"cs['{CONF_COPY_FILES_TO}'] must either be length 0, 1, or have the same number "
+                f"of entries as cs['{CONF_COPY_FILES_FROM}']. Actual values:\n"
+                f"    {CONF_COPY_FILES_TO}   : {copyFilesTo}\n"
+                f"    {CONF_COPY_FILES_FROM} : {copyFilesFrom}"
+            )
+            raise InputError(
+                f"Failed to process {CONF_COPY_FILES_FROM}/{CONF_COPY_FILES_TO}"
             )
-            raise InputError("Failed to process copyFilesTo/copyFilesFrom")
 
     def interactBOC(self, cycle=None):
         """Typically the first interface to interact beginning of cycle."""

armi/settings/fwSettings/globalSettings.py

@@ -26,8 +26,8 @@
 
 from armi import context
 from armi.settings import setting
-from armi.utils.mathematics import isMonotonic
 from armi.settings.fwSettings import tightCouplingSettings
+from armi.utils.mathematics import isMonotonic
 
 
 # Framework settings
@@ -221,8 +221,9 @@ def defineSettings() -> List[setting.Setting]:
             default=True,
             label="Input Height Considered Hot",
             description=(
-                "This is a flag to determine if block heights, as provided in blueprints, are at hot dimensions. "
-                "If false, block heights are at cold/as-built dimensions and will be thermally expanded as appropriate."
+                "This is a flag to determine if block heights, as provided in blueprints, are at "
+                "hot dimensions. If false, block heights are at cold/as-built dimensions and will "
+                "be thermally expanded as appropriate."
             ),
         ),
         setting.Setting(
@@ -236,8 +237,7 @@ def defineSettings() -> List[setting.Setting]:
             CONF_TRACE,
             default=False,
             label="Use the Python Tracer",
-            description="Activate Python trace module to print out each line as it's "
-            "executed",
+            description="Activate Python trace module to print out each line as it's executed",
             isEnvironment=True,
         ),
         setting.Setting(
@@ -305,8 +305,7 @@ def defineSettings() -> List[setting.Setting]:
             default=1.0,
             label="Plant Availability Factor",
             description="Availability factor of the plant. This is the fraction of the "
-            "time that the plant is operating. If variable, use `availabilityFactors` "
-            "setting.",
+            "time that the plant is operating. If variable, use `availabilityFactors` setting.",
             oldNames=[
                 ("capacityFactor", None),
             ],
@@ -441,10 +440,18 @@ def defineSettings() -> List[setting.Setting]:
             description="A comment describing this case",
         ),
         setting.Setting(
-            CONF_COPY_FILES_FROM, default=[], label="None", description="None"
+            CONF_COPY_FILES_FROM,
+            default=[],
+            label="Copy These Files",
+            description="A list of files that need to be copied at the start of a run.",
         ),
         setting.Setting(
-            CONF_COPY_FILES_TO, default=[], label="None", description="None"
+            CONF_COPY_FILES_TO,
+            default=[],
+            label="Copy to These Directories",
+            description="A list of directories to copy provided files into at the start of a run."
+            "This list can be of length zero (copy to working dir), 1 (copy all files to the same "
+            f"place), or it must be the same length as {CONF_COPY_FILES_FROM}",
         ),
         setting.Setting(
             CONF_DEBUG, default=False, label="Python Debug Mode", description="None"
@@ -453,8 +460,7 @@ def defineSettings() -> List[setting.Setting]:
             CONF_DEBUG_MEM,
             default=False,
             label="Debug Memory",
-            description="Turn on memory debugging options to help find problems with "
-            "the code",
+            description="Turn on memory debugging options to help find problems with the code",
         ),
         setting.Setting(
             CONF_DEBUG_MEM_SIZE,
@@ -489,8 +495,7 @@ def defineSettings() -> List[setting.Setting]:
             label="Detailed Assems - ID",
             description="Assembly numbers(IDs) for assemblies that will have "
             "'detailed' treatment. This option will track assemblies that not in the "
-            "core at BOL. Note: This option is interpreted differently by different "
-            "modules.",
+            "core at BOL. Note: This option is interpreted differently by different modules.",
             schema=vol.Schema([int]),
         ),
         setting.Setting(

armi/settings/setting.py

@@ -115,6 +115,11 @@ def __init__(
         """
         self.name = name
         self.description = description or name
+        if not description or description in ("None", "none"):
+            runLog.warning(
+                f"DeprecationWarning: Setting {name} defined without description.",
+                single=True,
+            )
         self.label = label or name
         self.options = options
         self.enforcedOptions = enforcedOptions