tradingview-mcp 1.0.0__py3-none-any.whl

tradingview_mcp/models.py

@@ -0,0 +1,154 @@
+"""
+Type definitions and models for TradingView Screener.
+
+Provides TypedDicts for API request/response structures.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+
+class FilterOperationDict(TypedDict):
+    """Filter operation for WHERE clauses."""
+
+    left: str
+    operation: Literal[
+        "greater",
+        "egreater",
+        "less",
+        "eless",
+        "equal",
+        "nequal",
+        "in_range",
+        "not_in_range",
+        "empty",
+        "nempty",
+        "crosses",
+        "crosses_above",
+        "crosses_below",
+        "match",
+        "nmatch",
+        "smatch",
+        "has",
+        "has_none_of",
+        "above%",
+        "below%",
+        "in_range%",
+        "not_in_range%",
+        "in_day_range",
+        "in_week_range",
+        "in_month_range",
+    ]
+    right: Any
+
+
+class SortByDict(TypedDict, total=False):
+    """Sort configuration."""
+
+    sortBy: str
+    sortOrder: Literal["asc", "desc"]
+    nullsFirst: bool
+
+
+class SymbolsDict(TypedDict, total=False):
+    """Symbols configuration for queries."""
+
+    query: dict[Literal["types"], list[str]]
+    tickers: list[str]
+    symbolset: list[str]
+    watchlist: dict[Literal["id"], int]
+    groups: list[dict[Literal["type", "values"], str]]
+
+
+class ExpressionDict(TypedDict):
+    """Single expression wrapper."""
+
+    expression: FilterOperationDict
+
+
+class OperationComparisonDict(TypedDict):
+    """AND/OR operation for complex filters."""
+
+    operator: Literal["and", "or"]
+    operands: list[Any]  # Can be OperationDict or ExpressionDict
+
+
+class OperationDict(TypedDict):
+    """Operation wrapper for complex filters."""
+
+    operation: OperationComparisonDict
+
+
+class QueryDict(TypedDict, total=False):
+    """Complete query structure for TradingView API."""
+
+    markets: list[str]
+    symbols: SymbolsDict
+    options: dict[str, Any]
+    columns: list[str]
+    filter: list[FilterOperationDict]
+    filter2: OperationComparisonDict
+    sort: SortByDict
+    range: list[int]
+    ignore_unknown_fields: bool
+    preset: str
+    price_conversion: dict[str, Any]
+
+
+class ScreenerRowDict(TypedDict):
+    """Single row in screener response."""
+
+    s: str  # symbol (NASDAQ:AAPL)
+    d: list[Any]  # data values
+
+
+class ScreenerDict(TypedDict):
+    """Screener API response structure."""
+
+    totalCount: int
+    data: list[ScreenerRowDict]
+
+
+class IndicatorMap(TypedDict, total=False):
+    """Common technical indicators."""
+
+    open: float | None
+    high: float | None
+    low: float | None
+    close: float | None
+    volume: float | None
+    change: float | None
+    SMA20: float | None
+    SMA50: float | None
+    SMA200: float | None
+    EMA20: float | None
+    EMA50: float | None
+    EMA200: float | None
+    RSI: float | None
+    RSI7: float | None
+    MACD_macd: float | None
+    MACD_signal: float | None
+    BB_upper: float | None
+    BB_lower: float | None
+    ADX: float | None
+    ATR: float | None
+    Stoch_K: float | None
+    Stoch_D: float | None
+    VWAP: float | None
+
+
+class AnalysisResult(TypedDict, total=False):
+    """Complete analysis result for a symbol."""
+
+    symbol: str
+    exchange: str
+    timeframe: str
+    timestamp: str
+    price: float
+    change_percent: float
+    indicators: IndicatorMap
+    bollinger: dict[str, Any]
+    signals: list[str]
+    rating: int
+    recommendation: str

tradingview_mcp/query.py

@@ -0,0 +1,367 @@
+"""
+Query class for building and executing TradingView screener queries.
+
+Provides a SQL-like interface for market screening.
+"""
+
+from __future__ import annotations
+
+import copy
+import pprint
+from typing import TYPE_CHECKING, Any, Literal
+
+import pandas as pd
+import requests
+
+from tradingview_mcp.column import Column
+from tradingview_mcp.constants import (
+    COLUMNS,
+    DEFAULT_RANGE,
+    HEADERS,
+    MARKETS,
+    URL,
+    get_column_name,
+)
+
+if TYPE_CHECKING:
+    from tradingview_mcp.models import (
+        FilterOperationDict,
+        OperationDict,
+        QueryDict,
+        SortByDict,
+    )
+
+
+def _impl_and_or_chaining(
+    expressions: tuple[FilterOperationDict | OperationDict, ...], operator: Literal["and", "or"]
+) -> OperationDict:
+    """Internal helper for AND/OR expression chaining."""
+    lst = []
+    for expr in expressions:
+        if "left" in expr:  # FilterOperationDict
+            lst.append({"expression": expr})
+        else:
+            lst.append(expr)
+    return {"operation": {"operator": operator, "operands": lst}}
+
+
+def And(*expressions: FilterOperationDict | OperationDict) -> OperationDict:
+    """
+    Combine filter expressions with AND logic.
+
+    Examples:
+        >>> And(Column('close') > 10, Column('volume') > 1000000)
+    """
+    return _impl_and_or_chaining(expressions, operator="and")
+
+
+def Or(*expressions: FilterOperationDict | OperationDict) -> OperationDict:
+    """
+    Combine filter expressions with OR logic.
+
+    Examples:
+        >>> Or(Column('type') == 'stock', Column('type') == 'fund')
+    """
+    return _impl_and_or_chaining(expressions, operator="or")
+
+
+class Query:
+    """
+    Build and execute TradingView screener queries.
+
+    Provides a SQL-like interface for market screening with support for:
+    - Column selection (SELECT)
+    - Filtering (WHERE)
+    - Sorting (ORDER BY)
+    - Pagination (OFFSET, LIMIT)
+    - Multiple markets
+
+    Examples:
+        Basic query:
+        >>> Query().get_scanner_data()
+
+        Custom columns:
+        >>> Query().select('name', 'close', 'RSI', 'MACD.macd').get_scanner_data()
+
+        With filters:
+        >>> Query().select('name', 'close').where(Column('RSI') < 30).get_scanner_data()
+
+        Multiple conditions:
+        >>> Query().where(
+        ...     Column('close') > 10,
+        ...     Column('volume') > 1000000,
+        ...     Column('RSI').between(30, 70)
+        ... ).get_scanner_data()
+
+        Crypto market:
+        >>> Query().set_markets('crypto').get_scanner_data()
+    """
+
+    def __init__(self) -> None:
+        """Initialize a new Query with default settings."""
+        self.query: QueryDict = {
+            "markets": ["america"],
+            "symbols": {"query": {"types": []}, "tickers": []},
+            "options": {"lang": "en"},
+            "columns": ["name", "close", "volume", "market_cap_basic"],
+            "sort": {"sortBy": "Value.Traded", "sortOrder": "desc"},
+            "range": DEFAULT_RANGE.copy(),
+        }
+        self.url = "https://scanner.tradingview.com/america/scan"
+
+    def set_markets(self, *markets: str) -> "Query":
+        """
+        Set the market(s) to query.
+
+        Available markets include:
+        - Crypto: 'crypto', 'coin'
+        - Countries: 'america', 'uk', 'germany', etc. (67 countries)
+        - Other: 'forex', 'futures', 'bonds', 'cfd', 'options'
+
+        Examples:
+            >>> Query().set_markets('crypto')
+            >>> Query().set_markets('america', 'uk', 'germany')
+
+        Args:
+            markets: One or more market identifiers
+
+        Returns:
+            Self for method chaining
+        """
+        if len(markets) == 1:
+            market = markets[0]
+            if market not in MARKETS:
+                raise ValueError(f"Unknown market: {market}. Available: {sorted(MARKETS)}")
+            self.url = URL.format(market=market)
+            self.query["markets"] = [market]
+        elif len(markets) > 1:
+            for m in markets:
+                if m not in MARKETS:
+                    raise ValueError(f"Unknown market: {m}. Available: {sorted(MARKETS)}")
+            self.url = URL.format(market="global")
+            self.query["markets"] = list(markets)
+        return self
+
+    def set_tickers(self, *tickers: str) -> "Query":
+        """
+        Set specific tickers to query.
+
+        Args:
+            tickers: One or more tickers in format 'EXCHANGE:SYMBOL'
+
+        Examples:
+            >>> Query().set_tickers('NASDAQ:TSLA', 'NYSE:GME', 'BINANCE:BTCUSDT')
+
+        Returns:
+            Self for method chaining
+        """
+        self.query.pop("markets", None)
+        self.query["symbols"] = {"tickers": list(tickers)}
+        self.url = "https://scanner.tradingview.com/global/scan"
+        return self
+
+    def select(self, *columns: Column | str) -> "Query":
+        """
+        Set columns to return in results.
+
+        Accepts both Column objects and string names.
+        Human-readable names are automatically converted to API names.
+
+        Examples:
+            >>> Query().select('name', 'close', 'RSI', 'MACD.macd')
+            >>> Query().select(Column('name'), 'close', 'Relative Strength Index (14)')
+
+        Args:
+            columns: Column objects or column names
+
+        Returns:
+            Self for method chaining
+        """
+        self.query["columns"] = [
+            col.name if isinstance(col, Column) else get_column_name(col) for col in columns
+        ]
+        return self
+
+    def where(self, *expressions: FilterOperationDict) -> "Query":
+        """
+        Add filter conditions (combined with AND).
+
+        Examples:
+            >>> Query().where(Column('RSI') < 30)
+            >>> Query().where(
+            ...     Column('close') > 10,
+            ...     Column('volume') > 1000000
+            ... )
+
+        Args:
+            expressions: Filter expressions created by Column comparisons
+
+        Returns:
+            Self for method chaining
+        """
+        self.query["filter"] = list(expressions)
+        return self
+
+    def where2(self, operation: OperationDict) -> "Query":
+        """
+        Add complex filter with AND/OR logic.
+
+        Use And() and Or() functions to build complex expressions.
+
+        Examples:
+            >>> Query().where2(
+            ...     Or(
+            ...         And(Column('type') == 'stock', Column('RSI') < 30),
+            ...         And(Column('type') == 'fund', Column('change') > 5)
+            ...     )
+            ... )
+
+        Args:
+            operation: Operation created by And() or Or()
+
+        Returns:
+            Self for method chaining
+        """
+        self.query["filter2"] = operation["operation"]
+        return self
+
+    def order_by(self, column: Column | str, ascending: bool = True) -> "Query":
+        """
+        Set sort order for results.
+
+        Examples:
+            >>> Query().order_by('volume', ascending=False)  # Highest volume first
+            >>> Query().order_by('RSI', ascending=True)  # Lowest RSI first
+
+        Args:
+            column: Column to sort by
+            ascending: True for ascending, False for descending
+
+        Returns:
+            Self for method chaining
+        """
+        column_name = column.name if isinstance(column, Column) else get_column_name(column)
+        sort_order: Literal["asc", "desc"] = "asc" if ascending else "desc"
+        self.query["sort"] = {"sortBy": column_name, "sortOrder": sort_order}
+        return self
+
+    def offset(self, offset: int) -> "Query":
+        """
+        Set starting position for results (for pagination).
+
+        Examples:
+            >>> Query().offset(50).limit(50)  # Get results 50-100
+
+        Args:
+            offset: Starting index (0-based)
+
+        Returns:
+            Self for method chaining
+        """
+        self.query["range"][0] = offset
+        return self
+
+    def limit(self, limit: int) -> "Query":
+        """
+        Set maximum number of results to return.
+
+        Examples:
+            >>> Query().limit(100)
+
+        Args:
+            limit: Maximum results (default 50)
+
+        Returns:
+            Self for method chaining
+        """
+        self.query["range"][1] = limit
+        return self
+
+    def get_scanner_data(
+        self, *, timeout: int = 20, **kwargs: Any
+    ) -> tuple[int, pd.DataFrame]:
+        """
+        Execute the query and return results.
+
+        Args:
+            timeout: Request timeout in seconds
+            **kwargs: Additional arguments passed to requests.post()
+
+        Returns:
+            Tuple of (total_count, DataFrame)
+            - total_count: Total matching records (may be more than returned)
+            - DataFrame: Results with columns as specified in select()
+
+        Raises:
+            requests.HTTPError: If the API request fails
+        """
+        kwargs.setdefault("headers", HEADERS)
+        kwargs.setdefault("timeout", timeout)
+
+        r = requests.post(self.url, json=self.query, **kwargs)
+
+        if r.status_code >= 400:
+            r.reason += f"\nBody: {r.text}\n"
+            r.raise_for_status()
+
+        json_obj = r.json()
+        rows_count = json_obj.get("totalCount", 0)
+        data = json_obj.get("data", [])
+
+        df = pd.DataFrame(
+            data=([row["s"], *row["d"]] for row in data),
+            columns=["ticker", *self.query.get("columns", [])],
+        )
+        return rows_count, df
+
+    def get_scanner_data_raw(self, *, timeout: int = 20, **kwargs: Any) -> dict[str, Any]:
+        """
+        Execute the query and return raw JSON response.
+
+        Useful when you don't need DataFrame conversion.
+
+        Returns:
+            Raw JSON response dict
+        """
+        kwargs.setdefault("headers", HEADERS)
+        kwargs.setdefault("timeout", timeout)
+
+        r = requests.post(self.url, json=self.query, **kwargs)
+        r.raise_for_status()
+        return r.json()
+
+    def copy(self) -> "Query":
+        """Create a deep copy of this query."""
+        new = Query()
+        new.query = copy.deepcopy(self.query)
+        new.url = self.url
+        return new
+
+    def __repr__(self) -> str:
+        return f"<Query {pprint.pformat(self.query)}>"
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Query) and self.query == other.query
+
+
+def get_all_symbols(market: str = "america") -> list[str]:
+    """
+    Get all symbols for a given market.
+
+    Examples:
+        >>> get_all_symbols('america')
+        ['NASDAQ:AAPL', 'NYSE:GME', ...]
+
+        >>> get_all_symbols('crypto')
+        ['BINANCE:BTCUSDT', 'COINBASE:ETHUSD', ...]
+
+    Args:
+        market: Market identifier (default 'america')
+
+    Returns:
+        List of ticker strings in 'EXCHANGE:SYMBOL' format
+    """
+    r = requests.get(URL.format(market=market), headers=HEADERS, timeout=20)
+    r.raise_for_status()
+    data = r.json().get("data", [])
+    return [dct["s"] for dct in data]