financetoolkit 2.3.2__tar.gz → 2.3.3__tar.gz

{financetoolkit-2.3.2 → financetoolkit-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: financetoolkit
-Version: 2.3.2
+Version: 2.3.3
 Summary: Transparent and Efficient Financial Analysis
 Project-URL: Homepage, https://www.jeroenbouma.com/projects/financetoolkit
 Project-URL: Documentation, https://www.jeroenbouma.com/projects/financetoolkit/docs
@@ -26,7 +26,7 @@ Requires-Dist: openpyxl>=3.1
 Requires-Dist: pandas>=3.0
 Requires-Dist: python-calamine>=0.3.0; python_full_version < '3.15'
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: requests>=2.32
+Requires-Dist: requests>=2.32.4
 Requires-Dist: scipy>=1.10
 Requires-Dist: xlrd>=2.0
 Requires-Dist: yfinance
@@ -34,6 +34,7 @@ Provides-Extra: econometrics
 Requires-Dist: linearmodels>=6.0; extra == 'econometrics'
 Requires-Dist: statsmodels>=0.14; extra == 'econometrics'
 Provides-Extra: mcp
+Requires-Dist: cryptography>=42; extra == 'mcp'
 Requires-Dist: fastmcp>=3.4.2; extra == 'mcp'
 Requires-Dist: linearmodels>=6.0; extra == 'mcp'
 Requires-Dist: mcp[cli]<2,>=1.27.0; extra == 'mcp'
@@ -362,7 +363,7 @@ Options usually price more risk than follows, as their sellers want to be paid f
 
 All three are listed in the United States and valued on earnings that lie years ahead, which makes US inflation and interest rates the backdrop to their share prices. In 2022, the year the maximum drawdown above shows each of them falling by more than half, inflation reached 9% and the Federal Reserve raised its policy rate from 0.12% to 4.38%.
 
-The [economics](https://www.jeroenbouma.com/projects/financetoolkit/docs/economics) module covers 60+ countries with 50+ indicators, from GDP and unemployment to money supply and interest rates, and the [fixed income](https://www.jeroenbouma.com/projects/financetoolkit/docs/fixedincome) module adds bond yields, yield curves, central bank rates and bond and derivative valuations. Both are reached through the same Toolkit instance, or on their own with `from financetoolkit import Economics, FixedIncome`:
+The [economics](https://www.jeroenbouma.com/projects/financetoolkit/docs/economics) module covers 60+ countries with 50+ indicators, from GDP and unemployment to money supply and interest rates, and the [fixed income](https://www.jeroenbouma.com/projects/financetoolkit/docs/fixedincome) module adds bond yields, yield curves, central bank rates and calculations on individual bonds. Both are reached through the same Toolkit instance, or on their own with `from financetoolkit import Economics, FixedIncome`:
 
 ```python
 # Inflation on the same month a year earlier and the Federal Reserve's policy rate
@@ -492,7 +493,7 @@ The three US funds and SMH largely hold the same companies, with SOXX and SMH sh
 
 ## Building a Diversified Portfolio
 
-A fund spreads the risk over the sector, but the sector still moves as one. The [portfolio](https://www.jeroenbouma.com/projects/financetoolkit/docs/portfolio-optimization) module builds portfolios from the tickers of any Toolkit: minimum variance, maximum Sharpe ratio, mean-variance, risk parity, Hierarchical Risk Parity, minimum CVaR and Black-Litterman weights, the efficient frontier, risk contributions, stress tests and attribution. Below the semiconductor fund is combined with health care (XLV), energy (XLE), long-term Treasuries (TLT) and gold (GLD):
+A fund spreads the risk over the sector, but the sector still moves as one. The [portfolio](https://www.jeroenbouma.com/projects/financetoolkit/docs/portfolio-optimization) module builds portfolios from the tickers of any Toolkit: minimum variance, maximum Sharpe ratio, mean-variance, risk parity, Hierarchical Risk Parity, Hierarchical Equal Risk Contribution, Nested Clustered Optimization, minimum CVaR, minimum drawdown, maximum Omega and CVaR ratio, Black-Litterman, maximum diversification, minimum tracking error and growth optimal (Kelly) weights, the efficient frontier, risk contributions, stress tests and attribution. Below the semiconductor fund is combined with health care (XLV), energy (XLE), long-term Treasuries (TLT) and gold (GLD):
 
 ```python
 # Initialize the Toolkit for funds across sectors and asset classes from 2021 to 2025
@@ -744,6 +745,8 @@ Alternatively, if your company's root certificate is already installed in your o
 
 If none of this is possible, you can accept the risk and allow requests with an API key to be sent without verification by setting `FINANCETOOLKIT_ALLOW_UNVERIFIED_SSL=1` in the same way as above. Only do so on a network you trust: the connection is then encrypted to whoever answers it, which may not be the website you think you are talking to, and your API key is readable to them.
 
+To go the other way and never send a request without verification, not even one without an API key, set `FINANCETOOLKIT_ALLOW_UNVERIFIED_SSL=0`. A hosted MCP server (the `sse` or `streamable-http` transport) does this by default, since the data it retrieves reaches every user through its cache.
+
 > **Are you part of FinancialModelingPrep?**
 
 *No, I am not*. I've merely picked them as the primary data provider given that they have a generous free tier and fair pricing compared to other providers. Therefore, any questions related to the data should go through [their contact form](https://site.financialmodelingprep.com/contact). When it comes to any type of ratios, performance metrics, risk metrics, technical indicators or economic indicators, feel free to reach out to me as this is my own work.

{financetoolkit-2.3.2 → financetoolkit-2.3.3}/README.md

@@ -318,7 +318,7 @@ Options usually price more risk than follows, as their sellers want to be paid f
 
 All three are listed in the United States and valued on earnings that lie years ahead, which makes US inflation and interest rates the backdrop to their share prices. In 2022, the year the maximum drawdown above shows each of them falling by more than half, inflation reached 9% and the Federal Reserve raised its policy rate from 0.12% to 4.38%.
 
-The [economics](https://www.jeroenbouma.com/projects/financetoolkit/docs/economics) module covers 60+ countries with 50+ indicators, from GDP and unemployment to money supply and interest rates, and the [fixed income](https://www.jeroenbouma.com/projects/financetoolkit/docs/fixedincome) module adds bond yields, yield curves, central bank rates and bond and derivative valuations. Both are reached through the same Toolkit instance, or on their own with `from financetoolkit import Economics, FixedIncome`:
+The [economics](https://www.jeroenbouma.com/projects/financetoolkit/docs/economics) module covers 60+ countries with 50+ indicators, from GDP and unemployment to money supply and interest rates, and the [fixed income](https://www.jeroenbouma.com/projects/financetoolkit/docs/fixedincome) module adds bond yields, yield curves, central bank rates and calculations on individual bonds. Both are reached through the same Toolkit instance, or on their own with `from financetoolkit import Economics, FixedIncome`:
 
 ```python
 # Inflation on the same month a year earlier and the Federal Reserve's policy rate
@@ -448,7 +448,7 @@ The three US funds and SMH largely hold the same companies, with SOXX and SMH sh
 
 ## Building a Diversified Portfolio
 
-A fund spreads the risk over the sector, but the sector still moves as one. The [portfolio](https://www.jeroenbouma.com/projects/financetoolkit/docs/portfolio-optimization) module builds portfolios from the tickers of any Toolkit: minimum variance, maximum Sharpe ratio, mean-variance, risk parity, Hierarchical Risk Parity, minimum CVaR and Black-Litterman weights, the efficient frontier, risk contributions, stress tests and attribution. Below the semiconductor fund is combined with health care (XLV), energy (XLE), long-term Treasuries (TLT) and gold (GLD):
+A fund spreads the risk over the sector, but the sector still moves as one. The [portfolio](https://www.jeroenbouma.com/projects/financetoolkit/docs/portfolio-optimization) module builds portfolios from the tickers of any Toolkit: minimum variance, maximum Sharpe ratio, mean-variance, risk parity, Hierarchical Risk Parity, Hierarchical Equal Risk Contribution, Nested Clustered Optimization, minimum CVaR, minimum drawdown, maximum Omega and CVaR ratio, Black-Litterman, maximum diversification, minimum tracking error and growth optimal (Kelly) weights, the efficient frontier, risk contributions, stress tests and attribution. Below the semiconductor fund is combined with health care (XLV), energy (XLE), long-term Treasuries (TLT) and gold (GLD):
 
 ```python
 # Initialize the Toolkit for funds across sectors and asset classes from 2021 to 2025
@@ -700,6 +700,8 @@ Alternatively, if your company's root certificate is already installed in your o
 
 If none of this is possible, you can accept the risk and allow requests with an API key to be sent without verification by setting `FINANCETOOLKIT_ALLOW_UNVERIFIED_SSL=1` in the same way as above. Only do so on a network you trust: the connection is then encrypted to whoever answers it, which may not be the website you think you are talking to, and your API key is readable to them.
 
+To go the other way and never send a request without verification, not even one without an API key, set `FINANCETOOLKIT_ALLOW_UNVERIFIED_SSL=0`. A hosted MCP server (the `sse` or `streamable-http` transport) does this by default, since the data it retrieves reaches every user through its cache.
+
 > **Are you part of FinancialModelingPrep?**
 
 *No, I am not*. I've merely picked them as the primary data provider given that they have a generous free tier and fair pricing compared to other providers. Therefore, any questions related to the data should go through [their contact form](https://site.financialmodelingprep.com/contact). When it comes to any type of ratios, performance metrics, risk metrics, technical indicators or economic indicators, feel free to reach out to me as this is my own work.

{financetoolkit-2.3.2 → financetoolkit-2.3.3}/financetoolkit/cache/cache_controller.py

@@ -2,9 +2,11 @@
 
 __docformat__ = "google"
 
+import contextlib
 import os
 import platform
 import time
+import zlib
 from dataclasses import dataclass, field
 from datetime import date, datetime, timedelta
 from pathlib import Path
@@ -280,7 +282,7 @@ class Cache:
         if enabled:
             try:
                 self._backend = SQLiteBackend(self._location)
-            except Exception as error:  # pylint: disable=broad-except
+            except Exception as error:
                 # A cache is an optimization, so a database that cannot be opened just disables it.
                 self._enabled = False
 
@@ -317,7 +319,7 @@ class Cache:
                 EVICTION_INTERVAL_SECONDS,
                 excluded_sources=frozenset({policy_model.MCP}),
             )
-        except Exception as error:  # pylint: disable=broad-except
+        except Exception as error:
             # Eviction is housekeeping, so a failure here is not surfaced.
             logger.debug("Could not evict stale cache entries: %s", error)
             return
@@ -478,7 +480,7 @@ class Cache:
                 ever_covered, fresh_covered, payload = self._backend.read_entity_state(
                     key, entity, minimum_fetched_at
                 )
-            except Exception as error:  # pylint: disable=broad-except
+            except Exception as error:
                 # A read that fails mid-session is a cache miss, not a failed call.
                 logger.debug(
                     "Could not read cached %s.%s for %s: %s",
@@ -512,8 +514,8 @@ class Cache:
                     plan.cached[entity] = frame_model.slice_frame(
                         stored, start, end, date_axis
                     )
-                except Exception as error:  # pylint: disable=broad-except
-                    # An unreadable payload is a miss: ask the source for the lot.
+                except Exception as error:
+                    # An unreadable payload (one in another format, such as a pickle, is never read) is a miss: ask the source for the lot.  # noqa: E501
                     logger.debug(
                         "Could not decode cached %s.%s for %s: %s",
                         source,
@@ -523,6 +525,10 @@ class Cache:
                     )
                     plan.missing[entity] = [request]
 
+                    # Removed with its coverage, so the rows fetched now are not recorded as merged with ranges that are no longer held.  # noqa: E501
+                    with contextlib.suppress(Exception):
+                        self._backend.delete_entity(key, entity)
+
         return plan
 
     def store(
@@ -599,11 +605,12 @@ class Cache:
             Returns:
                 bytes: The payload to store in its place.
             """
-            existing = (
-                serialization_model.decode_dataframe(existing_payload)
-                if existing_payload is not None
-                else None
-            )
+            existing = None
+
+            # A payload that can't be read (another format, such as a pickle) is replaced.
+            if existing_payload is not None:
+                with contextlib.suppress(ValueError, zlib.error):
+                    existing = serialization_model.decode_dataframe(existing_payload)
 
             return serialization_model.encode_dataframe(
                 frame_model.merge_frames(existing, data, date_axis)
@@ -620,7 +627,7 @@ class Cache:
                 dataset=dataset,
                 compaction_threshold=COVERAGE_COMPACTION_THRESHOLD,
             )
-        except Exception as error:  # pylint: disable=broad-except
+        except Exception as error:
             # A cache write must never break the call that produced the data.
             logger.debug(
                 "Could not cache %s.%s for %s: %s", source, dataset, entity, error
@@ -676,7 +683,7 @@ class Cache:
                 return None
 
             return serialization_model.decode_object(payload)
-        except Exception as error:  # pylint: disable=broad-except
+        except Exception as error:
             # Any read failure is reported as a miss, so the caller falls back to the source.
             logger.debug(
                 "Could not read cached %s.%s for %s: %s", source, dataset, entity, error
@@ -699,7 +706,8 @@ class Cache:
             source (str): The external data source.
             dataset (str): The dataset within that source.
             entity (str): The entity the data belongs to.
-            data (Any): The value to store. Any picklable object is accepted.
+            data (Any): The value to store: a DataFrame, Series or Index, a scalar, or a
+                list, tuple or dictionary of these (see serialization_model.encode_object).
             parameters (dict[str, Any] | None): Parameters that change the data.
         """
         if not self.serves(source):
@@ -715,7 +723,7 @@ class Cache:
                 source=source,
                 dataset=dataset,
             )
-        except Exception as error:  # pylint: disable=broad-except
+        except Exception as error:
             logger.debug(
                 "Could not cache %s.%s for %s: %s", source, dataset, entity, error
             )
@@ -796,7 +804,7 @@ class Cache:
 
         try:
             return self._backend.get_contents()
-        except Exception as error:  # pylint: disable=broad-except
+        except Exception as error:
             logger.warning("Could not read the cache contents: %s", error)
 
             return []
@@ -824,7 +832,7 @@ class Cache:
             return self._backend.remove_expired_entries(
                 ttl, source=source, dataset=dataset
             )
-        except Exception as error:  # pylint: disable=broad-except
+        except Exception as error:
             # Eviction is housekeeping on a timer, so a failure here is not surfaced.
             logger.debug("Could not evict expired cache entries: %s", error)
 

{financetoolkit-2.3.2 → financetoolkit-2.3.3}/financetoolkit/cache/policy_model.py

@@ -28,6 +28,9 @@ STATISTICS_BUREAU_OF_JAPAN = "StatisticsBureauOfJapan"
 US_TREASURY = "USTreasury"
 BUREAU_OF_LABOR_STATISTICS = "BLS"
 FREDDIE_MAC = "FreddieMac"
+DEPARTMENT_OF_LABOR = "DepartmentOfLabor"
+CENSUS_BUREAU = "CensusBureau"
+BUREAU_OF_ECONOMIC_ANALYSIS = "BEA"
 FEDERAL_RESERVE_BOARD = "FederalReserveBoard"
 NATIONAL_BUREAU_OF_ECONOMIC_RESEARCH = "NBER"
 IBGE = "IBGE"
@@ -257,7 +260,17 @@ POLICIES: dict[str, CachePolicy] = {
     # Auctions are added several times a week; a past year's results are final.
     f"{US_TREASURY}.auctions": CachePolicy(ttl_seconds=DAY),
     f"{US_TREASURY}.auctions_year": CachePolicy(ttl_seconds=30 * DAY),
+    # The FedInvest prices of a day are completed with the end-of-day price the next
+    # business day; a day that has them is final.
+    f"{US_TREASURY}.fedinvest_prices": CachePolicy(ttl_seconds=3600),
+    f"{US_TREASURY}.fedinvest_prices_final": CachePolicy(ttl_seconds=365 * DAY),
     f"{FREDDIE_MAC}.series": CachePolicy(ttl_seconds=DAY),
+    f"{DEPARTMENT_OF_LABOR}.series": CachePolicy(ttl_seconds=DAY),
+    f"{CENSUS_BUREAU}.series": CachePolicy(ttl_seconds=DAY),
+    f"{BUREAU_OF_ECONOMIC_ANALYSIS}.series": CachePolicy(ttl_seconds=DAY),
+    # The HQM curve is published monthly in files of five years; a past file is final.
+    f"{US_TREASURY}.hqm": CachePolicy(ttl_seconds=DAY),
+    f"{US_TREASURY}.hqm_years": CachePolicy(ttl_seconds=30 * DAY),
     f"{IBGE}.series": CachePolicy(ttl_seconds=DAY),
     # Daily bond yields; a rerun only asks for the last month, since yields are not revised
     # but a holiday or late publication can leave the latest days open.