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

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

@@ -1,4 +1,31 @@
 
+## 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) 
+
+### Additions
+* automatic "factoring" of value-shared properties from annotation-level to contains-level at serialization time works much more generally now (formerly only worked for `Annotation` type and `document` prop) 
+
+### Changes
+* fixed a bug in reading old MMIF files with non-canonical prop names (contains-level prop value was not properly propagated at deserialization for those non-canonical named props)
+
+
+
 ## releasing 1.5.2 (2026-07-07)
 ### Overview
 This is a quick patch on the bug that when MMIF is deserialized, the annotation ID counts in the views weren't properly initialized. This should not be a real bug since new annotations should always written to new views (of current processing app) but not to existing views (where annotation count > 0), however, bugs in app code can trigger this condition, and this patch preventively fixes such cases.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmif-python
-Version: 1.5.3
+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
@@ -21,7 +21,7 @@ Requires-Dist: pillow; extra == "cv"
 Requires-Dist: opencv-python; extra == "cv"
 Requires-Dist: ffmpeg-python; extra == "cv"
 Requires-Dist: wurlitzer; extra == "cv"
-Requires-Dist: av; extra == "cv"
+Requires-Dist: av>=15; extra == "cv"
 Provides-Extra: seq
 Requires-Dist: numpy; extra == "seq"
 Provides-Extra: docs

{mmif_python-1.5.3 → 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.3 → mmif_python-1.6.0}/documentation/target-versions.csv

@@ -1,4 +1,6 @@
 "``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/>`__
 `1.5.1 <https://pypi.org/project/mmif-python/1.5.1/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__

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

@@ -6,6 +6,7 @@ In MMIF, annotations are created by apps in a workflow as a part
 of a view. For documentation on how views are represented, see
 :mod:`mmif.serialize.view`.
 """
+import functools
 import importlib
 import itertools
 import os
@@ -22,7 +23,7 @@ from .model import MmifObject, PRMTV_TYPES
 from .. import DocumentTypes, AnnotationTypes
 import mmif_docloc_http
 
-__all__ = ['Annotation', 'AnnotationProperties', 'Document', 'DocumentProperties', 'Text']
+__all__ = ['Annotation', 'AnnotationProperties', 'Document', 'DocumentProperties', 'Text', 'canonicalize_prop_name']
 
 T = TypeVar('T')
 LIST_PRMTV = typing.List[PRMTV_TYPES]  # list of values (most cases for annotation props)
@@ -41,6 +42,40 @@ discovered_docloc_plugins.update({
 })
 
 
+@functools.lru_cache(maxsize=None)
+def _prop_alias_map(shortname: str) -> Dict[str, str]:
+    """
+    Maps every spelling of an aliased property of a type to the canonical
+    name. The table is read from the latest version of the type in the
+    vocabulary (``AnnotationTypes.<shortname>``), which is the single source
+    of truth for property aliases.
+
+    :param shortname: shortname of the annotation type (e.g. ``TimeFrame``)
+    :return: ``{spelling: canonical_name}``, empty for types without aliases
+    """
+    latest = getattr(AnnotationTypes, shortname, None)
+    groups = getattr(latest, '_property_aliases', None) or {}
+    return {alias: canonical for canonical, group in groups.items() for alias in group}
+
+
+def canonicalize_prop_name(at_type: ThingTypesBase, prop_name: str) -> str:
+    """
+    Resolves a property name to its canonical spelling for the given type.
+    Property aliases were introduced in MMIF 1.0.2, when the general
+    ``label`` property replaced ``frameType`` (``TimeFrame``) and ``boxType``
+    (``BoundingBox``). Names that are not aliases, and types without an alias
+    table, are returned unchanged.
+
+    :param at_type: the ``@type`` of the annotation
+    :param prop_name: a property name, canonical or deprecated
+    :return: the canonical property name
+    """
+    shortname = getattr(at_type, 'shortname', None)
+    if not shortname:
+        return prop_name
+    return _prop_alias_map(shortname).get(prop_name, prop_name)
+
+
 class Annotation(MmifObject):
     """
     MmifObject that represents an annotation in a MMIF view.
@@ -49,11 +84,11 @@ class Annotation(MmifObject):
     def __init__(self, anno_obj: Optional[Union[bytes, str, dict]] = None, *_) -> None:
         self._type: ThingTypesBase = ThingTypesBase('')
         # to store the parent view ID
-        self._props_ephemeral: AnnotationProperties = AnnotationProperties()
+        self._props_ephemeral: AnnotationProperties = AnnotationProperties(None, self)
         self._alignments = {}  # to hold alignment information (Alignment anno long_id -> aligned anno long_id)
         self.reserved_names.update(('_props_ephemeral', '_alignments'))
         if not hasattr(self, 'properties'):  # don't overwrite DocumentProperties on super() call
-            self.properties: AnnotationProperties = AnnotationProperties()
+            self.properties: AnnotationProperties = AnnotationProperties(None, self)
             self._attribute_classes = {'properties': AnnotationProperties}
         self.disallow_additional_properties()
         self._required_attributes = ["_type", "properties"]
@@ -69,9 +104,7 @@ class Annotation(MmifObject):
         # here is the place to parse formatted IDs and store prefixes in the parent mmif object. 
         # (see https://github.com/clamsproject/mmif/issues/64#issuecomment-849241309 for discussion)
         super()._deserialize(input_dict)
-        for k, v in self.properties.items():
-            self._add_prop_aliases(k, v)
-                            
+
     def _cache_alignment(self, alignment_ann: 'Annotation', alignedto_ann: 'Annotation') -> None:
         """
         Cache alignment information. This cache will not be serialized.
@@ -107,29 +140,20 @@ class Annotation(MmifObject):
             yield aligned
         
         
-    def _add_prop_aliases(self, key_to_add, val_to_add):
-        """
-        Method to handle aliases of the same property.
-        Annotation property aliases were first introduced in MMIF 1.0.2, 
-        with addition of general `label` property to all `Annotation` 
-        subtypes, and effectively deprecated `frameType` and `boxType`
-        in `TimeFrame` and `BoundingBox` respectively.
-        """
-        prop_aliases = AnnotationTypes._prop_aliases.get(self._type.shortname, {})
-        for alias_rep, alias_group in prop_aliases.items():
-            if key_to_add in alias_group:
-                for alias in alias_group:
-                    if alias != key_to_add:
-                        self._props_ephemeral[alias] = val_to_add
-                        if alias in self.properties.keys():
-                            warning_msg = (f'Both "{key_to_add}" and "{alias}" are in the properties of "{self.id}", '
-                                           f'however ')
-                            if alias == alias_rep:
-                                warning_msg += f'"{key_to_add}" is an alias of "{alias_rep}".'
-                            else:
-                                warning_msg += f'"{key_to_add}" and "{alias}" are both aliases of "{alias_rep}".'
-                            warning_msg += f'Having two synonyms in the same annotation can cause unexpected behavior. '
-                            warnings.warn(warning_msg, UserWarning)
+    def _add_ephemeral_defaults(self, defaults: typing.Mapping[str, typing.Any]) -> None:
+        """
+        Distributes view-level defaults (from the ``contains`` metadata of the
+        parent view) to this annotation as ephemeral properties, under their
+        canonical names. An annotation-level value takes precedence over a
+        view-level default, so a default is skipped when the annotation
+        carries the property itself.
+
+        :param defaults: property defaults for this annotation's ``@type``
+        """
+        for name, value in defaults.items():
+            name = canonicalize_prop_name(self._type, name)
+            if name not in self.properties:
+                self._props_ephemeral[name] = value
 
     def is_type(self, at_type: Union[str, ThingTypesBase]) -> bool:
         """
@@ -239,7 +263,9 @@ class Annotation(MmifObject):
     def add_property(self, name: str,
                      value: Union[PRMTV_TYPES, LIST_PRMTV, LIST_LIST_PRMTV, DICT_PRMTV, DICT_LIST_PRMTV]) -> None:
         """
-        Adds a property to the annotation's properties.
+        Adds a property to the annotation's properties. A deprecated spelling
+        of an aliased property (e.g. ``frameType``) is stored under its
+        canonical name (``label``), with a :class:`DeprecationWarning`.
 
         :param name: the name of the property
         :param value: the property's desired value
@@ -252,14 +278,14 @@ class Annotation(MmifObject):
         #                      "either string, number, boolean, None, a JSON array of them, "
         #                      "or a JSON object of them keyed by strings."
         #                      f"(\"{name}\": \"{str(value)}\"")
-        self._add_prop_aliases(name, value)
 
     def __getitem__(self, prop_name: str):
         if prop_name in {'at_type', '@type'}:
             return str(self._type)
         elif prop_name == 'properties':
             return self.properties
-        elif prop_name in self.properties:
+        prop_name = canonicalize_prop_name(self._type, prop_name)
+        if prop_name in self.properties:
             return self.properties[prop_name]
         elif prop_name in self._props_ephemeral:
             return self._props_ephemeral[prop_name]
@@ -279,7 +305,9 @@ class Annotation(MmifObject):
         3. Special fields (``@type``, ``properties``)
 
         This allows convenient access to properties without explicitly
-        checking the ``properties`` object or view-level metadata.
+        checking the ``properties`` object or view-level metadata. A
+        deprecated spelling of an aliased property (e.g. ``frameType``)
+        resolves to the canonical property (``label``).
 
         :param prop_name: The name of the property to retrieve
         :param default: The value to return if the property is not found (default: None)
@@ -318,23 +346,6 @@ class Annotation(MmifObject):
         except KeyError:
             return False
     
-    def _get_label(self) -> str:
-        """
-        Another prototypical method to handle property aliases.
-        See :meth:`.Annotation._add_prop_aliases` for more details on 
-        what property aliases are.
-        Not recommended to use this method as `_add_prop_aliases` method 
-        is preferred. 
-        """
-        if 'label' in self:
-            return str(self.get('label'))
-        elif self._type.shortname == 'TimeFrame' and 'frameType' in self:
-            return str(self.get('frameType'))
-        elif self._type.shortname == 'BoundingBox' and 'boxType' in self:
-            return str(self.get('boxType'))
-        else:
-            raise KeyError("No label found in this annotation.")
-    
     def is_document(self):
         return isinstance(self._type, DocumentTypesBase)
 
@@ -356,8 +367,14 @@ class Document(Annotation):
         # see https://github.com/clamsproject/mmif-python/issues/226 for discussion
         # around the use of these three dictionaries
         # (names changed since, `existing` >> `ephemeral` and `temporary` >> `pending`)
-        self._props_original: DocumentProperties = DocumentProperties()
-        self._props_pending: AnnotationProperties = AnnotationProperties()
+        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'))
         
         self._type: Union[ThingTypesBase, DocumentTypesBase] = ThingTypesBase('')
@@ -578,6 +595,7 @@ class AnnotationProperties(MmifObject, MutableMapping[str, T]):
     """
 
     def __delitem__(self, key: str) -> None:
+        key = self._canonical(key)
         frm = None
         for k in self.__iter__():
             if k == key:
@@ -593,36 +611,83 @@ class AnnotationProperties(MmifObject, MutableMapping[str, T]):
             del frm[key]
         else:
             raise KeyError(f'Key "{key}" not found.')
-                
+
     def __iter__(self) -> Iterator[str]:
         """
-        ``__iter__`` on Mapping should basically work as ``keys()`` method 
+        ``__iter__`` on Mapping should basically work as ``keys()`` method
         of vanilla dict.
         """
         for key in itertools.chain(self._named_attributes(), self._unnamed_attributes):
             yield key
-                
+
     def __getitem__(self, key):
         """
-        Parent MmifObject class has a __getitem__ method that checks if 
-        the value is empty when asked for an unnamed attribute. But for 
-        AnnotationProperties, any arbitrary property that's added 
-        explicitly by the user (developer) should not be ignored and 
-        returned even the value is empty. 
+        Parent MmifObject class has a __getitem__ method that checks if
+        the value is empty when asked for an unnamed attribute. But for
+        AnnotationProperties, any arbitrary property that's added
+        explicitly by the user (developer) should not be ignored and
+        returned even the value is empty.
         """
+        key = self._canonical(key)
         if key in self._named_attributes():
             return self.__dict__[key]
         else:
             return self._unnamed_attributes[key]
 
-    def __init__(self, mmif_obj: Optional[Union[bytes, str, dict]] = None, *_) -> None:
+    def __setitem__(self, key: str, value) -> None:
+        """
+        Sets a property. A deprecated spelling of an aliased property (e.g.
+        ``frameType``) is stored under its canonical name (``label``), with
+        a :class:`DeprecationWarning`.
+        """
+        canonical = self._canonical(key)
+        if canonical != key:
+            warnings.warn(f'"{key}" is a deprecated alias of "{canonical}", storing the value as "{canonical}".',
+                          DeprecationWarning)
+        super().__setitem__(canonical, value)
+
+    def __init__(self, mmif_obj: Optional[Union[bytes, str, dict]] = None,
+                 parent: Optional['Annotation'] = None, *_) -> None:
         self.id: str = ''
         # any individual at_type (subclassing this class) can have its own set of required attributes
         self._required_attributes = ["id"]
         # allowing additional attributes for arbitrary annotation properties
         self._unnamed_attributes = {}
+        # the Annotation these properties belong to; its `@type` decides which
+        # property names are aliases of each other (see `canonicalize_prop_name`)
+        self._parent_annotation = parent
+        self.reserved_names.add('_parent_annotation')
         super().__init__(mmif_obj)
 
+    def _canonical(self, key: str) -> str:
+        if self._parent_annotation is None:
+            return key
+        return canonicalize_prop_name(self._parent_annotation._type, key)
+
+    def _deserialize(self, input_dict: dict) -> None:
+        """
+        Deserializes the properties, rewriting deprecated spellings to their
+        canonical names so that there is one key per property. When two
+        spellings of the same property are present, the canonical one wins
+        (or the first one seen, when neither is canonical), with a warning.
+        """
+        canonical_dict = {}
+        # canonical name -> the deprecated spelling it was read from
+        from_alias = {}
+        for key, value in input_dict.items():
+            canonical = self._canonical(key)
+            if canonical in canonical_dict and (canonical != key or canonical in from_alias):
+                alias = key if canonical != key else from_alias[canonical]
+                warnings.warn(f'Both "{alias}" and "{canonical}" are in the properties of '
+                              f'"{input_dict.get("id", "")}", but "{alias}" is an alias of "{canonical}". '
+                              f'Keeping the value of "{canonical}".', UserWarning)
+                if canonical != key:
+                    continue
+            canonical_dict[canonical] = value
+            if canonical != key:
+                from_alias[canonical] = key
+        super()._deserialize(canonical_dict)
+
 
 class DocumentProperties(AnnotationProperties):
     """
@@ -632,7 +697,8 @@ class DocumentProperties(AnnotationProperties):
     :param mmif_obj: the JSON data that defines the properties
     """
 
-    def __init__(self, mmif_obj: Optional[Union[bytes, str, dict]] = None, *_) -> None:
+    def __init__(self, mmif_obj: Optional[Union[bytes, str, dict]] = None,
+                 parent: Optional['Annotation'] = None, *_) -> None:
         self.mime: str = ''
         # note the trailing underscore here. I wanted to use the name `location`
         # for @property in this class and `Document` class, so had to use a diff
@@ -643,9 +709,9 @@ class DocumentProperties(AnnotationProperties):
         self._attribute_classes = {'text': Text}
         # in theory, either `location` or `text` should appear in a `document`
         # but with current implementation, there's no easy way to set a condition 
-        # for `oneOf` requirement 
-        # see MmifObject::_required_attributes in model.py 
-        super().__init__(mmif_obj)
+        # for `oneOf` requirement
+        # see MmifObject::_required_attributes in model.py
+        super().__init__(mmif_obj, parent)
 
     def _deserialize(self, input_dict: dict) -> None:
         if "location" in input_dict:

{mmif_python-1.5.3 → 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]:
         """
@@ -276,25 +285,11 @@ class Mmif(MmifObject):
         super()._deserialize(input_dict)
         for view in self.views:
             view._parent_mmif = self
-            # this dict will be populated with properties 
-            # that are not encoded in individual annotations objects themselves
-            extrinsic_props = defaultdict(dict)
-            for at_type, type_lv_props in view.metadata.contains.items():
-                for prop_key, prop_value in type_lv_props.items():
-                    extrinsic_props[at_type][prop_key] = prop_value
             for ann in view.get_annotations():
                 ## for "capital" Annotation properties
-                # first add all extrinsic properties to the Annotation objects
-                # as "ephemeral" properties. A view-level `contains` default must
-                # not override an annotation-level value that is already present
-                # in `_props_ephemeral` -- namely an alias of a property set on the
-                # annotation itself (put there by `_add_prop_aliases` during the
-                # annotation's own deserialization, which runs earlier). Per the
-                # spec, the annotation-level value takes precedence over the
-                # view-level default.
-                for prop_key, prop_value in extrinsic_props[ann.at_type].items():
-                    if prop_key not in ann._props_ephemeral:
-                        ann._props_ephemeral[prop_key] = prop_value
+                # first, distribute view-level defaults from `contains` metadata
+                # to the Annotation objects as "ephemeral" properties
+                ann._add_ephemeral_defaults(view.metadata.contains.get(ann.at_type, {}))
                 # then, do the same to associated Document objects. Note that, 
                 # in a view, it is guaranteed that all Annotation objects are not duplicates
                 if ann.at_type == AnnotationTypes.Annotation:
@@ -350,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:
@@ -370,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:
@@ -777,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.3 → 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]: