DependencyManager
=================

Dependency Manager for optional Python packages.

This module provides centralized management for optional dependencies
(scikit-learn, scikit-image) with user confirmation before installation.

Follows 3D Slicer best practices:
- Uses slicer.util.pip_install() for installation
- Uses slicer.util.confirmOkCancelDisplay() to ask user first
- Installs at runtime when needed, NOT at startup

Classes
-------

.. py:class:: DependencySpec

   Specification for an optional dependency.
   
   Attributes:
       name: Human-readable package name (e.g., "scikit-learn")
       pip_name: Name for pip install (e.g., "scikit-learn")
       version_constraint: Version constraint (e.g., ">=1.0")
       feature_description: Description of feature requiring this package
       import_check: Module path to check availability (e.g., "sklearn.mixture")


.. py:class:: DependencyManager

   Centralized manager for optional Python package dependencies.
   
   This class follows the singleton pattern to maintain session state
   (user choices, install failures) across the application.
   
   Usage:
       from DependencyManager import dependency_manager
   
       # Check availability without prompting
       if dependency_manager.is_available("sklearn"):
           from sklearn.mixture import GaussianMixture
           # use GMM
   
       # Prompt and install if needed
       if dependency_manager.ensure_available("sklearn"):
           from sklearn.mixture import GaussianMixture
           # use GMM
       else:
           # use fallback

   **Methods:**

   .. py:method:: __init__()

      Initialize the dependency manager.

   .. py:method:: is_available()

      Check if a dependency is available without prompting.

   .. py:method:: ensure_available()

      Ensure a dependency is available, prompting to install if needed.

   .. py:method:: clear_session()

      Clear session state (declined choices, failures, and in-progress).


Functions
---------

.. py:function:: is_available()

   Check if a dependency is available without prompting.
   
   Args:
       key: Dependency key (e.g., "sklearn", "skimage")
   
   Returns:
       True if the package is installed and importable

.. py:function:: ensure_available()

   Ensure a dependency is available, prompting to install if needed.
   
   This method:
   1. Returns True immediately if already installed
   2. Returns False if user previously declined or install failed
   3. Shows a confirmation dialog if not installed
   4. Installs the package if user confirms
   5. Returns True if installation succeeds, False otherwise
   
   Args:
       key: Dependency key (e.g., "sklearn", "skimage")
   
   Returns:
       True if the package is available (was installed or just installed)

.. py:function:: clear_session()

   Clear session state (declined choices, failures, and in-progress).
   
   Call this if you want to allow re-prompting for dependencies
   that were previously declined or failed.

.. py:function:: get_dependency_manager()

   Get the singleton DependencyManager instance.
   
   Returns:
       The global DependencyManager instance