Add lifetime of package cache

docs/source/faq.rst

@@ -35,7 +35,11 @@ If you have any trouble with the cache, you can remove the cache directory to re
 How can I update an OptunaHub package already cached?
 -----------------------------------------------------
 
-Calling ``optunahub.load_module()`` with ``force_reload=True`` ensures the selected package is re-download from the package registry.
+You can set the environment variable ``OPTUNAHUB_CACHE_EXPIRATION_SECONDS`` to define the cache expiration time in seconds.
+The default value is 2,592,000 seconds (30 days).
+When the cache expires, the package will be re-downloaded from the package registry.
+
+If you want to force update the package every time you call it, you can use ``optunahub.load_module()`` with ``force_reload=True``.
 
 
 I got the "403: rate limit exceeded" error when loading a package. How can I fix it?

optunahub/_conf.py

@@ -39,3 +39,17 @@ def is_no_analytics() -> bool:
     """
 
     return os.getenv("OPTUNAHUB_NO_ANALYTICS", "0") == "1"
+
+
+def cache_expiration_seconds() -> int:
+    """Return the cache expiration time in seconds.
+
+    Returns:
+        The cache expiration time in seconds.
+    """
+    try:
+        # Default to 30 days
+        cache_expiration_seconds = int(os.getenv("OPTUNAHUB_CACHE_EXPIRATION_SECONDS", "2592000"))
+        return cache_expiration_seconds
+    except ValueError:
+        return 30 * 24 * 60 * 60

optunahub/hub.py

@@ -4,10 +4,12 @@
 import importlib.util
 import json
 import os
+from pathlib import Path
 import re
 import shutil
 import sys
 import tempfile
+import time
 import types
 from urllib.parse import urlparse
 from urllib.request import Request
@@ -132,7 +134,13 @@ def load_module(
         raise ValueError(f"Invalid base URI: {base_url}")
     cache_dir_prefix = os.path.join(_conf.cache_home(), hostname, repo_owner, repo_name, ref)
     package_cache_dir = os.path.join(cache_dir_prefix, dir_path)
-    use_cache = not force_reload and os.path.exists(package_cache_dir)
+    print(f"package_cache_dir: {package_cache_dir}")
+    use_cache = (
+        not force_reload
+        and os.path.exists(package_cache_dir)
+        and _is_cache_valid(package_cache_dir)
+    )
+    print(f"use_cache: {use_cache}")
 
     if not use_cache:
         if auth is None and shutil.which("git") is not None:
@@ -285,3 +293,16 @@ def load_local_module(
     spec.loader.exec_module(module)
 
     return module
+
+
+def _is_cache_valid(package_cache_dir: str) -> bool:
+    if not os.path.exists(package_cache_dir):
+        return False
+    package_cache_path = Path(package_cache_dir)
+    if not package_cache_path.exists():
+        return False
+    paths = [package_cache_path] + list(package_cache_path.rglob("*"))
+    # Get the most recent modification time among all files and directories in the package cache
+    last_modified_time = max(p.stat().st_mtime for p in paths)
+    diff_seconds = time.time() - last_modified_time
+    return diff_seconds < _conf.cache_expiration_seconds()

tests/test_hub.py

@@ -2,13 +2,16 @@
 
 import os
 import shutil
+import time
 
 import optuna
 import pytest
 from pytest import MonkeyPatch
 
 import optunahub
+from optunahub import _conf
 from optunahub.hub import _extract_hostname
+from optunahub.hub import _is_cache_valid
 
 
 @pytest.mark.parametrize(
@@ -83,3 +86,31 @@ def mock_do_nothing(*args, **kwargs) -> None:  # type: ignore[no-untyped-def]
     monkeypatch.setattr("optunahub.hub._report_stats", lambda *args, **kwargs: calls.append(None))
     optunahub.load_module(package="dummy/test")
     assert len(calls) > 0
+
+
+@pytest.mark.parametrize(
+    "package_name, cache_expiration_seconds, expected_result",
+    [
+        ("samplers/simulated_annealing", "1", False),
+        ("samplers/simulated_annealing", "1000000", True),
+        ("samplers/simulated_annealing", None, True),
+    ],
+)
+def test_if_cache_is_valid(
+    monkeypatch: MonkeyPatch,
+    package_name: str,
+    cache_expiration_seconds: str | None,
+    expected_result: bool,
+) -> None:
+    if cache_expiration_seconds is not None:
+        monkeypatch.setenv("OPTUNAHUB_CACHE_EXPIRATION_SECONDS", cache_expiration_seconds)
+    else:
+        monkeypatch.delenv("OPTUNAHUB_CACHE_EXPIRATION_SECONDS", raising=False)
+
+    cache_dir_prefix = os.path.join(
+        _conf.cache_home(), "github.com", "optuna", "optunahub-registry", "main"
+    )
+    package_cache_dir = os.path.join(cache_dir_prefix, "package", package_name)
+
+    time.sleep(2)
+    assert _is_cache_valid(package_cache_dir) == expected_result