mmif-python 1.0.12__tar.gz → 1.0.14__tar.gz

{mmif-python-1.0.12/mmif_python.egg-info → mmif-python-1.0.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mmif-python
-Version: 1.0.12
+Version: 1.0.14
 Summary: Python implementation of MultiMedia Interchange Format specification. (https://mmif.clams.ai)
 Home-page: https://mmif.clams.ai
 Author: Brandeis Lab for Linguistics and Computation

mmif-python-1.0.14/VERSION

@@ -0,0 +1 @@
+1.0.14

{mmif-python-1.0.12 → mmif-python-1.0.14}/mmif/serialize/annotation.py

@@ -26,7 +26,7 @@ __all__ = ['Annotation', 'AnnotationProperties', 'Document', 'DocumentProperties
 
 T = TypeVar('T')
 LIST_PRMTV = typing.List[PRMTV_TYPES]  # list of values (most cases for annotation props)
-LIST_LIST_PRMTV = typing.List[LIST_PRMTV]   # list of list of values (e.g. for coordinates)
+LIST_LIST_PRMTV = typing.List[LIST_PRMTV]   # list of lists of values (e.g. for coordinates)
 DICT_PRMTV = typing.Dict[str, PRMTV_TYPES]  # dict of values (`text` prop of `TextDocument` and other complex props)
 DICT_LIST_PRMTV = typing.Dict[str, LIST_PRMTV]  # dict of list of values (even more complex props)
 
@@ -127,6 +127,20 @@ class Annotation(MmifObject):
     def id(self, aid: str) -> None:
         self.properties.id = aid
         
+    @property
+    def long_id(self) -> str:
+        if self.parent is not None and len(self.parent) > 0:
+            return f"{self.parent}{self.id_delimiter}{self.id}"
+        else:
+            return self.id
+    
+    @long_id.setter
+    def long_id(self, long_id: str) -> None:
+        if self.id_delimiter in long_id:
+            self.parent, self.id = long_id.split(self.id_delimiter)
+        else:
+            self.id = long_id
+    
     @staticmethod
     def check_prop_value_is_simple_enough(
             value: Union[PRMTV_TYPES, LIST_PRMTV, LIST_LIST_PRMTV, DICT_PRMTV, DICT_LIST_PRMTV]) -> bool:
@@ -401,26 +415,31 @@ class AnnotationProperties(MmifObject, MutableMapping[str, T]):
                 
     def __iter__(self) -> Iterator[str]:
         """
-        ``__iter__`` on Mapping should basically work as ``keys()`` method of vanilla dict
-        however, when MMIF objects are serialized, all optional (not in ``_req_atts``),
-        empty props are ignored (note that emtpy but required props are serialized 
-        with the *emtpy* value). 
-        Hence, this ``__iter__`` method should also work in the same way and 
-        ignore empty optional props. 
+        ``__iter__`` on Mapping should basically work as ``keys()`` method 
+        of vanilla dict.
         """
         for key in itertools.chain(self._named_attributes(), self._unnamed_attributes):
-            if key in self._required_attributes:
-                yield key
-            else:
-                try:
-                    self.__getitem__(key)
-                    yield key
-                except KeyError:
-                    pass
+            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. 
+        """
+        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:
         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 = {}
         super().__init__(mmif_obj)
 
 

{mmif-python-1.0.12 → mmif-python-1.0.14}/mmif/serialize/mmif.py

@@ -10,13 +10,13 @@ import math
 import warnings
 from collections import defaultdict
 from datetime import datetime
-from typing import List, Union, Optional, Dict, ClassVar, cast
+from typing import List, Union, Optional, Dict, cast
 
 import jsonschema.validators
+
 import mmif
 from mmif import ThingTypesBase
 from mmif.vocabulary import AnnotationTypes, DocumentTypes
-
 from .annotation import Annotation, Document
 from .model import MmifObject, DataList
 from .view import View
@@ -32,9 +32,6 @@ class Mmif(MmifObject):
     :param validate: whether to validate the data against the MMIF JSON schema.
     """
 
-    view_prefix: ClassVar[str] = 'v_'
-    id_delimiter: ClassVar[str] = ':'
-
     def __init__(self, mmif_obj: Optional[Union[bytes, str, dict]] = None, *, validate: bool = True) -> None:
         self.metadata: MmifMetadata = MmifMetadata()
         self.documents: DocumentsList = DocumentsList()
@@ -362,8 +359,8 @@ class Mmif(MmifObject):
         :return: a reference to the corresponding document, if it exists
         :raises KeyError: if there is no corresponding document
         """
-        if Mmif.id_delimiter in doc_id:
-            vid, did = doc_id.split(Mmif.id_delimiter)
+        if self.id_delimiter in doc_id:
+            vid, did = doc_id.split(self.id_delimiter)
             view = self[vid]
             if isinstance(view, View):
                 return view.get_document_by_id(did) 
@@ -410,8 +407,8 @@ class Mmif(MmifObject):
                     aligned_types = set()
                     for ann_id in [alignment['target'], alignment['source']]:
                         ann_id = cast(str, ann_id)
-                        if Mmif.id_delimiter in ann_id:
-                            view_id, ann_id = ann_id.split(Mmif.id_delimiter)
+                        if self.id_delimiter in ann_id:
+                            view_id, ann_id = ann_id.split(self.id_delimiter)
                             aligned_type = cast(Annotation, self[view_id][ann_id]).at_type
                         else:
                             aligned_type = cast(Annotation, alignment_view[ann_id]).at_type
@@ -438,8 +435,8 @@ class Mmif(MmifObject):
             except StopIteration:
                 # means search failed by the full doc_id string, 
                 # now try trimming the view_id from the string and re-do the search
-                if Mmif.id_delimiter in doc_id:
-                    vid, did = doc_id.split(Mmif.id_delimiter)
+                if self.id_delimiter in doc_id:
+                    vid, did = doc_id.split(self.id_delimiter)
                     if view.id == vid:
                         annotations = view.get_annotations(document=did)
                         try:
@@ -450,6 +447,16 @@ class Mmif(MmifObject):
                             pass
         return views
 
+    def get_all_views_with_error(self) -> List[View]:
+        """
+        Returns the list of all views in the MMIF that have errors. 
+        
+        :return: the list of views that contain errors but no annotations
+        """
+        return [v for v in self.views if v.has_error()]
+    
+    get_views_with_error = get_all_views_with_error
+            
     def get_all_views_contain(self, at_types: Union[ThingTypesBase, str, List[Union[str, ThingTypesBase]]]) -> List[View]:
         """
         Returns the list of all views in the MMIF if given types
@@ -464,11 +471,27 @@ class Mmif(MmifObject):
         else:
             return [view for view in self.views if at_types in view.metadata.contains]
 
-    def get_views_contain(self, at_types: Union[ThingTypesBase, str, List[Union[str, ThingTypesBase]]]) -> List[View]:
+    get_views_contain = get_all_views_contain
+    
+    def get_view_with_error(self) -> Optional[View]:
         """
-        An alias to `get_all_views_contain` method.
+        Returns the last view appended that contains an error.
+        
+        :return: the view, or None if no error is found
+        """
+        for view in reversed(self.views):
+            if view.has_error():
+                return view
+        return None
+    
+    def get_last_error(self) -> Optional[str]:
+        """
+        Returns the last error message found in the views.
+        
+        :return: the error message in human-readable format, or None if no error is found
         """
-        return self.get_all_views_contain(at_types)
+        v = self.get_view_with_error()
+        return v.get_error() if v is not None else None
 
     def get_view_contains(self, at_types: Union[ThingTypesBase, str, List[Union[str, ThingTypesBase]]]) -> Optional[View]:
         """
@@ -506,8 +529,8 @@ class Mmif(MmifObject):
         elif 'targets' in props:
             
             def get_target_ann(cur_ann, target_id):
-                if Mmif.id_delimiter not in target_id:
-                    target_id = Mmif.id_delimiter.join((cur_ann.parent, target_id))
+                if self.id_delimiter not in target_id:
+                    target_id = self.id_delimiter.join((cur_ann.parent, target_id))
                 return self.__getitem__(target_id)
             
             if not targets_sorted:
@@ -549,7 +572,7 @@ class Mmif(MmifObject):
         """
         if item in self._named_attributes():
             return self.__dict__[item]
-        split_attempt = item.split(Mmif.id_delimiter)
+        split_attempt = item.split(self.id_delimiter)
 
         document_result = self.documents.get(split_attempt[0])
         view_result = self.views.get(split_attempt[0])

{mmif-python-1.0.12 → mmif-python-1.0.14}/mmif/serialize/model.py

@@ -14,7 +14,7 @@ for the different components of MMIF is added in the subclasses.
 
 import json
 from datetime import datetime
-from typing import Union, Any, Dict, Optional, TypeVar, Generic, Generator, Iterator, Type, Set
+from typing import Union, Any, Dict, Optional, TypeVar, Generic, Generator, Iterator, Type, Set, ClassVar
 
 from deepdiff import DeepDiff
 
@@ -44,41 +44,48 @@ class MmifObject(object):
 
     1. _unnamed_attributes:
        Only can be either None or an empty dictionary. If it's set to None,
-       it means the class won't take any ``Additional Attributes`` in the JSON
-       schema sense. If it's a dict, users can throw any k-v pairs to the
-       class, EXCEPT for the reserved two key names.
+       it means the class won't take any ``Additional Attributes`` in the 
+       JSON schema sense. If it's an empty dict, users can throw any k-v 
+       pairs to the class, as long as the key is not a "reserved" name, 
+       and those additional attributes will be stored in this dict while
+       in memory. 
     2. _attribute_classes:
        This is a dict from a key name to a specific python class to use for
        deserialize the value. Note that a key name in this dict does NOT
        have to be a *named* attribute, but is recommended to be one.
     3. _required_attributes:
-       This is a simple list of names of attributes that are required in the object.
-       When serialize, an object will skip its *empty* (e.g. zero-length, or None)
-       attributes unless they are in this list. Otherwise, the serialized JSON
-       string would have empty representations (e.g. ``""``, ``[]``).
+       This is a simple list of names of attributes that are required in 
+       the object. When serialize, an object will skip its *empty* (e.g. 
+       zero-length, or None) attributes unless they are in this list. 
+       Otherwise, the serialized JSON string would have empty 
+       representations (e.g. ``""``, ``[]``).
     4. _exclude_from_diff:
-       This is a simple list of names of attributes that should be excluded from
-       the diff calculation in ``__eq__``. 
+       This is a simple list of names of attributes that should be excluded 
+       from the diff calculation in ``__eq__``. 
 
     # TODO (krim @ 8/17/20): this dict is however, a duplicate with the type hints in the class definition.
-    Maybe there is a better way to utilize type hints (e.g. getting them as a programmatically), but for now
-    developers should be careful to add types to hints as well as to this dict.
+    Maybe there is a better way to utilize type hints (e.g. getting them 
+    as a programmatically), but for now developers should be careful to 
+    add types to hints as well as to this dict.
 
     Also note that those special attributes MUST be set in the __init__()
     before calling super method, otherwise deserialization will not work.
 
     And also, a subclass that has one or more *named* attributes, it must
-    set those attributes in the __init__() before calling super method. When
-    serializing a MmifObject, all *empty* attributes will be ignored, so for
-    optional named attributes, you must leave the values empty (len == 0), but
-    NOT None. Any None-valued named attributes will cause issues with current
-    implementation.
+    set those attributes in the __init__() before calling super method. 
+    When serializing a MmifObject, all *empty* attributes will be ignored, 
+    so for optional named attributes, you must leave the values empty 
+    (len == 0), but NOT None. Any None-valued named attributes will cause 
+    issues with current implementation.
 
     :param mmif_obj: JSON string or `dict` to initialize an object.
      If not given, an empty object will be initialized, sometimes with
      an ID value automatically generated, based on its parent object.
     """
     
+    view_prefix: ClassVar[str] = 'v_'
+    id_delimiter: ClassVar[str] = ':'
+
     # these are the reserved names that cannot be used as attribute names, and 
     # they won't be serialized
     reserved_names: Set[str] = {
@@ -269,8 +276,8 @@ class MmifObject(object):
         """
         Returns number of attributes that are not *empty*. 
         """
-        return sum([named in self and not self.is_empty(self[named]) for named in self._named_attributes()]) \
-               + (len(self._unnamed_attributes) if self._unnamed_attributes else 0)
+        return (sum([named in self and not self.is_empty(self[named]) for named in self._named_attributes()]) 
+                + (len(self._unnamed_attributes) if self._unnamed_attributes else 0))
 
     def __setitem__(self, key, value) -> None:
         if key in self.reserved_names:

{mmif-python-1.0.12 → mmif-python-1.0.14}/mmif/serialize/view.py

@@ -5,6 +5,7 @@ as a live Python object.
 In MMIF, views are created by apps in a pipeline that are annotating
 data that was previously present in the MMIF file.
 """
+import json
 from datetime import datetime
 from typing import Dict, Union, Optional, Generator, List, cast
 
@@ -230,6 +231,23 @@ class View(MmifObject):
     def set_error(self, err_message: str, err_trace: str) -> None:
         self.metadata.set_error(err_message, err_trace)
         self.annotations.empty()
+    
+    def get_error(self) -> Optional[str]:
+        """
+        Get the "text" representation of the error occurred during 
+        processing. Text representation is supposed to be human-readable. 
+        When ths view does not have any error, returns None.
+        """
+        if self.has_error():
+            return self.metadata.get_error_as_text()
+        else:
+            return None
+
+    def has_error(self) -> bool:
+        return self.metadata.has_error()
+
+    def has_warnings(self):
+        return self.metadata.has_warnings()
 
 
 class ViewMetadata(MmifObject):
@@ -267,7 +285,24 @@ class ViewMetadata(MmifObject):
         if not (self.contains.items() or self.error or self.warnings):
             serialized['contains'] = {}
         return serialized
-
+    
+    def has_error(self) -> bool:
+        return len(self.error) > 0
+    
+    def has_warnings(self):
+        return len(self.warnings) > 0
+    
+    def get_error_as_text(self) -> str:
+        if self.has_error():
+            if isinstance(self.error, ErrorDict):
+                return str(self.error)
+            elif isinstance(self.error, dict):
+                return f"Error: {json.dumps(self.error, indent=2)}"
+            else:
+                return f"Error (unknown error format): {self.error}"
+        else:
+            raise KeyError(f"No error found")
+            
     def new_contain(self, at_type: Union[str, ThingTypesBase], **contains_metadata) -> Optional['Contain']:
         """
         Adds a new element to the ``contains`` dictionary.
@@ -346,6 +381,9 @@ class ErrorDict(MmifObject):
         self.message: str = ''
         self.stackTrace: str = ''
         super().__init__(error_obj)
+    
+    def __str__(self):
+        return f"({self.message})\n\n{self.stackTrace}"
         
 
 class Contain(DataDict[str, str]):

{mmif-python-1.0.12 → mmif-python-1.0.14}/mmif/utils/timeunit_helper.py

@@ -68,17 +68,17 @@ def convert(t: Union[int, float, str], in_unit: str, out_unit: str, fps: float)
     elif out_unit == 'frame':
         # ms>f
         if 'millisecond' == in_unit:
-            return int(t / 1000 * fps)
+            return round(t / 1000 * fps)
         # s>f
         elif 'second' == in_unit:
-            return int(t * fps)
+            return round(t * fps)
     # s>(ms or i)
     elif in_unit == 'second':
-        return int(t * 1000) if out_unit == 'millisecond' else _second_to_isoformat(t)
+        return round(t * 1000) if out_unit == 'millisecond' else _second_to_isoformat(t)
     # ms>(s or i)
     elif in_unit == 'millisecond':
         return t / 1000 if out_unit == 'second' else _millisecond_to_isoformat(t)
     # f>ms, f>s
     else:
-        return (t / fps) if out_unit == 'second' else (round(t / fps, 3) * 1000)  # pytype: disable=bad-return-type
+        return (t / fps) if out_unit == 'second' else round(round(t / fps, 3) * 1000)  # pytype: disable=bad-return-type
 

{mmif-python-1.0.12 → mmif-python-1.0.14}/mmif/utils/video_document_helper.py

@@ -1,6 +1,7 @@
 import importlib
 import warnings
 from typing import List, Union, Tuple
+import math
 
 import mmif
 from mmif import Annotation, Document, Mmif
@@ -124,22 +125,23 @@ def extract_mid_frame(mmif: Mmif, time_frame: Annotation, as_PIL: bool = False):
     return extract_frames_as_images(vd, [get_mid_framenum(mmif, time_frame)], as_PIL=as_PIL)[0]
 
 
-def sample_frames(start_frame: int, end_frame: int, sample_ratio: int = 1) -> List[int]:
+def sample_frames(start_frame: int, end_frame: int, sample_rate: float = 1) -> List[int]:
     """
     Helper function to sample frames from a time interval.
-    Can also be used as a "cutoff" function when used with ``start_frame==0`` and ``sample_ratio==1``.
+    Can also be used as a "cutoff" function when used with ``start_frame==0`` and ``sample_rate==1``.
     
     :param start_frame: start frame of the interval
     :param end_frame: end frame of the interval
-    :param sample_ratio: sample ratio (or step) to configure how often to take a frame, default is 1, meaning all consecutive frames are sampled
+    :param sample_rate: sampling rate (or step) to configure how often to take a frame, default is 1, meaning all consecutive frames are sampled
 
     """
-    sample_ratio = int(sample_ratio)
-    if sample_ratio < 1:
-        raise ValueError(f"Sample ratio must be greater than 1, but got {sample_ratio}")
+    if sample_rate < 1:
+        raise ValueError(f"Sample rate must be greater than 1, but got {sample_rate}")
     frame_nums: List[int] = []
-    for i in range(start_frame, end_frame, sample_ratio):
-        frame_nums.append(i)
+    cur_f = start_frame
+    while cur_f < end_frame:
+        frame_nums.append(math.ceil(cur_f))
+        cur_f += sample_rate
     return frame_nums
 
 

mmif-python-1.0.14/mmif/ver/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "1.0.14"
+__specver__ = "1.0.4"

{mmif-python-1.0.12 → mmif-python-1.0.14/mmif_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mmif-python
-Version: 1.0.12
+Version: 1.0.14
 Summary: Python implementation of MultiMedia Interchange Format specification. (https://mmif.clams.ai)
 Home-page: https://mmif.clams.ai
 Author: Brandeis Lab for Linguistics and Computation

mmif-python-1.0.12/VERSION

@@ -1 +0,0 @@
-1.0.12

mmif-python-1.0.12/mmif/ver/__init__.py

@@ -1,2 +0,0 @@
-__version__ = "1.0.12"
-__specver__ = "1.0.4"