from typing import Any

from pandas import DataFrame

DEFAULT_MAX_DEBUG_DATAFRAME_ROWS = 100


def build_dataframe_debug_message(
    message: str,
    data: Any,
    max_rows: int = DEFAULT_MAX_DEBUG_DATAFRAME_ROWS,
) -> str:
    """
    Build a safe debug message for dataframe payloads

    Args:
     - message (str): Base message to identify the logged payload
     - data (Any): Payload to evaluate for dataframe-aware logging
     - max_rows (int): Maximum dataframe row count allowed for full payload logging

    Return:
     Formatted debug message with full dataframe content or compact summary
    """
    if not isinstance(data, DataFrame):
        return f'{message} {data}'

    rows = data.shape[0]
    if rows <= max_rows:
        return f'{message}\n{data.to_csv()}'

    return (
        f'{message} skipped because dataframe has {rows} rows '
        f'(max: {max_rows}). Shape: {data.shape}'
    )