"""Table type markers and resolved table info for use with ``model.Table()``.

``Iceberg`` and ``Native`` are passed as the ``type=`` kwarg to ``model.Table()``
to explicitly control how a table is created, overriding any defaults set in
the ``tables:`` section of ``raiconfig.yaml``.

``TableInfo`` is the fully-resolved config for a table, populated at
``Table.__init__`` time and accessible via ``table.info``.

Example::

    from relationalai.semantics import Model
    from relationalai.config.tables import Iceberg, Native

    m = Model("my_model")

    # Iceberg table with volume from config default
    out1 = m.Table("db.schema.table1", type=Iceberg())

    # Iceberg table with explicit volume override
    out2 = m.Table("db.schema.table2", type=Iceberg(external_volume="my_volume"))

    # Explicit opt-out of iceberg default
    out3 = m.Table("db.schema.table3", type=Native())
"""

from __future__ import annotations

from dataclasses import dataclass


@dataclass
class Iceberg:
    """Marks a table as an Iceberg table.

    Parameters
    ----------
    external_volume : str, optional
        Snowflake external volume to use for this table. If ``None``, falls
        back to ``tables.default_volume`` in config, then to Snowflake-managed.
    """

    external_volume: str | None = None


@dataclass
class Native:
    """Marks a table as a native Snowflake table.

    Use this to explicitly opt out of a ``default_type: iceberg`` set in
    ``raiconfig.yaml`` for a specific table.
    """

    pass


@dataclass
class TableInfo:
    """Fully-resolved table configuration, stored on ``Table.info``.

    Populated at ``Table.__init__`` time by merging the explicit ``type=``
    kwarg, the matching per-table config entry, and global defaults from
    ``tables:`` in ``raiconfig.yaml``.

    Attributes
    ----------
    type : Iceberg or Native
        Resolved table type. Never ``None`` — defaults to ``Native()``.
    volume : str or None
        Resolved external volume. Priority: ``Iceberg(external_volume=...)``
        kwarg → per-table ``volume:`` in config → ``default_volume`` in config.
    fqn : str or None
        FQN override from per-table config entry, or ``None`` if not set.
    physical_name : str
        Resolved physical name. Priority: ``fqn`` → ``default_schema`` prefix
        for unqualified names → logical name as-is.
    """

    type: Iceberg | Native
    volume: str | None
    fqn: str | None
    physical_name: str
