tradingview_screener.models

  1from __future__ import annotations
  2
  3from typing import TypedDict, TYPE_CHECKING
  4
  5if TYPE_CHECKING:
  6    from typing_extensions import Any, Literal, NotRequired
  7
  8
  9class FilterOperationDict(TypedDict):
 10    left: str
 11    operation: Literal[
 12        'greater',
 13        'egreater',
 14        'less',
 15        'eless',
 16        'equal',
 17        'nequal',
 18        'in_range',  # equivalent to SQL `BETWEEN` or `IN (...)`
 19        'not_in_range',
 20        'empty',
 21        'nempty',
 22        'crosses',
 23        'crosses_above',
 24        'crosses_below',
 25        'match',  # the same as: `LOWER(col) LIKE '%pattern%'`
 26        'nmatch',  # not match
 27        # simple match, there is no method for this operation as of right now, because it does
 28        # the same thing as `match`
 29        'smatch',
 30        'has',  # set must contain one of the values
 31        'has_none_of',  # set must NOT contain ANY of the values
 32        'above%',
 33        'below%',
 34        'in_range%',
 35        'not_in_range%',
 36        'in_day_range',
 37        'in_week_range',
 38        'in_month_range',
 39    ]
 40    right: Any  # its optional when the operation is `empty` or `nempty`
 41
 42
 43class SortByDict(TypedDict):
 44    sortBy: str
 45    sortOrder: Literal['asc', 'desc']
 46    nullsFirst: NotRequired[bool]
 47
 48
 49class SymbolsDict(TypedDict, total=False):
 50    query: dict[Literal['types'], list[str]]
 51    tickers: list[str]
 52    symbolset: list[str]
 53    watchlist: dict[Literal['id'], int]
 54    groups: list[dict[Literal['type', 'values'], str]]
 55    # for example [{'type': 'index', 'values': ['DJ:DJU']}]
 56
 57
 58class ExpressionDict(TypedDict):
 59    expression: FilterOperationDict
 60
 61
 62class OperationComparisonDict(TypedDict):
 63    operator: Literal['and', 'or']
 64    operands: list[OperationDict | ExpressionDict]
 65
 66
 67class OperationDict(TypedDict):
 68    operation: OperationComparisonDict
 69
 70
 71class QueryDict(TypedDict, total=False):
 72    """
 73    The fields that can be passed to the tradingview scan API
 74    """
 75
 76    markets: list[str]
 77    symbols: SymbolsDict
 78    options: dict[str, Any]  # example: `{"options": {"lang": "en"}}`
 79    columns: list[str]
 80    filter: list[FilterOperationDict]
 81    filter2: OperationComparisonDict
 82    sort: SortByDict
 83    range: list[int]  # list with two integers, i.e. `[0, 100]`
 84    ignore_unknown_fields: bool  # default false
 85    preset: Literal['index_components_market_pages', 'pre-market-gainers']  # there are many
 86    # other presets (these are just some a examples)
 87    price_conversion: (
 88        dict[Literal['to_symbol'], bool]
 89        | dict[
 90            Literal['to_currency'], str  # this string should be the currency in lower-case
 91        ]
 92    )
 93
 94
 95class ScreenerRowDict(TypedDict):
 96    s: str  # symbol (NASDAQ:AAPL)
 97    d: list  # data, list of values
 98
 99
100class ScreenerDict(TypedDict):
101    totalCount: int
102    data: list[ScreenerRowDict]
103
104
105class ScreenerRowDictV2(TypedDict):
106    s: str  # for options: 'OPRA:AAPL260821C200.0'
107    f: list  # data, list of values
108
109
110class ScreenerDictV2(TypedDict):
111    totalCount: int
112    fields: list[str]
113    symbols: list[ScreenerRowDictV2]
114    time: str  # '2026-04-24T13:45:37Z'