"""Factor system API module."""


class FactorsAPI:
    """Access the factor system (standard tier).

    Available via ``client.factors``.
    """

    def __init__(self, client):
        self._request = client._request

    def list(self) -> dict:
        """Get list of all available factors with metadata."""
        return self._request("GET", "/api/factors")

    def categories(self) -> dict:
        """Get factor taxonomy with counts per category."""
        return self._request("GET", "/api/factors/categories")

    def data(self, factor_name: str, date: str = None) -> dict:
        """Get cross-sectional data for a factor across all stocks.

        Args:
            factor_name: Factor name (e.g. ``ep``).
            date: Date (YYYY-MM-DD). Defaults to latest.
        """
        return self._request(
            "GET", f"/api/factors/{factor_name}/data",
            params={"date": date},
        )

    def detail(self, factor_name: str) -> dict:
        """Get factor detailed metadata and statistics (mean, std, IC).

        Args:
            factor_name: Factor name.
        """
        return self._request("GET", f"/api/factors/{factor_name}/detail")

    def backtest(self, factor_name: str) -> dict:
        """Get single-factor backtest results (long-short returns, IC series).

        Args:
            factor_name: Factor name.
        """
        return self._request("GET", f"/api/factors/{factor_name}/backtest")

    def top_bottom(self, factor_name: str, top_n: int = None) -> dict:
        """Get stocks with highest and lowest factor values.

        Args:
            factor_name: Factor name.
            top_n: Number to return (default 10).
        """
        return self._request(
            "GET", f"/api/factors/{factor_name}/top-bottom-stocks",
            params={"top_n": top_n},
        )
