Merge pull request #1191 from esm-tools/provenance_motd

Update motd.yaml

docs/esm_runscripts.rst

@@ -332,6 +332,11 @@ This will enable the `pdb Python debugger <https://docs.python.org/3/library/pdb
 
     general: 
         debug_recipe: True
+
+Configuration Provenance
+------------------------
+
+In addition to the hints summarized in the "Debugging an Experiment" section, you will also find that the ``finished_config.yaml`` found in your ``config`` directory contains end-of-line comments detailing where a particular setting came from. You can use this to better track down what is being set and why, but it is **strongly recommended** that the configuration files found in your ``esm-tools`` source directory should **not** be changed unless you know exactly what you are doing. All of the configuration settings can be overridden from the run configuration, which is the prefered location for user changes. For more information see :ref:`YAML File Hierarchy:How can I know where a parameter is defined?`.
 
 Setting the file movement method for filetypes in the runscript
 ---------------------------------------------------------------

esm_tools/motd/motd.yaml

@@ -0,0 +1 @@
+../../motd/motd.yaml

motd/motd.yaml

@@ -146,6 +146,29 @@ oasis_branchoff6.21.23:
         action: DELAY(1)
         announcement: true
 
+provenance_feature:
+        package: "esm_tools"
+        versions: "<6.35.0"
+        message: "\x1b[1m\x1b[96mCONFIGURATION IS HISTORY!\x1b[0m\n
+
+            A useful \x1b[96mnew feature to show configuration provenance \x1b[0mis now\n
+            ready to be used! To get started, make sure you have at least version 6.35\n
+            and \x1b[96mmake sure to reinstall the package (cd <PATH>/esm_tools; ./install.sh)\n
+            \x1b[0msince new depdency libraries have been added. Once active, you can see\n
+            where each value in your configuration originated in the >> \x1b[96mfinished_config.yaml\x1b[0m\n
+            << files in you experiment config directories\n
+
+            Within the finish_config.yaml you will be able to see the provenance of parameters\n
+            as a comment, in the form:\n\n
+              \x1b[96mmodel\x1b[35m: \x1b[31mfesom \x1b[34m# /home/a/a270152/esm_tools/configs/components/fesom/fesom-2.5.yaml,line:4,col:8\x1b[0m\n
+\x1b[96mbranch\x1b[35m: \x1b[31m'2.5' \x1b[34m# /home/a/a270152/esm_tools/configs/components/fesom/fesom-2.5.yaml,line:27,col:13\x1b[0m\n
+
+            Read more about it in:\n
+            \x1b[34mhttps://esm-tools.readthedocs.io/en/latest/yaml_hierarchy.html#how-can-i-know-where-a-parameter-is-defined\x1b[0m\n
+            "
+        action: DELAY(1)
+        announcement: true
+
 #online_workshops:
 #        package: "esm_tools"
 #        versions: "<7.0.0"

src/esm_motd/esm_motd.py

@@ -126,7 +126,7 @@ def motd_handler(self, mypackage, myversion):
                 print()
                 print(self.message_dict[message]["message"])
                 if mypackage == "esm_tools":
-                    esm_tools_path = esm_tools._get_real_dir_from_pth_file('')
+                    esm_tools_path = esm_tools._get_real_dir_from_pth_file("")
                     print(
                         f"Upgrade ESM-Tools to the version contianing this fix (\x1b[96m{version}\x1b[0m) by:\n"
                         f"\x1b[96m1.\x1b[0m \x1b[35mcd {esm_tools_path}\x1b[0m\n"
@@ -167,16 +167,31 @@ def check_all_esm_packages():
     motd.motd_handler("esm_tools", esm_tools.__version__)
 
 
-if __name__ == "__main__":
+def check_esm_package_with_version_and_local_options(
+    package, myversion="1.0.0", local=False
+):
+    """
+    Method to check the message of the day for a specific package, version and with an
+    option to use a local MOTD file. To be called from the ``esm_tools`` CLI.
+
+    Parameters
+    ----------
+    package : str
+        Name of the package to check the MOTD for.
+    myversion : str
+        Version of the package to check the MOTD for.
+    local : bool
+        Option to use the local MOTD file. The default is ``False``.
+    """
     mypackage = "esm_tools"
-    myversion = "1.0.0"
 
     motd = MessageOfTheDayHandler()
-    # Uncomment the following lines For testing using the local motd.yaml
-    #import os
-    #local_motd = f"{os.path.dirname(__file__)}/../../esm_tools/motd/motd.yaml"
-    #print(local_motd)
-    #with open(local_motd, "r") as motdfile:
-    #    motd.message_dict = yaml.load(motdfile, Loader=yaml.FullLoader)
+    # For testing using the local motd.yaml
+    if local:
+        import os
+
+        local_motd = f"{os.path.dirname(__file__)}/../../esm_tools/motd/motd.yaml"
+        with open(local_motd, "r") as motdfile:
+            motd.message_dict = yaml.load(motdfile, Loader=yaml.FullLoader)
     motd.motd_handler(mypackage, myversion)
     sys.exit(0)

src/esm_tools/cli.py

@@ -90,5 +90,21 @@ def check_transient_forcing(file_name=None, current_year=None):
     print(f"CLONP: {clonp}")
 
 
+@main.command()
+@click.argument("version", nargs=1, required=False)
+@click.option("--local", default=False, help="Use the local MOTD file", is_flag=True)
+def motd(version=None, local=False):
+    """Prints the message of the day."""
+    import esm_motd
+
+    if version is None:
+        version = esm_tools.__version__
+
+    esm_motd.check_esm_package_with_version_and_local_options(
+        "esm_tools", version, local
+    )
+    return 0
+
+
 if __name__ == "__main__":
     sys.exit(main())