mmif-python 1.1.1__tar.gz → 1.2.0__tar.gz

{mmif_python-1.1.1/mmif_python.egg-info → mmif_python-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmif-python
-Version: 1.1.1
+Version: 1.2.0
 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
@@ -11,7 +11,6 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: deepdiff>5
 Requires-Dist: orderly-set==5.3.*
 Requires-Dist: jsonschema
 Provides-Extra: seq

mmif_python-1.2.0/VERSION

@@ -0,0 +1 @@
+1.2.0

{mmif_python-1.1.1 → mmif_python-1.2.0}/mmif/serialize/annotation.py

@@ -74,10 +74,11 @@ class Annotation(MmifObject):
                             
     def _cache_alignment(self, alignment_ann: 'Annotation', alignedto_ann: 'Annotation') -> None:
         """
-        Cache alignment information. This cache will not be serialized. 
-        
+        Cache alignment information. This cache will not be serialized.
+
         :param alignment_ann: the Alignment annotation that has this annotation on one side
         :param alignedto_ann: the annotation that this annotation is aligned to (other side of Alignment)
+        :return: None
         """
         self._alignments[alignment_ann] = alignedto_ann
     
@@ -228,7 +229,7 @@ class Annotation(MmifObject):
                      value: Union[PRMTV_TYPES, LIST_PRMTV, LIST_LIST_PRMTV, DICT_PRMTV, DICT_LIST_PRMTV]) -> None:
         """
         Adds a property to the annotation's properties.
-        
+
         :param name: the name of the property
         :param value: the property's desired value
         :return: None
@@ -256,18 +257,41 @@ class Annotation(MmifObject):
 
     def get(self, prop_name: str, default=None):
         """
-        A getter for Annotation, will search for a property by its name, 
-        and return the value if found, or the default value if not found.
-        This is designed to allow for directly accessing properties without 
-        having to go through the properties object, or view-level 
-        annotation metadata (common properties) encoded in the 
-        ``view.metadata.contains`` dict. Note that the regular properties 
-        will take the priority over the view-level common properties when 
-        there are name conflicts.
-        
-        :param prop_name: the name of the property to get
-        :param default: the value to return if the property is not found
-        :return: the value of the property
+        Safe property access with optional default value.
+
+        Searches for an annotation property by name and returns its value,
+        or a default value if not found. This method searches in multiple
+        locations with the following priority:
+
+        1. Direct properties (in ``annotation.properties``)
+        2. Ephemeral properties (view-level metadata from ``contains``)
+        3. Special fields (``@type``, ``properties``)
+
+        This allows convenient access to properties without explicitly
+        checking the ``properties`` object or view-level metadata.
+
+        :param prop_name: The name of the property to retrieve
+        :param default: The value to return if the property is not found (default: None)
+        :return: The property value, or the default value if not found
+
+        Examples
+        --------
+        .. code-block:: python
+
+           # Access annotation properties:
+           label = annotation.get('label', default='unknown')
+           start_time = annotation.get('start', default=0)
+
+           # Access @type:
+           at_type = annotation.get('@type')
+
+           # Safe access with custom default:
+           targets = annotation.get('targets', default=[])
+
+        See Also
+        --------
+        __getitem__ : Direct property access that raises KeyError when not found
+        get_property : Alias for this method
         """
         try:
             return self.__getitem__(prop_name)
@@ -336,29 +360,32 @@ class Document(Annotation):
                      ) -> None:
         """
         Adds a property to the document's properties.
-        
-        Unlike the parent :class:`Annotation` class, added properties of a 
-        ``Document`` object can be lost during serialization unless it belongs 
-        to somewhere in a ``Mmif`` object. This is because we want to keep 
-        ``Document`` object as "read-only" as possible. Thus, if you want to add 
-        a property to a ``Document`` object, 
-        
-        * add the document to a ``Mmif`` object (either in the documents list or 
+
+        Unlike the parent :class:`Annotation` class, added properties of a
+        ``Document`` object can be lost during serialization unless it belongs
+        to somewhere in a ``Mmif`` object. This is because we want to keep
+        ``Document`` object as "read-only" as possible. Thus, if you want to add
+        a property to a ``Document`` object,
+
+        * add the document to a ``Mmif`` object (either in the documents list or
           in a view from the views list), or
         * directly write to ``Document.properties`` instead of using this method
-          (which is not recommended). 
-        
-        With the former method, the SDK will record the added property as a 
-        `Annotation` annotation object, separate from the original `Document` 
+          (which is not recommended).
+
+        With the former method, the SDK will record the added property as a
+        `Annotation` annotation object, separate from the original `Document`
         object. See :meth:`.Mmif.generate_capital_annotations()` for more.
-        
+
         A few notes to keep in mind:
-        
-        #. You can't overwrite an existing property of a ``Document`` object. 
-        #. A MMIF can have multiple ``Annotation`` objects with the same 
+
+        #. You can't overwrite an existing property of a ``Document`` object.
+        #. A MMIF can have multiple ``Annotation`` objects with the same
            property name but different values. When this happens, the SDK will
-           only keep the latest value (in order of appearances in views list) of 
+           only keep the latest value (in order of appearances in views list) of
            the property, effectively overwriting the previous values.
+
+        :param name: the name of the property
+        :param value: the property's desired value (note: Document accepts fewer value types than Annotation)
         """
         # we don't checking if this k-v already exists in _original (new props) or _ephemeral (read from existing MMIF)
         # because it is impossible to keep the _original updated when a new annotation is added (via `new_annotation`)
@@ -378,13 +405,44 @@ class Document(Annotation):
 
     def get(self, prop_name, default=None):
         """
-        A special getter for Document properties. The major difference from
-        the super class's :py:meth:`Annotation.get` method is that Document 
-        class has one more set of *"pending"* properties, that are added after 
-        the Document object is created and will be serialized as a separate 
-        :py:class:`Annotation` object of which ``@type = Annotation``. The 
-        pending properties will take the priority over the regular properties 
-        when there are conflicts.
+        Safe property access with optional default value for Document objects.
+
+        Searches for a document property by name and returns its value, or a
+        default value if not found. Documents have a more complex property
+        hierarchy than regular annotations:
+
+        Priority order (highest to lowest):
+        1. Special fields ('id', 'location')
+        2. Pending properties (added after creation, to be serialized as ``Annotation`` objects)
+        3. Ephemeral properties (from existing ``Annotation`` annotations or view metadata)
+        4. Original properties (in ``document.properties``)
+
+        This allows convenient access to all document properties regardless of
+        where they're stored internally.
+
+        :param prop_name: The name of the property to retrieve
+        :param default: The value to return if the property is not found (default: None)
+        :return: The property value, or the default value if not found
+
+        Examples
+        --------
+        .. code-block:: python
+
+           # Access document properties:
+           mime = document.get('mime', default='application/octet-stream')
+           location = document.get('location')
+
+           # Access properties added after creation (pending):
+           author = document.get('author', default='anonymous')
+           publisher = document.get('publisher')
+
+           # Access ephemeral properties from Annotation objects:
+           sentiment = document.get('sentiment', default='neutral')
+
+        See Also
+        --------
+        add_property : Add a new property to the document
+        Mmif.generate_capital_annotations : How pending properties are serialized
         """
         if prop_name == 'id':
             # because all three dicts have `id` key as required field, we need
@@ -399,7 +457,7 @@ class Document(Annotation):
         elif prop_name in self._props_ephemeral:
             return self._props_ephemeral[prop_name]
         else:
-            return super().get(prop_name)
+            return super().get(prop_name, default)
 
     get_property = get
     
@@ -559,8 +617,8 @@ class DocumentProperties(AnnotationProperties):
             self.location = input_dict.pop("location")
         super()._deserialize(input_dict)
 
-    def _serialize(self, alt_container: Optional[Dict] = None) -> dict:
-        serialized = super()._serialize()
+    def _serialize(self, *args, **kwargs) -> dict:
+        serialized = super()._serialize(**kwargs)
         if "location_" in serialized:
             serialized["location"] = serialized.pop("location_")
         return serialized

{mmif_python-1.1.1 → mmif_python-1.2.0}/mmif/serialize/mmif.py

@@ -2,6 +2,11 @@
 The :mod:`mmif` module contains the classes used to represent a full MMIF
 file as a live Python object.
 
+The :class:`Mmif` class is a high-level container that provides convenient
+string-based access to documents, views, and annotations via ``mmif[id]``.
+The underlying ``documents`` and ``views`` attributes are list-like collections
+that use integer indexing; use container-level access for ID-based lookups.
+
 See the specification docs and the JSON Schema file for more information.
 """
 
@@ -139,8 +144,35 @@ class Mmif(MmifObject):
     """
     MmifObject that represents a full MMIF file.
 
+    This is a high-level container object that provides convenient string-based
+    access to documents, views, and annotations using their IDs. The underlying
+    collections (``documents`` and ``views``) are list-like and use integer
+    indexing, but Mmif itself accepts string IDs for convenient access.
+
     :param mmif_obj: the JSON data
     :param validate: whether to validate the data against the MMIF JSON schema.
+
+    Examples
+    --------
+    Accessing objects by ID (high-level, convenient):
+
+    .. code-block:: python
+
+       mmif = Mmif(mmif_json)
+       doc = mmif['m1']              # Get document by ID
+       view = mmif['v1']             # Get view by ID
+       ann = mmif['v1:a1']           # Get annotation by long-form ID
+
+       # Safe access with default:
+       doc = mmif.get('m99', default=None)
+
+    Accessing via underlying lists (positional access):
+
+    .. code-block:: python
+
+       first_doc = mmif.documents[0]     # First document
+       last_view = mmif.views[-1]        # Last view
+       all_views = mmif.views[1:4]       # Slice of views
     """
 
     def __init__(self, mmif_obj: Optional[Union[bytes, str, dict]] = None, *, validate: bool = True) -> None:
@@ -179,17 +211,18 @@ class Mmif(MmifObject):
             json_str = json.loads(json_str)
         jsonschema.validators.validate(json_str, schema)
 
-    def serialize(self, pretty: bool = False, sanitize: bool = False, autogenerate_capital_annotations=True) -> str:
+    def serialize(self, sanitize: bool = False, autogenerate_capital_annotations: bool = True, **kwargs) -> str:
         """
         Serializes the MMIF object to a JSON string.
 
-        :param sanitize: If True, performs some sanitization of before returning 
+        :param sanitize: If True, performs some sanitization of before returning
             the JSON string. See :meth:`sanitize` for details.
-        :param autogenerate_capital_annotations: If True, automatically convert 
-            any "pending" temporary properties from `Document` objects to 
-            `Annotation` objects. See :meth:`generate_capital_annotations` for 
+        :param autogenerate_capital_annotations: If True, automatically convert
+            any "pending" temporary properties from `Document` objects to
+            `Annotation` objects. See :meth:`generate_capital_annotations` for
             details.
-        :param pretty: If True, returns string representation with indentation.
+        :param kwargs: Keyword arguments to pass to the parent's ``serialize``
+                       method (e.g., ``pretty=True``, ``include_context=False``).
         :return: JSON string of the MMIF object.
         """
         if autogenerate_capital_annotations:
@@ -197,7 +230,7 @@ class Mmif(MmifObject):
         # sanitization should be done after `Annotation` annotations are generated
         if sanitize:
             self.sanitize()
-        return super().serialize(pretty)
+        return super().serialize(**kwargs)
 
     def _deserialize(self, input_dict: dict) -> None:
         """
@@ -266,8 +299,8 @@ class Mmif(MmifObject):
         ## caching alignments
         if all(map(lambda x: x in alignment_ann.properties, ('source', 'target'))):
             try:
-                source_ann = self[alignment_ann.get('source')]
-                target_ann = self[alignment_ann.get('target')]
+                source_ann = self.__getitem__(alignment_ann.get('source'))
+                target_ann = self.__getitem__(alignment_ann.get('target'))
                 if isinstance(source_ann, Annotation) and isinstance(target_ann, Annotation):
                     source_ann._cache_alignment(alignment_ann, target_ann)
                     target_ann._cache_alignment(alignment_ann, source_ann)
@@ -408,13 +441,13 @@ class Mmif(MmifObject):
         """
         Appends a View object to the views list.
 
-        Fails if there is already a view with the same ID or a document 
+        Fails if there is already a view with the same ID or a document
         with the same ID in the MMIF object.
 
-        :param view: the Document object to add
+        :param view: the View object to add
         :param overwrite: if set to True, will overwrite
                           an existing view with the same ID
-        :raises KeyError: if ``overwrite`` is set to False and existing 
+        :raises KeyError: if ``overwrite`` is set to False and existing
                           object (document or view) with the same ID exists
         :return: None
         """
@@ -503,6 +536,7 @@ class Mmif(MmifObject):
         Only top-level documents have locations, so we only check them.
 
         :param m_type: the type to search for
+        :param path_only: if True, returns resolved file system paths instead of location URIs
         :return: a list of the values of the location fields in the corresponding documents
         """
         docs = [document for document in self.documents if document.is_type(m_type) and document.location is not None]
@@ -516,6 +550,7 @@ class Mmif(MmifObject):
         Method to get the location of *first* document of given type.
 
         :param m_type: the type to search for
+        :param path_only: if True, returns resolved file system path instead of location URI
         :return: the value of the location field in the corresponding document
         """
         # TODO (krim @ 8/10/20): Is returning the first location desirable?
@@ -568,6 +603,8 @@ class Mmif(MmifObject):
         """
         Finds views where alignments between two given annotation types occurred.
 
+        :param at_type1: the first annotation type to search for alignments
+        :param at_type2: the second annotation type to search for alignments
         :return: a dict that keyed by view IDs (str) and has lists of alignment Annotation objects as values.
         """
         v_and_a = {}
@@ -586,7 +623,7 @@ class Mmif(MmifObject):
                     aligned_types = set()
                     for ann_id in [alignment['target'], alignment['source']]:
                         ann_id = cast(str, ann_id)
-                        aligned_type = cast(Annotation, self[ann_id]).at_type
+                        aligned_type = cast(Annotation, self.__getitem__(ann_id)).at_type
                         aligned_types.add(aligned_type)
                     aligned_types = list(aligned_types)  # because membership check for sets also checks hash() values
                     if len(aligned_types) == 2 and at_type1 in aligned_types and at_type2 in aligned_types:
@@ -691,8 +728,8 @@ class Mmif(MmifObject):
         """
         Finds annotations that are anchored between the given time points.
 
-        :param start: the start time point in the unit of `input_unit`
-        :param end: the end time point in the unit of `input_unit`
+        :param start: the start time point
+        :param end: the end time point
         :param time_unit: the unit of the input time points. Default is `ms`.
         :param at_types: a list of annotation types to filter with. Any type in this list will be included in the return.
         :return: an iterator of Annotation objects that are anchored between the given time points
@@ -725,12 +762,12 @@ class Mmif(MmifObject):
     def _get_linear_anchor_point(self, ann: Annotation, targets_sorted=False, start: bool = True) -> Union[int, float]:
         # TODO (krim @ 2/5/24): Update the return type once timeunits are unified to `ms` as integers (https://github.com/clamsproject/mmif/issues/192)
         """
-        Retrieves the anchor point of the annotation. Currently, this method only supports linear anchors, 
+        Retrieves the anchor point of the annotation. Currently, this method only supports linear anchors,
         namely time and text, hence does not work with spatial anchors (polygons or video-object).
-        
+
         :param ann: An Annotation object that has a linear anchor point. Namely, some subtypes of `Region` vocabulary type.
-        :param start: If True, returns the start anchor point. Otherwise, returns the end anchor point. N/A for `timePoint` anchors.
         :param targets_sorted: If True, the method will assume that the targets are sorted in the order of the anchor points.
+        :param start: If True, returns the start anchor point. Otherwise, returns the end anchor point. N/A for `timePoint` anchors.
         :return: the anchor point of the annotation. 1d for linear regions (time, text)
         """
         props = ann.properties
@@ -745,10 +782,10 @@ class Mmif(MmifObject):
                 point = math.inf if start else -1
                 comp = min if start else max
                 for target_id in ann.get_property('targets'):
-                    point = comp(point, self._get_linear_anchor_point(self[target_id], start=start))
+                    point = comp(point, self._get_linear_anchor_point(self.__getitem__(target_id), start=start))
                 return point
             target_id = ann.get_property('targets')[0 if start else -1]
-            return self._get_linear_anchor_point(self[target_id], start=start)
+            return self._get_linear_anchor_point(self.__getitem__(target_id), start=start)
         elif (start and 'start' in props) or (not start and 'end' in props):
             return ann.get_property('start' if start else 'end')
         else:
@@ -766,50 +803,77 @@ class Mmif(MmifObject):
         """
         return self._get_linear_anchor_point(annotation, start=False)
 
-    def __getitem__(self, item: str) \
-            -> Union[Document, View, Annotation, MmifMetadata, DocumentsList, ViewsList]:
+    def __getitem__(self, item: str) -> Union[Document, View, Annotation, MmifMetadata]:
         """
-        index ([]) implementation for Mmif. This will try to find any object, given an identifier or an immediate 
-        attribute name. When nothing is found, this will raise an error rather than returning a None 
+        High-level string-based access to MMIF objects by their IDs.
+
+        This method provides convenient access to documents, views, and annotations
+        using their string identifiers. For long-form annotation IDs (format: ``V:A``),
+        performs a two-level search through the specified view.
+
+        Note: This is a high-level convenience method on the Mmif container itself.
+        The underlying ``documents`` and ``views`` collections are list-like and
+        only support integer indexing.
 
-        :raises KeyError: if the item is not found or if the search results are ambiguous
-        :param item: an attribute name or an object identifier (a document ID, a view ID, or an annotation ID). When 
-                     annotation ID is given as a "short" ID (without view ID prefix), the method will try to find a 
-                     match from the first view, and return immediately if found.
-        :return: the object searched for
-        :raise KeyError: if the item is not found or multiple objects are found with the same ID
+        :param item: An object identifier:
+                     - Document ID (e.g., 'm1', 'd1')
+                     - View ID (e.g., 'v1', 'v_0')
+                     - Annotation ID in long form (e.g., 'v1:a1', 'v1:tf1')
+                     - Attribute name (e.g., 'metadata', 'documents', 'views')
+        :return: The requested Document, View, Annotation, or attribute object
+        :raises KeyError: If the item is not found
+
+        Examples
+        --------
+        High-level access by ID:
+
+        .. code-block:: python
+
+           mmif = Mmif(mmif_json)
+
+           # Access documents:
+           doc = mmif['m1']           # Returns Document with ID 'm1'
+
+           # Access views:
+           view = mmif['v1']          # Returns View with ID 'v1'
+
+           # Access annotations (long-form ID):
+           ann = mmif['v1:a1']        # Returns Annotation from view v1
+
+           # Access attributes:
+           metadata = mmif['metadata']  # Returns MmifMetadata object
+
+           # Will raise KeyError:
+           doc = mmif['nonexistent']  # KeyError!
+
+        For list-style positional access, use the underlying collections:
+
+        .. code-block:: python
+
+           first_doc = mmif.documents[0]           # Integer index
+           second_view = mmif.views[1]             # Integer index
+
+        See Also
+        --------
+        get : Safe access with default value instead of raising KeyError
         """
         if item in self._named_attributes():
-            return self.__dict__[item]
+            return self.__dict__.__getitem__(item)
         if self.id_delimiter in item:
             vid, _ = item.split(self.id_delimiter, 1)
-            return self.views[vid].annotations[item]
+            view = self.views._items.get(vid)
+            if view is None:
+                raise KeyError(f"View with ID {vid} not found in the MMIF object.")
+            ann = view.annotations._items.get(item)
+            if ann is None:
+                raise KeyError(f"Annotation with ID {item} not found in the MMIF object.")
+            return ann
         else:
             # search for document first, then views
             # raise KeyError if nothing is found
-            try:
-                return self.documents.__getitem__(item)
-            except KeyError:
-                try:
-                    return self.views.__getitem__(item)
-                except KeyError:
+            ret = self.documents._items.get(item)
+            if ret is None:
+                ret = self.views._items.get(item)
+                if ret is None:
                     raise KeyError(f"Object with ID {item} not found in the MMIF object. ")
-    
-    def get(self, obj_id, default=None):
-        """
-        High-level getter for Mmif. This will try to find any object, given 
-        an identifier or an immediate attribute name. When nothing is found, 
-        this will return a default value instead of raising an error.
-
-        :param obj_id: an immediate attribute name or an object identifier 
-                     (a document ID, a view ID, or an annotation ID). When 
-                     annotation ID is given as a "short" ID (without view 
-                     ID prefix), the method will try to find a match from 
-                     the first view, and return immediately if found.
-        :param default: the default value to return if none is found
-        :return: the object searched for or the default value
-        """
-        try:
-            return self.__getitem__(obj_id)
-        except KeyError:
-            return default
+            return ret