Files
dlee-bq 53d4dcc46d [Feature] Drop Python 3.10 and Resolve Open Dependabot Alerts (#7804)
* 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>
2026-11-01 18:16:45 +00:00
..
…

BLS Provider Extension for the OpenBB Platform

openbb-bls integrates the U.S. Bureau of Labor Statistics into the OpenBB Platform. It combines three data paths:

  • BLS Public Data API v2 — point-in-time time series by series ID (the only endpoint that can use an API key).
  • Published release files — News Release tables, supplemental XLSX files, and the news-release chart packages, parsed directly from bls.gov.
  • A bundled series catalog — a local, partitioned cache of ~1.1M BLS series (14 survey families) so the catalog search works offline with no API calls.

A bundled OpenBB Workspace dashboard (apps.json) ships five apps: a BLS home app plus dedicated Employment Situation, CPI, PPI, and Productivity apps.

Installation

From PyPI:

pip install openbb-bls

For local development from a clone of the OpenBB monorepo, run from this folder:

pip install -e .

Authentication

No key is required. Every News-Release table, supplemental table, and chart endpoint is parsed from published files and works with no credentials.

An (optional) BLS registration key only affects the series endpoint, where it raises the per-request limits — 50 symbols / 20-year window / 500 requests per day (registered) vs. 25 / 10 years / 25 per day (unregistered). Get one at https://data.bls.gov/registrationEngine/ and set it as bls_api_key:

from openbb import obb

obb.user.credentials.bls_api_key = "YOUR_KEY"

Coverage

Python commands are obb.bls.<group>.<command>(...); the equivalent REST route is GET /api/v1/bls/<group>/<command>. Every group also exposes a documents command listing the release PDFs/files for that program.

Consumer Price Index — bls.cpi

Command Description
t1_expenditure_category … t7_12m_analysis News Release tables 1–7 (expenditure category, detailed, special aggregates, selected areas, chained vs. CPI-U, 1-month and 12-month analyses)
relative_importance Relative-importance / weights (U.S. city average and selected local areas)
seasonal_factors Revised seasonally-adjusted indexes and seasonal factors
supplemental_tables C-CPI-U, CPI-W, historical CPI-U, and other supplemental XLSX tables
average_prices, by_category, by_category_line, by_metro, by_region News-release chart package

Employment Situation — bls.employment_situation

Command Description
summary_household, summary_establishment Summary Tables A (CPS) and B (CES)
t1_employment_changes … t7_peak_trough, confidence_intervals CES analytical tables
civilian_unemployment_rate, civilian_unemployment, civilian_employment, employment_population_ratio, labor_force_participation_rate, labor_underutilization, duration_of_unemployment, reasons_for_unemployment, unemployment_by_education, unemployment_by_veteran_status, long_term_unemployed_share, not_in_labor_force_indicators, not_in_labor_force_want_a_job Household-survey (CPS) chart package
employment_levels_by_industry, average_weekly_hours_production, employment_change_by_industry_ci, employment_by_industry_monthly_changes, employment_and_hourly_earnings_by_industry, employment_and_weekly_earnings_by_industry Establishment-survey (CES) chart package

Producer Price Index — bls.ppi

Command Description
detailed_report Monthly Detailed Report tables (XLSX)
relative_importance, seasonal_factors Relative importance and seasonal factors
final_demand_1m / _12m, final_demand_components_1m / _12m, intermediate_processed_1m / _12m, intermediate_services_1m / _12m, intermediate_unprocessed_1m / _12m Final- and intermediate-demand chart package

JOLTS — bls.jolts

Command Description
change_analysis, revisions Over-the-month change analysis and SA/NSA revisions
beveridge_curve, unemp_per_opening, openings_by_industry, hires_seps_rates, openings_hires_seps_levels, openings_hires_seps_rates, openings_hires_seps_by_region Job openings, hires, and separations chart package

Productivity & Costs — bls.productivity

Command Description
tables Long-form major-sector / total-economy productivity datasets
by_sector, nonfarm_business_productivity / _indexes / _labor_costs, manufacturing_productivity / _indexes / _labor_costs, nonfinancial_corporations_indexes Major-sector productivity & costs charts
tfp_output_and_inputs, tfp_combined_inputs_output, tfp_contributions, tfp_percent_change, tfp_ict_trends, tfp_fire_trends Total Factor Productivity
wr_productivity_change / _by_period, wr_1yr_change, wr_longterm_change, wr_indexes_by_sector, wr_labor_cost_by_sector, wr_lp_by_industry Wholesale & Retail Trade productivity
mm_productivity_change / _by_period, mm_1yr_change, mm_longterm_change, mm_indexes_by_industry, mm_labor_cost_by_industry Mining & Manufacturing productivity

Import / Export Price Indexes — bls.import_export

Command Description
price_indexes U.S. import and export price indexes
imports_by_category, exports_by_category, imports_by_origin, exports_by_grains, air_passenger_fares Import/export chart package

Real Earnings — bls.real_earnings

Command Description
documents Real Earnings news-release archive

Search, Series & Calendar

These cross-survey commands fetch live or cached data by series ID:

Command Description
search Search the bundled ~1.1M-series catalog by category, keyword, or code (offline, no API call)
series Fetch one or more time series by symbol from the BLS Public Data API (optional bls_api_key)
calendar BLS data-release schedule

When openbb-economy is installed these register under the Economy survey namespace (e.g. obb.economy.survey.bls_search(...), and the release calendar as obb.economy.calendar(provider="bls")); otherwise they are available standalone as obb.bls.search(...), obb.bls.series(...), and obb.bls.calendar(...).

Usage

from openbb import obb

# Latest CPI-U expenditure-category table (no key required)
obb.bls.cpi.t1_expenditure_category(provider="bls").to_df()

# A specific time series from the BLS Public Data API
obb.bls.series(symbol="CUUR0000SA0", provider="bls").to_df()

# Find series in the local catalog, then chart one
obb.bls.search(category="cpi", query="urban", provider="bls").to_df()

Documentation for the OpenBB Platform is available at https://docs.openbb.co/platform.