The Problem

Applications that consume market data typically stitch together multiple vendors or scrape endpoints by hand. Finnhub offers a single API covering equities, forex, crypto, fundamentals, and news, but raw HTTP calls leave you managing auth, pagination, and error handling yourself. This client wraps the entire Finnhub REST API in one Python object so a developer can pull quotes, financials, and economic data without writing request plumbing.

What This Does

finnhub-python is a generated API client for the Finnhub financial data platform. The core is finnhub/client.py, a single Client class exposing 128 methods, one per Finnhub endpoint. finnhub/exceptions.py defines FinnhubAPIException and FinnhubRequestException for error propagation.

The package is installable via pip (see setup.py and requirements.txt) and ships with examples.py, a runnable script demonstrating nearly every endpoint. CI runs through Travis (.travis.yml) and GitLab (.gitlab-ci.yml).

How It Is Wired

Execution starts in finnhub/__init__.py, which re-exports the Client class. The constructor in finnhub/client.py calls _init_session to set up a requests.Session with your API key. Every public method—quote, company_profile2, covid19, etc.—delegates to _get, which is called from 116 distinct places. _get routes through _request, which formats parameters via _format_params, performs the HTTP call, and hands the response to _handle_response. That method raises FinnhubAPIException for API-level errors and FinnhubRequestException for transport failures.

The call graph shows 236 internal edges total. The widest blast radius is _get: change its signature and 116 call sites break. _merge_two_dicts is the only other shared helper, used 5 times for optional parameter merging.

File-by-file map:

  • finnhub/client.py — all endpoint methods, session lifecycle (close, __enter__, __exit__)
  • finnhub/exceptions.py — two exception classes; imported by the client
  • finnhub/__init__.py — package export
  • examples.py — standalone usage script, imports the client
  • setup.py — package metadata and install entry point

How To Use It

Setup — install from PyPI:

pip install finnhub-python

Configuration — no config file. The API key is passed directly to the constructor:

import finnhub
client = finnhub.Client(api_key="YOUR API KEY")

Running it — no CLI. Use the client in Python, or run examples.py as a demonstration:

python examples.py

Real-World Use

A portfolio dashboard that needs daily closing prices and company news without maintaining a custom API layer:

import finnhub
client = finnhub.Client(api_key="key")

candles = client.stock_candles('AAPL', 'D', 1590988249, 1591852249)
news = client.company_news('AAPL', _from="2024-01-01", to="2024-01-31")

Code Health & Issues

Static analysis (not manual review) found 2 high-severity findings, both cognitive_load — deep nesting in finnhub/client.py and examples.py, with max indentation depth of 8. The fix is guard clauses and extracting inner blocks. One medium finding: no Dependabot or Renovate configured, so dependency advisories go unpatched until a manual audit. No lockfile exists, so builds are not reproducible. Tests are present, CI is configured, and no secrets are committed. The finnhub/client.py file is a 128-method monolith; expect high merge friction when modifying shared helpers.

The Bottom Line

A functional, complete wrapper for the Finnhub API with broad endpoint coverage and a simple design. It is a fork of the official client with no added value visible from the file structure. Suitable for production use if you accept the missing lockfile and the maintenance burden of a generated-style monolith; otherwise the upstream package is equivalent.