"""
This package provides a unified API for working with a variety of software-defined radios.
It streamlines tasks involving signal reception and transmission, as well as common administrative
operations such as detecting and configuring available devices.
"""

__all__ = ["SDR", "SDRError", "SDRParameterError", "MockSDR", "get_sdr_device"]

from .mock import MockSDR
from .sdr import SDR, SDRError, SDRParameterError


def get_sdr_device(device_type: str, ident: str | None = None, tx: bool = False) -> SDR:
    """Return an SDR instance for *device_type*.

    For ``"mock"`` / ``"sim"`` device types, returns a :class:`MockSDR`
    immediately (no hardware required).  For all real device types, delegates
    to ``ria_toolkit_oss_cli.ria_toolkit_oss.common.get_sdr_device`` if the
    CLI package is installed; otherwise raises ``ImportError`` with a helpful
    message.

    Args:
        device_type: Device name (``"mock"``, ``"pluto"``, ``"usrp"``, …).
        ident: Optional device identifier (IP address, serial number, …).
        tx: If True, require TX capability.
    """
    if device_type in ("mock", "sim"):
        return MockSDR()

    # Delegate real device types to the CLI package which holds the driver
    # imports behind hardware-specific optional dependencies.
    try:
        from ria_toolkit_oss_cli.ria_toolkit_oss.common import (
            get_sdr_device as _cli_get,
        )
    except ImportError as exc:
        raise ImportError(
            f"ria_toolkit_oss_cli is required to use hardware SDR device '{device_type}'. "
            "Install it with: pip install ria-toolkit-oss-cli"
        ) from exc

    return _cli_get(device_type, ident=ident, tx=tx)