"""图表导出。

工具箱的最终消费者是**论文**，所以这一层不是"附赠功能"，
而是原建议里最被低估的部分（它只给了一句 `save_figure`）。
"""

from __future__ import annotations

from pathlib import Path
from typing import Any

__all__ = ["save_figure", "save_table"]


def save_figure(
    fig: Any,
    path: str | Path,
    dpi: int = 300,
    formats: tuple[str, ...] = ("png", "pdf"),
    bbox_inches: str = "tight",
    transparent: bool = False,
) -> list[Path]:
    """保存图，默认同时出 PNG（预览用）和 PDF（LaTeX 插图用）。

    Parameters
    ----------
    formats:
        美赛论文如果用 LaTeX 排版，**矢量图（PDF/EPS）比 PNG 清晰得多**，
        所以默认两种都出。

    Returns
    -------
    实际写出的文件路径列表。

    Notes
    -----
    建议配合项目的 figure 目录约定：`figures/fig{序号}_{短名}.pdf`，
    图号与正文引用一一对应，最后核对时不容易错位。
    """
    # TODO(L0)
    raise NotImplementedError


def save_table(
    df: Any,
    path: str | Path,
    fmt: tuple[str, ...] = ("csv", "latex", "markdown"),
    caption: str | None = None,
    label: str | None = None,
    float_format: str = "%.4f",
    index: bool = True,
) -> list[Path]:
    r"""导出结果表，默认同时出 CSV + LaTeX + Markdown。

    这是**节省时间最多的一个函数**：`compare_models`、`parameter_sweep`、
    `topsis` 的结果都能直接 `save_table(r.data, "tab3_model_compare")`，
    然后把 LaTeX 片段粘进论文，不用手工敲表格。

    Parameters
    ----------
    caption / label:
        写进 LaTeX 的 `\caption{}` 与 `\label{}`，
        表号与正文 `\ref{}` 的对应关系就不会断。

    Returns
    -------
    实际写出的文件路径列表。

    Examples
    --------
    >>> paths = save_table(df, "tables/tab2", caption="模型对比")   # doctest: +SKIP
    """
    # TODO(L1)
    raise NotImplementedError