finvizp

Finviz for Python — an unofficial, async-first, Arrow-native Finviz client built on fastreq, direct lxml, and PyArrow.

Install

uv add finvizp  # or: pip install finvizp

Quick start

Async-first:

import asyncio
import finvizp


async def main() -> None:
    async with finvizp.FinvizClient() as client:
        universe = await finvizp.symbols_async(client=client)
        bundle = await finvizp.quote_async("AAPL", client=client)
        print(bundle.data.snapshot.num_rows)


asyncio.run(main())

Every operation has a sync twin (same name, no _async suffix) for scripts and notebooks:

import finvizp

matches = finvizp.search_symbols("APPLE")
income = finvizp.statements("AAPL", statement="IA")  # IA/IQ/BA/BQ/CA/CQ
snap = finvizp.snapshot("AAPL")  # cached, no 2nd request
quote = finvizp.quote("AAPL")  # complete bundle
universe = finvizp.symbols()
finvizp.capabilities()  # implemented/planned ledger

Sync twins reject an active event loop; results, caching, and errors are identical.

What's implemented

The full implemented/planned ledger lives in the capability matrix and finvizp.capabilities().

Design in one screen

• Async-first with sync twins — one transport, no hidden event loops.
• Arrow-native — every dataset is a versioned, deterministic Arrow table.
• Immutable FetchResult[T] — full provenance, typed partial/error diagnostics, no in-place mutation.
• Complete compound bundles — e.g. a quote page yields every relation in one fetch; cache-preserving projections (snapshot, ratings, news, insider, peers, etf_holders) never re-request.
• Structured-first sources — public JSON/XHR or embedded payloads when same-tier, complete, direct, and snapshot-coherent; lxml parsing otherwise.
• Explicit proxies, route-isolated auth, conservative pacing/retries, bounded result caching, single-flight coalescing. A per-client 429 circuit breaker trips after 3 consecutive rate limits and fails fast (CircuitOpenError, no request sent) until the cooldown passes.
• No login/browser automation, bulk crawling, pandas contract, persistence layer, telemetry, or entitlement bypass.

Documentation

User docs (Diataxis — tutorials, how-to, reference, explanation), rendered with Zensical from docs/user/:

Deep links: screener · screener registry · groups/maps/events · markets/artifacts · schema versioning · keep your own history · access & responsible use

Build the site locally:

uv run zensical build --clean

Background research (surface inventory, finvizfinance audit, Yahoo overlap, snapshot-history semantics) lives under docs/research/ and docs/brainstorming/; the foundation design tracks the approved architecture. Publication mechanics: docs/publishing.md.

Development

uv sync --all-groups
uv run pytest
uv run ruff format --check . && uv run ruff check .
uv run ty check src
uv build

Access policy

Finviz public pages, Elite features, and export/API endpoints carry different entitlements. finvizp does not automate login, solve challenges, bypass access controls, or rotate proxies to evade limits. Callers are responsible for valid access and data-use rights. See access & responsible use.