financetoolkit 2.3.1__tar.gz → 2.3.3__tar.gz

{financetoolkit-2.3.1 → financetoolkit-2.3.3}/.gitignore

@@ -1,197 +1,194 @@
-# Finance Toolkit Ignored Files
-*.csv
-*.xlsx
-*.xls
-*.ipynb
-cached/
-debugging.py
-.planning/
-
-# Finance Toolkit Example Datasets
-!financetoolkit/portfolio/example_datasets/*.xlsx
-!financetoolkit/portfolio/example_datasets/*.csv
-
-# Finance Toolkit Normalization Files
-!financetoolkit/normalization/*.csv
-
-# Finance Toolkit Tests
-!tests/datasets/*.xlsx
-!tests/*/csv/*/*.csv
-!tests/csv/*/*.csv
-
-# VS Code
-.agents
-.vscode/
-.claude/
-*.sh
-
-# Claude
-CLAUDE.md
-
-# Specific files for the MCP Bundle
-!financetoolkit/mcp_server/mcpb/build-mcpb.sh
-
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-.DS_Store
-.ipynb_checkpoints/
-.DS_Store
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/#use-with-ide
-.pdm.toml
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+# Finance Toolkit Ignored Files
+*.csv
+*.xlsx
+*.xls
+*.ipynb
+cached/
+debugging.py
+.planning/
+
+# Finance Toolkit Example Datasets
+!financetoolkit/portfolio/example_datasets/*.xlsx
+!financetoolkit/portfolio/example_datasets/*.csv
+
+# Finance Toolkit Normalization Files
+!financetoolkit/normalization/*.csv
+
+# Finance Toolkit Tests
+!tests/datasets/*.xlsx
+!tests/*/csv/*/*.csv
+!tests/csv/*/*.csv
+
+# VS Code
+.agents
+.vscode/
+.claude/
+*.sh
+
+# Claude
+CLAUDE.md
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+.DS_Store
+.ipynb_checkpoints/
+.DS_Store
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
 articles/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: financetoolkit
-Version: 2.3.1
+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.1 → 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.1 → 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(
@@ -581,6 +587,10 @@ class Cache:
                 coverage_start = min(coverage_start, bounds[0])
                 coverage_end = max(coverage_end, bounds[1])
 
+            # A bar of a session that has not closed is a snapshot: the day stays uncovered, so the next call asks for it again.  # noqa: E501
+            if policy_model.get_policy(source, dataset).settles_at_close:
+                coverage_end = min(coverage_end, policy_model.get_last_closed_session())
+
             if coverage_start <= coverage_end:
                 coverage = (coverage_start, coverage_end)
 
@@ -595,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)
@@ -616,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
@@ -672,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
@@ -695,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):
@@ -711,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
             )
@@ -792,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 []
@@ -820,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)