emmi_inference.cli_utils
========================

.. py:module:: emmi_inference.cli_utils


Exceptions
----------

.. autoapisummary::

   emmi_inference.cli_utils.ParallelErrors


Functions
---------

.. autoapisummary::

   emmi_inference.cli_utils.resolve_dir
   emmi_inference.cli_utils.fmt_bytes
   emmi_inference.cli_utils.run_cli


Module Contents
---------------

.. py:exception:: ParallelErrors(errors)

   Bases: :py:obj:`Exception`


   Aggregate exception for parallel/async tasks.

   Used to collect multiple failures and surface them together in CLI flows.

   .. attribute:: errors

      A list of `(input, exception)` tuples for each failed item.

   Initialize self.  See help(type(self)) for accurate signature.


   .. py:attribute:: errors


.. py:function:: resolve_dir(path)

   Expand, resolve, and ensure a directory exists.

   This is a convenience for CLI arguments pointing to output folders.

   :param path: A file-system path that may include `~` and relative segments.

   :returns: The absolute, expanded `Path`. The directory is created if missing.


.. py:function:: fmt_bytes(num)

   Format a byte count into a human-readable string.

   .. rubric:: Examples

   >>> fmt_bytes(1536)
   '1.50 KB'

   :param num: Size in bytes.

   :returns: A string like `'B'`, `'KB'`, `'MB'`, `'GB'`, or `'TB'` with 2 decimals.


.. py:function:: run_cli(fn)

   Run a CLI task and translate exceptions into user-friendly output.

   Behavior:
     * Executes `fn()`.
     * If a :class:`ParallelErrors` is raised, prints each failed input and exits with code `1` (without
       an exception traceback).
     * Re-raises `typer.Exit` to respect early exits.
     * Any other exception is rendered as a single red error line and the process exits with code `1`.

   :param fn: Zero-argument callable encapsulating the command body.

   :raises typer.Exit: Re-raised when a command intentionally exits early.