"""因子表达式注册表（包装 vnpy.alpha AlphaDataset 范式）."""
from typing import Any

_REGISTRY: dict[str, dict[str, Any]] = {}


def register_factor(name: str, expression: str, category: str = "custom") -> None:
    """注册因子表达式.

    Args:
        name: 因子名称
        expression: 因子表达式字符串（使用 ts_/cs_/math 算子 + 列名）
        category: 因子分类（默认 "custom"）

    Raises:
        ValueError: 当因子名称已存在时
    """
    if name in _REGISTRY:
        raise ValueError(f"因子已存在: {name}")
    _REGISTRY[name] = {
        "name": name,
        "expression": expression,
        "category": category
    }


def get_factor(name: str) -> dict[str, Any] | None:
    """获取因子表达式.

    Args:
        name: 因子名称

    Returns:
        因子信息字典，不存在时返回 None
    """
    return _REGISTRY.get(name)


def list_factors(category: str | None = None) -> list[dict[str, Any]]:
    """列出因子表达式.

    Args:
        category: 分类过滤器，None 表示返回所有因子

    Returns:
        因子信息字典列表
    """
    if category is None:
        return list(_REGISTRY.values())
    return [f for f in _REGISTRY.values() if f["category"] == category]