mmif-python 1.5.4__tar.gz → 1.6.0__tar.gz

{mmif_python-1.5.4 → mmif_python-1.6.0}/CHANGELOG.md

@@ -1,4 +1,19 @@
 
+## releasing 1.5.4 (2026-10-05)
+### Overview
+
+This patch fixes image extraction from truncated or otherwise incomplete video files, and the handling of deprecated annotation property names.
+
+### Changes
+
+* `video_document_helper`: image extraction no longer fails or returns wrong images on incomplete video files. Timepoints with no image now come back as `None`, with a warning that tells how to check the file (https://github.com/clamsproject/mmif-python/issues/400).
+    * *Note: apps that process every returned image must handle `None`.*
+    * `av` is now pinned to `>= 15` for `mmif-python[cv]` 
+* Deprecated property names (e.g., `frameType` for `label`) work again for values stored in a view's `contains` metadata, including in `mmif summarize` output (https://github.com/clamsproject/mmif-python/issues/401).
+
+
+
+
 ## releasing 1.5.3 (2026-07-08)
 ### Overview
 This patch includes improvements in automatic conversion between contains-metadata properties and annotation properties (#396) 

{mmif_python-1.5.4 → mmif_python-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmif-python
-Version: 1.5.4
+Version: 1.6.0
 Summary: Python implementation of MultiMedia Interchange Format specification. (https://mmif.clams.ai)
 License-Expression: Apache-2.0
 Project-URL: homepage, https://mmif.clams.ai

{mmif_python-1.5.4 → mmif_python-1.6.0}/documentation/introduction.rst

@@ -94,6 +94,6 @@ For a full list of available helper methods, please refer to the API documentati
 MMIF usage in CLAMS Workflows
 -----------------------------
 
-In the context of CLAMS, a **Workflow** refers to the sequence of CLAMS applications that have been executed to generate the views and annotations within a MMIF file.
+In the context of CLAMS, a **Workflow** refers to the sequence of CLAMS applications that have been executed to generate the views and annotations within a MMIF file. Each step of a workflow is one *app execution*: the views produced by a single run of an app, which share the same ``app`` and ``timestamp`` values in their metadata. A step counts whether its views hold annotations, only warnings, or an error, so the workflow records every app that ran, including ones that failed or found nothing to annotate.
 
-When using the ``mmif-python`` SDK, a unique identifier for a workflow (``workflowId``) is calculated based on the applications involved. This identifier is constructed by concatenating the application name, version, and a hash of the runtime parameters for each step in the sequence. This ensures that the identifier uniquely represents not just the apps used, but their specific configurations, aiding in reproducibility.
+When using the ``mmif-python`` SDK, a unique identifier for a workflow (``workflowId``) is calculated based on the applications involved. This identifier is constructed by concatenating a prefix that describes the source documents, followed by the application name, version, and a hash of the runtime parameters for each step in the sequence. This ensures that the identifier uniquely represents not just the apps used, but their specific configurations, aiding in reproducibility. The ``mmif rewind`` command in app mode counts the same steps, so rewinding N apps from a MMIF yields the ``workflowId`` with its last N steps removed.

{mmif_python-1.5.4 → mmif_python-1.6.0}/documentation/target-versions.csv

@@ -1,4 +1,5 @@
 "``mmif-python`` version","Target MMIF Specification"
+`1.6.0 <https://pypi.org/project/mmif-python/1.6.0/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
 `1.5.4 <https://pypi.org/project/mmif-python/1.5.4/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
 `1.5.3 <https://pypi.org/project/mmif-python/1.5.3/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
 `1.5.2 <https://pypi.org/project/mmif-python/1.5.2/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__

{mmif_python-1.5.4 → mmif_python-1.6.0}/mmif/serialize/annotation.py

@@ -368,6 +368,12 @@ class Document(Annotation):
         # around the use of these three dictionaries
         # (names changed since, `existing` >> `ephemeral` and `temporary` >> `pending`)
         self._props_original: DocumentProperties = DocumentProperties(None, self)
+        # pending props are never cleared: every `Mmif.serialize()` call
+        # converts them into `Annotation`s again, and
+        # `Mmif.generate_capital_annotations()` relies on its duplicate check
+        # to skip values already written. Calling it more than once (e.g.,
+        # early in clams-python's `ClamsApp.annotate()`) is safe only while
+        # that check holds.
         self._props_pending: AnnotationProperties = AnnotationProperties(None, self)
         self.reserved_names.update(('_props_original', '_props_pending'))
         

{mmif_python-1.5.4 → mmif_python-1.6.0}/mmif/serialize/mmif.py

@@ -15,7 +15,8 @@ import math
 import warnings
 from collections import defaultdict
 from datetime import datetime, timezone
-from typing import Any, List, Union, Optional, Dict, cast, Iterator
+from typing import Any, List, Union, Optional, Dict, cast, Iterable, Iterator
+from urllib.parse import urlparse
 
 import jsonschema.validators
 
@@ -28,6 +29,10 @@ from mmif.vocabulary import AnnotationTypes, DocumentTypesBase
 
 __all__ = ['Mmif']
 
+# base URL of first-party CLAMS app identifiers
+# (e.g., ``http://apps.clams.ai/swt-detection/v8.6``)
+app_directory_baseurl = "http://apps.clams.ai"
+
 
 class MmifMetadata(MmifObject):
     """
@@ -122,11 +127,15 @@ class ViewsList(DataList[View]):
 
     def get_last_contentful_view(self) -> Optional[View]:
         """
-        Returns the last view that is contentful, i.e., has no error or warning .
+        Returns the last view that is contentful, i.e., has at least one
+        annotation (see :meth:`~mmif.serialize.view.View.has_content`).
+        Views with no annotations, including error and warning views, are
+        skipped.
         """
         for view in reversed(self._items.values()):
-            if 'error' not in view.metadata and 'warnings' not in view.metadata:
+            if view.has_content():
                 return view
+        return None
     
     def get_last_view(self) -> Optional[View]:
         """
@@ -336,7 +345,9 @@ class Mmif(MmifObject):
         behind this behavior and discussion.
         """
         # this view will be the default kitchen sink for all generated annotations.
-        last_view = self.views.get_last_contentful_view()
+        # this can be an empty view, from an app that only adds document properties
+        last_view = next((v for v in reversed(self.views)
+                          if not v.has_error() and not v.has_warnings()), None)
         
         # proceed only when there's at least one view
         if last_view:
@@ -356,18 +367,12 @@ class Mmif(MmifObject):
             # new properties to record in the current serialization call
             anns_to_write = defaultdict(dict)
             for view in self.views:
-                doc_id = None
-                if AnnotationTypes.Annotation in view.metadata.contains:
-                    if 'document' in view.metadata.contains[AnnotationTypes.Annotation]:
-                        doc_id = view.metadata.contains[AnnotationTypes.Annotation]['document']
-                    for ann in view.get_annotations(AnnotationTypes.Annotation):
-                        if doc_id is None:
-                            # note that in the input MMIF that generated with old implementation,
-                            # this value can be in the "short" form, i.e., without view ID prefix
-                            # however, after deserialization, all document IDs should have the 
-                            # view ID prefix, at least within in-memory representation.
-                            doc_id = ann.get_property('document')
-                        existing_anns[doc_id].update(ann.properties.items())
+                for ann in view.get_annotations(AnnotationTypes.Annotation):
+                    # view-level `contains` defaults are exposed on each
+                    # annotation as ephemeral properties; in MMIF made by old
+                    # SDKs, the id may be in the short form (no view prefix)
+                    existing_anns[ann.get_property('document')].update(
+                        ann.properties.items())
                 for doc in view.get_documents():
                     anns_to_write[doc.id].update(doc._props_pending.items())
             for doc in self.documents:
@@ -763,6 +768,111 @@ class Mmif(MmifObject):
                     return view
         return None
 
+    @staticmethod
+    def _full_app_id(app_id: str) -> str:
+        """
+        Expands a first-party app ID shorthand (e.g.,
+        ``swt-detection/v8.6``) into a full URI under
+        :data:`app_directory_baseurl`. An ``http(s)`` URL is returned as is.
+        """
+        if urlparse(app_id).scheme in ('http', 'https'):
+            return app_id
+        return f"{app_directory_baseurl}/{app_id.strip('/')}"
+
+    def get_all_views_by_app(self, *app_ids: str) -> List[View]:
+        """
+        Returns the list of all views produced by any of the given apps.
+
+        Each app ID is either a full app URI (required for third-party
+        apps) or a first-party shorthand such as ``swt-detection/v8.6``,
+        which is expanded under :data:`app_directory_baseurl`. Matching is
+        exact: an ID without a version matches no view, and there are no
+        wildcards, so list every version to cover a version range. To group
+        views into app runs instead, see
+        :func:`mmif.utils.workflow_helper.group_views_by_app`.
+
+        :param app_ids: one or more app IDs; a view matches if it was
+            produced by any of them
+        :return: the list of matching views
+        """
+        full_ids = {self._full_app_id(app_id) for app_id in app_ids}
+        return [view for view in self.views if view.metadata.app in full_ids]
+
+    get_views_by_app = get_all_views_by_app
+
+    def get_view_by_app(self, *app_ids: str) -> Optional[View]:
+        """
+        Returns the last view appended that was produced by any of the given
+        apps. App IDs are matched as in :meth:`get_all_views_by_app`.
+
+        :param app_ids: one or more app IDs
+        :return: the view, or None if no view matches
+        """
+        matches = self.get_all_views_by_app(*app_ids)
+        return matches[-1] if matches else None
+
+    def get_all_views_by_apptag(self, *tags: str) -> List[View]:
+        """
+        Returns the list of all views whose ``appTags`` metadata contains
+        any of the given tags.
+
+        :param tags: one or more tags; a view matches if it carries any of
+            them
+        :return: the list of matching views
+        """
+        return [view for view in self.views
+                if any(tag in view.metadata.appTags for tag in tags)]
+
+    get_views_by_apptag = get_all_views_by_apptag
+
+    def get_view_by_apptag(self, *tags: str) -> Optional[View]:
+        """
+        Returns the last view appended whose ``appTags`` metadata contains
+        any of the given tags.
+
+        :param tags: one or more tags
+        :return: the view, or None if no view matches
+        """
+        matches = self.get_all_views_by_apptag(*tags)
+        return matches[-1] if matches else None
+
+    def get_annotations_of_labels(
+            self, at_type: Union[ThingTypesBase, str],
+            include_labels: Iterable[str] = (),
+            exclude_labels: Iterable[str] = ()) -> Iterator[Annotation]:
+        """
+        Finds annotations of a type across all views, filtered by their
+        ``label`` property.
+
+        With both label lists empty (the default), every annotation of
+        ``at_type`` is returned, including annotations that have no
+        ``label``. A non-empty ``include_labels`` keeps only annotations
+        whose ``label`` is listed, so annotations without a ``label`` are
+        dropped. ``exclude_labels`` is applied after ``include_labels`` and
+        never drops annotations without a ``label``.
+
+        The ``label`` value is read with
+        :py:meth:`~mmif.serialize.annotation.Annotation.get_property`, so
+        the deprecated spellings of the property (``frameType`` on
+        ``TimeFrame``, ``boxType`` on ``BoundingBox``) are honored.
+
+        :param at_type: the type of the annotations to look for
+        :param include_labels: labels to keep; empty means no restriction
+        :param exclude_labels: labels to leave out
+        :return: an iterator of matching annotations, in view order and
+                 then in annotation order within each view
+        """
+        include = tuple(include_labels)
+        exclude = tuple(exclude_labels)
+        for view in self.get_all_views_contain(at_type):
+            for ann in view.get_annotations(at_type):
+                label = ann.get_property('label')
+                if include and label not in include:
+                    continue
+                if label is not None and label in exclude:
+                    continue
+                yield ann
+
     def _is_in_time_range(self, ann: Annotation, range_s: Union[int, float], range_e: Union[int, float]) -> bool:
         """
         Checks if the annotation is anchored within the given time range. Any overlap is considered included. 

{mmif_python-1.5.4 → mmif_python-1.6.0}/mmif/serialize/model.py

@@ -134,13 +134,31 @@ class MmifObject(object):
         """
         Method to set values in _unnamed_attributes.
 
+        A key that matches a declared (named) attribute is stored in that
+        attribute instead, with a warning, so that a key never lives in both
+        places. A leading ``@`` in the key is read as the ``_`` prefix of
+        the attribute name, following the JSON-LD mapping used in
+        serialization.
+
         :param key: the attribute name
         :param value: the desired value
         :return: None
         :raise: AttributeError if additional properties are disallowed by :func:`disallow_additional_properties`
+        :raise: KeyError if the key is a reserved name
         """
+        attr = f'_{key[1:]}' if key.startswith('@') else key
         if self._unnamed_attributes is None:
-            raise AttributeError(f"Additional properties are disallowed by {self.__class__}")
+            hint = (f' "{key}" is a declared attribute; use obj["{attr}"] = value.'
+                    if attr in self._named_attributes() else '')
+            raise AttributeError(f"Additional properties are disallowed by {self.__class__}.{hint}")
+        if key in self.reserved_names or attr in self.reserved_names:
+            raise KeyError(f"can't set a reserved name: {key}")
+        if attr in self._named_attributes():
+            warnings.warn(f'"{key}" is a declared attribute of {type(self).__name__}; '
+                          f'storing it as the attribute, not as an additional property.',
+                          stacklevel=2)
+            self[attr] = value
+            return
         self._unnamed_attributes[key] = value  # pytype: disable=unsupported-operands
 
     def _named_attributes(self) -> Generator[str, None, None]:

{mmif_python-1.5.4 → mmif_python-1.6.0}/mmif/serialize/view.py

@@ -418,6 +418,14 @@ class View(MmifObject):
     def has_warnings(self):
         return self.metadata.has_warnings()
 
+    def has_content(self) -> bool:
+        """
+        Returns True if the view has at least one annotation. Per the MMIF
+        specification, error views and warning views carry no annotations,
+        so a view with content has neither an error nor warnings.
+        """
+        return len(self.annotations) > 0
+
 
 class ViewMetadata(MmifObject):
     """
@@ -430,6 +438,7 @@ class ViewMetadata(MmifObject):
         self.document: str = ''
         self.timestamp: Optional[datetime] = None
         self.app: str = ''
+        self.appTags: List[str] = []
         self.contains: ContainsDict = ContainsDict()
         self.parameters: Dict[str, str] = {}
         self.appConfiguration: Dict[str, Union[PRMTV_TYPES, List[PRMTV_TYPES]]] = {}

{mmif_python-1.5.4 → mmif_python-1.6.0}/mmif/utils/cli/rewind.py

@@ -31,11 +31,14 @@ def prompt_user(mmif_obj: mmif.Mmif) -> int:
 
 def rewind_mmif(mmif_obj: mmif.Mmif, choice: int, choice_is_viewnum: bool = True) -> mmif.Mmif:
     """
-    Rewind MMIF by deleting the last N views. 
-    The number of views to rewind is given as a number of "views", or number of "producer apps". 
-    By default, the number argument is interpreted as the number of "views". 
-    Note that when the same app is repeatedly run in a CLAMS workflow and produces multiple views in a row,
-    rewinding in "app" mode will rewind all those views at once.
+    Rewind MMIF by deleting the last N views.
+    The number of views to rewind is given as a number of "views", or number of "producer apps".
+    By default, the number argument is interpreted as the number of "views".
+    In "app" mode, one app is one app execution as grouped by
+    :func:`mmif.utils.workflow_helper.group_views_by_app`: all views that
+    share the same ``app`` and ``timestamp``, including warning and error
+    views. Rewinding one app removes the last execution only; earlier runs
+    of the same app are kept.
 
     :param mmif_obj: mmif object
     :param choice: number of views to rewind
@@ -59,7 +62,9 @@ def describe_argparser():
     oneliner = 'provides CLI to rewind a MMIF from a CLAMS workflow.'
     additional = textwrap.dedent("""
     MMIF rewinder rewinds a MMIF by deleting the last N views.
-    N can be specified as a number of views, or a number of producer apps. """)
+    N can be specified as a number of views, or a number of producer apps.
+    In app mode, one app is one app execution: all views that share the
+    same app and timestamp, including warning and error views. """)
     return oneliner, oneliner + '\n\n' + additional
 
 

{mmif_python-1.5.4 → mmif_python-1.6.0}/mmif/utils/video_document_helper.py

@@ -9,12 +9,12 @@ import math
 import warnings
 from io import StringIO
 from typing import Iterable  # todo: replace with collections.abc.Iterable in Python 3.9
-from typing import List, Optional, Union, Tuple
+from typing import Iterator, List, Optional, Union, Tuple
 
 import mmif
-from mmif import Annotation, Document, Mmif
+from mmif import Annotation, Document, Mmif, View
 from mmif.utils.timeunit_helper import convert
-from mmif.vocabulary import DocumentTypes
+from mmif.vocabulary import AnnotationTypes, DocumentTypes
 
 _CV_DEPS = ('av', 'cv2', 'PIL', 'wurlitzer')
 _cv_import_warning = (
@@ -699,6 +699,95 @@ def extract_images_by_mode_with_sources(
     return images, sources
 
 
+def _to_timepoints(
+    output_view: View,
+    video_document: Document,
+    sources: List[Union[str, int]],
+) -> List[str]:
+    """
+    Turns per-image sources, as returned by
+    :py:func:`extract_images_by_mode_with_sources`, into ``TimePoint``
+    annotation ids, parallel to ``sources``.
+
+    A ``str`` source is the id of an existing ``TimePoint`` and is passed
+    through. An ``int`` source is a timepoint in milliseconds that no
+    ``TimePoint`` backs; a new ``TimePoint`` is created for it in
+    ``output_view`` and its id is used. No lookup for an existing
+    ``TimePoint`` at the same time is done, so two calls on the same
+    fallback timepoint create two annotations.
+
+    :param output_view: the view new ``TimePoint`` annotations are added to
+    :param video_document: the video the timepoints belong to
+    :param sources: per-image sources
+    :return: ``TimePoint`` ids, parallel to ``sources``
+    """
+    ids: List[str] = []
+    for source in sources:
+        if isinstance(source, str):
+            ids.append(source)
+        else:
+            tp = output_view.new_annotation(
+                AnnotationTypes.TimePoint, document=video_document.id,
+                timePoint=int(source), timeUnit='milliseconds')
+            ids.append(tp.id)
+    return ids
+
+
+def iter_timeframe_images(
+    mmif: Mmif,
+    output_view: View,
+    include_labels: Iterable[str] = (),
+    exclude_labels: Iterable[str] = (),
+    mode: Union[SamplingMode, None] = None,
+    as_PIL: bool = False,
+) -> Iterator[Tuple[Annotation, List, List[str]]]:
+    """
+    Samples images from every ``TimeFrame`` in the MMIF, filtered by label,
+    and yields them with the ``TimePoint`` each image was taken from.
+
+    ``TimeFrame`` annotations are selected with
+    :py:meth:`~mmif.serialize.mmif.Mmif.get_annotations_of_labels`, and
+    images are sampled from each with
+    :py:func:`extract_images_by_mode_with_sources`. Images that cannot be
+    read from the video (``None`` in that function's result, already
+    reported there in a warning) are left out together with their sources.
+    A ``TimeFrame`` with no readable image is skipped.
+
+    Every image comes with the id of a ``TimePoint``. When an image was
+    sampled at a time no ``TimePoint`` backs (``tfSamplingMode`` fallback),
+    a new ``TimePoint`` is created in ``output_view`` as a side effect of
+    iterating, so pass the view the calling app writes its own output into.
+    The ids are meant for the ``origins`` of whatever the app derives from
+    the images.
+
+    :param mmif: :py:class:`~mmif.serialize.mmif.Mmif` instance
+    :param output_view: the view new ``TimePoint`` annotations are added to
+    :param include_labels: ``TimeFrame`` labels to keep; empty means all
+    :param exclude_labels: ``TimeFrame`` labels to leave out
+    :param mode: :py:class:`SamplingMode`, or None to use the context
+        default (the ``tfSamplingMode`` runtime parameter in CLAMS apps)
+    :param as_PIL: return :py:class:`PIL.Image.Image` instead of
+        :py:class:`~numpy.ndarray`
+    :return: an iterator of ``(time_frame, images, timepoint_ids)``, where
+        ``images`` and ``timepoint_ids`` are parallel, non-empty lists
+    """
+    # select first, so TimePoints added to ``output_view`` while iterating
+    # never interfere with the views being read
+    time_frames = list(mmif.get_annotations_of_labels(
+        AnnotationTypes.TimeFrame, include_labels, exclude_labels))
+    for time_frame in time_frames:
+        images, sources = extract_images_by_mode_with_sources(
+            mmif, time_frame, mode=mode, as_PIL=as_PIL)
+        readable = [(image, source) for image, source in zip(images, sources)
+                    if image is not None]
+        if not readable:
+            continue
+        video_document = _resolve_video_document(mmif, time_frame)
+        timepoint_ids = _to_timepoints(
+            output_view, video_document, [source for _, source in readable])
+        yield time_frame, [image for image, _ in readable], timepoint_ids
+
+
 def extract_images_by_mode(
     mmif: Mmif,
     time_frame: Annotation,

{mmif_python-1.5.4 → mmif_python-1.6.0}/mmif/utils/workflow_helper.py

@@ -14,8 +14,22 @@ def group_views_by_app(views: ViewsList) -> List[List[Any]]:
     """
     Groups views into app executions based on app and timestamp.
 
-    An "app" is a set of views produced by the same app at the
-    exact same timestamp.
+    An app execution is the set of views produced by a single run of an
+    app. Apps based on ``clams-python`` give every view from one run the
+    same ``metadata.timestamp``, so views that share ``app`` and
+    ``timestamp`` form one execution, and two runs of the same app form
+    two executions. Every execution counts, whether its views hold
+    annotations, only warnings, or an error. Views without ``app`` or
+    ``timestamp`` cannot be grouped and are left out.
+
+    The executions are the common unit of
+    :func:`generate_workflow_identifier`, :func:`describe_single_mmif`,
+    and app-mode rewinding (:func:`mmif.utils.cli.rewind.rewind_mmif`),
+    so all three agree on the number and order of executions.
+
+    :param views: views to group
+    :return: list of app executions, each a list of views, ordered by
+        timestamp
     """
     # Filter out views that don't have a timestamp or app, as they can't be grouped.
     groupable_views = [
@@ -121,9 +135,15 @@ def generate_workflow_identifier(mmif_input: Union[str, Path, Mmif],
     document mix as ``Type-N`` pairs joined by ``-`` and sorted by type
     name (e.g. ``TextDocument-1-VideoDocument-1``).
 
+    Each app execution, as grouped by :func:`group_views_by_app`, adds
+    exactly one ``app_name/version/param_hash`` segment, including
+    executions that produced only warnings, only an error, or no
+    annotations. Hence, rewinding N apps from a MMIF (see
+    :func:`mmif.utils.cli.rewind.rewind_mmif`) yields the identifier with
+    its last N segments removed.
+
     Uses view.metadata.parameters (raw user-passed values) for hashing
-    to ensure reproducibility. Views with errors or warnings are excluded
-    from the identifier; empty views are included.
+    to ensure reproducibility.
 
     :param mmif_input: Path to MMIF file (str or Path) or a Mmif object
     :param return_param_dicts: If True, also return the parameter dictionaries
@@ -144,10 +164,6 @@ def generate_workflow_identifier(mmif_input: Union[str, Path, Mmif],
         # Use the first view in the run as representative for metadata
         first_view = app_execution[0]
 
-        # Skip runs where the representative view has errors or warnings
-        if first_view.has_error() or first_view.has_warnings():
-            continue
-
         app = first_view.metadata.get("app")
         if app is None:
             continue
@@ -183,7 +199,7 @@ class SingleMmifStats(BaseModel):
     app_count: int = Field(..., alias="appCount", description="Total number of app executions identified.")
     error_views: List[str] = Field(default_factory=list, alias="errorViews", description="List of view IDs that contain errors.")
     warning_views: List[str] = Field(default_factory=list, alias="warningViews", description="List of view IDs that contain warnings.")
-    empty_views: List[str] = Field(default_factory=list, alias="emptyViews", description="List of view IDs that contain no annotations.")
+    empty_views: List[str] = Field(default_factory=list, alias="emptyViews", description="List of view IDs that contain no annotations, error, or warnings.")
     annotation_count_by_type: Dict[str, int] = Field(default_factory=dict, alias="annotationCountByType", description="Total annotation counts across the file.")
 
 class AppProfiling(BaseModel):
@@ -254,7 +270,15 @@ def describe_single_mmif(mmif_input: Union[str, Path, Mmif]) -> dict:
     conceptual hierarchy is that a **workflow** is a sequence of **apps**,
     and each **app** execution can produce one or more **views**. This function
     groups views that share the same ``app`` and ``metadata.timestamp`` into
-    a single logical "app execution".
+    a single logical "app execution" (see :func:`group_views_by_app`).
+
+    Every app execution is listed in ``apps``, including executions whose
+    views hold only warnings or an error; the IDs of such views are also
+    listed in ``stats.warningViews`` and ``stats.errorViews``. The
+    ``workflowId`` is computed from the same executions by
+    :func:`generate_workflow_identifier`, so its segments match the
+    ``apps`` entries one to one. The only exception is the trailing
+    ``non-existing-app`` entry that collects views that cannot be grouped.
 
     .. note::
         For MMIF files generated by apps based on ``clams-python`` <= 1.3.3, all 
@@ -276,9 +300,17 @@ def describe_single_mmif(mmif_input: Union[str, Path, Mmif]) -> dict:
     """
     mmif = _read_mmif_from_path(mmif_input)
 
+    # view status is a property of each view, independent of grouping
     error_view_ids = []
     warning_view_ids = []
     empty_view_ids = []
+    for view in mmif.views:
+        if view.has_error():
+            error_view_ids.append(view.id)
+        elif view.has_warnings():
+            warning_view_ids.append(view.id)
+        elif not view.has_content():
+            empty_view_ids.append(view.id)
 
     # Generate the new "apps" list
     grouped_apps = []
@@ -286,14 +318,9 @@ def describe_single_mmif(mmif_input: Union[str, Path, Mmif]) -> dict:
     view_groups = group_views_by_app(mmif.views)
     for group in view_groups:
         first_view = group[0]
-        # skip executions with errors or warnings
-        if first_view.has_error() or first_view.has_warnings():
-            continue
 
         execution_ann_counter = Counter()
         for view in group:
-            if len(view.annotations) == 0:
-                empty_view_ids.append(view.id)
             execution_ann_counter.update(Counter(str(ann.at_type) for ann in view.annotations))
 
         execution_view_ids = [v.id for v in group]
@@ -315,19 +342,8 @@ def describe_single_mmif(mmif_input: Union[str, Path, Mmif]) -> dict:
             annotationCountByType=count_dict
         ))
 
-    # Handle unassigned and problematic views
-    all_view_ids = set(v.id for v in mmif.views)
-
-    for view in mmif.views:
-        if view.id not in processed_view_ids:
-            if view.has_error():
-                error_view_ids.append(view.id)
-            elif view.has_warnings():
-                warning_view_ids.append(view.id)
-            elif len(view.annotations) == 0:
-                empty_view_ids.append(view.id)
-
-    unassigned_view_ids = all_view_ids - processed_view_ids - set(error_view_ids) - set(warning_view_ids)
+    # views that cannot be grouped (no app or timestamp), whatever they hold
+    unassigned_view_ids = set(v.id for v in mmif.views) - processed_view_ids
 
     # Store app_count before potentially adding the special entry
     app_count = len(grouped_apps)

{mmif_python-1.5.4 → mmif_python-1.6.0}/mmif_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmif-python
-Version: 1.5.4
+Version: 1.6.0
 Summary: Python implementation of MultiMedia Interchange Format specification. (https://mmif.clams.ai)
 License-Expression: Apache-2.0
 Project-URL: homepage, https://mmif.clams.ai

mmif_python-1.6.0/mmif_python.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "1.6.0",
+  "distance": 0,
+  "node": "gc6ccccda0690ca67b16b2ab988234217d55aba74",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-27"
+}