Files
Wei-Lun Li fac2bd450f fix(famafrench): select the 'Not Reqd' tables when all_data_items_required=False (#7823)
get_international_portfolio filtered the frames and their metadata with
different conditions when all_data_items_required is False. The frames
kept the tables without "Not Reqd" in the description, which are the
"Required" tables, and the metadata kept descriptions ending with
"Not Reqd", which the ex-dividend files never do because their
descriptions end with " - Ex-Dividends".

So with dividends=True the call returned the "All 4 Data Items
Required" returns under the "Not Reqd" description, and with
dividends=False the metadata list was empty and transform_data raised
IndexError. The documented example
obb.famafrench.country_portfolio_returns(frequency="annual",
measure="local", country="japan", dividends=False,
all_data_items_required=False) fails with
"[Unexpected Error] -> IndexError -> list index out of range".

Filter both lists on "Not Reqd" in the description.

Co-authored-by: dlee-bq <dlee@brightquery.com>
Co-authored-by: Danglewood <85772166+deeleeramone@users.noreply.github.com>
2026-11-15 19:40:37 +00:00
..
…
…

OpenBB Platform

The OpenBB Platform is a set of Python packages that turn financial and economic data sources into one typed Python client (from openbb import obb), a FastAPI REST API, and an MCP server.

openbb-core is the runtime. It ships no data and no commands; it discovers the extensions installed in the environment through entry points and assembles them. Everything else in this folder is an extension:

  • Routers add command namespaces such as obb.equity or obb.economy.
  • Providers implement those commands against a data source, and may add their own namespace such as obb.fred.
  • OBBject extensions add accessors to every result, such as result.charting.

Documentation lives at docs.openbb.co.

Repository layout

Path Contents
core/ openbb-core: the runtime, the generated openbb package, and the REST API app.
extensions/ Routers, plus the API launcher, the MCP server, and developer tooling.
providers/ Data provider extensions.
obbject_extensions/ Result accessors (openbb-charting).
dev_install.py Editable install of every package for local development.
../cli/ openbb-cli, the command-line interface.

Packages

Core and tooling

Package Path Description
openbb-core core Runtime, extension loader, static package builder (openbb-build), and REST API app.
openbb-platform-api extensions/platform_api openbb-api launcher for the REST API and the OpenBB Workspace custom-backend connector.
openbb-mcp-server extensions/mcp_server openbb-mcp: serves the installed commands as Model Context Protocol tools.
openbb-devtools extensions/devtools Linters, type checker, and test dependencies for development.
openbb-cli ../cli openbb: interactive command-line interface.

Routers

Package Namespace
openbb-commodity obb.commodity
openbb-crypto obb.crypto
openbb-currency obb.currency
openbb-derivatives obb.derivatives
openbb-econometrics obb.econometrics
openbb-economy obb.economy
openbb-equity obb.equity
openbb-etf obb.etf
openbb-fixedincome obb.fixedincome
openbb-index obb.index
openbb-news obb.news
openbb-quantitative obb.quantitative
openbb-technical obb.technical

Providers

Package Path Source Credential
openbb-bls providers/bls U.S. Bureau of Labor Statistics bls_api_key
openbb-cboe providers/cboe Cboe None
openbb-cftc providers/cftc CFTC and DTCC Public Price Dissemination cftc_app_token
openbb-deribit providers/deribit Deribit None
openbb-ecb providers/ecb European Central Bank None
openbb-famafrench providers/famafrench Ken French Data Library None
openbb-federal-reserve providers/federal_reserve Federal Reserve System, FOMC, and the twelve regional districts None
openbb-finra providers/finra FINRA None
openbb-fred providers/fred FRED fred_api_key
openbb-government-us providers/government_us U.S. Congress, U.S. Treasury, and USDA congress_gov_api_key
openbb-imf providers/imf International Monetary Fund None
openbb-jodi providers/jodi Joint Organisations Data Initiative None
openbb-nasdaq providers/nasdaq Nasdaq None
openbb-oecd providers/oecd OECD None
openbb-sec providers/sec SEC EDGAR None
openbb-tmx providers/tmx TMX (Canadian markets) None
openbb-us-eia providers/eia U.S. Energy Information Administration eia_api_key

OBBject extensions

Package Accessor
openbb-charting result.charting: Plotly charts, with native window rendering through the pywry extra.

Installation

Install openbb-core together with the routers and providers you need; openbb-core is pulled in by each of them.

pip install openbb-equity openbb-cboe

The openbb Python package is generated from whatever is installed. It rebuilds on import when the installed extensions change, and openbb-build rebuilds it explicitly after installing or removing an extension.

openbb-build

Python

from openbb import obb

output = obb.equity.price.historical("AAPL", provider="cboe")
df = output.to_dataframe()

Credentials

Providers that need a key read it as <provider>_<credential>, as listed in the provider table.

Set keys in ~/.openbb_platform/user_settings.json:

{
  "credentials": {
    "fred_api_key": "REPLACE_ME",
    "bls_api_key": "REPLACE_ME"
  }
}

Or as environment variables, which take precedence over the file. ~/.openbb_platform/.env is loaded automatically.

export FRED_API_KEY=REPLACE_ME

Or for the current session only:

from openbb import obb

obb.user.credentials.fred_api_key = "REPLACE_ME"

REST API

openbb-platform-api serves every installed command over FastAPI, with OpenAPI docs at /docs and a widgets.json for OpenBB Workspace.

pip install openbb-platform-api
openbb-api

The bare FastAPI app is openbb_core.api.rest_api:app and runs under any ASGI server.

uvicorn openbb_core.api.rest_api:app --host 127.0.0.1 --port 8000

MCP server

pip install openbb-mcp-server
openbb-mcp

See extensions/mcp_server/README.md for transports, tool discovery, and configuration.

Local development

Requirements:

  • Git
  • Python 3.11 or newer
  • uv

From an activated virtual environment at the repository root:

python openbb_platform/dev_install.py --routers

This installs every tracked package under core, extensions, obbject_extensions, providers, and ../cli in editable mode, with all optional extras and each package's dev dependency group, then runs openbb-build. A new extension is picked up once its pyproject.toml is committed in one of those folders.

Router extensions (openbb-equity, openbb-economy, openbb-fixedincome, and the rest of the router table except openbb-news) are installed only with --routers. Without it, you get core, the tooling, openbb-news, the providers, openbb-charting, and the CLI.

Install the git hooks, which run the same ruff, ty, codespell, and markdownlint checks as CI:

pre-commit install

Each package is linted and tested from its own directory, matching its CI workflow:

cd openbb_platform/providers/fred
ruff format --check .
ruff check .
ty check openbb_fred
pytest tests

See CONTRIBUTING.md for extension guidelines.

License

Apache-2.0. See LICENSE.