Study version display

cumulus_library/cli.py

@@ -2,6 +2,7 @@
 """Utility for building/retrieving data views in AWS Athena"""
 
 import copy
+import importlib.util
 import json
 import os
 import pathlib
@@ -362,11 +363,8 @@ def main(cli_args=None):
     parser = cli_parser.get_parser()
     args = vars(parser.parse_args(cli_args))
     if args["version"]:
-        print(__version__)
+        print(f"Cumulus library version: {__version__}")
         sys.exit(0)
-    if args["action"] is None:
-        parser.print_usage()
-        sys.exit(1)
 
     arg_env_pairs = (
         ("data_path", "CUMULUS_LIBRARY_DATA_PATH"),
@@ -392,6 +390,35 @@ def main(cli_args=None):
                 args[pair[0]] = env_val
             read_env_vars.append([pair[1], env_val])
 
+    if args.get("study_dir"):
+        posix_paths = []
+        for path in args["study_dir"]:
+            posix_paths.append(get_abs_path(path))
+        args["study_dir"] = posix_paths
+
+    if study := args.get("study_version"):
+        if study in ("core", "discovery", "vocab"):
+            print(
+                f"{args['study_version']} distributed with Cumulus library.\n"
+                f"Cumulus library:  {__version__}"
+            )
+            sys.exit(0)
+        studies = get_study_dict(args["study_dir"])
+        if study in studies.keys():
+            spec = importlib.util.spec_from_file_location(
+                "study_init", studies[study] / "__init__.py"
+            )
+            study_init = importlib.util.module_from_spec(spec)
+            sys.modules["study_init"] = study_init
+            spec.loader.exec_module(study_init)
+            print(f"{study} version {study_init.__version__}")
+            sys.exit(0)
+        sys.exit(f"'{study}' is not an installed Cumulus study")
+
+    if args["action"] is None:
+        parser.print_usage()
+        sys.exit(1)
+
     if len(read_env_vars) > 0:
         table = rich.table.Table(title="Values read from environment variables")
         table.add_column("Environment Variable", style="green")
@@ -419,12 +446,6 @@ def main(cli_args=None):
     if args.get("data_path"):
         args["data_path"] = get_abs_path(args["data_path"])
 
-    if args.get("study_dir"):
-        posix_paths = []
-        for path in args["study_dir"]:
-            posix_paths.append(get_abs_path(path))
-        args["study_dir"] = posix_paths
-
     return run_cli(args)
 
 

cumulus_library/cli_parser.py

@@ -158,6 +158,8 @@ def get_parser() -> argparse.ArgumentParser:
         "--version", action="store_true", help="Display cumulus-library version number"
     )
 
+    parser.add_argument("--study-version", help="Display version of specific study")
+
     actions = parser.add_subparsers(
         title="actions",
         help="Available library actions",

docs/creating-studies.md

@@ -24,11 +24,18 @@ to any build/export call to tell it where to look for your work.
 
 ## Creating a new study
 
-If you're authoring a study, you just need to do two things to get started:
+If you're authoring a study, you just need to do three things to get started:
 
 - Make a new directory inside the directory you're keeping studies in. The name of this
 directory will be the name you use to run it using the `cumulus-library` cli command.
 In this document, we're calling this directory `my_study` as an example.
+- Make a new file, `__init__.py`, which contains the following:
+```python
+__version__='0.1.0'
+```
+The CLI will use this to display the study's version on demand. Consider using
+[semantic versioning rules](https://semver.org/#semantic-versioning-specification-semver)
+to update this value as appropriate.
 - Make a new file, `manifest.toml`. A
 [toml file](https://toml.io/en/)
 is a config file format - you don't need to worry too much about the details of this 

docs/first-time-setup.md

@@ -40,12 +40,15 @@ loading data into analytics packages.
 [Cumulus Aggregator](https://docs.smarthealthit.org/cumulus/aggregator/)
 - `generate-sql` and `generate-md` both create documentation artifacts, for
 users authoring studies
+- `--version` will provide the installed version of `cumulus-library`, and
+`--study-version [name]` will provide the version of a given study. 
 
-By default, all available studies will be used by build and export, but you can use
-or `--target` to specify a specific study to be run. You can use it multiple
-times to configure several studies in order. 
+You can use `--target` to specify a specific study to be run. You can use it multiple
+times to configure several studies in order. You can use `--study-dir` to target
+a directory where you are working on studies/working with studies that aren't
+available to install with `pip`
 
-Several pip installable studies will automatically be added to the list of available
+Several `pip` installable studies will automatically be added to the list of available
 studies to run. See [study list](./study-list.md) for more details.
 
 There are several other options - use `--help` to get a detailed list of commands.

tests/test_cli.py

@@ -807,6 +807,25 @@ def test_version(capfd):
         assert out == __version__
 
 
+@pytest.mark.parametrize(
+    "study,msg",
+    [("core", "distributed_with"), ("study_valid", "version"), ("not_a_study", "not an installed")],
+)
+@mock.patch.dict(os.environ, clear=True)
+def test_study_version(capfd, study, msg):
+    with pytest.raises(SystemExit):
+        cli.main(
+            cli_args=[
+                "--study-version",
+                study,
+                "-s",
+                "tests/test_data/study_valid/",
+            ]
+        )
+        out, _ = capfd.readouterr()
+        assert msg in out
+
+
 @mock.patch.dict(os.environ, clear=True)
 def test_study_dir(tmp_path):
     os.environ["CUMULUS_LIBRARY_STUDY_DIR"] = str(