tvscreener wraps TradingView screeners in Python, and its licence metadata disagrees with itself

One entry point per screener, all of them returning a dataframe

The library's shape is a class per screener type, each constructed empty and each terminated by get(), which returns a Pandas Dataframe. The Stock screener returns 150 rows by default:

import tvscreener as tvs

ss = tvs.StockScreener()
df = ss.get()  # returns a dataframe with 150 rows by default

The other constructors follow the same shape: ForexScreener, CryptoScreener, BondScreener, FuturesScreener, CoinScreener, ETFScreener, IndexScreener and EconomicsScreener. Two of them need an argument or differ meaningfully. OptionScreener takes an underlying symbol, for example tvs.OptionScreener("NASDAQ:AAPL"), and the README notes it returns option chains with greeks and implied volatility. IndexScreener has a main_indices() shortcut for indices, CFDs and crypto market caps.

There are also module-level helpers for things that are not screeners at all: get_iv_term_structure, get_yield_curve, search_symbols, and the fundamentals and news functions below.

The economics screener is the one to note for sizing. The README calls it 15,000+ economic indicators, and you narrow it with a field filter such as tvs.EconomicsField.COUNTRY_CODE == 'US'. Yield curves are country-scoped, with get_yield_curve("US") as the example.

Filtering is field objects, not strings, and OR is a pipe

Queries are built with a where() method that takes comparison expressions against typed field objects, one namespace per screener, StockField, OptionField, EconomicsField and so on. Filtering combines with & and |, and the README calls the OR form a nested filter:

ss = tvs.StockScreener()
ss.where((tvs.StockField.SECTOR == 'Finance') | (tvs.StockField.SECTOR == 'Utilities'))
ss.where(tvs.StockField.PRICE.above_pct(tvs.StockField.SIMPLE_MOVING_AVERAGE_50, 5))
df = ss.get()

The field objects carry their own comparison helpers, above_pct() in that line, and the feature list names others: has(), in_day_range() and between(), the last used in the option example where(tvs.OptionField.DELTA.between(0.4, 0.6)). Using a field object rather than a string is what makes the type-safe validation possible, since the library can catch a field that belongs to a different screener before the request is sent.

Field coverage is the headline claim: 13,000+ fields across all screener types. Discovery is treated as a feature in its own right, with the README listing field search by name, technicals, category filtering, and curated field presets. TradingView's own screens are exposed through set_preset(), for example tvs.StockScreener().set_preset(tvs.Preset.GAINERS).get() for gainers, with losers and all-time highs named as the other examples.

A code generator at deepentropy.github.io/tvscreener builds the same queries visually and emits Python, across the 10 screener types including Government Bond, with filters combined by AND and OR.

Version 0.8 turned a screener client into a fundamentals client

The most recent release train is worth looking at, because it changed the scope of the library. The tags v0.7.0, v0.8.0 and v0.8.1 all landed on 2026-10-15, and the README marks 0.8 as the release that added financial statements, real-time quotes, an economic calendar, news, filings and earnings call transcripts, also exposed as MCP tools.

income = tvs.get_financials("NASDAQ:AAPL", "income", "FY")
balance = tvs.get_financials("NASDAQ:AAPL", "balance_sheet", "FQ")
events = tvs.get_corporate_events("NASDAQ:AAPL")
seasonals = tvs.get_seasonals("NASDAQ:AAPL")

The README states about 20 years of annual and 8 years of quarterly income statement, balance sheet and cash flow data. Real-time quotes are pushed rather than polled, which is why websocket-client is a runtime dependency:

for quote in tvs.stream_quotes(["NASDAQ:AAPL", "BINANCE:BTCUSDT"], duration=60):
    print(quote["symbol"], quote.get("price"))

News and documents are separate from the screener. get_news filters by category, with corp_activity="insider_trading" as the example, get_article pulls the text of one article, get_documents lists documents by category such as call_transcript, and get_document retrieves one transcript by id.

Calendars cover earnings, dividends, IPOs and macro releases, each taking date bounds:

earnings = tvs.get_earnings_calendar("2026-10-12", "2026-10-18")
ipos = tvs.get_ipo_calendar("2026-10-01", "2026-10-31", markets=tvs.Market.ALL)
macro = tvs.get_economic_calendar("2026-10-12", "2026-10-18", countries=["US", "EU"], importance="high")

The README also notes any time interval is available with no need to be a registered user, from 1D down to 5m and 1h, and that results can be styled to resemble TradingView's own formatting.

Installing, the MCP extra, and what the metadata actually says

Install from PyPI or from GitHub:

pip install tvscreener

$ pip install git+https://github.com/deepentropy/tvscreener.git

There is an extra for the MCP server that exposes the library to AI assistants, installed as tvscreener[mcp] and registered as a command:

pip install tvscreener[mcp]
claude mcp add tvscreener -- tvscreener-mcp

The pyproject.toml is where the concrete constraints live. Python 3.10 or newer is required, the build backend is setuptools with a wheel, and there are three runtime dependencies and no others: pandas>=1.3.0, requests>=2.27.1 and websocket-client>=1.6.0. Dev extras add pytest, pytest-cov, build and twine; the mcp extra adds mcp[cli]>=1.0.0 and tabulate. The package ships py.typed, so type checkers use its annotations, and the project is classified as Development Status :: 4 - Beta.

One contradiction is worth flagging before you adopt. The repository's licence metadata is Apache-2.0, while pyproject.toml declares license = "MIT" and names the author as DeepEntropy. Those are different licences with different notice and patent terms, and the README carries no licence section of its own to break the tie. Treat the terms as unresolved until you ask, rather than picking the one you prefer.

requirements.txt exists alongside pyproject.toml and repeats the same three runtime pins, with a comment saying it is for convenience during development and pointing at pip install -e ".[dev]".

An unofficial client over an undocumented endpoint

The disclaimer in the README is unusually direct and should be read before any code, not after a problem appears. The project states it is an unofficial, third-party library, is not affiliated with, endorsed by or connected to TradingView in any way, that TradingView is a trademark of TradingView, Inc., that it provides a Python interface to publicly available data, and that use is at your own risk and subject to TradingView's terms of service.

The project is not archived and the last push was on 2026-10-15, the same day as the three tags. Maintenance activity is real, but it also means the library tracks an interface that moves with TradingView's own front end.

Editorial conclusion

tvscreener fits a Python researcher who wants TradingView's screener fields and presets in a dataframe without a browser, especially now that version 0.8 added financials, real-time quotes and an MCP server. It does not fit anything that needs a data licensing guarantee or a stable vendor contract, because the README states it is an unofficial third-party library, is not affiliated with TradingView, and use is at your own risk and subject to TradingView's terms of service. Before adopting it, resolve the licence contradiction, since the repository is filed under Apache-2.0 while pyproject.toml declares MIT, and confirm that automated querying of this data is permitted under the terms you are subject to.

Frequently asked questions

Official sources

1. deepentropy/tvscreener on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases