financetoolkit 2.3.0__tar.gz → 2.3.2__tar.gz

{financetoolkit-2.3.0 → financetoolkit-2.3.2}/.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.0 → financetoolkit-2.3.2}/PKG-INFO

@@ -1,7 +1,11 @@
 Metadata-Version: 2.5
 Name: financetoolkit
-Version: 2.3.0
+Version: 2.3.2
 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
+Project-URL: Repository, https://github.com/JerBouma/FinanceToolkit
+Project-URL: Issues, https://github.com/JerBouma/FinanceToolkit/issues
 Author: Jeroen Bouma
 License: MIT
 License-File: LICENSE.txt
@@ -36,7 +40,6 @@ Requires-Dist: mcp[cli]<2,>=1.27.0; extra == 'mcp'
 Requires-Dist: python-dotenv>=1.0; extra == 'mcp'
 Requires-Dist: rich>=13.0; extra == 'mcp'
 Requires-Dist: statsmodels>=0.14; extra == 'mcp'
-Requires-Dist: tabulate>=0.9.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 <!-- mcp-name: io.github.JerBouma/financetoolkit -->

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

@@ -29,6 +29,13 @@ DATABASE_FILE_NAME = "financetoolkit_cache.db"
 # Compacted into merged intervals past this many rows, to bound table growth.
 COVERAGE_COMPACTION_THRESHOLD = 16
 
+# Point-in-time entries are kept at least this long after they were written, also past their
+# time-to-live, since an expired entry still answers when its source cannot be reached.
+STALE_ENTRY_RETENTION_SECONDS = 90 * policy_model.DAY
+
+# How often the entries nobody asks for any more are removed.
+EVICTION_INTERVAL_SECONDS = policy_model.DAY
+
 _CACHE_REGISTRY: dict[str, "Cache"] = {}
 _REGISTRY_LOCK = Lock()
 
@@ -103,7 +110,7 @@ def get_default_cache_location() -> Path:
     override = os.environ.get("FINANCE_TOOLKIT_CACHE_DB")
 
     if override:
-        return Path(override).expanduser()
+        return Path(override).expanduser().absolute()
 
     if platform.system() == "Windows":
         base = Path(
@@ -113,7 +120,7 @@ def get_default_cache_location() -> Path:
         xdg_config_home = os.environ.get("XDG_CONFIG_HOME")
         base = Path(xdg_config_home) if xdg_config_home else Path.home() / ".config"
 
-    return base / "financetoolkit" / DATABASE_FILE_NAME
+    return (base / "financetoolkit" / DATABASE_FILE_NAME).absolute()
 
 
 def resolve_cache_location(location: str | Path | None) -> Path:
@@ -133,7 +140,9 @@ def resolve_cache_location(location: str | Path | None) -> Path:
     if location is None:
         return get_default_cache_location()
 
-    path = Path(location).expanduser()
+    # Absolute, so a relative folder keeps pointing at the same database after a change of
+    # working directory and caches opened from different directories are told apart.
+    path = Path(location).expanduser().absolute()
 
     if path.suffix in (".db", ".sqlite", ".sqlite3"):
         return path
@@ -283,6 +292,38 @@ class Cache:
                 )
 
         self._warn_on_schema_mismatch()
+        self._remove_stale_entries()
+
+    def _remove_stale_entries(self) -> None:
+        """
+        Remove the point-in-time entries of every source that have not been refreshed for
+        longer than their time-to-live and the retention for unreachable sources, at most
+        once a day. The MCP server's responses are left to the server, which evicts them
+        on its own time-to-live.
+        """
+        try:
+            # A database of another schema version is left exactly as it is.
+            if (
+                self._backend is None
+                or self._backend.get_schema_version() != SCHEMA_VERSION
+            ):
+                return
+
+            evicted = self._backend.remove_stale_blobs(
+                lambda source, dataset: max(
+                    policy_model.get_policy(source, dataset).ttl_seconds,
+                    STALE_ENTRY_RETENTION_SECONDS,
+                ),
+                EVICTION_INTERVAL_SECONDS,
+                excluded_sources=frozenset({policy_model.MCP}),
+            )
+        except Exception as error:  # pylint: disable=broad-except
+            # Eviction is housekeeping, so a failure here is not surfaced.
+            logger.debug("Could not evict stale cache entries: %s", error)
+            return
+
+        if evicted:
+            logger.debug("Removed %s stale cache entries.", evicted)
 
     def _warn_on_schema_mismatch(self) -> None:
         """
@@ -388,9 +429,9 @@ class Cache:
             start (str | date | None): Inclusive start of the requested range.
             end (str | date | None): Inclusive end of the requested range.
             parameters (dict[str, Any] | None): Parameters that change the data.
-            date_axis (int): 0 when the index holds the dates, 1 when the columns do.
+            date_axis (int): 0 when the index holds the dates, 1 when the columns do. Defaults to 0.
             reference_date (date | None): The date the revision window is measured
-                back from when the requested range has no end. Defaults to today;
+                back from when the requested range has no end or ends after it. Defaults to today;
                 mainly useful for testing.
 
         Returns:
@@ -405,6 +446,10 @@ class Cache:
             coverage_model.normalize_date(start) if start else date(1900, 1, 1)
         )
         requested_end = coverage_model.normalize_date(end) if end else reference
+        # Nothing after today has been published yet, so a range that runs into the future is
+        # covered up to today and its revision window ends today, as an open range's does.
+        if requested_start <= reference < requested_end:
+            requested_end = reference
 
         if not self.serves(source):
             plan.missing = {
@@ -507,7 +552,7 @@ class Cache:
             start (str | date | None): Inclusive start of the range that was requested.
             end (str | date | None): Inclusive end of the range that was requested.
             parameters (dict[str, Any] | None): Parameters that change the data.
-            date_axis (int): 0 when the index holds the dates, 1 when the columns do.
+            date_axis (int): 0 when the index holds the dates, 1 when the columns do. Defaults to 0.
         """
         if not self.serves(source):
             return
@@ -520,8 +565,10 @@ class Cache:
             if start
             else (bounds[0] if bounds else None)
         )
+        # A request that runs into the future holds what was published up to today; claiming the
+        # future as well would never ask for those days once they have passed.
         coverage_end = (
-            coverage_model.normalize_date(end)
+            min(coverage_model.normalize_date(end), date.today())  # noqa: DTZ011
             if end
             else (bounds[1] if bounds else None)
         )
@@ -534,7 +581,12 @@ class Cache:
                 coverage_start = min(coverage_start, bounds[0])
                 coverage_end = max(coverage_end, bounds[1])
 
-            coverage = (coverage_start, coverage_end)
+            # 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)
 
         def merge_payload(existing_payload: bytes | None) -> bytes:
             """
@@ -813,7 +865,7 @@ def get_cache(
         location (str | Path | None): Directory or database file to use. None
             selects the shared default location.
         enabled (bool): When False a disabled cache is returned, which misses on
-            every read and ignores every write.
+            every read and ignores every write. Defaults to True.
         excluded_sources (frozenset[str] | set[str] | None): Sources this cache never
             reads or writes, see Cache. Defaults to None.
 
@@ -829,12 +881,14 @@ def get_cache(
     registry_key = f"{resolved}|{','.join(sorted(excluded))}"
 
     with _REGISTRY_LOCK:
-        if registry_key not in _CACHE_REGISTRY:
-            _CACHE_REGISTRY[registry_key] = Cache(
-                location=location, enabled=True, excluded_sources=excluded
-            )
+        cache = _CACHE_REGISTRY.get(registry_key)
+    if cache is not None:
+        return cache
 
-        return _CACHE_REGISTRY[registry_key]
+    # Opened outside the lock: opening evicts stale entries once a day, which can wait for another process's write lock, and that would hold up every other caller meanwhile. When two threads open the same location at once, the first instance registered is kept.  # noqa: E501
+    cache = Cache(location=location, enabled=True, excluded_sources=excluded)
+    with _REGISTRY_LOCK:
+        return _CACHE_REGISTRY.setdefault(registry_key, cache)
 
 
 def reset_cache_registry() -> None: