JerBouma/FinanceToolkit v2.3.1

FinanceToolkit v2.3.1

on GitHub

Some minor new functionalities that resolve edge cases and potential security flaws. Also introduced point-in-time mode as suggested by #298.

Package

New

• Point-in-time mode (Toolkit(..., point_in_time=True), #301, closes #298).
  • Statements, ratios and models use each period's figures only from the day they were filed (FMP's accepted and filing dates, otherwise the reporting deadline).
  • end_date works as an "as of" date.
  • The statistics statement now holds the Filing Date and Fiscal Year.
• Country equity risk premium in the Cost of Equity (#307).
  • CAPM, WACC, EVA, residual income and PVGO use the Damodaran premium of each company's country instead of the benchmark's historical excess return.
  • An explicit market_risk_premium still wins.
  • AAPL's 2024 WACC goes from 0.1947 to 0.0823.
• Portfolio performance on the MCP server. The new tool portfolio_performance takes a portfolio as transactions, holdings, weights or a preset. It returns the overview, performance, positions, transactions and the money-weighted return.

Improved

• Toolkit core (#300, #305):
  • Quarterly data looks back far enough for the trailing year and its growth in the first periods.
  • Supplied statements are never downloaded again and detect their own date order.
  • Statement periods after end_date are left out.
  • Exchange rates older than a month aren't used.
  • Inputs are validated (tickers, benchmark, lag, dates).
• Data layer (#304):
  • The price cache refetches when a dividend or split rescales the adjusted history.
  • Prices with a failed dividend or adjusted-close request aren't cached.
  • API keys are removed from logged errors.
  • Discovery queries are URL-encoded ("AT&T", "Aerospace & Defense").
  • Certificate errors fail at once instead of retrying for minutes.
  • On the Free plan, dividends before the latest five come from Yahoo Finance.
• Portfolio (#311):
  • Transactions in several currencies are converted to one reporting currency at each day's rate; pence and pounds are unified.
  • Purchases come before sales within a day.
  • Decimal commas are read per column.
  • The stored data is not rounded.
• Utilities and cache (#311):
  • Growth is NaN around a gap.
  • standardize covers the shown window.
  • Cache entries are evicted daily, and the coverage of a cached range never extends past today.
• Heavy calculations are bounded (#306): option, bond, Monte Carlo and binomial models cap their sizes.
• Edge-case fixes:
  • Brinson, Black-Litterman, cointegration, YTM, DCC-GARCH, Omega and the MWR (#306).
  • SAR, OBV, the McClellan Oscillator, Supertrend, support/resistance and the volume indicators per ticker over gaps (#309).
  • ETFs compared on common dates (#299).
  • Hurst lags (#297).
  • Brinson looks through funds (#296).
• Speed (#310): the rolling CVaR, CDaR and Omega, the grouped Ulcer Index and period resampling are vectorised.
• Clearer messages (#308): a missing key outside the statements says which data is missing, and inflation expectations name the countries they cover.
• Fixes in this PR:
  • Discovery:
    • The screener sends the upper market cap bound.
    • UK home listings are recognised (SHEL.L instead of the NYSE ADR).
  • Performance: the whole-period Omega, Gain-to-Pain and Rachev ratios are no longer empty.
  • Company data:
    • Annual ESG scores take the year's latest disclosure.
    • Missing revenue segments are NaN, and names keep FMP's spelling ("iPhone").
    • A changed actual_dates applies to a cached earnings calendar.
    • Statements and analyst estimates are stored unrounded, so the rounding of a first call no longer sticks.
    • The statistics statement follows start_date and end_date.
  • Docstrings: the WLS and GLS examples use the estimated weights and the AR(1) Omega.
• Docs and packaging (#302): docstring defaults match the code, and the package metadata has project links.

Breaking

• The reverse_dates and smooth_widow parameters are removed (#305, #302).
• ROC, PPO, TRIX and the KST are decimals instead of percentages (#309).
• Economics country names follow the Global Macro Database: Macedonia, Macau, Cape Verde, Sao Tome and Principe. The official names are accepted too (#309).
• The rolling Omega is inf for a window with gains and no losses, like get_omega_ratio (#306, #310).

MCP server

• Tools:
  • New tool portfolio_performance. Its inputs are validated before anything is fetched (one way to describe the portfolio, at most 1,000 transactions and 50 tickers), and transactions never reach the server as a file path.
  • 25 router tools.
• OAuth hardening (#303):
  • Single-use authorization codes that expire after 5 minutes.
  • Validated redirect URIs.
  • PKCE S256 is required.
  • Field length caps.
  • An invalid token gets a 401.
• Request handling (#303):
  • Tools run in a bounded thread pool with a lock per cached Toolkit.
  • A call waiting for a busy Toolkit gives up its slot.
  • Default dates are computed per call.
  • Ticker, search and series counts are capped.
  • Credentials are redacted from the access log.
  • The secret file is created private.
• Inputs (#295): fractional, JSON and estimated inputs are accepted.

Other

• Tests:
  • The flaky CI tests are fixed. 16 portfolio and point-in-time tests built Toolkits from supplied prices but without Treasury data, so valuing them retrieved Treasury yields from Yahoo Finance in parallel threads, which locked yfinance's SQLite cache ("database is locked"). Every such Toolkit now gets the supplied Treasury yields; with yfinance blocked, no test reaches it any more. Another test re-read the shared Portfolio's dataset and sent later tests online; it now uses its own Portfolio, and each test process gets its own yfinance cache.
  • 20 technical indicator tests that only recorded NaN now run on 60 sample bars and assert values.
  • New offline tests for the company data parsers.
• Weekly source checks: a source that returns nothing is reported with what it logged, and a refusal over a request limit is skipped. The BLS allows 25 keyless requests a day per IP address, which GitHub's runners share (#315).
• Dependencies:
  • tabulate moves from the mcp extra to the dev group.
  • Dependabot: tornado 6.6, joserfc 1.7.6, authlib 1.9.1, dnspython 2.9.0 (#312–#314, #316).
• Dead code: the dead "pip install yfinance" branches are removed (yfinance is a required dependency).