Merge branch 'main' into develop

Author: keighrim

CHANGELOG.md

@@ -1,4 +1,50 @@
 
+## releasing 1.2.1 (2025-11-28)
+### Overview
+Updated output formats of the experimental `mmif describe` command
+
+### Changes
+* `mmif describe` command 
+    * simplified output JSON format of single-mmif input (`mmif.utils.workflow_helper.describe_single_mmif`)
+    * more informative output from multi-mmif input (`mmif.utils.workflow_helper.describe_mmif_collection`)
+
+> [!NOTE]
+> `mmif describe` (and the underlying `mmif.utils.workflow_helper`) is still experimental and subject to change in future releases without notice. Backward compatibility is not guaranteed.
+
+## releasing 1.2.0 (2025-11-20)
+### Overview
+This version is minor release with addition of a new cli (`describe`), lots of in-line documentation updates, and deprecation of some "getter" methods
+
+### Additions
+* `mmif describe` command to summarize views and annotations of a give MMIF file (https://github.com/clamsproject/mmif-python/pull/339). 
+
+### Changes
+* "list-like" objects in MMIF (`DataList`, `DocumentsList`, `ViewsList`, `AnnotationsList`) - `get()` method is now deprecated (https://github.com/clamsproject/mmif-python/issues/295). Use their parent containers' `get` methods 
+```
+mmif.views.get(some_view_id)  # will show deprecation warning as of 1.1.3 (note that there's no 1.1.3, we moved from 1.1.2 to 1.2.0)
+# instead use 
+mmif.get(some_view_id)
+# same for view.annotations.get(ann_id) ==> view.get(ann_id)
+```
+* comparing two Mmif objects no longer depends on buggy `deepdiff` library, and handled more robustly (https://github.com/clamsproject/mmif-python/issues/311)
+* many  outdated documentation updates
+
+
+## releasing 1.1.2 (2025-07-28)
+### Overview
+Patch release with a hotfix of a bug. 
+
+### Changes
+* Fixed bug with handling "list of ID" props in 1.0.x MMIF. 
+
+## releasing 1.1.1 (2025-07-26)
+### Overview
+Patch release to support installation on python 3.12 and newer (fixes https://github.com/clamsproject/mmif-python/issues/314). 
+
+### Additions
+- `setup.py` is now compatible with the latest setuptools (80) .
+- [Since python 3.12 no longer ship `setuptools` as a part of standard installation](https://docs.python.org/3/whatsnew/3.12.html#ensurepip), added setuptools as a `dev` dependency.
+
 ## releasing 1.1.0  (2025-07-23)
 ### Overview
 This is a minor version release, but it includes several significant changes and improvements across the codebase. 

documentation/cli.rst

@@ -11,10 +11,6 @@ The CLI is installed as ``mmif`` shell command. To see the available commands, r
 
     mmif --help
 
-.. contents::
-    :local:
-    :backlinks: none
-
 The following documentation is automatically generated from the CLI help messages.
 
 .. include:: cli_help.rst

documentation/target-versions.csv

@@ -1,4 +1,7 @@
 "``mmif-python`` version","Target MMIF Specification"
+1.2.0,"1.1.0"
+1.1.2,"1.1.0"
+1.1.1,"1.1.0"
 1.1.0,"1.1.0"
 1.0.19,"1.0.5"
 1.0.18,"1.0.5"

mmif/utils/workflow_helper.py

@@ -181,22 +181,32 @@ def describe_single_mmif(mmif_file: Union[str, Path]) -> dict:
 
     The output format is a dictionary with the following keys:
 
-    * ``workflowId``: A unique identifier for the workflow, based on the
-      sequence of app executions (app, version, parameter hashes). App
-      executions with errors are excluded from this identifier. App
-      executions with warnings are still considered successful for the purpose of this identifier.
-    * ``stats``:
-        * ``appCount``: Total number of identified app executions.
-        * ``errorViews``: A list of view IDs that reported errors.
-        * ``warningViews``: A list of view IDs that reported warnings.
-        * ``emptyViews``: A list of view IDs that contain no annotations.
-        * ``annotationCountByType``: A dictionary mapping each annotation
-          type to its count, plus a ``total`` key for the sum of all
-          annotations across all app executions.
-    * ``apps``: A list of objects, where each object represents one app
-      execution. It includes metadata, profiling, and aggregated statistics
-      for all views generated by that execution. A special entry for views
-      that could not be assigned to an execution will be at the end of the list.
+    * ``workflowId``
+        A unique identifier for the workflow, based on the
+        sequence of app executions (app, version, parameter hashes). App
+        executions with errors are excluded from this identifier. App
+        executions with warnings are still considered successful for the purpose
+        of this identifier.
+    * ``stats``
+        A dictionary with the following keys:
+
+        ``appCount``
+            Total number of identified app executions.
+        ``errorViews``
+            A list of view IDs that reported errors.
+        ``warningViews``
+            A list of view IDs that reported warnings.
+        ``emptyViews``
+            A list of view IDs that contain no annotations.
+        ``annotationCountByType``
+            A dictionary mapping each annotation type to its count, plus a
+            ``total`` key for the sum of all annotations across all app
+            executions.
+    * ``apps``
+        A list of objects, where each object represents one app
+        execution. It includes metadata, profiling, and aggregated statistics
+        for all views generated by that execution. A special entry for views
+        that could not be assigned to an execution will be at the end of the list.
 
     ---
     The docstring above is used to generate help messages for the CLI command.
@@ -311,24 +321,38 @@ def describe_mmif_collection(mmif_dir: Union[str, Path]) -> dict:
 
     The output format is a dictionary with the following keys:
 
-    * ``mmifCountByStatus``: A dictionary summarizing the processing status of
-      all MMIF files in the collection. It includes:
-        * ``total``: Total number of MMIF files found.
-        * ``successful``: Number of MMIF files processed without errors (may contain warnings).
-        * ``withErrors``: Number of MMIF files containing app executions that reported errors.
-        * ``withWarnings``: Number of MMIF files containing app executions that reported warnings.
-        * ``invalid``: Number of files that failed to be parsed as valid MMIF.
-    * ``workflows``: A list of "workflow" objects found in the "successful" MMIF files (files with errors
-        are excluded), where each object contains:
-        * ``workflowId``: The unique identifier for the workflow.
-        * ``apps``: A list of app objects, each with ``app`` (name+ver identifier),
-          ``appConfiguration``, and ``appProfiling`` statistics (avg, min, max, stdev running times)
-          aggregated per workflow.
-        * ``mmifs``: A list of MMIF file basenames belonging to this workflow.
-        * ``mmifCount``: The number of MMIF files in this workflow.
-    * ``annotationCountByType``: A dictionary aggregating annotation counts
-      across the entire collection. It includes a ``total`` key for the grand
-      total, plus integer counts for each individual annotation type.
+    * ``mmifCountByStatus``
+        A dictionary summarizing the processing status of all MMIF files in the
+        collection. It includes:
+
+        ``total``
+            Total number of MMIF files found.
+        ``successful``
+            Number of MMIF files processed without errors (may contain warnings).
+        ``withErrors``
+            Number of MMIF files containing app executions that reported errors.
+        ``withWarnings``
+            Number of MMIF files containing app executions that reported warnings.
+        ``invalid``
+            Number of files that failed to be parsed as valid MMIF.
+    * ``workflows``
+        A list of "workflow" objects found in the "successful" MMIF files (files
+        with errors are excluded), where each object contains:
+
+        ``workflowId``
+            The unique identifier for the workflow.
+        ``apps``
+            A list of app objects, each with ``app`` (name+ver identifier),
+            ``appConfiguration``, and ``appProfiling`` statistics (avg, min, max,
+            stdev running times) aggregated per workflow.
+        ``mmifs``
+            A list of MMIF file basenames belonging to this workflow.
+        ``mmifCount``
+            The number of MMIF files in this workflow.
+    * ``annotationCountByType``
+        A dictionary aggregating annotation counts across the entire collection.
+        It includes a ``total`` key for the grand total, plus integer counts for
+        each individual annotation type.
 
     ---
     The docstring above is used to generate help messages for the CLI command.
@@ -439,4 +463,4 @@ def describe_mmif_collection(mmif_dir: Union[str, Path]) -> dict:
         'mmifCountByStatus': dict(status_summary),
         'workflows': final_workflows_list,
         'annotationCountByType': final_annotation_counts
-    }
+    }