53d4dcc46d
* Drop Python 3.10 support
Python 3.10 reached end of life on 2026-10-01, and the patched releases of
Pillow (13.0.0) and filelock (>=4.2.1) require Python >=3.11, so the 3.10
resolution fork kept vulnerable versions in every lockfile.
- requires-python = ">=3.11,<4" in all pyproject.toml files, the
cookiecutter template, and the CLI codegen project template
- CI: drop the ubuntu 3.10 matrix rows, move the macOS/Windows minimum
rows and the lint jobs to 3.11, drop 3.10 from the nox sessions
- READMEs: state 3.11 as the minimum supported version
* Relock with patched certifi, filelock, virtualenv, Pillow, and fastmcp
Regenerate all 38 uv.lock files against requires-python >=3.11 and upgrade
only the packages with open Dependabot advisories:
- certifi 2026.7.22 -> 2026.10.23 (GHSA-6q48-6c7w-9gw2, compromised emSign CAs)
- virtualenv 21.14.7 -> 21.14.13
- filelock 4.1.0/4.2.0 -> 4.2.4
- Pillow 12.3.0 -> 13.0.0
- fastmcp / fastmcp-slim 4.1.0 -> 4.1.3
All other changes are removed Python 3.10-only resolution forks; no other
package changes version for Python 3.11+.
* desktop: bump zod, @hookform/resolvers, and vitest
- zod ^3.25.76 -> ^4.6.7 (GHSA-mrhx-c7xc-m3w5; no patched 3.x exists)
- @hookform/resolvers ^3.10.0 -> ^5.9.2 for zod 4 support
- vitest ^4.1.11 -> ^4.1.12 (@vitest/mocker GHSA-qxg6-89mg-rqv8,
GHSA-xp26-3454-mjgp)
- override zod to the root version so @openbb/ui-pro, which declares
zod ^3 but never imports it, does not pull in a second, vulnerable copy
* desktop: remove Python 3.10 from environment pickers
- version pickers in InstallComponents and AddExtensionSelector start at 3.11
- create_environment_from_requirements accepts 3.11 through 3.14 and falls
back to 3.12 otherwise (previously 3.10 through 3.13)
- component tests select 3.11 instead of 3.10
* Remove Python 3.10 tomli fallbacks
With requires-python >=3.11, tomllib is always available, so the
version-conditional tomli imports are dead code.
- import tomllib directly in the cli and core config loaders, the
mcp_server and platform_api config validators, dev_install.py, and
the cli and cookiecutter tests; dev_install.py no longer pip-installs
tomli on the fly
- drop the tomli>=2.0; python_version<'3.11' dependency from cli, core,
mcp_server, and platform_api, plus platform_api's backport comment
- raise the fake-extension fixtures in cli/conftest.py,
core/integration/conftest.py, and the charting test metadata to
>=3.11
- relock cli, core, mcp_server, and platform_api; only the tomli
requires-dist entry is removed and resolution markers are reordered,
no package versions change
* Target Python 3.11 in ruff and ty for cli, core, mcp_server, platform_api, cookiecutter
With ruff target-version py310 and ty python-version 3.10, both tools
reject an unconditional `import tomllib`: ty reports it as unresolved
(exit 1) and ruff's isort classifies it as third-party. Raise the targets
in the projects that now import tomllib directly, and in the root
ruff.toml that governs dev_install.py.
- ruff target-version = "py311" and ty python-version = "3.11" in cli,
core, mcp_server, platform_api, and cookiecutter; root ruff.toml
target-version = "py311"
- UP042: OutputMode, ChartLifecycle, MCPType, and HTTPMethod become
StrEnum; every consumer uses .value or == comparisons, so only str()
and format() output change
- UP017: datetime.timezone.utc -> datetime.UTC (ruff autofix) in the cli
dispatchers, the cli test generator, and a core test
* Fix ruff and ty failures in packages this PR touches
CI installs unpinned dependencies, so the lint jobs ran against
pandas 3.1.0, ruff 0.17.2, and ty 0.0.91.
- cli/conftest.py: guard the find_spec("openbb") lookup so ty no longer
reports an Optional ModuleSpec/origin (failing Lint openbb-cli)
- quantitative: pandas 3.1 types Index.max() as object; cast max_date to
Timestamp before period_start in attribution, factors, and
risk_decomposition (failing ty)
- federal_reserve: use Series(...).dt.date instead of
DatetimeIndex.date so neither pandas 3.0 nor 3.1 needs a ty: ignore
(pandas 3.1 made the existing ignores unused, failing ty)
- core tests: type the filter_by_dates doubles as Data subclasses and
cast the deliberate bad arguments in test_helpers.py; apply ruff format
to test_docstring_generator_helpers.py
- platform_api README: apply ruff format to the Python code blocks
* Fix pandas 3.1 deprecations failing fred, sec, and eia tests
These suites turn warnings into errors, and pandas 3.1.0 adds
Pandas4Warning deprecations for several patterns they use. Every change
also passes with the locked pandas 3.0.6.
- fred, sec: replace inplace=True sort_values/reset_index/rename/
set_index/drop with reassignment
- fred balance_of_payments, sec as_filed_widget: replace fillna with a
string on float columns by astype(object).where(notna, ...)
- sec: build quarter start dates from ISO strings instead of parsing
"2024Q2"-style strings; use the DataFrame constructor instead of
DataFrame.from_records for column dicts; pad CIK lookup rows to two
fields instead of constructing a ragged DataFrame
- eia: read EIA workbooks with the calamine engine (xlrd is deprecated);
replace the xlrd dependency with python-calamine and relock; calamine
workbooks are not safe for concurrent reads, so the petroleum status
report serializes its sheet reads with a lock
* imf: fall back to the published catalog when the IMF API is unreachable
imf_cache.json.xz is generated at build time and is not committed, so
every CI build of openbb-imf needed a live api.imf.org. The only fallback
was actions/cache, and caches saved by pull_request runs are scoped to
that PR, so a new PR never had one. With api.imf.org returning
"503 no healthy upstream" during IMF's data portal maintenance window,
the build failed.
When live generation fails on a non-forced build, the hook now copies
imf_cache.json.xz from the latest openbb-imf wheel on PyPI, after
checking the wheel's sha256 against the digest PyPI publishes. Builds
with OPENBB_IMF_FORCE_CACHE_REBUILD=1, which the publish workflow sets,
still fail hard, so a release never ships a stale catalog.
---------
Co-authored-by: dlee-bq <325002271+dlee-bq@users.noreply.github.com>
OpenBB IMF Provider Extension
This package adds the openbb-imf provider extension to the Open Data Platform by OpenBB.
It provides everything you need - endpoints, tools, and metadata - to access and explore the entirety of https://data.imf.org, without any previous experience working with it.
Installation
Install from PyPI with:
pip install openbb-imf
Then build the Python static assets by running:
openbb-build
The package also ships a precomputed IMF SDMX metadata catalog at
openbb_imf/assets/imf_cache.json.xz. Released wheels and sdists
carry it verbatim — it is materialized from api.imf.org/external/sdmx/3.0
by a Hatchling build hook (hatch_build.py) at packaging time. If the
IMF API is unreachable, the hook copies the catalog from the latest
openbb-imf wheel on PyPI instead, unless OPENBB_IMF_FORCE_CACHE_REBUILD=1
is set, in which case the build fails. End users have nothing to do;
developers can refresh it with either:
generate-imf-cache # standalone script
OPENBB_IMF_FORCE_CACHE_REBUILD=1 pip install -e . # via the build hook
Quick Start
The fastest way to get started is by connecting to the OpenBB Workspace as a custom backend.
Start Server
openbb-api
This starts the FastAPI server over localhost on port 6900.
Add to Workspace
See the documentation here for more details.
Click to Open App
Once added, click on the app to open the dashboard.
The dashboard contains widgets with metadata and information, as well ones for exploring and retrieving the data.
Implementation Details
IMF is a SDMX API, and they organize their data by "dataflows". You can think of these as databases. Each one has their own definitions for parameters and output. Some definitions are shared, others are domain-specific. In SDMX, query models are expressed as dimensions, and data models as attributes.
The extension comes with a base level of metadata used for normalizing, translating, and validating inputs and outputs. When mapping requires a code list that is not included, a network request is made to retrieve it.
User input is validated by calling the constraints API for each dimension. The cached metadata contains all the potential values for parameters, but the availability of each is determined by other choices - country, frequency, etc. When making the actual request for data, parameters are tested for compatibility in the sequence defined by the data structure definition. Invalid parameter combinations are returned as helpful error messages with descriptions of what went wrong and what the valid choices are.
The output converts ID codes into human-readable labels, and includes dataset and series metadata in a separate object.
Indicators
In this library, we refer to indicators as "indicator-like" dimensions within individual dataflows.
It includes dimensions like COICOP_1999, so items such as CPI All Items, or Clothing and footwear,
are considered.
The IMF codes for these values - _T, CP01, etc. - are used to construct ticker-like symbols.
Presentation Tables
Presentation tables are built from hierarchical code lists defining the parent-child relationship between individual series.
Internally, table IDs are prefixed with H_ - i.e, H_BOP_BOP_AGG_STANDARD_PRESENTATION.
The symbology allows entering references to tables, or indicators.
Symbology
The Open Data Platform generally refers to all time series IDs as a symbol.
Requesting time series data or presentation tables requires a symbol constructed from
the dataflow ID and the indicator-like dimensions, split with ::.
CPI::CPI returns all series for CPI under the TYPE_OF_INDEX dimension.
CPI::CPI_CP01 returns just component of CPI, Food and non-alcoholic beverages.
The symbol mapper matches the items after :: intelligently to its corresponding dimension.
Entering, CPI::CP01, gets the same result as, CPI::CPI_CP01.
CPI::CPI__T returns just the top-level, All Items.
CPI::H_CPI_BY_COMPONENT returns the entire presentation table, Consumer Price Index (CPI) by Component.
Use, obb.imf.list_tables(), for a list of tables and their symbol.
Use, obb.economy.available_indicators(provider='imf', ...), to search for, or list all, individual time series and symbols within specific dataflows.
(If openbb-economy is not installed, the same endpoints are aliased onto obb.imf.available_indicators / obb.imf.indicators.)
This example lists all the indicators in the CPI and PI dataflows.
from openbb import obb
indicators = obb.economy.available_indicators(provider="imf", dataflows="CPI,PI")
print(indicators.to_dict("records"))
...
{'symbol_root': 'CP01',
'symbol': 'CPI::CP01',
'description': 'Food and non-alcoholic beverages',
'agency_id': 'IMF.STA',
'dataflow_id': 'CPI',
'dataflow_name': 'Consumer Price Index (CPI)',
'structure_id': 'DSD_CPI',
'dimension_id': 'COICOP_1999',
'long_description': 'Food and non-alcholoic beverages consumer price index is produced using prices related to food items and non-alcoholic beverages such as fresh produce, packaged foods, and beverages excluding alcoholic drinks, aggregated by their respective consumer expenditure weights.',
'member_of': ['CPI::H_CPI_BY_COMPONENT'],
'extra_dimensions': ['TYPE_OF_TRANSFORMATION']}
...
Coverage
All data available from https://data.imf.org/en/Data-Explorer can be retrieved, via obb.economy.indicators(provider='imf', **kwargs). When openbb-economy is not installed, the same fetcher is aliased onto obb.imf.indicators.
Additionally, the extension exposes IMF Port Watch endpoints under obb.imf.portwatch.* — these cover country activity, monthly TradeNow indices, container metrics, and disruption events / sankey / map data sourced from the UN Global Platform / IMF Port Watch (not part of the SDMX Data Explorer).
The extension creates a router path, imf, that exposes presentation tables, the dataflow-aware indicator catalog, choice helpers for UI widgets, and the Port Watch subrouter.
Endpoints
Data endpoints exposed via the standard openbb-economy routes when that extension is
installed (provider imf):
obb.economy.available_indicators(providerimf)obb.economy.indicators(providerimf)obb.economy.balance_of_payments(providerimf)obb.economy.cpi(providerimf)obb.economy.direction_of_trade(providerimf)obb.economy.shipping.chokepoint_info(providerimf)obb.economy.shipping.chokepoint_volume(providerimf)obb.economy.shipping.port_info(providerimf)obb.economy.shipping.port_volume(providerimf)
When openbb-economy is absent the same fetchers register under IMF-prefixed model
names and the IMF router exposes equivalent paths: obb.imf.available_indicators,
obb.imf.indicators, obb.imf.balance_of_payments, obb.imf.cpi,
obb.imf.direction_of_trade, obb.imf.port_info, obb.imf.port_volume,
obb.imf.chokepoint_info, obb.imf.chokepoint_volume.
IMF-native endpoints (always under obb.imf.*):
obb.imf.list_dataflowsobb.imf.list_dataflow_choicesobb.imf.get_dataflow_dimensionsobb.imf.list_tablesobb.imf.list_table_choicesobb.imf.presentation_tableobb.imf.presentation_table_choicesobb.imf.indicator_choicesobb.imf.list_bop_country_choicesobb.imf.list_cpi_country_choices
IMF Port Watch endpoints (obb.imf.portwatch.* — UN Global Platform / IMF Port Watch
data not part of the SDMX Data Explorer):
obb.imf.portwatch.country_activityobb.imf.portwatch.monthly_tradeobb.imf.portwatch.container_metricsobb.imf.portwatch.disruption_eventsobb.imf.portwatch.disruption_sankeyobb.imf.portwatch.disruptions_mapobb.imf.portwatch.list_port_id_choicesobb.imf.portwatch.list_container_port_choicesobb.imf.portwatch.list_country_choicesobb.imf.portwatch.list_disruption_event_choicesobb.imf.portwatch.list_tradenow_region_choices
"Choices" endpoints are utilized by OpenBB Workspace to populate widget dropdown menus.