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

{mmif_python-1.2.0 → mmif_python-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmif-python
-Version: 1.2.0
+Version: 1.3.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
@@ -13,6 +13,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: orderly-set==5.3.*
 Requires-Dist: jsonschema
+Requires-Dist: pydantic>=2.0
 Provides-Extra: seq
 Requires-Dist: numpy; extra == "seq"
 Provides-Extra: cv
@@ -38,20 +39,22 @@ 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](https://mmif.clams.ai) is a JSON(-LD)-based data format designed for transferring annotation data between computational analysis applications of the [CLAMS project](https://clams.ai).
 
 
 ## mmif-python
-`mmif-python` is a Python implementation of the MMIF data format. 
-`mmif-python` provides various helper classes and functions to handle MMIF JSON in Python, 
-including ; 
 
-1. de-/serialization of MMIF internal data structures to/from JSON
+`mmif-python` is a Python implementation of the MMIF data format. It provides various helper classes and functions to handle MMIF JSON in Python, including:
+
+1. serialization and de-serialization of MMIF internal data structures to/from JSON
 2. validation of MMIF JSON
 3. handling of CLAMS vocabulary types
-4. navigation of MMIF object via various "search" methods (e.g. `mmif.get_all_views_contain(vocab_type))`)
+4. navigation of MMIF objects via various "search" methods (e.g. `mmif.get_all_views_contain(vocab_type)`)
 
 ## For more ...
+
 * [Version history and patch notes](https://github.com/clamsproject/mmif-python/blob/main/CHANGELOG.md)
-* [MMIF Python API documentation](https://clamsproject.github.io/mmif-python)
+* [MMIF Python API documentation](https://clamsproject.github.io/mmif-python/latest)
 * [MMIF JSON specification and schema](https://clamsproject.github.io/mmif)
+* [Contributing guide](CONTRIBUTING.md)

{mmif_python-1.2.0 → mmif_python-1.3.0}/README.md

@@ -1,18 +1,20 @@
 ## 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](https://mmif.clams.ai) is a JSON(-LD)-based data format designed for transferring annotation data between computational analysis applications of the [CLAMS project](https://clams.ai).
 
 
 ## mmif-python
-`mmif-python` is a Python implementation of the MMIF data format. 
-`mmif-python` provides various helper classes and functions to handle MMIF JSON in Python, 
-including ; 
 
-1. de-/serialization of MMIF internal data structures to/from JSON
+`mmif-python` is a Python implementation of the MMIF data format. It provides various helper classes and functions to handle MMIF JSON in Python, including:
+
+1. serialization and de-serialization of MMIF internal data structures to/from JSON
 2. validation of MMIF JSON
 3. handling of CLAMS vocabulary types
-4. navigation of MMIF object via various "search" methods (e.g. `mmif.get_all_views_contain(vocab_type))`)
+4. navigation of MMIF objects via various "search" methods (e.g. `mmif.get_all_views_contain(vocab_type)`)
 
 ## For more ...
+
 * [Version history and patch notes](https://github.com/clamsproject/mmif-python/blob/main/CHANGELOG.md)
-* [MMIF Python API documentation](https://clamsproject.github.io/mmif-python)
+* [MMIF Python API documentation](https://clamsproject.github.io/mmif-python/latest)
 * [MMIF JSON specification and schema](https://clamsproject.github.io/mmif)
+* [Contributing guide](CONTRIBUTING.md)

mmif_python-1.3.0/VERSION

@@ -0,0 +1 @@
+1.3.0

{mmif_python-1.2.0 → mmif_python-1.3.0}/mmif/__init__.py

@@ -34,28 +34,28 @@ def find_all_modules(pkgname):
 
 
 def prep_argparser_and_subcmds():
-    parser = argparse.ArgumentParser()
+    parser = argparse.ArgumentParser(prog='mmif')
     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 = {}
+    subcmds = {}
     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
+        subcmds[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,
                               )
+    return parser, subparsers, subcmds
+
+
+def cli():
+    parser, subparsers, cli_modules = prep_argparser_and_subcmds()
     if len(sys.argv) == 1:
         parser.print_help(sys.stderr)
         sys.exit(1)

{mmif_python-1.2.0 → mmif_python-1.3.0}/mmif/serialize/__init__.py

@@ -1,3 +1,7 @@
+"""
+Core package to provide serialization and deserialization of MMIF format.
+"""
+
 from .annotation import *
 from .annotation import __all__ as anno_all
 from .mmif import *

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

@@ -2,7 +2,7 @@
 The :mod:`annotation` module contains the classes used to represent a
 MMIF annotation as a live Python object.
 
-In MMIF, annotations are created by apps in a pipeline as a part
+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`.
 """
@@ -374,7 +374,7 @@ class Document(Annotation):
 
         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.
+        object. See :meth:`mmif.serialize.mmif.Mmif.generate_capital_annotations` for more.
 
         A few notes to keep in mind:
 
@@ -442,7 +442,7 @@ class Document(Annotation):
         See Also
         --------
         add_property : Add a new property to the document
-        Mmif.generate_capital_annotations : How pending properties are serialized
+        mmif.serialize.mmif.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

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

@@ -14,8 +14,8 @@ import json
 import math
 import warnings
 from collections import defaultdict
-from datetime import datetime
-from typing import List, Union, Optional, Dict, cast, Iterator
+from datetime import datetime, timezone
+from typing import Any, List, Union, Optional, Dict, cast, Iterator
 
 import jsonschema.validators
 
@@ -24,7 +24,7 @@ from mmif import ThingTypesBase
 from mmif.serialize.annotation import Annotation, Document
 from mmif.serialize.model import MmifObject, DataList
 from mmif.serialize.view import View
-from mmif.vocabulary import AnnotationTypes, DocumentTypes
+from mmif.vocabulary import AnnotationTypes, DocumentTypesBase
 
 __all__ = ['Mmif']
 
@@ -433,7 +433,7 @@ class Mmif(MmifObject):
         """
         new_view = View()
         new_view.id = self.new_view_id()
-        new_view.metadata.timestamp = datetime.now()
+        new_view.metadata.timestamp = datetime.now(timezone.utc)
         self.add_view(new_view)
         return new_view
 
@@ -487,11 +487,11 @@ class Mmif(MmifObject):
         else:
             return []
 
-    def get_documents_by_type(self, doc_type: Union[str, DocumentTypes]) -> List[Document]:
+    def get_documents_by_type(self, doc_type: DocumentTypesBase) -> List[Document]:
         """
         Method to get all documents where the type matches a particular document type, which should be one of the CLAMS document types.
 
-        :param doc_type: the type of documents to search for, must be one of ``Document`` type defined in the CLAMS vocabulary.
+        :param doc_type: the type of documents to search for, must be one of ``Document`` types defined in the CLAMS vocabulary.
         :return: a list of documents matching the requested type, or an empty list if none found.
         """
         docs = []
@@ -530,7 +530,7 @@ class Mmif(MmifObject):
         docs.extend([document for document in self.documents if document[prop_key] == prop_value])
         return docs
 
-    def get_documents_locations(self, m_type: Union[DocumentTypes, str], path_only=False) -> List[Union[str, None]]:
+    def get_documents_locations(self, m_type: Union[DocumentTypesBase, str], path_only=False) -> List[Union[str, None]]:
         """
         This method returns the file paths of documents of given type.
         Only top-level documents have locations, so we only check them.
@@ -545,7 +545,7 @@ class Mmif(MmifObject):
         else:
             return [doc.location for doc in docs]
 
-    def get_document_location(self, m_type: Union[DocumentTypes, str], path_only=False) -> Optional[str]:
+    def get_document_location(self, m_type: Union[DocumentTypesBase, str], path_only=False) -> Optional[str]:
         """
         Method to get the location of *first* document of given type.
 
@@ -635,7 +635,7 @@ class Mmif(MmifObject):
     def get_views_for_document(self, doc_id: str) -> List[View]:
         """
         Returns the list of all views that have annotations anchored on a particular document.
-        Note that when the document is inside a view (generated during the pipeline's running),
+        Note that when the document is inside a view (generated during the workflow's running),
         doc_id must be prefixed with the view_id.
         """
         views = []

{mmif_python-1.2.0 → mmif_python-1.3.0}/mmif/serialize/model.py

@@ -402,7 +402,10 @@ class MmifObjectEncoder(json.JSONEncoder):
         if hasattr(obj, '_serialize'):
             return obj._serialize()
         elif hasattr(obj, 'isoformat'):         # for datetime objects
-            return obj.isoformat()
+            s = obj.isoformat()
+            if s.endswith('+00:00'):
+                s = s[:-6] + 'Z'
+            return s
         elif hasattr(obj, '__str__'):
             return str(obj)
         else:

{mmif_python-1.2.0 → mmif_python-1.3.0}/mmif/serialize/view.py

@@ -2,7 +2,7 @@
 The :mod:`view` module contains the classes used to represent a MMIF view
 as a live Python object.
 
-In MMIF, views are created by apps in a pipeline that are annotating
+In MMIF, views are created by apps in a workflow that are annotating
 data that was previously present in the MMIF file.
 
 The :class:`View` class is a high-level container that provides convenient

mmif_python-1.3.0/mmif/utils/__init__.py

@@ -0,0 +1,4 @@
+"""
+Package containing utility modules for handling different types of source
+documents, and general implementation of common data structures and algorithms.
+"""

mmif_python-1.3.0/mmif/utils/cli/__init__.py

@@ -0,0 +1,226 @@
+"""
+Package containing CLI modules.
+"""
+
+import contextlib
+import io
+import os
+import sys
+from typing import Iterator, Optional, TextIO, Type, Union, cast, get_args, get_origin
+
+from pydantic import BaseModel
+
+
+@contextlib.contextmanager
+def open_cli_io_arg(
+    path_or_dash: Optional[str],
+    mode: str = "r",
+    encoding: Optional[str] = None,
+    errors: Optional[str] = None,
+    default_stdin: bool = False,
+) -> Iterator[TextIO]:
+    """
+    Context manager for opening files with stdin/stdout support.
+
+    This function is intended for plain text streams (e.g. JSON/MMIF) and does
+    not support binary modes (e.g., 'rb', 'wb').
+
+    This is a native replacement for argparse.FileType which is deprecated as
+    of Python 3.14 due to resource leak issues. Unlike FileType, this defers
+    file opening until actually needed and ensures proper cleanup via context
+    manager.
+
+    Handles the common CLI pattern where:
+
+    - '-' means stdin (read mode) or stdout (write mode)
+    - None means "argument not provided"; when default_stdin=True, it falls back
+      to stdin/stdout
+    - Regular paths open actual files with proper resource management
+
+    :param path_or_dash: File path, '-' for stdin/stdout, or None for no argument
+    :param mode: File mode ('r' for reading, 'w' for writing). Binary modes are
+        not supported.
+    :param encoding: Optional file encoding
+    :param errors: Optional error handling strategy for encoding
+    :param default_stdin: If True and path_or_dash is None, default to stdin
+        (mode 'r') or stdout (mode 'w')
+    :returns: Context manager yielding text-mode file handle
+    :rtype: Iterator[TextIO]
+
+    Example usage::
+
+        # Read from file or stdin
+        with open_cli_io_arg(args.input, 'r', default_stdin=True) as f:
+            content = f.read()
+
+        # Write to file or stdout
+        with open_cli_io_arg(args.output, 'w', default_stdin=True) as f:
+            f.write(content)
+    """
+    # Valid text modes for file operations
+    _READ_FLAGS = frozenset({"r", "+"})
+    _WRITE_FLAGS = frozenset({"w", "a", "x", "+"})
+
+    if "b" in mode:
+        raise ValueError(
+            f"Binary mode '{mode}' is not supported. "
+            "Use text modes ('r', 'w', 'a', 'x') instead."
+        )
+
+    needs_read = bool(set(mode) & _READ_FLAGS)
+    needs_write = bool(set(mode) & _WRITE_FLAGS)
+
+    should_use_stdio = path_or_dash == "-" or (path_or_dash is None and default_stdin)
+
+    file_handle: Optional[TextIO] = None
+    should_close = False
+
+    try:
+        if should_use_stdio:
+            if needs_read and needs_write:
+                raise ValueError(
+                    f"Mode '{mode}' not supported with stdin/stdout "
+                    "(use read or write only)"
+                )
+
+            if needs_read:
+                # Check for missing input when stdin is a terminal
+                if path_or_dash is None and default_stdin and sys.stdin.isatty():
+                    raise SystemExit("error: No input provided.")
+                file_handle = sys.stdin
+
+            elif needs_write:
+                file_handle = sys.stdout
+
+            else:
+                raise ValueError(
+                    f"Mode '{mode}' not supported with stdin/stdout (use 'r' or 'w')"
+                )
+
+        elif isinstance(path_or_dash, str):
+            if needs_read and not os.path.exists(path_or_dash):
+                raise FileNotFoundError(f"Input path does not exist: {path_or_dash}")
+            file_handle = cast(
+                TextIO, io.open(path_or_dash, mode, encoding=encoding, errors=errors)
+            )
+            should_close = True
+
+        elif path_or_dash is None:
+            # None without default_stdin means no file specified
+            raise ValueError(
+                "No file path provided. Use '-' for stdin/stdout or set default_stdin=True."
+            )
+        else:
+            raise TypeError(
+                f"Invalid type for path_or_dash: {type(path_or_dash).__name__}. "
+                "Expected str or None."
+            )
+
+        if file_handle is not None:
+            yield file_handle
+
+    finally:
+        if should_close and file_handle is not None:
+            file_handle.close()
+
+
+def generate_model_summary(model: Type[BaseModel], indent: int = 0) -> str:
+    lines = []
+    prefix = " " * indent
+
+    # model_fields is a dictionary of FieldInfo objects
+    for name, field in model.model_fields.items():
+        # Get the alias if available, otherwise use the field name
+        field_name = field.alias if field.alias else name
+
+        # Get type annotation
+        type_annotation = field.annotation
+
+        def format_type(t) -> str:
+            origin = get_origin(t)
+            args = get_args(t)
+
+            # Handle Optional (Union[T, None])
+            if origin is Union and type(None) in args:
+                non_none_args = [arg for arg in args if arg is not type(None)]
+                if len(non_none_args) == 1:
+                    return f"{format_type(non_none_args[0])}, optional"
+
+            # Handle List
+            if origin is list:
+                if args:
+                    return f"[{format_type(args[0])}]"
+                return "[]"
+
+            # Handle Dict
+            if origin is dict:
+                return "obj"
+
+            # Handle Pydantic Models (Custom Classes)
+            if isinstance(t, type) and issubclass(t, BaseModel):
+                return "obj"
+
+            # Handle basic types and cleanup
+            t_str = str(t)
+            if t_str.startswith("<class '"):
+                t_str = t_str[8:-2]
+            if t_str.startswith("typing."):
+                t_str = t_str[7:]
+
+            # Remove module prefix if present
+            if "." in t_str:
+                t_str = t_str.split(".")[-1]
+
+            return t_str
+
+        display_type = format_type(type_annotation)
+
+        description = field.description if field.description else ""
+
+        line_content = f"{prefix}- {field_name} ({display_type})"
+        if description:
+            line_content += f": {description}"
+        lines.append(line_content)
+
+        # Check if it's a Pydantic model or a list/dict of Pydantic models
+        origin = get_origin(type_annotation)
+        args = get_args(type_annotation)
+
+        nested_model = None
+        # Handle Optional wrappers for nesting check
+        check_type = type_annotation
+        if origin is Union and type(None) in args:
+            non_none_args = [arg for arg in args if arg is not type(None)]
+            if len(non_none_args) == 1:
+                check_type = non_none_args[0]
+                origin = get_origin(check_type)
+                args = get_args(check_type)
+
+        if isinstance(check_type, type) and issubclass(check_type, BaseModel):
+            nested_model = check_type
+        elif (
+            origin is list
+            and args
+            and isinstance(args[0], type)
+            and issubclass(args[0], BaseModel)
+        ):
+            nested_model = args[0]
+        elif (
+            origin is dict
+            and args
+            and len(args) > 1
+            and isinstance(args[1], type)
+            and issubclass(args[1], BaseModel)
+        ):
+            nested_model = args[1]
+
+        if nested_model:
+            lines.append(generate_model_summary(nested_model, indent + 4))
+
+    return "\n".join(lines)
+
+
+# keep imports of CLI modules for historical reasons
+# keep them here in the bottom to avoid circular imports
+from mmif.utils.cli import rewind
+from mmif.utils.cli import source

mmif_python-1.3.0/mmif/utils/cli/describe.py

@@ -0,0 +1,144 @@
+import argparse
+import json
+import sys
+import textwrap
+from pathlib import Path
+from typing import Union, cast
+
+from mmif.utils.cli import open_cli_io_arg, generate_model_summary
+
+# gen_param_hash is imported for backward compatibility
+from mmif.utils.workflow_helper import (
+    CollectionMmifDesc,
+    SingleMmifDesc,
+    describe_mmif_collection,
+    describe_single_mmif,
+    generate_workflow_identifier,
+)
+
+
+def get_pipeline_specs(mmif_file: Union[str, Path]):
+    import warnings
+    warnings.warn("get_pipeline_specs is deprecated, use mmif.utils.workflow_helper.describe_single_mmif instead",
+                  DeprecationWarning)
+    return describe_single_mmif(mmif_file)
+
+
+def generate_pipeline_identifier(mmif_file: Union[str, Path]) -> str:
+    import warnings
+    warnings.warn("generate_pipeline_identifier is deprecated, use generate_workflow_identifier instead",
+                  DeprecationWarning)
+    return cast(str, generate_workflow_identifier(mmif_file))
+
+
+def describe_argparser():
+    oneliner = (
+        'Describe the workflow specification from a MMIF file or a '
+        'collection of MMIF files.'
+    )
+
+    additional = textwrap.dedent(f"""
+    This command extracts workflow information from a single MMIF file or 
+    a directory of MMIF files. The output is serialized as JSON.
+    
+    Output Schemas:
+    
+    1. Single MMIF File (mmif-file):
+{generate_model_summary(SingleMmifDesc, indent=4)}
+    
+    2. MMIF Collection (mmif-dir):
+{generate_model_summary(CollectionMmifDesc, indent=4)}
+    
+    Use `--help-schema` to inspect the full JSON schema for a specific output type.
+    """)
+    return oneliner, additional
+
+
+def prep_argparser(**kwargs):
+    parser = argparse.ArgumentParser(
+        description=describe_argparser()[1],
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        **kwargs
+    )
+    
+    parser.add_argument(
+        "MMIF_FILE",
+        nargs="?",
+        type=str,
+        default=None,
+        help='input MMIF file, a directory of MMIF files, or STDIN if `-` or not provided.'
+    )
+    parser.add_argument(
+        "-o", "--output",
+        type=str, default=None,
+        help='output file path, or STDOUT if not provided.'
+    )
+    parser.add_argument(
+        "-p", "--pretty",
+        action="store_true",
+        help="Pretty-print JSON output"
+    )
+    parser.add_argument(
+        "--help-schema",
+        nargs=1,
+        choices=["mmif-file", "mmif-dir"],
+        metavar="SCHEMA_NAME",
+        help="Print the JSON schema for the output. Options: mmif-file, mmif-dir."
+    )
+    return parser
+
+
+def main(args):
+    """
+    Main block for the describe CLI command.
+    This function basically works as a wrapper around
+    :func:`describe_single_mmif` (for single file input) or 
+    :func:`describe_mmif_collection` (for directory input).
+    """
+    if hasattr(args, 'help_schema') and args.help_schema is not None:
+        schema_name = args.help_schema[0]
+        if schema_name == 'mmif-file':
+            model_cls = SingleMmifDesc
+        elif schema_name == 'mmif-dir':
+            model_cls = CollectionMmifDesc
+        
+        schema = model_cls.model_json_schema()
+        print(json.dumps(schema, indent=2))
+        sys.exit(0)
+
+    output = {}
+    # if input is a directory
+    if Path(str(args.MMIF_FILE)).is_dir():
+        output = describe_mmif_collection(args.MMIF_FILE)
+    # if input is a file or stdin
+    else:
+        # Read MMIF content
+        with open_cli_io_arg(args.MMIF_FILE, 'r', default_stdin=True) as input_file:
+            mmif_content = input_file.read()
+
+        # For file input, we need to handle the path
+        # If input is from stdin, create a temp file
+        import tempfile
+        tmp_path = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                    mode='w', suffix='.mmif', delete=False
+            ) as tmp:
+                tmp.write(mmif_content)
+                tmp_path = Path(tmp.name)
+            output = describe_single_mmif(tmp_path)
+        finally:
+            if tmp_path and tmp_path.exists():
+                tmp_path.unlink()
+
+    if output:
+        # Convert Pydantic models to dicts
+        with open_cli_io_arg(args.output, 'w', default_stdin=True) as output_file:
+            json.dump(output, output_file, indent=2 if args.pretty else None)
+            output_file.write('\n')
+
+
+if __name__ == "__main__":
+    parser = prep_argparser()
+    args = parser.parse_args()
+    main(args)