"""Transport protocol interface for AR488 backend.

Defines the abstract interface that both DirectTransport and BridgeTransport
implement. This keeps sessions.py transport-agnostic.
"""

import abc


class AR488Transport(abc.ABC):
    """Abstract interface for AR488 command transport.

    All methods are synchronous — the async bridging (if needed)
    happens inside BridgeTransport.
    """

    @abc.abstractmethod
    def connect(self) -> None:
        """Establish connection and run AR488 init sequence."""

    @abc.abstractmethod
    def disconnect(self) -> None:
        """Close the connection."""

    @abc.abstractmethod
    def is_connected(self) -> bool:
        """Check if transport is connected."""

    @abc.abstractmethod
    def send_command(self, command: str) -> None:
        """Send a SCPI command to the currently addressed instrument."""

    @abc.abstractmethod
    def send_raw(self, command: str) -> None:
        """Send a raw AR488 ++ command."""

    @abc.abstractmethod
    def read_response(self, timeout_ms: int = 10000) -> str:
        """Send ++read eoi and read the response line."""

    @abc.abstractmethod
    def set_address(self, address: int) -> None:
        """Address a GPIB device (++addr)."""

    @abc.abstractmethod
    def serial_poll(self, address: int) -> int:
        """Serial poll an instrument (++spoll), return status byte."""

    @abc.abstractmethod
    def find_listeners(self) -> list[int]:
        """Scan bus for listeners (++findlstn), return addresses."""

    @abc.abstractmethod
    def interface_clear(self) -> None:
        """Assert IFC (++ifc)."""
