coco_pipe.utils
===============

.. py:module:: coco_pipe.utils

.. autoapi-nested-parse::

   Shared package utilities.

   This module holds small helpers that are not specific to one subpackage.



Attributes
----------

.. autoapisummary::

   coco_pipe.utils.PACKAGE_VERSIONS


Functions
---------

.. autoapisummary::

   coco_pipe.utils.stable_hash
   coco_pipe.utils.import_optional_dependency
   coco_pipe.utils.get_git_revision_hash
   coco_pipe.utils.get_package_version
   coco_pipe.utils.get_environment_info
   coco_pipe.utils.slug
   coco_pipe.utils.resolve_n_jobs
   coco_pipe.utils.run_task_batch


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

.. py:data:: PACKAGE_VERSIONS
   :type:  collections.abc.Mapping[str, str]

.. py:function:: stable_hash(value, *, length = 64)

   Return a deterministic SHA-256 prefix for a JSON-compatible value.

   Dictionaries are serialized with sorted keys and compact separators. Values
   such as paths that are not directly JSON serializable fall back to ``str``.


.. py:function:: import_optional_dependency(loader, feature, dependency, install_hint = None)

   Lazily import an optional dependency with clearer failure modes.

   :param loader: Zero-argument callable returning the imported dependency.
   :type loader: callable
   :param feature: Feature or component name using the dependency.
   :type feature: str
   :param dependency: Human-readable dependency name.
   :type dependency: str
   :param install_hint: Installation hint shown on ImportError.
   :type install_hint: str, optional

   :returns: Imported dependency returned by ``loader``.
   :rtype: Any

   :raises ImportError: If the dependency is not installed.
   :raises RuntimeError: If the dependency is installed but fails during initialization.


.. py:function:: get_git_revision_hash(cwd = None)

   Return the current short git hash, or ``"Unknown"`` when unavailable.


.. py:function:: get_package_version(package_name)

   Return an installed distribution version, or ``"Unknown"``.


.. py:function:: get_environment_info(cwd = None, packages = None)

   Capture runtime provenance metadata for reports and experiment results.


.. py:function:: slug(value, *, max_len = 80)

   Return a filesystem-safe slug from an arbitrary value.

   Collapses runs of non-alphanumeric characters (except ``.``, ``_``, ``=``,
   ``-``) into a single ``-``, strips leading/trailing punctuation, and
   truncates at *max_len*.

   :param value: Any object; ``str(value)`` is used as the source text.
   :param max_len: Maximum character length of the returned slug.


.. py:function:: resolve_n_jobs(n_jobs)

   Resolve ``n_jobs`` to a concrete positive integer.

   ``-1`` maps to ``os.cpu_count()`` (minimum 1).  Any other value must
   already be a positive integer, or :class:`ValueError` is raised.


.. py:function:: run_task_batch(tasks, worker_fn, max_workers)

   Execute *tasks* with *worker_fn*, optionally in parallel.

   When *max_workers* is 1 the tasks are run serially in the current process.
   For any larger value :func:`joblib.Parallel` is used with
   ``n_jobs=min(max_workers, len(tasks))`` so the pool size never exceeds the
   actual work to do.

   :param tasks: Sequence of opaque task objects passed one-by-one to *worker_fn*.
   :param worker_fn: Single-argument callable that processes one task and returns a result.
   :param max_workers: Maximum number of parallel workers.  Pass ``1`` for serial execution.

   :returns: Results in the same order as *tasks*.
   :rtype: list