tvscreener - Moses Yebei

The Problem

Clients need programmatic access to TradingView’s public screener data across stocks, crypto, forex, bonds, futures and coins. The native UI provides no API, and scraping the site manually is brittle and hard to maintain. A reusable Python wrapper that hides the HTTP details, validates field types and returns a tidy pandas.DataFrame removes the most common source of friction for quantitative teams.

What This Does

tvscreener implements a thin, type‑safe client library. Core screener classes live under tvscreener/core/ (e.g. stock.py, crypto.py) and inherit common logic from tvscreener/core/base.py. Field definitions are collected in tvscreener/field/ – the package’s hub (tvscreener/field/__init__.py) re‑exports 16 field classes and utilities such as add_rec and add_historical.

The optional MCP server (tvscreener/mcp/server.py) exposes a small HTTP/JSON endpoint that AI assistants (Claude, etc.) can call. It offers high‑level helpers like discover_fields, custom_query, search_stocks, and get_top_movers. The web UI in app/ (HTML + JS) drives the visual code generator that produces ready‑to‑run Python snippets.

How It Is Wired

Execution starts at the MCP entry points in tvscreener/mcp/server.py. For example, custom_query (line 103) invokes a chain of 12 internal functions, ultimately calling StockScreener._get_filter (used in 21 places) and get_url (network request) defined in tvscreener/util.py. The most‑used class is StockScreener – its methods appear in 46 distinct call sites.

core/base.py creates the HTTP payload, validates filters via tvscreener/filter.py, and forwards the request to TradingView. The response is parsed into a pandas.DataFrame by beauty.py.

The hub module tvscreener/field/__init__.py is referenced by 11 other modules and defines 65 functions and 16 classes; any change here has a large blast radius. Two import cycles exist (field/__init__.py ↔ filter.py), which increase cognitive load and risk of runtime errors. Deep nesting (max depth 6) appears in util.py, filter.py and the code‑gen script .dev/codegen/generate.py, making the control flow harder to follow.

Only two external effects are observed: a single file‑write in app/scripts/export_fields.py and a single outbound HTTP call in core/base.py. All other logic stays inside the repository.

How To Use It

# Install the library with optional MCP support
pip install "tvscreener[mcp]"

# Run the MCP server (entry point installed by the package)
tvscreener-mcp

The server listens on localhost:8000 (default). To screen stocks from Python:

from tvscreener import StockScreener, StockField

ss = StockScreener()
ss.where(StockField.PRICE > 50, StockField.VOLUME >= 1_000_000)
df = ss.get()          # returns pandas.DataFrame
print(df.head())

The web UI is served from app/index.html; the bundled app/js/code-generator.js calls the MCP endpoints to generate the same Python code shown above.

Real‑World Use

A quant team can embed the library in nightly pipelines:

from tvscreener import StockScreener, STOCK_VALUATION_FIELDS

screener = StockScreener()
screener.select(*STOCK_VALUATION_FIELDS)
screener.where(StockField.MARKET_CAPITALIZATION.between(1e9, 5e10))
df = screener.get()
df.to_parquet("data/stock_valuation.parquet")

The resulting parquet file feeds downstream risk models without any custom scraping logic.

Code Health & Issues

HIGH – Pin third‑party GitHub Actions to a commit SHA (.github/workflows/*).
HIGH – No lockfile alongside pyproject.toml; reproducing the exact dependency set is impossible.
MEDIUM – Dependabot/Renovate not configured; vulnerable transitive packages could linger.
MEDIUM – No dependency‑vulnerability scan in CI; known CVEs would not be caught automatically.
MEDIUM – Checkout step keeps the token; set persist-credentials: false in codecov.yml.
LOW – CI jobs lack timeout-minutes; long‑running steps could block the schedule.

Additional static findings: two import cycles (field/__init__.py, filter.py), several oversized files (>800 LOC) and deep nesting (indentation depth 6) increase maintenance risk.

The Bottom Line

tvscreener delivers a functional, well‑documented Python wrapper for TradingView screener data and a convenient MCP server for AI‑driven queries. The core API is usable out‑of‑the‑box, but the codebase shows classic technical‑debt signals—import cycles, large modules and missing lockfiles—that should be addressed before relying on it for production‑critical pipelines. Engineers comfortable with Python and pandas will find it a practical shortcut, provided they budget time for the identified refactoring and security hardening.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

112 files

Python42
Markdown25
JSON13
Jupyter Notebook7
YAML4
JavaScript3

Expresspandas

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["tvscreener<br/>26 modules"] g1["tests<br/>14 modules"] g2["app<br/>3 modules"] g1 -->|21| g0 g2 -->|8| g0

Module dependencies

The 10 most depended-upon modules of 44, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_tvscreener_field___init__["__init__"] n1_tvscreener___init__["__init__"] n2_tvscreener_util["util"] n3_tvscreener_core_base["base"] n4_tvscreener_filter["filter"] n5_tvscreener_field_crypto["crypto"] n6_tvscreener_field_forex["forex"] n7_tvscreener_field_stock["stock"] n8_tvscreener_field_bond["bond"] n9_tvscreener_field_coin["coin"] n1_tvscreener___init__ --> n3_tvscreener_core_base n1_tvscreener___init__ --> n0_tvscreener_field___init__ n1_tvscreener___init__ --> n7_tvscreener_field_stock n1_tvscreener___init__ --> n6_tvscreener_field_forex n1_tvscreener___init__ --> n5_tvscreener_field_crypto n1_tvscreener___init__ --> n8_tvscreener_field_bond n1_tvscreener___init__ --> n9_tvscreener_field_coin n1_tvscreener___init__ --> n4_tvscreener_filter n1_tvscreener___init__ --> n2_tvscreener_util n3_tvscreener_core_base --> n0_tvscreener_field___init__ n3_tvscreener_core_base --> n5_tvscreener_field_crypto n3_tvscreener_core_base --> n6_tvscreener_field_forex n3_tvscreener_core_base --> n7_tvscreener_field_stock n3_tvscreener_core_base --> n4_tvscreener_filter n3_tvscreener_core_base --> n2_tvscreener_util n0_tvscreener_field___init__ --> n4_tvscreener_filter n8_tvscreener_field_bond --> n0_tvscreener_field___init__ n9_tvscreener_field_coin --> n0_tvscreener_field___init__ classDef cyc stroke:#ef4444,stroke-width:2px; class n0_tvscreener_field___init__,n4_tvscreener_filter cyc;

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium3

low1

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

codecov/codecov-action@v4, pypa/gh-action-pypi-publish@release/v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/codecov.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/codecov.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.