mmif-python 1.5.0__tar.gz → 1.5.2__tar.gz

mmif_python-1.5.2/.github/workflows/release-check.yml

@@ -0,0 +1,11 @@
+name: "🔖 Release PR check"
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, edited]
+
+jobs:
+  release-check:
+    name: "🤙 Call SDK release-check workflow"
+    uses: clamsproject/.github/.github/workflows/sdk-release-check.yml@main

{mmif_python-1.5.0 → mmif_python-1.5.2}/CHANGELOG.md

@@ -1,4 +1,34 @@
 
+## releasing 1.5.1 (2026-06-19)
+### Overview
+This patch contains a bug fix in VDH that couldn't handle some mkv-contained video files (https://github.com/clamsproject/mmif-python/issues/390) , and some other minor documentation generation bugs.
+
+
+## releasing 1.5.0 (2026-05-27)
+### Overview
+
+Improves image-extraction API in `video_document_helper` for TP source tracking, restores the source-composition prefix in workflow identifiers, and fixes the versioned-docs publishing pipeline.
+
+### Additions
+
+* `extract_images_by_count_with_sources` and `extract_images_by_mode_with_sources`: new public functions in `mmif.utils.video_document_helper` that return per-image source IDs (or sampled timepoints in ms when a fallback path is used), so downstream apps can anchor each extracted image to a specific point in the source media (https://github.com/clamsproject/mmif-python/pull/385, https://github.com/clamsproject/mmif-python/issues/384).
+
+### Changes
+
+* `mmif.utils.video_document_helper`: renamed 
+    * `extract_timepoints_as_images` --> `extract_images_from_timepoints`, 
+    * `extract_target_frames` -->  `extract_images_by_count_with_sources` (alongside new bare `extract_images_by_count`), and 
+    * `extract_frames_by_mode` --> `extract_images_by_mode`. 
+    * The three pre-rename names remain importable as soft-deprecated aliases through 2.0.0 (https://github.com/clamsproject/mmif-python/pull/385).
+* `mmif.utils.workflow_helper.generate_workflow_identifier`: now prefixes a `source_composition` segment (`TextDocument-1-VideoDocument-1/...`) describing the top-level document mix in the input MMIF (https://github.com/clamsproject/mmif-python/pull/386).
+* `build-tools/docs.py`: versioned-docs build now works against pyproject-only tags, restoring docs publishing in the release workflow (https://github.com/clamsproject/mmif-python/pull/388, https://github.com/clamsproject/mmif-python/issues/387).
+
+> [!NOTE]
+> - `mmif describe` (and the underlying `mmif.utils.workflow_helper`) is still experimental and subject to change in future releases without notice. Backward compatibility is not guaranteed.
+> - The new `source_composition` prefix in `generate_workflow_identifier()` changes the format of returned identifiers. Downstream tools parsing the identifier path (e.g. for storage-directory routing) may need to account for the extra leading segment.
+
+
+
 ## releasing 1.4.0 (2026-04-22)
 ### Overview
 * This is minor level release that 1) replacing simple string enums in `mmif.vocabulary` with fully-fledged pydantic classes in `clams-vocabulary` package 2) deprecating framenum-based image extraction functions in VDH (frame numbers are no longer considered as proper timestamps)

{mmif_python-1.5.0 → mmif_python-1.5.2}/CONTRIBUTING.md

@@ -13,10 +13,17 @@ We follow a Gitflow-inspired branching model to maintain a stable `main` branch
     - Once work is complete, open a PR targeting the `develop` branch.
     - **Communication**: High-level discussion and planning should occur in the issue thread. The PR conversation is strictly for code review and implementation-specific feedback.
 5. **Releases**:
-    - When `develop` is ready for a new release, open a PR from `develop` to `main` using the "release" PR template.
+    - When `develop` is ready for a new release, open a PR from `develop` to `main` using the "release" PR template. See the **Releases** section below for the required title format and preparation steps.
     - After merging the release candidate into `main`, manually tag the commit with the version number. This tag triggers the automated CI/CD pipeline for publishing.
 6. **Branch Protection**: Both `main` and `develop` are protected branches. Direct pushes are disabled; all changes must be introduced via Pull Requests.
 
+## Releases
+
+Release PRs (from `develop` to `main`) are gated by the `release-check` CI workflow. Before opening one:
+
+1. Title the PR exactly `releasing X.Y.Z` (strict semver); `release-check` reads the version from the title.
+2. Run `python build-tools/prep_release.py X.Y.Z` and commit its changes. See inside the prep script to see what's actually prepared.
+
 ## CLI Scripts
 
 The `mmif` command-line interface supports subcommands (e.g., `mmif source`, `mmif describe`). These are implemented as Python modules in `mmif/utils/cli/`.
@@ -155,7 +162,7 @@ To build documentation for a specific historical version (e.g., `v1.0.0`):
 python3 build-tools/docs.py --build-ver v1.0.0
 ```
 
-This runs the build in a sandboxed temporary directory. The output will be in `docs-test/<version>`.
+This runs the build in a sandboxed temporary directory. A single `--build-ver` places the built docs **flat** in the output directory (`docs-test/` by default). The batch `--build-all-since` mode instead nests each version under a `<version>/` subdirectory of the output directory, so multiple versions can coexist. The flat single-version layout is what the CI docs-publish workflow relies on — it invokes `docs.py --build-ver <ver> --output-dir _docs` and uploads `_docs/` as-is, without needing to know whether the project is versioned.
 
 > [!NOTE]
 > In CI, documentation is built and published automatically by the `publish.yml` workflow via the shared `sdk-docs.yml`. The CI calls `docs.py --build-ver <version> --output-dir _docs`. All CLAMS SDK repos use the same `docs.py` CLI interface (`--build-ver`, `--output-dir`).

{mmif_python-1.5.0/mmif_python.egg-info → mmif_python-1.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmif-python
-Version: 1.5.0
+Version: 1.5.2
 Summary: Python implementation of MultiMedia Interchange Format specification. (https://mmif.clams.ai)
 License-Expression: Apache-2.0
 Project-URL: homepage, https://mmif.clams.ai

{mmif_python-1.5.0 → mmif_python-1.5.2}/build-tools/docs.py

@@ -188,7 +188,8 @@ def linkcode_resolve(domain, info):
     return docs_build_dir
 
 
-def build_docs_for_version(version: str, output_base_dir: Path, repo_path: Path = None):
+def build_docs_for_version(version: str, output_base_dir: Path, repo_path: Path = None,
+                           versioned_subdir: bool = True):
     """
     Builds docs for a specific version in a sandbox.
     Uses local repo copy instead of cloning for efficiency.
@@ -197,6 +198,12 @@ def build_docs_for_version(version: str, output_base_dir: Path, repo_path: Path
         version: Git tag/ref to build
         output_base_dir: Directory to output built docs
         repo_path: Path to local repo to copy from (defaults to cwd)
+        versioned_subdir: when True (batch/from-scratch rebuild), the built
+            docs are placed under ``output_base_dir/<version>/`` so multiple
+            versions can coexist. When False (single build, as used by CI),
+            the docs are placed flat into ``output_base_dir`` so the shared
+            docs-publish workflow can upload them as-is without knowing about
+            versioning.
     """
     print(f"--- Running in Version Build Mode for version: {version} ---")
 
@@ -226,13 +233,19 @@ def build_docs_for_version(version: str, output_base_dir: Path, repo_path: Path
         built_docs_path = build_versioned_docs(env, source_path, version)
 
         print(f"\n--- Step 4: Copying built artifacts to output directory ---")
-        version_output_dir = output_base_dir / version
-        if version_output_dir.exists():
-            print(f"Removing existing directory: {version_output_dir}")
-            shutil.rmtree(version_output_dir)
-        shutil.copytree(built_docs_path, version_output_dir)
+        if versioned_subdir:
+            dest = output_base_dir / version
+            if dest.exists():
+                print(f"Removing existing directory: {dest}")
+                shutil.rmtree(dest)
+            shutil.copytree(built_docs_path, dest)
+        else:
+            # flat: place the built docs directly into output_base_dir
+            output_base_dir.mkdir(parents=True, exist_ok=True)
+            shutil.copytree(built_docs_path, output_base_dir, dirs_exist_ok=True)
+            dest = output_base_dir
 
-        print(f"\nDocumentation for {version} built successfully in: {version_output_dir}")
+        print(f"\nDocumentation for {version} built successfully in: {dest}")
 
 
 def get_all_tags():
@@ -317,7 +330,9 @@ def main():
             for version, error in failed:
                 print(f"  {version}: {error}")
     elif args.build_ver:
-        build_docs_for_version(args.build_ver, output_dir)
+        # single build (CI + local single-version): flat output so the
+        # shared docs-publish workflow uploads it version-agnostically
+        build_docs_for_version(args.build_ver, output_dir, versioned_subdir=False)
     else:
         build_docs_local(Path.cwd(), output_dir)
 

mmif_python-1.5.2/build-tools/prep_release.py

@@ -0,0 +1,91 @@
+"""
+Prepare release artifacts for the mmif-python package.
+
+Run while preparing a release PR, passing the version being released::
+
+    python build-tools/prep_release.py X.Y.Z
+
+Currently this adds a row to ``documentation/target-versions.csv`` for
+the release version, resolving the target MMIF spec version from the
+installed package metadata (``mmif.__specver__``). This script is the
+single place that writes the target-versions table; the docs build only
+renders it, and CI verifies (on the release PR) that a row for the PR's
+version exists.
+
+Requires an editable install (``pip install -e .``) so that
+``mmif.__specver__`` is importable.
+"""
+import argparse
+import re
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).parent.parent
+CSV_PATH = PROJECT_ROOT / 'documentation' / 'target-versions.csv'
+
+VERSION_RE = re.compile(r'^\d+\.\d+\.\d+$')
+TOP_ROW_RE = re.compile(r'`(\d+\.\d+\.\d+) <')
+
+
+def _row(version, specver):
+    return (
+        f'`{version} <https://pypi.org/project/mmif-python/{version}/>`__,'
+        f'`{specver} <https://mmif.clams.ai/{specver}/>`__'
+    )
+
+
+def _version_tuple(v):
+    return tuple(int(x) for x in v.split('.'))
+
+
+def _top_version(data_lines):
+    if not data_lines:
+        return None
+    m = TOP_ROW_RE.match(data_lines[0])
+    return m.group(1) if m else None
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Prepare release artifacts for mmif-python."
+    )
+    parser.add_argument(
+        "version", metavar="X.Y.Z",
+        help="the release version being prepared",
+    )
+    args = parser.parse_args()
+    version = args.version
+
+    if not VERSION_RE.match(version):
+        sys.exit(f"Error: '{version}' is not a valid X.Y.Z version.")
+
+    try:
+        import mmif
+        specver = mmif.__specver__
+    except (ImportError, AttributeError):
+        sys.exit("Error: cannot read mmif.__specver__. "
+                 "Run `pip install -e .` first.")
+
+    lines = CSV_PATH.read_text().splitlines()
+    header, data = lines[0], lines[1:]
+    top = _top_version(data)
+
+    if top is not None and _version_tuple(version) < _version_tuple(top):
+        sys.exit(f"Error: {version} is older than the current top row "
+                 f"{top}; refusing to insert an out-of-order version.")
+
+    new_row = _row(version, specver)
+    if top == version:
+        data[0] = new_row            # update in place (e.g. spec changed)
+        action = "updated"
+    else:
+        data.insert(0, new_row)      # prepend as the new latest
+        action = "added"
+
+    CSV_PATH.write_text('\n'.join([header] + data) + '\n')
+    print(f"target-versions.csv: {action} row "
+          f"{version} -> MMIF spec {specver}")
+
+
+if __name__ == "__main__":
+    main()

{mmif_python-1.5.0 → mmif_python-1.5.2}/documentation/conf.py

@@ -6,7 +6,6 @@ import datetime
 import inspect
 import json
 import os
-import re
 import subprocess
 import sys
 import textwrap
@@ -148,42 +147,6 @@ def linkcode_resolve(domain, info):
         return None
 
 
-def update_target_versions(app):
-    """
-    Update documentation/target-versions.csv with the current version and spec version.
-    This replaces the old logic in setup.py.
-    """
-    # Check if we have __specver__ (it might not be there if not installed via setup.py develop)
-    if not hasattr(mmif, '__specver__'):
-        return
-
-    current_ver = mmif.__version__
-    # Skip dev/dummy versions to avoid dirtying the git-tracked CSV
-    if 'dev' in current_ver or not re.match(r'^\d+\.\d+\.\d+$', current_ver):
-        return
-    spec_ver = mmif.__specver__
-
-    csv_path = proj_root_dir / 'documentation' / 'target-versions.csv'
-    if not csv_path.exists():
-        return
-
-    # Read existing content
-    with open(csv_path, 'r') as f:
-        lines = f.readlines()
-
-    # Check if current version is already in the file (first data line)
-    # lines[0] is header, lines[1] is latest version
-    if len(lines) > 1 and lines[1].startswith(f'{current_ver},'):
-        return
-
-    # Insert new version
-    logger.info(f"Updating target-versions.csv: {current_ver} -> {spec_ver}")
-    lines.insert(1, f'{current_ver},"{spec_ver}"\n')
-
-    with open(csv_path, 'w') as f:
-        f.writelines(lines)
-
-
 def generate_cli_rst(app):
     from mmif import prep_argparser_and_subcmds
 
@@ -292,7 +255,6 @@ def run_apidoc(app):
 def setup(app):
     try:
         app.connect('builder-inited', run_apidoc)
-        app.connect('builder-inited', update_target_versions)
         app.connect('builder-inited', generate_cli_rst)
         app.connect('builder-inited', generate_whatsnew_rst)
     except ImportError:

mmif_python-1.5.2/documentation/target-versions.csv

@@ -0,0 +1,53 @@
+"``mmif-python`` version","Target MMIF Specification"
+`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/>`__
+`1.5.0 <https://pypi.org/project/mmif-python/1.5.0/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
+`1.4.0 <https://pypi.org/project/mmif-python/1.4.0/>`__,`1.1.1 <https://mmif.clams.ai/1.1.1/>`__
+`1.3.1 <https://pypi.org/project/mmif-python/1.3.1/>`__,`1.1.0 <https://mmif.clams.ai/1.1.0/>`__
+`1.3.0 <https://pypi.org/project/mmif-python/1.3.0/>`__,`1.1.0 <https://mmif.clams.ai/1.1.0/>`__
+`1.2.1 <https://pypi.org/project/mmif-python/1.2.1/>`__,`1.1.0 <https://mmif.clams.ai/1.1.0/>`__
+`1.2.0 <https://pypi.org/project/mmif-python/1.2.0/>`__,`1.1.0 <https://mmif.clams.ai/1.1.0/>`__
+`1.1.2 <https://pypi.org/project/mmif-python/1.1.2/>`__,`1.1.0 <https://mmif.clams.ai/1.1.0/>`__
+`1.1.1 <https://pypi.org/project/mmif-python/1.1.1/>`__,`1.1.0 <https://mmif.clams.ai/1.1.0/>`__
+`1.1.0 <https://pypi.org/project/mmif-python/1.1.0/>`__,`1.1.0 <https://mmif.clams.ai/1.1.0/>`__
+`1.0.19 <https://pypi.org/project/mmif-python/1.0.19/>`__,`1.0.5 <https://mmif.clams.ai/1.0.5/>`__
+`1.0.18 <https://pypi.org/project/mmif-python/1.0.18/>`__,`1.0.5 <https://mmif.clams.ai/1.0.5/>`__
+`1.0.17 <https://pypi.org/project/mmif-python/1.0.17/>`__,`1.0.5 <https://mmif.clams.ai/1.0.5/>`__
+`1.0.16 <https://pypi.org/project/mmif-python/1.0.16/>`__,`1.0.4 <https://mmif.clams.ai/1.0.4/>`__
+`1.0.15 <https://pypi.org/project/mmif-python/1.0.15/>`__,`1.0.4 <https://mmif.clams.ai/1.0.4/>`__
+`1.0.14 <https://pypi.org/project/mmif-python/1.0.14/>`__,`1.0.4 <https://mmif.clams.ai/1.0.4/>`__
+`1.0.13 <https://pypi.org/project/mmif-python/1.0.13/>`__,`1.0.4 <https://mmif.clams.ai/1.0.4/>`__
+`1.0.12 <https://pypi.org/project/mmif-python/1.0.12/>`__,`1.0.4 <https://mmif.clams.ai/1.0.4/>`__
+`1.0.11 <https://pypi.org/project/mmif-python/1.0.11/>`__,`1.0.4 <https://mmif.clams.ai/1.0.4/>`__
+`1.0.10 <https://pypi.org/project/mmif-python/1.0.10/>`__,`1.0.2 <https://mmif.clams.ai/1.0.2/>`__
+`1.0.9 <https://pypi.org/project/mmif-python/1.0.9/>`__,`1.1.0 <https://mmif.clams.ai/1.1.0/>`__
+`1.0.8 <https://pypi.org/project/mmif-python/1.0.8/>`__,`1.0.0 <https://mmif.clams.ai/1.0.0/>`__
+`1.0.7 <https://pypi.org/project/mmif-python/1.0.7/>`__,`1.0.0 <https://mmif.clams.ai/1.0.0/>`__
+`1.0.6 <https://pypi.org/project/mmif-python/1.0.6/>`__,`1.0.0 <https://mmif.clams.ai/1.0.0/>`__
+`1.0.5 <https://pypi.org/project/mmif-python/1.0.5/>`__,`1.0.0 <https://mmif.clams.ai/1.0.0/>`__
+`1.0.4 <https://pypi.org/project/mmif-python/1.0.4/>`__,`1.0.0 <https://mmif.clams.ai/1.0.0/>`__
+`1.0.3 <https://pypi.org/project/mmif-python/1.0.3/>`__,`1.0.0 <https://mmif.clams.ai/1.0.0/>`__
+`1.0.2 <https://pypi.org/project/mmif-python/1.0.2/>`__,`1.0.0 <https://mmif.clams.ai/1.0.0/>`__
+`1.0.1 <https://pypi.org/project/mmif-python/1.0.1/>`__,`1.0.0 <https://mmif.clams.ai/1.0.0/>`__
+`1.0.0 <https://pypi.org/project/mmif-python/1.0.0/>`__,`0.5.0 <https://mmif.clams.ai/0.5.0/>`__
+`0.5.2 <https://pypi.org/project/mmif-python/0.5.2/>`__,`0.5.0 <https://mmif.clams.ai/0.5.0/>`__
+`0.5.1 <https://pypi.org/project/mmif-python/0.5.1/>`__,`0.5.0 <https://mmif.clams.ai/0.5.0/>`__
+`0.5.0 <https://pypi.org/project/mmif-python/0.5.0/>`__,`0.5.0 <https://mmif.clams.ai/0.5.0/>`__
+`0.4.8 <https://pypi.org/project/mmif-python/0.4.8/>`__,`0.4.2 <https://mmif.clams.ai/0.4.2/>`__
+`0.4.7 <https://pypi.org/project/mmif-python/0.4.7/>`__,`0.4.1 <https://mmif.clams.ai/0.4.1/>`__
+`0.4.6 <https://pypi.org/project/mmif-python/0.4.6/>`__,`0.4.0 <https://mmif.clams.ai/0.4.0/>`__
+`0.4.5 <https://pypi.org/project/mmif-python/0.4.5/>`__,`0.4.0 <https://mmif.clams.ai/0.4.0/>`__
+`0.4.4 <https://pypi.org/project/mmif-python/0.4.4/>`__,`0.4.0 <https://mmif.clams.ai/0.4.0/>`__
+`0.4.3 <https://pypi.org/project/mmif-python/0.4.3/>`__,`0.4.0 <https://mmif.clams.ai/0.4.0/>`__
+`0.4.2 <https://pypi.org/project/mmif-python/0.4.2/>`__,`0.4.0 <https://mmif.clams.ai/0.4.0/>`__
+`0.4.1 <https://pypi.org/project/mmif-python/0.4.1/>`__,`0.4.0 <https://mmif.clams.ai/0.4.0/>`__
+`0.4.0 <https://pypi.org/project/mmif-python/0.4.0/>`__,`0.4.0 <https://mmif.clams.ai/0.4.0/>`__
+`0.3.5 <https://pypi.org/project/mmif-python/0.3.5/>`__,`0.3.1 <https://mmif.clams.ai/0.3.1/>`__
+`0.3.4 <https://pypi.org/project/mmif-python/0.3.4/>`__,`0.3.1 <https://mmif.clams.ai/0.3.1/>`__
+`0.3.3 <https://pypi.org/project/mmif-python/0.3.3/>`__,`0.3.1 <https://mmif.clams.ai/0.3.1/>`__
+`0.3.2 <https://pypi.org/project/mmif-python/0.3.2/>`__,`0.3.1 <https://mmif.clams.ai/0.3.1/>`__
+`0.3.1 <https://pypi.org/project/mmif-python/0.3.1/>`__,`0.3.0 <https://mmif.clams.ai/0.3.0/>`__
+`0.3.0 <https://pypi.org/project/mmif-python/0.3.0/>`__,`0.3.0 <https://mmif.clams.ai/0.3.0/>`__
+`0.2.2 <https://pypi.org/project/mmif-python/0.2.2/>`__,`0.2.1 <https://mmif.clams.ai/0.2.1/>`__
+`0.2.1 <https://pypi.org/project/mmif-python/0.2.1/>`__,`0.2.1 <https://mmif.clams.ai/0.2.1/>`__
+`0.2.0 <https://pypi.org/project/mmif-python/0.2.0/>`__,`0.2.1 <https://mmif.clams.ai/0.2.1/>`__

{mmif_python-1.5.0 → mmif_python-1.5.2}/mmif/serialize/annotation.py

@@ -414,22 +414,56 @@ class Document(Annotation):
             else:
                 super().add_property(name, value)
 
-    def get(self, prop_name, default=None):
+    def __getitem__(self, prop_name: str):
         """
-        Safe property access with optional default value for Document objects.
+        Property access for ``Document`` objects, following the document
+        property hierarchy (highest to lowest priority):
 
-        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:
+        #. Special fields (``id``, ``location``)
+        #. Pending properties (added via :meth:`add_property` after creation,
+           to be serialized as capital ``Annotation`` objects)
+        #. Original properties (in ``document.properties``)
+        #. Ephemeral properties (from existing ``Annotation`` objects or view
+           ``contains`` metadata)
 
-        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``)
+        ``Document`` overrides ``__getitem__`` (not only :meth:`get`) so that
+        the ``in`` operator, subscripting, and :meth:`get` all agree.
+        ``__contains__`` is implemented on top of ``__getitem__``, so without
+        this override a property added via :meth:`add_property` (which lands in
+        ``_props_pending``) is readable through :meth:`get` yet invisible to
+        ``in`` until a serialize/deserialize round trip. See issue #390.
 
-        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
+        :raises KeyError: if the property is not found in any of the stores
+        """
+        if prop_name == 'id':
+            # because all three dicts have `id` key as required field, we need
+            # this special case to return the correct value from the correct dict
+            return self.id
+        elif prop_name == 'location':
+            # location is internally stored as `location_`, so the regular
+            # lookup below never finds it. Treat an unset location as absent
+            # (raise) rather than returning None, so the inherited
+            # `__contains__` does not report `'location'` as always present.
+            if self.location is None:
+                raise KeyError(prop_name)
+            return self.location
+        elif prop_name in self._props_pending:
+            return self._props_pending[prop_name]
+        else:
+            # Delegates to Annotation.__getitem__(), which checks
+            # self.properties (_props_original) before _props_ephemeral.
+            # This gives annotation-level properties precedence over
+            # view-level contains defaults (MMIF spec >= 1.1.1).
+            return super().__getitem__(prop_name)
+
+    def get(self, prop_name, default=None):
+        """
+        Safe property access with optional default value for Document objects.
+
+        Searches for a document property by name and returns its value, or
+        ``default`` if not found, following the priority order documented on
+        :meth:`__getitem__`.
 
         :param prop_name: The name of the property to retrieve
         :param default: The value to return if the property is not found (default: None)
@@ -455,22 +489,10 @@ class Document(Annotation):
         add_property : Add a new property to the document
         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
-            # this special case to return the correct value from the correct dict
-            return self.id
-        elif prop_name == 'location':
-            # because location is internally stored in self.location_,
-            # it doesn't work with regular __getitem__ method
-            return self.location
-        elif prop_name in self._props_pending:
-            return self._props_pending[prop_name]
-        else:
-            # Delegates to Annotation.__getitem__(), which checks
-            # self.properties (_props_original) before _props_ephemeral.
-            # This gives annotation-level properties precedence over
-            # view-level contains defaults (MMIF spec >= 1.1.1).
-            return super().get(prop_name, default)
+        try:
+            return self.__getitem__(prop_name)
+        except KeyError:
+            return default
 
     get_property = get
     

{mmif_python-1.5.0 → mmif_python-1.5.2}/mmif/serialize/view.py

@@ -82,6 +82,25 @@ class View(MmifObject):
         self._required_attributes = ["id", "metadata", "annotations"]
         super().__init__(view_obj)
         self._fix_old_short_ids()
+        self._rebuild_id_counts()
+
+    def _rebuild_id_counts(self):
+        """
+        Re-seed the per-view auto-ID counters from the annotations loaded during
+        deserialization.
+
+        ``_id_counts`` is not serialized, so a view read back from JSON starts
+        with an empty counter. Without this, the next :meth:`new_annotation`
+        regenerates an ID (e.g. ``an_1``) that already exists in the
+        deserialized view and :meth:`AnnotationsList.append` raises ``KeyError``.
+        See issue #393.
+        """
+        for annotation in self.annotations:
+            local_id = annotation.id.split(self.id_delimiter)[-1]
+            prefix, _, num = local_id.rpartition('_')
+            if prefix and num.isdigit():
+                self._id_counts[prefix] = max(
+                    self._id_counts.get(prefix, 0), int(num))
 
     def _fix_old_short_ids(self):
         """

{mmif_python-1.5.0 → mmif_python-1.5.2}/mmif/utils/video_document_helper.py

@@ -96,20 +96,36 @@ def open_container(video_document: Document):
     container = av.open(video_document.location_path(nonexist_ok=False))
     stream = container.streams.video[0]
     time_base = float(stream.time_base)
-    fps = round(float(stream.average_rate), 2)
+    # Frame rate: prefer ffmpeg's guessed rate (av_guess_frame_rate), which
+    # falls back to the stream's base rate (r_frame_rate) when the average
+    # rate (avg_frame_rate) is unset. Matroska/webm commonly leave
+    # `average_rate` as None (which would crash float()) or 0, so it cannot be
+    # used directly. `rate` stays a Fraction for exact frame-count math; both
+    # None and a zero rate are falsy, so the chain yields the first usable one.
+    rate = stream.guessed_rate or stream.average_rate or stream.base_rate
+    fps = round(float(rate), 2) if rate else 0.0
+    # Resolve duration (in seconds) from the most reliable source available.
+    # `stream.duration` is exact for CFR H.264/MP4, but Matroska/webm leave it
+    # unset and carry the length only at the container level
+    # (`container.duration`, in `av.time_base` microseconds).
+    if stream.duration is not None:
+        duration_s = float(stream.duration) * time_base
+    elif container.duration is not None:
+        duration_s = container.duration / av.time_base
+    else:
+        duration_s = None
     # `stream.frames` comes from the container header. Verified exact on
     # CFR H.264/MP4 inputs even with non-zero start offset; for VFR or
     # headerless streams it may be 0, in which case `duration * rate` is
     # the best available (approximate) estimate.
     if stream.frames > 0:
         frame_count = stream.frames
-    elif stream.duration is not None and stream.average_rate is not None:
-        frame_count = int(round(float(stream.duration) * time_base
-                                * float(stream.average_rate)))
+    elif duration_s is not None and rate:
+        frame_count = int(round(duration_s * float(rate)))
     else:
         frame_count = 0
-    if stream.duration is not None:
-        duration_ms = int(round(float(stream.duration) * time_base * 1000))
+    if duration_s is not None:
+        duration_ms = int(round(duration_s * 1000))
     elif frame_count > 0 and fps > 0:
         duration_ms = int(round(frame_count / fps * 1000))
     else:

{mmif_python-1.5.0 → mmif_python-1.5.2/mmif_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmif-python
-Version: 1.5.0
+Version: 1.5.2
 Summary: Python implementation of MultiMedia Interchange Format specification. (https://mmif.clams.ai)
 License-Expression: Apache-2.0
 Project-URL: homepage, https://mmif.clams.ai

{mmif_python-1.5.0 → mmif_python-1.5.2}/mmif_python.egg-info/SOURCES.txt

@@ -9,9 +9,11 @@ pyproject.toml
 .github/workflows/issue-close.yml
 .github/workflows/issue-infra-project.yml
 .github/workflows/publish.yml
+.github/workflows/release-check.yml
 build-tools/build.py
 build-tools/clean.py
 build-tools/docs.py
+build-tools/prep_release.py
 build-tools/publish.py
 build-tools/test.py
 documentation/cli.rst
@@ -61,8 +63,11 @@ mmif_python.egg-info/SOURCES.txt
 mmif_python.egg-info/dependency_links.txt
 mmif_python.egg-info/entry_points.txt
 mmif_python.egg-info/requires.txt
+mmif_python.egg-info/scm_file_list.json
+mmif_python.egg-info/scm_version.json
 mmif_python.egg-info/top_level.txt
 tests/black-2997fps.mp4
+tests/black-2997fps.webm
 tests/mmif_examples.py
 tests/test_serialize.py
 tests/test_specver.py

mmif_python-1.5.2/mmif_python.egg-info/scm_file_list.json

@@ -0,0 +1,95 @@
+{
+  "files": [
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    ".gitignore",
+    "build-tools/publish.py",
+    "build-tools/prep_release.py",
+    "build-tools/build.py",
+    "build-tools/docs.py",
+    "build-tools/clean.py",
+    "build-tools/test.py",
+    "documentation/target-versions.csv",
+    "documentation/consumer-tutorial.rst",
+    "documentation/target-versions.rst",
+    "documentation/index.rst",
+    "documentation/introduction.rst",
+    "documentation/cli.rst",
+    "documentation/plugins.rst",
+    "documentation/summarizer.rst",
+    "documentation/conf.py",
+    "documentation/_mmif_example_builder/__init__.py",
+    "documentation/_templates/versions.html",
+    "mmif/__init__.py",
+    "mmif/vocabulary/__init__.py",
+    "mmif/vocabulary/base_types.py",
+    "mmif/vocabulary/document_types.py",
+    "mmif/vocabulary/annotation_types.py",
+    "mmif/utils/__init__.py",
+    "mmif/utils/text_document_helper.py",
+    "mmif/utils/timeunit_helper.py",
+    "mmif/utils/workflow_helper.py",
+    "mmif/utils/video_document_helper.py",
+    "mmif/utils/sequence_helper.py",
+    "mmif/utils/summarizer/__init__.py",
+    "mmif/utils/summarizer/config.py",
+    "mmif/utils/summarizer/utils.py",
+    "mmif/utils/summarizer/summary.py",
+    "mmif/utils/summarizer/graph.py",
+    "mmif/utils/summarizer/nodes.py",
+    "mmif/utils/cli/__init__.py",
+    "mmif/utils/cli/source.py",
+    "mmif/utils/cli/rewind.py",
+    "mmif/utils/cli/summarize.py",
+    "mmif/utils/cli/describe.py",
+    "mmif/serialize/model.py",
+    "mmif/serialize/__init__.py",
+    "mmif/serialize/view.py",
+    "mmif/serialize/annotation.py",
+    "mmif/serialize/mmif.py",
+    "mmif/res/__init__.py",
+    "mmif/res/mmif.json",
+    "mmif/ver/__init__.py",
+    "tests/mmif_examples.py",
+    "tests/test_specver.py",
+    "tests/test_utils.py",
+    "tests/test_utils_cli.py",
+    "tests/test_vocab.py",
+    "tests/testsrc-2997fps-ptsoffset.mp4",
+    "tests/test_serialize.py",
+    "tests/black-2997fps.mp4",
+    "tests/black-2997fps.webm",
+    "tests/mmif-examples/README.md",
+    "tests/mmif-examples/examples.json",
+    "tests/mmif-examples/1.0.5-old-shortid.json",
+    "tests/mmif-examples/swt-1.0.mmif",
+    "tests/mmif-examples/segmenter-kaldi-ner/raw.json",
+    "tests/mmif-examples/everything/raw.json",
+    "tests/mmif-examples/others/video-transcript.json",
+    "tests/mmif-examples/others/image-box-ocr-timex.json",
+    "tests/mmif-examples/others/README.md",
+    "tests/mmif-examples/others/video.json",
+    "tests/mmif-examples/others/video-transcript-demux-fa.json",
+    "tests/mmif-examples/others/image.json",
+    "tests/mmif-examples/others/video-transcript-sentencesplit.json",
+    "tests/mmif-examples/others/video-transcript-demux-fa.short.json",
+    "tests/mmif-examples/others/slate-detect.json",
+    "tests/mmif-examples/others/image-box.json",
+    "tests/mmif-examples/others/slate-reco.json",
+    "tests/mmif-examples/others/video-transcript-demux.json",
+    "tests/mmif-examples/others/image-box-ocr.json",
+    "tests/mmif-examples/others/video-demux.json",
+    "tests/mmif-examples/bars-tones-slates/raw.json",
+    "tests/mmif-examples/east-tesseract-typing/raw.json",
+    "mmif_docloc_http/__init__.py",
+    ".github/workflows/issue-close.yml",
+    ".github/workflows/codecov.yml",
+    ".github/workflows/release-check.yml",
+    ".github/workflows/issue-infra-project.yml",
+    ".github/workflows/issue-assign.yml",
+    ".github/workflows/publish.yml"
+  ]
+}

mmif_python-1.5.2/mmif_python.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "1.5.2",
+  "distance": 0,
+  "node": "g1b794b4741b27b9999c5cd9fec00d46bef6d5d8e",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-07"
+}

{mmif_python-1.5.0 → mmif_python-1.5.2}/tests/test_serialize.py

@@ -1304,7 +1304,36 @@ class TestDocument(unittest.TestCase):
         doc1_mmif_roundtrip = mmif_roundtrip['doc1']
         self.assertEqual(0, len(doc1_mmif_roundtrip._props_pending))
         self.assertEqual('me', doc1_mmif_roundtrip.get_property('author'))
-        
+
+    def test_document_pending_property_membership(self):
+        # regression for issue #390: a property added via `add_property`
+        # lands in `_props_pending` and must be visible through `get_property`,
+        # subscripting, AND the `in` operator consistently -- without needing a
+        # serialize/deserialize round trip first.
+        doc = Document()
+        doc.at_type = DocumentTypes.VideoDocument
+        doc.id = 'doc1'
+        doc.add_property('fps', 29.97)
+        self.assertIn('fps', doc._props_pending)
+        # all three access paths must agree
+        self.assertEqual(29.97, doc.get_property('fps'))
+        self.assertEqual(29.97, doc['fps'])
+        self.assertIn('fps', doc)
+        # special fields and absent keys are unaffected
+        self.assertIn('id', doc)
+        self.assertEqual('doc1', doc['id'])
+        self.assertNotIn('nope', doc)
+        with self.assertRaises(KeyError):
+            _ = doc['nope']
+        # an unset `location` must read as absent, not as always-present None
+        self.assertNotIn('location', doc)
+        with self.assertRaises(KeyError):
+            _ = doc['location']
+        self.assertIsNone(doc.get('location'))
+        doc.location = 'file:///tmp/doc1.mp4'
+        self.assertIn('location', doc)
+        self.assertEqual('file:///tmp/doc1.mp4', doc['location'])
+
     def test_document_adding_duplicate_properties(self):
         mmif = Mmif(self.data['everything']['string'])
         doc1 = Document()
@@ -1422,7 +1451,57 @@ class TestDocument(unittest.TestCase):
             'author'))
         self.assertEqual('you', list(mmif_roundtrip2.views.get_last_contentful_view().get_annotations(AnnotationTypes.Annotation))[
             0].get_property('author'))
-        
+
+    def test_view_id_counts_rebuilt_on_deserialize(self):
+        # regression for issue #393: `_id_counts` is not serialized, so after
+        # deserialization the next generated id must not collide with an existing
+        # one already present in the view.
+        mmif = Mmif(validate=False)
+        doc = Document(); doc.at_type = DocumentTypes.VideoDocument
+        doc.id = 'd1'; doc.location = 'file:///v.mp4'
+        mmif.add_document(doc)
+        v = mmif.new_view()
+        v.metadata.app = tester_appname
+        a1 = v.new_annotation(AnnotationTypes.Annotation, document='d1', frameCount=10)
+        self.assertTrue(a1.id.endswith('an_1'))
+        # round-trip: the reloaded view still contains `an_1` but starts with an
+        # empty counter unless rebuilt
+        v2 = Mmif(mmif.serialize())[v.id]
+        a2 = v2.new_annotation(AnnotationTypes.Annotation, document='d1', duration=20)
+        self.assertTrue(a2.id.endswith('an_2'))   # must not regenerate an_1
+
+    def test_capital_annotation_no_collision_across_apps(self):
+        # regression for issue #393: a downstream app re-deriving a document
+        # property with a *different* value must not crash on serialize; the
+        # distinct value is recorded as an additional capital annotation
+        # (value-based de-dup preserves both assertions), not a colliding one.
+        m = Mmif(validate=False)
+        d = Document()
+        d.at_type = DocumentTypes.VideoDocument
+        d.id = 'd1'
+        d.location = 'file:///v.mp4'
+        m.add_document(d)
+        v1 = m.new_view(); v1.metadata.app = 'http://app/producer'
+        v1.new_annotation(AnnotationTypes.TimeFrame, label='bars')
+        d.add_property('frameCount', 51248.0)
+        d.add_property('duration', 1709977.0)
+
+        # downstream app loads it and re-derives a *different* duration value
+        m2 = Mmif(m.serialize())
+        d2 = m2['d1']
+        v2 = m2.new_view(); v2.metadata.app = 'http://app/consumer'
+        v2.new_annotation(AnnotationTypes.TimeFrame, label='caption')
+        d2.add_property('frameCount', 51248)      # same value -> de-duped away
+        d2.add_property('duration', 1709975)      # different value -> new annotation
+        out = Mmif(m2.serialize())                # must not raise KeyError
+
+        caps = [a for view in out.views
+                for a in view.get_annotations(AnnotationTypes.Annotation)]
+        durations = {a.get_property('duration') for a in caps if 'duration' in a}
+        # both distinct duration assertions coexist; neither is lost or overwritten
+        self.assertEqual(2, len(caps))
+        self.assertEqual({1709977.0, 1709975}, durations)
+
     def test_capital_annotation_generation_viewfinder(self):
         mmif = Mmif(validate=False)
         for i in range(1, 3):

{mmif_python-1.5.0 → mmif_python-1.5.2}/tests/test_utils.py

@@ -183,6 +183,26 @@ class TestVideoDocumentHelper(unittest.TestCase):
         finally:
             c.close()
 
+    def test_open_container_matroska(self):
+        # regression for issue #390: Matroska/webm leave the per-stream
+        # `frames`/`duration` fields unset, so open_container must fall back to
+        # the container-level duration instead of caching frameCount/duration 0.
+        vd = Document({
+            "@type": "http://mmif.clams.ai/vocabulary/VideoDocument/v1",
+            "properties": {
+                "mime": "video",
+                "id": "o1",
+                "location": f"file://{pathlib.Path(__file__).parent}/black-2997fps.webm",
+            }
+        })
+        c = vdh.open_container(vd)
+        try:
+            self.assertAlmostEqual(29.97, vd.get_property('fps'), places=1)
+            self.assertGreater(vd.get_property('frameCount'), 0)
+            self.assertGreater(vd.get_property('duration'), 0)
+        finally:
+            c.close()
+
     def test_sample_timepoints(self):
         # half-open interval; step in ms
         self.assertEqual([0, 100, 200, 300, 400],

mmif_python-1.5.0/documentation/target-versions.csv

@@ -1,47 +0,0 @@
-"``mmif-python`` version","Target MMIF Specification"
-1.3.0,"1.1.0"
-1.2.0,"1.1.0"
-1.1.2,"1.1.0"
-1.1.1,"1.1.0"
-1.1.0,"1.1.0"
-1.0.19,"1.0.5"
-1.0.18,"1.0.5"
-1.0.17,"1.0.5"
-1.0.16,"1.0.4"
-1.0.15,"1.0.4"
-1.0.14,"1.0.4"
-1.0.13,"1.0.4"
-1.0.12,"1.0.4"
-1.0.11,"1.0.4"
-1.0.10,"1.0.2"
-1.0.9,"1.1.0"
-1.0.8,"1.0.0"
-1.0.7,"1.0.0"
-1.0.6,"1.0.0"
-1.0.5,"1.0.0"
-1.0.4,"1.0.0"
-1.0.3,"1.0.0"
-1.0.2,"1.0.0"
-1.0.1,"1.0.0"
-1.0.0,"0.5.0"
-0.5.2,"0.5.0"
-0.5.1,"0.5.0"
-0.5.0,"0.5.0"
-0.4.8,"0.4.2"
-0.4.7,"0.4.1"
-0.4.6,"0.4.0"
-0.4.5,"0.4.0"
-0.4.4,"0.4.0"
-0.4.3,"0.4.0"
-0.4.2,"0.4.0"
-0.4.1,"0.4.0"
-0.4.0,"0.4.0"
-0.3.5,"0.3.1"
-0.3.4,"0.3.1"
-0.3.3,"0.3.1"
-0.3.2,"0.3.1"
-0.3.1,"0.3.0"
-0.3.0,"0.3.0"
-0.2.2,"0.2.1"
-0.2.1,"0.2.1"
-0.2.0,"0.2.1"