# DO NOT EDIT THIS FILE!
#
# This file is generated from the WebDriver BiDi specification. If you need to make
# changes, edit the generator and regenerate all of the modules.
#
# WebDriver BiDi module: speculation
"""
WebDriver BiDi speculation module.

Provides events for observing the status of Speculation Rules prefetch
requests initiated by the browser (e.g. via <script type='speculationrules'>).
"""

from __future__ import annotations

from collections.abc import Callable
from dataclasses import dataclass
from typing import Any

from selenium.webdriver.common.bidi._event_manager import EventConfig, _EventWrapper, _EventManager

class PreloadingStatus:
    """
    Status values for a speculation-rules prefetch operation.

    PENDING: The prefetch has been queued but not yet attempted.
    READY:   The prefetch succeeded and the resource is cached.
    SUCCESS: The prefetched navigation was used successfully.
    FAILURE: The prefetch failed or was cancelled.
    """

    PENDING = "pending"
    READY = "ready"
    SUCCESS = "success"
    FAILURE = "failure"


@dataclass
class PrefetchStatusUpdatedParameters:
    """
    Event payload emitted when a prefetch status changes.

    Attributes:
        context: The browsing context ID that owns the speculation rule.
        url: The URL being prefetched.
        status: The new prefetch status (see PreloadingStatus).
    """

    context: str | None = None
    url: str | None = None
    status: Any | None = None


# BiDi Event Name to Parameter Type Mapping
EVENT_NAME_MAPPING = {
    "prefetch_status_updated": "speculation.prefetchStatusUpdated",
}

class Speculation:
    """BiDi interface for observing Speculation Rules prefetch activity."""

    EVENT_CONFIGS: dict[str, EventConfig] = {}
    def __init__(self, conn) -> None:
        self._conn = conn
        self._event_manager = _EventManager(conn, self.EVENT_CONFIGS)


    def add_event_handler(self, event: str, callback: Callable, contexts: list[str] | None = None) -> int:
        """Add an event handler.

        Args:
            event: The event to subscribe to.
            callback: The callback function to execute on event.
            contexts: The context IDs to subscribe to (optional).

        Returns:
            The callback ID.
        """
        return self._event_manager.add_event_handler(event, callback, contexts)

    def remove_event_handler(self, event: str, callback_id: int) -> None:
        """Remove an event handler.

        Args:
            event: The event to unsubscribe from.
            callback_id: The callback ID.
        """
        return self._event_manager.remove_event_handler(event, callback_id)

    def clear_event_handlers(self) -> None:
        """Clear all event handlers."""
        return self._event_manager.clear_event_handlers()

# Event Info Type Aliases
# Event: speculation.prefetchStatusUpdated
PrefetchStatusUpdated = globals().get('PrefetchStatusUpdatedParameters', dict)  # Fallback to dict if type not defined


# Populate EVENT_CONFIGS with event configuration mappings
_globals = globals()
Speculation.EVENT_CONFIGS = {
    "prefetch_status_updated": EventConfig(
        "prefetch_status_updated",
        "speculation.prefetchStatusUpdated",
        _globals.get("PrefetchStatusUpdated", dict) if _globals.get("PrefetchStatusUpdated") else dict,
    ),
}