from __future__ import annotations

from qroissant._config import DecodeOptions, EncodeOptions
from qroissant._message import Compression, Encoding, MessageType
from qroissant._values import Value

def decode(
    payload: object,
    /,
    *,
    options: DecodeOptions | None = None,
) -> Value:
    """Decode an IPC payload into a typed qroissant value.

    Parameters
    ----------
    payload : object
        Raw q IPC payload as ``bytes``, a read-only contiguous buffer,
        or an object exposing such a buffer via ``.data``.
    options : DecodeOptions | None, optional
        Decoding and Arrow projection options. When omitted, the default
        qroissant options are used.

    Returns
    -------
    Value
        Decoded q object represented by qroissant wrapper types.

    Raises
    ------
    DecodeError
        Raised when the IPC payload cannot be decoded into a valid q value.
    ProtocolError
        Raised when the frame header is malformed or unsupported.
    """
    ...


def encode(
    value: object,
    /,
    *,
    options: EncodeOptions | None = None,
    encoding: Encoding = Encoding.LITTLE_ENDIAN,
    message_type: MessageType = MessageType.ASYNCHRONOUS,
    compression: Compression = Compression.UNCOMPRESSED,
) -> bytes:
    """Encode a qroissant value into q IPC bytes.

    Parameters
    ----------
    value : object
        A qroissant wrapper value, ``None`` for q null, any object exposing a
        compatible ``serialize`` method, or an object implementing the Arrow
        PyCapsule interface.
    options : EncodeOptions | None, optional
        Arrow-to-q encoding hints applied when ``value`` is encoded
        from an Arrow array or stream.
    encoding : Encoding, default=Encoding.LITTLE_ENDIAN
        Endianness used in the generated IPC payload.
    message_type : MessageType, default=MessageType.ASYNCHRONOUS
        IPC message type tag written into the frame header.
    compression : Compression, default=Compression.UNCOMPRESSED
        Compression mode for payload encoding.

    Returns
    -------
    bytes
        Encoded q IPC payload.
    """
    ...

