# shner-elmo/tradingview-screener architecture

> Architecture diagram of the GitHub repository shner-elmo/tradingview-screener, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shner-elmo/tradingview-screener
- Repository: https://github.com/shner-elmo/tradingview-screener

## Overview

This Python library builds TradingView screener queries and returns matching market data, commonly as a pandas DataFrame. Users can choose a market-specific screener, select fields and timeframes, compose filters, set sorting and limits, then submit the query; cookies can be supplied for authenticated real-time data. Column builds filter expressions, while models defines the query and response shapes. Source excerpts establish query construction, HTTP submission, and screener factories; unsampled query methods and response-conversion details are represented only at the documented level.

Main entry points: [`src/tradingview_screener/query.py`](https://github.com/shner-elmo/tradingview-screener/blob/master/src/tradingview_screener/query.py) (Query Builder), [`src/tradingview_screener/column.py`](https://github.com/shner-elmo/tradingview-screener/blob/master/src/tradingview_screener/column.py) (Column Filters), [`src/tradingview_screener/screeners.py`](https://github.com/shner-elmo/tradingview-screener/blob/master/src/tradingview_screener/screeners.py) (Market Screeners), [`src/tradingview_screener/models.py`](https://github.com/shner-elmo/tradingview-screener/blob/master/src/tradingview_screener/models.py) (Query Schemas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_querying["Query Construction"]
  node_query["Query Builder<br/>[query.py]"]
  node_column["Column Filters<br/>[column.py]"]
end

subgraph group_catalog["Screener Catalog"]
  node_screeners["Market Screeners<br/>[screeners.py]"]
end

subgraph group_contracts["Data Contracts"]
  node_models["Query Schemas<br/>[models.py]"]
end

node_user(("Library User"))
node_tradingview["TradingView API"]
node_pandas["Pandas DataFrame"]

node_user -->|"chooses market"| node_screeners
node_user -->|"builds query"| node_query
node_screeners -->|"creates"| node_query
node_query -->|"uses fields"| node_column
node_column -->|"types filters"| node_models
node_query -->|"types payload"| node_models
node_query -->|"POSTs scan"| node_tradingview
node_tradingview -->|"returns results"| node_query
node_query -->|"builds DataFrame"| node_pandas

click node_query "https://github.com/shner-elmo/tradingview-screener/blob/master/src/tradingview_screener/query.py"
click node_column "https://github.com/shner-elmo/tradingview-screener/blob/master/src/tradingview_screener/column.py"
click node_screeners "https://github.com/shner-elmo/tradingview-screener/blob/master/src/tradingview_screener/screeners.py"
click node_models "https://github.com/shner-elmo/tradingview-screener/blob/master/src/tradingview_screener/models.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_query,node_column,node_user,node_tradingview toneBlue
class node_screeners toneAmber
class node_models toneMint
class node_pandas toneIndigo
```

## Components

### Query Construction

- [Query Builder](https://github.com/shner-elmo/tradingview-screener/blob/master/src/tradingview_screener/query.py): `src/tradingview_screener/query.py`
- [Column Filters](https://github.com/shner-elmo/tradingview-screener/blob/master/src/tradingview_screener/column.py): `src/tradingview_screener/column.py`

### Screener Catalog

- [Market Screeners](https://github.com/shner-elmo/tradingview-screener/blob/master/src/tradingview_screener/screeners.py): `src/tradingview_screener/screeners.py`

### Data Contracts

- [Query Schemas](https://github.com/shner-elmo/tradingview-screener/blob/master/src/tradingview_screener/models.py): `src/tradingview_screener/models.py`

### Other components

- **Library User**
- **TradingView API**
- **Pandas DataFrame**

## Connections

- Library User → Market Screeners: chooses market (evidence: `README.md`)
- Library User → Query Builder: builds query (evidence: `README.md`)
- Market Screeners → Query Builder: creates (evidence: `src/tradingview_screener/screeners.py`)
- Query Builder → Column Filters: uses fields (evidence: `src/tradingview_screener/query.py`)
- Column Filters → Query Schemas: types filters (evidence: `src/tradingview_screener/column.py`)
- Query Builder → Query Schemas: types payload (evidence: `src/tradingview_screener/query.py`)
- Query Builder → TradingView API: POSTs scan (evidence: `src/tradingview_screener/query.py`)
- TradingView API → Query Builder: returns results (evidence: `README.md`)
- Query Builder → Pandas DataFrame: builds DataFrame (evidence: `src/tradingview_screener/query.py`)
