Tickers

def get_yfinance_symbol_candidates(symbol: str) -> list[str]:
    """Return Yahoo Finance ticker candidates for a user supplied symbol.

    Explicit Yahoo Finance symbols such as `AAPL`, `TSM`, or `2330.TW` are
    accepted directly. Bare symbols are resolved by Yahoo Finance Search, so
    Taiwan stock codes like `2330` and `8069` can be passed without suffixes.

    Args:
        symbol (str): The symbol to find candidates for.

    Returns:
        list[str]: A list of candidate ticker symbols.

    Raises:
        ValueError: If the ticker symbol is empty.
    """
    raw_symbol = symbol.strip()
    if not raw_symbol:
        raise ValueError("Ticker symbol cannot be empty.")

    if ":" in raw_symbol:
        _, raw_symbol = raw_symbol.split(":", 1)
        raw_symbol = raw_symbol.strip()

    yahoo_symbol = raw_symbol.upper()
    if "." in yahoo_symbol:
        candidates = [yahoo_symbol]
        if not yahoo_symbol.endswith(TAIWAN_SUFFIXES):
            candidates.append(yahoo_symbol.replace(".", "-"))
        return _dedupe_symbols(candidates)

    candidates = []
    if yahoo_symbol.replace("-", "").isalpha():
        candidates.append(yahoo_symbol)
    candidates.extend(_search_yfinance_symbols(raw_symbol))
    if yahoo_symbol.isdigit():
        candidates.extend(f"{yahoo_symbol}{suffix}" for suffix in TAIWAN_SUFFIXES)
    candidates.append(yahoo_symbol)

    return _dedupe_symbols(candidates)

def describe_symbol_candidates(symbol: str, candidates: list[str]) -> str:
    """Format attempted Yahoo Finance symbols for user-facing tool output.

    Args:
        symbol (str): The original symbol queried.
        candidates (list[str]): The list of candidates attempted.

    Returns:
        str: A comma-separated string of candidates or the single matching symbol.
    """
    if len(candidates) == 1 and candidates[0] == symbol.upper():
        return candidates[0]
    return candidates[0] if len(candidates) == 1 else ", ".join(candidates)