mmif-python 1.0.19__tar.gz → 1.1.0__tar.gz

{mmif_python-1.0.19/mmif_python.egg-info → mmif_python-1.1.0}/PKG-INFO

@@ -1,18 +1,19 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: mmif-python
-Version: 1.0.19
+Version: 1.1.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
 Author-email: admin@clams.ai
 Classifier: Development Status :: 2 - Pre-Alpha
-Classifier: Intended Audience :: Developers 
+Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3 :: Only
-Requires-Python: >=3.8
+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
 Requires-Dist: numpy; extra == "seq"
@@ -20,11 +21,23 @@ Provides-Extra: cv
 Requires-Dist: pillow; extra == "cv"
 Requires-Dist: opencv-python; extra == "cv"
 Requires-Dist: ffmpeg-python; extra == "cv"
+Requires-Dist: wurlitzer; extra == "cv"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-pep8; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytype; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 ## MultiMedia Interchange Format
 [MMIF](https://mmif.clams.ai) is a JSON(-LD)-based data format designed for transferring annotation data between computational analysis applications in [CLAMS project](https://clams.ai). 

mmif_python-1.1.0/VERSION

@@ -0,0 +1 @@
+1.1.0

mmif_python-1.1.0/mmif/__init__.py

@@ -0,0 +1,66 @@
+from importlib.resources import files
+
+import argparse
+import importlib
+import pkgutil
+import sys
+
+# DO NOT CHANGE THIS ORDER, important to prevent circular imports
+from mmif.ver import __version__
+from mmif.ver import __specver__
+from mmif.vocabulary import *
+from mmif.serialize import *
+from mmif.utils.cli import rewind
+from mmif.utils.cli import source
+
+_res_pkg = 'res'
+_ver_pkg = 'ver'
+_vocabulary_pkg = 'vocabulary'
+_schema_res_name = 'mmif.json'
+version_template = "{} (based on MMIF spec: {})"
+
+
+def get_mmif_json_schema():
+    return files(f'{__package__}.{_res_pkg}').joinpath(_schema_res_name).read_text()
+
+
+def find_all_modules(pkgname):
+    parent = importlib.import_module(pkgname)
+    if not hasattr(parent, '__path__'):
+        raise ImportError(f"Error: '{pkgname}' is not a package.")
+    for importer, module, ispkg in pkgutil.walk_packages(parent.__path__, parent.__name__ + '.'):
+        if not ispkg:  # Only process modules, not subpackages themselves
+            yield importlib.import_module(module)
+
+
+def prep_argparser_and_subcmds():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        '-v', '--version',
+        action='version',
+        version=version_template.format(__version__, __specver__)
+    )
+    subparsers = parser.add_subparsers(title='sub-command', dest='subcmd')
+    return parser, subparsers
+
+
+def cli():
+    parser, subparsers = prep_argparser_and_subcmds()
+    cli_modules = {}
+    for cli_module in find_all_modules('mmif.utils.cli'):
+        cli_module_name = cli_module.__name__.rsplit('.')[-1]
+        cli_modules[cli_module_name] = cli_module
+        subcmd_parser = cli_module.prep_argparser(add_help=False)
+        subparsers.add_parser(cli_module_name, parents=[subcmd_parser],
+                              help=cli_module.describe_argparser()[0],
+                              description=cli_module.describe_argparser()[1],
+                              formatter_class=argparse.RawDescriptionHelpFormatter,
+                              )
+    if len(sys.argv) == 1:
+        parser.print_help(sys.stderr)
+        sys.exit(1)
+    args = parser.parse_args()
+    if args.subcmd not in cli_modules:
+        parser.print_help(sys.stderr)
+    else:
+        cli_modules[args.subcmd].main(args)

{mmif_python-1.0.19 → mmif_python-1.1.0}/mmif/res/clams.vocabulary.yaml

@@ -72,11 +72,25 @@ properties:
   label:
     type: String
     description: >-
-      A label given to this object by a classifier. The value must be a simple 
-      string value of the label and must be one of the values defined in the
-      <code>labelset</code> or <code>labelsetUri</code> annotation metadata.
+      A label given to this object by classification. The value must be a
+      simple string value of the label and must be one of the values 
+      defined in the <code>labelset</code> or <code>labelsetUri</code> 
+      annotation metadata. 
       <br><br>
-      [Note] Annotations from a classifier app must have this property.
+      For example, for the <code>Sentence</code> subtype, this could
+      be used to indicate the type of sentence, such as "declarative", 
+      "interrogative", "exclamatory", etc. For <code>NamedEntity</code> 
+      subtype, this could be used to indicate the type of named entity, 
+      such as "PER", "ORG", "LOC", "MISC" (following the CoNLL-2003 labels). 
+      <br><br>
+      For non-linguistic annotations, for example for <code>TimeFrame<code>, 
+      this could be used to indicate the type of the time frame, such as
+      "speech", "music", "noise", "bars-and-tones", etc, for acoustic 
+      classification. Or "slate", "lower-third", "credits" for visual 
+      classification of video frames.
+      <br><br>
+      [Note] Annotations from a type of classifier model must have this 
+      property.
   classifications:
     type: Map from String to Number
     description: >-
@@ -110,7 +124,9 @@ metadata:
     description: >-
       Specifies which unit of time the measurement is based. 
       Can be *seconds* or *milliseconds*, or in case of annotations on 
-      a VideoDocument, *frames*. 
+      a VideoDocument, *frames*. If not specified, *milliseconds* (in whole numbers) is assumed.
+      <br><br>
+      [Note] This metadata is only relevant for time-based annotations.
 
 ---
 
@@ -174,6 +190,115 @@ description: >-
   pointing directly into primary data (by using start and end offsets) or
   by linking to one or more other Annotations with the targets property.
 
+properties: 
+  text:
+    type: String
+    description: The surface string in the primary data covered by this span.
+---
+
+name: Token
+parent: Span
+
+similarTo:
+  - http://vocab.lappsgrid.org/Token
+
+description: >-
+  A string of one or more characters that serves as an indivisible unit 
+  for the purposes of morpho-syntactic labeling (part of speech tagging).
+
+properties:
+  pos:
+    type: String or URI
+    description: Part-of-speech tag associated with the token.
+  lemma:
+    type: String or URI
+    description: >-
+      The root (base) form associated with the token. URI may point to a 
+      lexicon entry.
+  orth:
+    type: String or URI
+    description: >-
+      Orthographic properties of the token such as LowerCase, UpperCase, 
+      UpperInitial, etc. Ideally a URI referencing a pre-defined descriptor.
+
+---
+
+name: Sentence
+parent: Span
+
+similarTo:
+  - http://vocab.lappsgrid.org/Sentence
+
+description: >
+  A sequence of words capable of standing alone to make an assertion, ask a
+  question, or give a command, usually consisting of a subject and a predicate
+  containing a finite verb.
+
+---
+
+name: Paragraph
+parent: Span
+
+similarTo:
+  - http://vocab.lappsgrid.org/Paragraph
+
+description: >-
+  A division of a piece of writing, usually dealing with a single theme and 
+  indicated by a new line, indentation, and/or numbering.
+
+---
+
+name: NamedEntity
+parent: Span
+
+similarTo:
+  - http://vocab.lappsgrid.org/NamedEntity
+
+description: >-
+  A phrase that clearly identifies an individual from others that have similar 
+  attributes, such as the name of a person, organization, location, artifact, 
+  etc. as well as temporal expressions.
+
+---
+
+name: NounChunk
+parent: Span
+
+similarTo:
+  - http://vocab.lappsgrid.org/NounChunk
+
+description: >-
+  The initial portion of a non-recursive noun phrase up to the head, including 
+  determiners but not including postmodifying prepositional phrases or clauses.
+
+---
+
+name: VerbChunk
+parent: Span
+
+similarTo: 
+  - http://vocab.lappsgrid.org/VerbChunk
+  
+description: >-
+  Non-recursive verb groups, which include modals, auxiliary verbs, and medial
+  adverbs, and end at the head verb or predicate adjective.
+
+properties:
+  tense:
+    type: String or URI
+    description: >-
+      Provides tense information for the verb. Example values include BeVBG,
+      BeVBN, FutCon, HaveVBN, Pas, PasCon, PasPer, PasPerCon, Per, Pre, PreCon,
+      PrePer, PrePerCon, SimFut, SimPas, SimPre, none
+  voice:
+    type: String or URI
+    description: >-
+      Indicates if the verb group is active or passive. Possible values include
+      ACTIVE, PASSIVE, or NONE
+  neg:
+    type: String or URI
+    description: Indicates whether or not the verb is negated. Values include YES, NO.
+
 ---
 
 name: TimeFrame
@@ -195,7 +320,6 @@ properties:
       No longer encouraged to use, instead <code>label</code> property
       should replace this property.
 
-
 ---
 
 name: Chapter

{mmif_python-1.0.19 → mmif_python-1.1.0}/mmif/serialize/annotation.py

@@ -49,10 +49,9 @@ 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._parent_view_id = ''
         self._props_ephemeral: AnnotationProperties = AnnotationProperties()
         self._alignments = {}  # to hold alignment information (Alignment anno long_id -> aligned anno long_id)
-        self.reserved_names.update(('_parent_view_id', '_props_ephemeral', '_alignments'))
+        self.reserved_names.update(('_props_ephemeral', '_alignments'))
         if not hasattr(self, 'properties'):  # don't overwrite DocumentProperties on super() call
             self.properties: AnnotationProperties = AnnotationProperties()
             self._attribute_classes = {'properties': AnnotationProperties}
@@ -116,17 +115,18 @@ class Annotation(MmifObject):
         in `TimeFrame` and `BoundingBox` respectively.
         """
         prop_aliases = AnnotationTypes._prop_aliases.get(self._type.shortname, {})
-        for alias_reprep, alias_group in prop_aliases.items():
+        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'Found both "{key_to_add}" and "{alias}" in the properties of "{self.id}" annotation in "{self.parent}" view. '
-                            if alias == alias_reprep:
-                                warning_msg += f'However "{key_to_add}" is an alias of "{alias_reprep}".'
+                            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'However "{key_to_add}" and "{alias}" are boath aliases of "{alias_reprep}".'
+                                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)
 
@@ -134,6 +134,8 @@ class Annotation(MmifObject):
         """
         Check if the @type of this object matches.
         """
+        if isinstance(at_type, str):
+            at_type = ThingTypesBase.from_str(at_type)
         return self.at_type == at_type
 
     @property
@@ -149,13 +151,28 @@ class Annotation(MmifObject):
 
     @property
     def parent(self) -> str:
-        return self._parent_view_id
-
+        if self.id_delimiter in self.properties.id:
+            id_split = self.properties.id.split(self.id_delimiter)
+            if len(id_split) == 2:
+                return id_split[0]
+        raise ValueError(f'Annotation {self.id} does not have a parent view, or its ID does not follow the expected format. ')
+    
     @parent.setter
-    def parent(self, parent_view_id: str) -> None:
-        # I want to make this to accept `View` object as an input too,
-        # but import `View` will break the code due to circular imports
-        self._parent_view_id = parent_view_id
+    def parent(self, parent_id: str) -> None:
+        """
+        .. deprecated:: 1.1.0
+           Will be removed in 2.0.0. 
+           Setting parent ID is no longer allowed. Instead, the parent ID
+           should be prefixed to the annotation ID. 
+          
+        Sets the parent view ID of this annotation.
+        :param parent_id: 
+        """
+        warnings.warn(
+            "Setting parent ID is deprecated and nothing happened. Use prefixed annotation ID instead.",
+            DeprecationWarning
+        )
+
 
     @property
     def id(self) -> str:
@@ -167,17 +184,27 @@ class Annotation(MmifObject):
         
     @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
+        warnings.warn(
+            'long_id is deprecated. Use `id` instead. ', DeprecationWarning
+        )
+        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
+        warnings.warn(
+            'long_id is deprecated. Use `id` instead. ', DeprecationWarning
+        )
+        self.id = long_id
+    
+    @property
+    def _short_id(self) -> str:
+        # TODO (krim @ 6/27/25): DELETE THIS METHOD!
+        """
+        Method to directly get "short" form of the ID, not supposed to be used for general purpose, since 
+        we want to force usage of "long" form ID when recording and referring annotations. 
+        :return: 
+        """
+        return self.properties.id
     
     @staticmethod
     def check_prop_value_is_simple_enough(
@@ -215,14 +242,7 @@ class Annotation(MmifObject):
         #                      f"(\"{name}\": \"{str(value)}\"")
         self._add_prop_aliases(name, value)
 
-    def get(self, prop_name: str) -> Union['AnnotationProperties', PRMTV_TYPES, LIST_PRMTV, LIST_LIST_PRMTV, DICT_PRMTV, DICT_LIST_PRMTV]:
-        """
-        A special getter for Annotation properties. This is to allow for
-        directly accessing properties without having to go through the
-        properties object, or view-level annotation properties encoded in the 
-        ``view.metadata.contains`` dict. Note that the regular props will take 
-        the priority over the ephemeral props when there are conflicts.
-        """
+    def __getitem__(self, prop_name: str):
         if prop_name in {'at_type', '@type'}:
             return str(self._type)
         elif prop_name == 'properties':
@@ -234,14 +254,31 @@ class Annotation(MmifObject):
         else:
             raise KeyError(f"Property {prop_name} does not exist in this annotation.")
 
+    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
+        """
+        try:
+            return self.__getitem__(prop_name)
+        except KeyError:
+            return default
+
     get_property = get
 
-    def __getitem__(self, prop_name: str):
-        return self.get(prop_name)
-    
     def __contains__(self, item):
         try:
-            self.get(item)
+            self.__getitem__(item)
             return True
         except KeyError:
             return False
@@ -339,7 +376,7 @@ class Document(Annotation):
             else:
                 super().add_property(name, value)
 
-    def get(self, prop_name):
+    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 
@@ -448,13 +485,21 @@ class AnnotationProperties(MmifObject, MutableMapping[str, T]):
     """
 
     def __delitem__(self, key: str) -> None:
+        frm = None
         for k in self.__iter__():
             if k == key:
-                if k not in self._required_attributes:
-                    del self.__dict__[k]
-                else:
+                if k in self._required_attributes:
                     raise AttributeError(f'Cannot delete a required attribute "{key}"!')
-        raise KeyError(f'Key "{key}" not found.')
+                elif k in self._unnamed_attributes:
+                    frm = self._unnamed_attributes
+                    break
+                else:
+                    frm = self.__dict__
+                    break
+        if frm is not None:
+            del frm[key]
+        else:
+            raise KeyError(f'Key "{key}" not found.')
                 
     def __iter__(self) -> Iterator[str]:
         """
@@ -576,6 +621,11 @@ class DocumentProperties(AnnotationProperties):
             return "".join((parsed_location.netloc, parsed_location.path))
 
     def location_path(self) -> Optional[str]:
+        """
+        .. deprecated:: 1.0.2
+           Will be removed in 2.0.0. 
+           Use :meth:`location_path_resolved` instead.
+        """
         warnings.warn('location_path() is deprecated. Use location_path_resolved() instead.', DeprecationWarning)
         return self.location_path_resolved()