from __future__ import annotations

import logging
import warnings

_LOGGER = logging.getLogger("calibrated_explanations.<domain>.<module>")
# Domain guidance (ADR-028):
#   core.*     — core runtime (explain, predict, cache, parallel)
#   plugins.*  — plugins (interval, explanation, plot)
#   governance.* — trust/deny decisions


def _emit_fallback(msg: str, *, stacklevel: int = 2) -> None:
    """Emit a mandatory visible fallback notification.

    Parameters
    ----------
    msg : str
        Human-readable reason and chosen fallback path.
    stacklevel : int, optional
        Stack depth for the warning (default 2 — immediate caller).
    """
    _LOGGER.info(msg)
    warnings.warn(msg, UserWarning, stacklevel=stacklevel + 1)

def _run_parallel(self, data):
    try:
        return self._parallel_backend.run(data)
    except Exception as exc:          # noqa: BLE001
        _emit_fallback(
            f"{self.__class__.__name__}: parallel execution failed "
            f"({exc!r}). Falling back to sequential.",
            stacklevel=2,
        )
        return self._sequential_fallback(data)

import warnings, logging
_LOGGER = logging.getLogger("calibrated_explanations.core.parallel")

def _parallel_or_sequential(tasks, *, backend):
    try:
        return backend.run(tasks)
    except Exception as exc:  # noqa: BLE001
        msg = (
            f"Parallel backend '{backend.__class__.__name__}' failed "
            f"({type(exc).__name__}). Falling back to sequential execution. "
            "Set backend='sequential' to suppress this warning."
        )
        _LOGGER.info(msg)
        warnings.warn(msg, UserWarning, stacklevel=2)
        return [task() for task in tasks]

def _resolve_plugin_or_legacy(name: str):
    plugin = registry.find_plugin(name, trusted=True)
    if plugin is None:
        msg = (
            f"Plugin '{name}' not found or not trusted. "
            "Falling back to legacy path. Register and trust the plugin to use it."
        )
        _LOGGER.info(msg)
        warnings.warn(msg, UserWarning, stacklevel=3)
        return _LEGACY_PLUGIN
    return plugin

def _render_with_fallback(spec, backend):
    try:
        return backend.render(spec)
    except RuntimeError as exc:
        msg = (
            f"Visualization backend '{backend}' failed ({exc!r}). "
            "Falling back to simplified legend-only view."
        )
        _LOGGER.info(msg)
        warnings.warn(msg, UserWarning, stacklevel=2)
        return _render_simplified(spec)

import pytest

def test_should_warn_when_parallel_backend_fails(monkeypatch):
    """Fallback warning must be raised when parallel execution fails."""
    # Arrange
    from calibrated_explanations.core.parallel import _parallel_or_sequential

    def _failing_backend(tasks):
        raise RuntimeError("connection refused")

    # Act + Assert
    with pytest.warns(UserWarning, match="Falling back to sequential"):
        result = _parallel_or_sequential(tasks=[lambda: 1], backend=_failing_backend)

    assert result == [1]

# No extra setup needed if using the autouse fixture.
# If the autouse fixture is not applied for some reason:
@pytest.fixture(autouse=True)
def _disable_fallbacks(disable_fallbacks):
    pass

# ❌ Silent fallback — no warn, no log
try:
    do_fast_path()
except Exception:
    do_slow_path()   # user has no idea this happened

# ❌ Log only — no UserWarning
_LOGGER.warning("Using sequential")  # Python 'logging' warning != warnings.warn

# ❌ print() instead of proper channels
print("WARNING: falling back")

# ❌ RuntimeError/ValueError for a recoverable decision
raise RuntimeError("parallel failed")  # should fall back, not raise