JerBouma/FinanceToolkit v2.3.4

FinanceToolkit v2.3.4

on GitHub

A release on macro data and on judging how unusual a move is. Producer prices by country come from current official sources, with new export and import price indices; the economic calendar reads as a time series; any series can be ranked against its own history, as a level, a spread or a streak; a stock's market-adjusted move gets its size in money and its rank; a basket's market value compares with a country's GDP. Real interest rates, core CPI and commodity prices since 1960 come by month, a basket of stocks gets its own summed statements, and every MCP answer names the publishers its data comes from. Cached data gives the same answers as fresh data, and the MCP server logs every request again.

Package

All modules

• Every get_, collect_ and search_ method takes show_columns=, a name or a list of names, e.g. economics.get_shiller_stock_market_data(show_columns=["Price", "CAPE"]). A column level left with a single name is dropped, so the Close of several tickers has the tickers as columns; get_historical_data with one ticker and one column returns a DataFrame (#431).

Economics

• get_producer_price_index comes from the official publishers without an API key: Eurostat for the euro area, the EU and around 35 European countries, the BLS for the United States (FRED with a key for the full history) and the Bank of Japan's corporate goods price index. The OECD dataset it used stopped in 2022. China has no reachable index and is left out with a note; its monthly year-on-year change is in the economic calendar (#405).
• get_export_price_index and get_import_price_index from the same publishers (#405).
• get_economic_calendar(as_series=True) returns each event's actual value (and the consensus estimate) by the period it covers, read from the event text, one column per event (#404).
• Removed: the model function oecd_model.get_producer_price_index (#405).
• get_chokepoint_transits: IMF PortWatch's daily ship transits through 28 maritime chokepoints from 2019 (the Strait of Hormuz, Suez, Bab el-Mandeb, Panama, Malacca and more), by ship category, as counts or estimated trade volume in metric tons, summed by week, month, quarter or year (#432).
• get_commodity_prices: the World Bank Pink Sheet, monthly from 1960 (energy, metals including gold, agriculture, fertilizers), with deflate_with= for prices in today's money (#413).
• get_consumer_price_index(measure=...) and get_inflation_rate(measure=...): core, energy, food, goods, services and shelter (BLS for the United States, Eurostat HICP aggregates for Europe). The US CPI includes the months the BLS released since the BIS last republished it (#415).
• get_real_interest_rate is monthly by default (period="yearly" for the annual calculation) and takes rate_type="policy", which covers the euro area (#414).
• The policy rates add the days since the BIS's weekly update from the Bank of England and the ECB, and get_european_central_bank_rates takes period= (#414).
• get_government_interest_expenditure (with ratios to GDP and to revenue) and get_government_expenditure_by_function (COFOG, with a ratio to GDP), from the IMF (#407).
• get_purchasing_power, with overnight_rate=True for the real value of cash; get_consumer_price_index(cumulative=True) and get_overnight_rate(cumulative=True) (#408).
• Monthly, quarterly and yearly data shows a period a source skipped as an empty row, so a change never compares the wrong periods; annual changes compare the same period a year earlier (#413, #417).
• The economic calendar series keep a release that covers two months (China's January and February trade) once, under the later month, and leave out releases without a period (#417).
• Removed: fred_model.get_real_yield_curve and fred_model.get_breakeven_inflation_expectations; the US real yields and breakevens come from the Treasury (#414).

Econometrics

• get_level_significance: the latest value of any series (a rate, a macro series or a close) with its percentile over the history and the last date it was as high or as low (#402).
• get_streaks: the current run of positive or negative values of a series, its start and length, the run before it and the longest earlier run of the same sign (#404).
• spread_over= ranks or counts one series minus another, such as producer minus consumer prices (#404).
• get_level_significance adds the change since the start, the highest and lowest of the range, the first date above a level=, the annualised change, the largest drawdown with its recovery date, and the rank of the latest value (#409, #410, #413, #416, #417).
• get_window_change_by_year: the change over the same months every year, ranked (#415).
• get_streaks(level=...) counts runs above or below a level, and ratio=True divides by the spread_over series instead of subtracting it (#416).
• With changes="difference", the changes of get_level_significance and get_window_change_by_year are in points, such as the change of a yield over a month (#419).
• zone=True on the Altman, Zmijewski, Springate and Taffler scores adds the Distress / Grey / Safe zone of each score (#420).
• get_optimization_backtest shows the return and Sharpe ratio each strategy expected in sample next to what it realised (#420).
• get_issuer_spreads compares issuers' spreads at the same maturities (2Y, 5Y, 10Y, ...) by interpolating along each issuer's bonds (#420).
• get_yield_decomposition splits the nominal yield of the United States, United Kingdom and Germany into the real yield and breakeven inflation, with the daily change of each part (#422).
• Econometrics.get_move_significance measures how unusual each change of any series is, e.g. the largest one-day rise of a yield since a date (#422).
• get_initial_jobless_claims without a FRED key retries when the Department of Labor's report cannot reach its database, which happens for up to half of the requests, and otherwise serves the cached claims instead of failing (#434).
• The yearly consumer price index and inflation rate warn about years the Global Macro Database repeats from the year before (inflation 0 by construction, e.g. Germany 1913-1914) and about hyperinflations, after which the yearly average still rises sharply (Germany 1924: +723%) (#435).
• The per-ticker earnings and dividend calendars keep the scheduled dates after today (the next earnings release); price targets FMP lists under another analyst company than the article names are credited to the named company, and get_price_target_history adds each company's Previous Target, Previous Date and Target Change (#437).
• The US inflation rate and CPI are the CPI-U for every date range; a range ending before 2025 returned Eurostat's experimental HICP-concept US figures (#422).
• Returns of currency pairs, cryptocurrencies and low-priced shares from FinancialModelingPrep use an unrounded adjusted close; FMP's is rounded to two decimals (#423).
• get_millennium_of_macroeconomic_data(deflate_with=...) puts the long-run series in real terms, e.g. the oil price since 1861 in today's dollars (#424).
• get_weighted_average_cost_of_capital accepts single numbers as well as series (#425, @pengpengyi92).
• The Merton model leaves a non-positive or non-finite horizon empty instead of solving it (#426, @pengpengyi92).
• The daily present value of growth opportunities keeps figures dated on non-trading days (#427, @pengpengyi92).
• The estimated EPS growth rate is empty for invalid single inputs, such as a zero trailing EPS (#428, @pengpengyi92).
• As-of lookups of the credit models sort histories that are not in date order (#429, @pengpengyi92).

Performance

• get_beta_implied_return adds the Residual Value (the residual times the market cap at the previous close), the Residual Percentile and the Residual Largest Since date, so one row judges the latest stock-specific move against its history (#401).

Bonds and rates

• get_taylor_price_change(from_date=...) gives each Treasury's own yield change between two dates, the duration and convexity estimate and the realised price change from the FedInvest prices (#402).
• get_treasury_rates takes maturities= (#402).
• get_loan_payment, get_affordable_loan and get_amortization_schedule at the 30-year mortgage rate, or any rate (#409).

Data

• Futures tickers (BZ=F, CL=F, NG=F and others) return quotes and intraday data, and TTF=F its daily history again (#410).
• Cached financial statements keep every period that overlaps the requested range, the same as a fresh request. Before, a warm cache could drop the year before the start date that the statements are fetched with, so factor analyses and other measures that need that year could differ between a first and a later call (#398).

Discovery

• With primary_only=True, the earnings calendar chooses primary listings from the releases of a week either side of the range. A company that reported just before the range, while its listings abroad dated the same release inside it, no longer shows with a listing abroad as its primary one (#398).

Data sources

• Every data source is checked weekly, FinancialModelingPrep (every endpoint, through the public methods) and FRED included, and a failing source opens an issue (#434).

Documentation

• Docstrings across the package: Args match the signatures and their defaults, mentions that no API key is needed are gone, and errors are fixed (#433).
• The example tables of the valuation models, factor analysis and tail dependence are regenerated from the current calculations (#398).
• The performance and risk docstrings describe their definitions directly (#397).

Ratios

• Toolkit(tickers, basket=True) adds a company named Total whose statements are the summed statements of the tickers, so its ratios and models weight each company by its size (#412).
• get_market_cap(share=True) gives each ticker's share of the total market value, and get_market_cap_to_gdp(country=...) divides the total by a country's GDP in US dollars, on each date the previous complete year's (#406, #412).
• get_net_capital_expenditure: capital expenditure beyond depreciation and amortization (#412).
• The asset coverage ratio deducts goodwill as well as the other intangible assets (#400). Every tangible measure (asset coverage, return on tangible assets, tangible asset value, price to tangible book) takes the combined goodwill and intangible assets row, or the separate rows where it is missing, with a missing part counting as zero (#403).

Code

• Log records without a credential keep their arguments, and a credential inside an argument is replaced in that argument, so formatters that read the arguments themselves keep working (#396).
• soupsieve, used by beautifulsoup4, is locked at 4.1 (2.10 below Python 3.11.5) (#439).
• opentelemetry-api, used by fastmcp, is locked at 1.45.2 (#440).
• tornado is locked at 6.6.1 and dnspython at 2.9.2 (#443).

MCP server

• A series= reference passes period= on to the indicators it reads, and reads a calendar event as a series (#402, #404).

• Every answer lists the publishers its data comes from under _sources, also when it is answered from the cache or from data loaded by an earlier call (#418).

• An indicator without a period parameter is converted to the requested period, with a note (#416).

• Daily prices name the days a ticker did not trade (an exchange holiday), which carry its last close (#419).

• Instances unused for 30 minutes are dropped and their memory is released, so a long-running server no longer keeps the memory of its busiest moment (#419).

• rank=true on every tool ranks the tickers or countries within each period, with each one's gap to its neighbour (#421).

• FT_MCP_COMPACT_TOOLS=1 lists the tools without their long descriptions, and search_metrics with an indicator's name returns its description and parameters (#422).

• The Altman, Zmijewski, Springate and Taffler scores include their zone by default (#420).

• The access log writes a line for every request again instead of a logging error, with request paths still free of credentials (#396).