mmif.utils.cli package

Package containing CLI modules.

mmif.utils.cli.open_cli_io_arg(path_or_dash: str | None, mode: str = 'r', encoding: str | None = None, errors: str | None = None, default_stdin: bool = False) → Iterator[TextIO][source]

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

Parameters:

  • path_or_dash – File path, ‘-’ for stdin/stdout, or None for no argument

  • mode – File mode (‘r’ for reading, ‘w’ for writing). Binary modes are not supported.

  • encoding – Optional file encoding

  • errors – Optional error handling strategy for encoding

  • 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

Return type:

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)
mmif.utils.cli.generate_model_summary(model: Type[BaseModel], indent: int = 0) → str[source]

Submodules

mmif.utils.cli.describe module

mmif.utils.cli.describe.get_pipeline_specs(mmif_file: str | Path)[source]
mmif.utils.cli.describe.generate_pipeline_identifier(mmif_file: str | Path) → str[source]
mmif.utils.cli.describe.describe_argparser()[source]
mmif.utils.cli.describe.prep_argparser(**kwargs)[source]
mmif.utils.cli.describe.main(args)[source]

Main block for the describe CLI command. This function basically works as a wrapper around describe_single_mmif() (for single file input) or describe_mmif_collection() (for directory input).

mmif.utils.cli.rewind module

mmif.utils.cli.rewind.prompt_user(mmif_obj: Mmif) → int[source]

Function to ask user to choose the rewind range.

mmif.utils.cli.rewind.rewind_mmif(mmif_obj: Mmif, choice: int, choice_is_viewnum: bool = True) → Mmif[source]

Rewind MMIF by deleting the last N views. The number of views to rewind is given as a number of “views”, or number of “producer apps”. By default, the number argument is interpreted as the number of “views”. Note that when the same app is repeatedly run in a CLAMS workflow and produces multiple views in a row, rewinding in “app” mode will rewind all those views at once.

Parameters:

  • mmif_obj – mmif object

  • choice – number of views to rewind

  • choice_is_viewnum – if True, choice is the number of views to rewind. If False, choice is the number of producer apps to rewind.

Returns:

rewound mmif object

mmif.utils.cli.rewind.describe_argparser()[source]
mmif.utils.cli.rewind.prep_argparser(**kwargs)[source]
mmif.utils.cli.rewind.main(args)[source]

mmif.utils.cli.source module

class mmif.utils.cli.source.WorkflowSource(common_documents_json: List[str | dict] | None = None, common_metadata_json: str | dict | None = None)[source]

Bases: object

A WorkflowSource object is used at the beginning of a CLAMS workflow to populate a new MMIF file with media.

The same WorkflowSource object can be used repeatedly to generate multiple MMIF objects.

Parameters:

  • common_documents_json – JSON doc_lists for any documents that should be common to all MMIF objects produced by this workflow.

  • common_metadata_json – JSON doc_lists for metadata that should be common to all MMIF objects produced by this workflow.

mmif: Mmif
add_document(document: str | dict | Document) → None[source]

Adds a document to the working source MMIF.

When you’re done, fetch the source MMIF with produce().

Parameters:

document – the medium to add, as a JSON dict or string or as a MMIF Medium object

change_metadata(key: str, value)[source]

Adds or changes a metadata entry in the working source MMIF.

Parameters:

  • key – the desired key of the metadata property

  • value – the desired value of the metadata property

prime() → None[source]

Primes the WorkflowSource with a fresh MMIF object.

Call this method if you want to reset the WorkflowSource without producing a MMIF object with produce().

produce() → Mmif[source]

Returns the source MMIF and resets the WorkflowSource.

Call this method once you have added all the documents for your Workflow.

Returns:

the current MMIF object that has been prepared

from_data(doc_lists: Iterable[List[str | dict | Document]], metadata_objs: Iterable[str | dict | MmifMetadata | None] | None = None) → Generator[Mmif, None, None][source]

Provided with an iterable of document lists and an optional iterable of metadata objects, generates MMIF objects produced from that data.

doc_lists and metadata_objs should be matched pairwise, so that if they are zipped together, each pair defines a single MMIF object from this workflow source.

Parameters:

  • doc_lists – an iterable of document lists to generate MMIF from

  • metadata_objs – an iterable of metadata objects paired with the document lists

Returns:

a generator of produced MMIF files from the data

mmif.utils.cli.summarize module

mmif.utils.cli.summarize.describe_argparser() → tuple[source]
mmif.utils.cli.summarize.prep_argparser(**kwargs)[source]

Create the ArgumentParser instance for the summarizer.

mmif.utils.cli.summarize.main(args: Namespace)[source]

The main summarizer command.