added human-friendly summary for pydantic classes in describe --help

Author: keighrim

mmif/utils/cli/__init__.py

@@ -6,16 +6,19 @@
 import io
 import os
 import sys
-from typing import Iterator, Optional, TextIO, cast
+from typing import Iterator, Optional, TextIO, Type, Union, cast, get_args, get_origin
+
+from pydantic import BaseModel
 
 
 @contextlib.contextmanager
-def open_cli_io_arg(path_or_dash: Optional[str],
-                    mode: str = 'r',
-                    encoding: Optional[str] = None,
-                    errors: Optional[str] = None,
-                    default_stdin: bool = False,
-                    ) -> Iterator[TextIO]:
+def open_cli_io_arg(
+    path_or_dash: Optional[str],
+    mode: str = "r",
+    encoding: Optional[str] = None,
+    errors: Optional[str] = None,
+    default_stdin: bool = False,
+) -> Iterator[TextIO]:
     """
     Context manager for opening files with stdin/stdout support.
 
@@ -55,10 +58,10 @@ def open_cli_io_arg(path_or_dash: Optional[str],
             f.write(content)
     """
     # Valid text modes for file operations
-    _READ_FLAGS = frozenset({'r', '+'})
-    _WRITE_FLAGS = frozenset({'w', 'a', 'x', '+'})
+    _READ_FLAGS = frozenset({"r", "+"})
+    _WRITE_FLAGS = frozenset({"w", "a", "x", "+"})
 
-    if 'b' in mode:
+    if "b" in mode:
         raise ValueError(
             f"Binary mode '{mode}' is not supported. "
             "Use text modes ('r', 'w', 'a', 'x') instead."
@@ -67,9 +70,7 @@ def open_cli_io_arg(path_or_dash: Optional[str],
     needs_read = bool(set(mode) & _READ_FLAGS)
     needs_write = bool(set(mode) & _WRITE_FLAGS)
 
-    should_use_stdio = path_or_dash == '-' or (
-        path_or_dash is None and default_stdin
-    )
+    should_use_stdio = path_or_dash == "-" or (path_or_dash is None and default_stdin)
 
     file_handle: Optional[TextIO] = None
     should_close = False
@@ -84,11 +85,7 @@ def open_cli_io_arg(path_or_dash: Optional[str],
 
             if needs_read:
                 # Check for missing input when stdin is a terminal
-                if (
-                    path_or_dash is None
-                    and default_stdin
-                    and sys.stdin.isatty()
-                ):
+                if path_or_dash is None and default_stdin and sys.stdin.isatty():
                     raise SystemExit("error: No input provided.")
                 file_handle = sys.stdin
 
@@ -97,14 +94,15 @@ def open_cli_io_arg(path_or_dash: Optional[str],
 
             else:
                 raise ValueError(
-                    f"Mode '{mode}' not supported with stdin/stdout "
-                    "(use 'r' or 'w')"
+                    f"Mode '{mode}' not supported with stdin/stdout (use 'r' or 'w')"
                 )
 
         elif isinstance(path_or_dash, str):
             if needs_read and not os.path.exists(path_or_dash):
                 raise FileNotFoundError(f"Input path does not exist: {path_or_dash}")
-            file_handle = cast(TextIO, io.open(path_or_dash, mode, encoding=encoding, errors=errors))
+            file_handle = cast(
+                TextIO, io.open(path_or_dash, mode, encoding=encoding, errors=errors)
+            )
             should_close = True
 
         elif path_or_dash is None:
@@ -126,6 +124,102 @@ def open_cli_io_arg(path_or_dash: Optional[str],
             file_handle.close()
 
 
+def generate_model_summary(model: Type[BaseModel], indent: int = 0) -> str:
+    lines = []
+    prefix = " " * indent
+
+    # model_fields is a dictionary of FieldInfo objects
+    for name, field in model.model_fields.items():
+        # Get the alias if available, otherwise use the field name
+        field_name = field.alias if field.alias else name
+
+        # Get type annotation
+        type_annotation = field.annotation
+
+        def format_type(t) -> str:
+            origin = get_origin(t)
+            args = get_args(t)
+
+            # Handle Optional (Union[T, None])
+            if origin is Union and type(None) in args:
+                non_none_args = [arg for arg in args if arg is not type(None)]
+                if len(non_none_args) == 1:
+                    return f"{format_type(non_none_args[0])}, optional"
+
+            # Handle List
+            if origin is list:
+                if args:
+                    return f"[{format_type(args[0])}]"
+                return "[]"
+
+            # Handle Dict
+            if origin is dict:
+                return "obj"
+
+            # Handle Pydantic Models (Custom Classes)
+            if isinstance(t, type) and issubclass(t, BaseModel):
+                return "obj"
+
+            # Handle basic types and cleanup
+            t_str = str(t)
+            if t_str.startswith("<class '"):
+                t_str = t_str[8:-2]
+            if t_str.startswith("typing."):
+                t_str = t_str[7:]
+
+            # Remove module prefix if present
+            if "." in t_str:
+                t_str = t_str.split(".")[-1]
+
+            return t_str
+
+        display_type = format_type(type_annotation)
+
+        description = field.description if field.description else ""
+
+        line_content = f"{prefix}- {field_name} ({display_type})"
+        if description:
+            line_content += f": {description}"
+        lines.append(line_content)
+
+        # Check if it's a Pydantic model or a list/dict of Pydantic models
+        origin = get_origin(type_annotation)
+        args = get_args(type_annotation)
+
+        nested_model = None
+        # Handle Optional wrappers for nesting check
+        check_type = type_annotation
+        if origin is Union and type(None) in args:
+            non_none_args = [arg for arg in args if arg is not type(None)]
+            if len(non_none_args) == 1:
+                check_type = non_none_args[0]
+                origin = get_origin(check_type)
+                args = get_args(check_type)
+
+        if isinstance(check_type, type) and issubclass(check_type, BaseModel):
+            nested_model = check_type
+        elif (
+            origin is list
+            and args
+            and isinstance(args[0], type)
+            and issubclass(args[0], BaseModel)
+        ):
+            nested_model = args[0]
+        elif (
+            origin is dict
+            and args
+            and len(args) > 1
+            and isinstance(args[1], type)
+            and issubclass(args[1], BaseModel)
+        ):
+            nested_model = args[1]
+
+        if nested_model:
+            lines.append(generate_model_summary(nested_model, indent + 4))
+
+    return "\n".join(lines)
+
+
 # keep imports of CLI modules for historical reasons
 # keep them here in the bottom to avoid circular imports
 from mmif.utils.cli import rewind

mmif/utils/cli/describe.py

@@ -3,11 +3,9 @@
 import sys
 import textwrap
 from pathlib import Path
-from typing import Dict, Type, Union, cast
+from typing import Union, cast
 
-from pydantic import BaseModel
-
-from mmif.utils.cli import open_cli_io_arg
+from mmif.utils.cli import open_cli_io_arg, generate_model_summary
 
 # gen_param_hash is imported for backward compatibility
 from mmif.utils.workflow_helper import (
@@ -18,12 +16,6 @@
     generate_workflow_identifier,
 )
 
-models_to_help = [SingleMmifDesc, CollectionMmifDesc]
-model_modules = set(model.__module__ for model in models_to_help)
-def get_all_models() -> Dict[str, Type[BaseModel]]:
-    return {
-        name: cls for name, cls in models_to_help
-    }
 
 def get_pipeline_specs(mmif_file: Union[str, Path]):
     import warnings
@@ -49,7 +41,15 @@ def describe_argparser():
     This command extracts workflow information from a single MMIF file or 
     a directory of MMIF files. The output is serialized as JSON.
     
-    Use `--help-schemas` to inspect the structure of the JSON output.
+    Output Schemas:
+    
+    1. Single MMIF File (mmif-file):
+{generate_model_summary(SingleMmifDesc, indent=4)}
+    
+    2. MMIF Collection (mmif-dir):
+{generate_model_summary(CollectionMmifDesc, indent=4)}
+    
+    Use `--help-schema` to inspect the full JSON schema for a specific output type.
     """)
     return oneliner, additional
 
@@ -79,13 +79,11 @@ def prep_argparser(**kwargs):
         help="Pretty-print JSON output"
     )
     parser.add_argument(
-        "--help-schemas",
-        nargs="*",
-        choices=["all"] + [m.__name__ for m in models_to_help],
+        "--help-schema",
+        nargs=1,
+        choices=["mmif-file", "mmif-dir"],
         metavar="SCHEMA_NAME",
-        help=f"Print the JSON schema for the output. For human-readable documentation, "
-             f"visit https://clams.ai/mmif-python and see the following modules: "
-             f"{', '.join(model_modules)}.\nOptions: all, {', '.join([m.__name__ for m in models_to_help])}."
+        help="Print the JSON schema for the output. Options: mmif-file, mmif-dir."
     )
     return parser
 
@@ -97,19 +95,15 @@ def main(args):
     :func:`describe_single_mmif` (for single file input) or 
     :func:`describe_mmif_collection` (for directory input).
     """
-    if hasattr(args, 'help_schemas') and args.help_schemas is not None:
-        models_map = {m.__name__: m for m in models_to_help}
-        to_show = []
-        if len(args.help_schemas) == 0 or 'all' in args.help_schemas:
-            to_show = [m.__name__ for m in models_to_help]
-        else:
-            to_show = args.help_schemas
+    if hasattr(args, 'help_schema') and args.help_schema is not None:
+        schema_name = args.help_schema[0]
+        if schema_name == 'mmif-file':
+            model_cls = SingleMmifDesc
+        elif schema_name == 'mmif-dir':
+            model_cls = CollectionMmifDesc
 
-        for name in to_show:
-            model_cls = models_map[name]
-            schema = model_cls.model_json_schema()
-            print(json.dumps(schema, indent=2))
-            print()
+        schema = model_cls.model_json_schema()
+        print(json.dumps(schema, indent=2))
         sys.exit(0)
 
     output = {}