from __future__ import annotations

from pathlib import Path
from typing import Any

import pandas as pd

CSV_KW_ALLOWED = {"sep", "encoding", "dtype", "parse_dates", "na_values", "nrows"}


def coerce_to_df(data: Any, **csv_kwargs) -> pd.DataFrame:
    """Convert a CSV path, buffer, or DataFrame into a pandas DataFrame."""
    if isinstance(data, pd.DataFrame):
        return data
    if isinstance(data, (str, bytes, Path)):
        return pd.read_csv(data, **{k: v for k, v in csv_kwargs.items() if k in CSV_KW_ALLOWED})
    if hasattr(data, "read"):  # file-like object
        return pd.read_csv(data, **{k: v for k, v in csv_kwargs.items() if k in CSV_KW_ALLOWED})
    raise TypeError("data must be a pandas.DataFrame, a path/CSV string, or a file-like object")
