Merge pull request #223 from michealroberts/feature/iers/fetch_iers_rapid_service_data

feat: add cache strategy to fetch_iers_rapid_service_data in celerity module

Author: michealroberts

examples/iers.py

@@ -6,20 +6,23 @@
 
 # **************************************************************************************
 
-from celerity.iers import (
-    IERS_DUT1_URL,
-    fetch_iers_rapid_service_data,
-)
+from datetime import datetime, timezone
+
+from celerity.temporal import get_ut1_utc_offset
 
 # **************************************************************************************
 
 if __name__ == "__main__":
     try:
-        # Fetch the latest IERS Rapid Service data
-        data = fetch_iers_rapid_service_data(url=IERS_DUT1_URL)
-        print("IERS Rapid Service Data fetched successfully.")
-        print(data)
+        now = datetime.now(timezone.utc)
+        # Fetch the IERS Rapid Service data again to demonstrate caching:
+        dut1 = get_ut1_utc_offset(now)
+        print(f"UT1-UTC offset at {now.isoformat()}: {dut1} seconds")
+
+        # This should hit the cache:
+        dut1 = get_ut1_utc_offset(now)
+        print(f"UT1-UTC offset at {now.isoformat()}: {dut1} seconds")
     except Exception as e:
-        print(f"An error occurred while fetching IERS data: {e}")
+        print(f"An error occurred while getting UT1-UTC offset: {e}")
 
 # **************************************************************************************

src/celerity/__init__.py

@@ -11,6 +11,8 @@
 Python library for astronomical calculations.
 """
 
+# **************************************************************************************
+
 __version__ = "0.40.0"
 
 # **************************************************************************************

src/celerity/iers.py

@@ -6,12 +6,46 @@
 
 # **************************************************************************************
 
+from __future__ import annotations
+
+from dataclasses import dataclass
 from json import loads
-from typing import TypedDict
+from threading import Lock
+from time import monotonic
+from typing import Dict, TypedDict
 from urllib.request import Request, urlopen
 
 # **************************************************************************************
 
+URL_OPEN_TIMEOUT_SECONDS = 10
+
+# **************************************************************************************
+
+IERS_EOP_BASE_URL = "https://datacenter.iers.org/webservice/REST/eop/RestController.php"
+
+# **************************************************************************************
+
+
+@dataclass
+class IERSCache:
+    at: float
+    entry: DUT1Entry
+
+
+# **************************************************************************************
+
+_iers_cache_lock = Lock()
+
+# **************************************************************************************
+
+_iers_cache: Dict[str, IERSCache] = {}
+
+# **************************************************************************************
+
+MAX_CACHE_AGE_SECONDS = 6 * 60 * 60  # 6 hours
+
+# **************************************************************************************
+
 
 class DUT1Entry(TypedDict):
     # The Modified Julian Date (MJD) of the DUT1 entry:
@@ -22,21 +56,26 @@ class DUT1Entry(TypedDict):
 
 # **************************************************************************************
 
-IERS_DUT1_URL = "https://datacenter.iers.org/webservice/REST/eop/RestController.php"
 
-# **************************************************************************************
+def fetch_iers_rapid_service_data(url: str) -> DUT1Entry:
+    now = monotonic()
 
+    with _iers_cache_lock:
+        if url in _iers_cache and now - _iers_cache[url].at < MAX_CACHE_AGE_SECONDS:
+            return _iers_cache[url].entry
 
-def fetch_iers_rapid_service_data(url: str) -> DUT1Entry:
     # Ensure we always expect to accept JSON responses, whilst also letting the server
     # know that we are a client (e.g., celerity) to avoid any potential issues with
     # server-side rate limiting or blocking:
     request = Request(
         url,
-        headers={"Accept": "application/json", "User-Agent": "celerity"},
+        headers={
+            "Accept": "application/json",
+            "User-Agent": "celerity",
+        },
     )
 
-    with urlopen(request) as response:
+    with urlopen(request, timeout=URL_OPEN_TIMEOUT_SECONDS) as response:
         # Assume UTF-8 or ASCII text in the response:
         raw = response.read().decode("utf-8", errors="ignore")
 
@@ -59,10 +98,18 @@ def fetch_iers_rapid_service_data(url: str) -> DUT1Entry:
     if data["MJD"] is None:
         raise ValueError("MJD is None, no valid data found.")
 
-    return DUT1Entry(
+    entry = DUT1Entry(
         mjd=data["MJD"],
         dut1=float(data["Value"]) * 0.001,
     )
 
+    with _iers_cache_lock:
+        _iers_cache[url] = IERSCache(
+            at=now,
+            entry=entry,
+        )
+
+    return entry
+
 
 # **************************************************************************************

src/celerity/temporal.py

@@ -13,7 +13,7 @@
 
 from .common import GeographicCoordinate
 from .constants import J1900, J2000, JULIAN_DAYS_PER_CENTURY
-from .iers import IERS_DUT1_URL, fetch_iers_rapid_service_data
+from .iers import IERS_EOP_BASE_URL, fetch_iers_rapid_service_data
 from .tai import get_tai_utc_offset
 
 # **************************************************************************************
@@ -350,7 +350,7 @@ def get_ut1_utc_offset(when: datetime) -> float:
 
     # Construct the URL for the IERS Rapid Service data with the UT1-UTC, mjd and series
     # parameters set:
-    url = f"{IERS_DUT1_URL}?{urlencode(q, safe=' ')}".replace("+", "%20")
+    url = f"{IERS_EOP_BASE_URL}?{urlencode(q, safe=' ')}".replace("+", "%20")
 
     # Fetch the DUT1 entry from the IERS Rapid Service data:
     entry = fetch_iers_rapid_service_data(url)

tests/test_iers.py

@@ -9,6 +9,11 @@
 import unittest
 from datetime import datetime, timedelta, timezone
 
+from celerity.iers import (
+    IERS_EOP_BASE_URL,
+    MAX_CACHE_AGE_SECONDS,
+    _iers_cache,
+)
 from celerity.temporal import get_ut1_utc_offset
 
 # **************************************************************************************
@@ -48,5 +53,60 @@ def test_get_ut1_utc_offset_invalid_date(self) -> None:
         with self.assertRaises(ValueError):
             get_ut1_utc_offset(datetime(1972, 1, 1, 0, 0, 0, tzinfo=timezone.utc))
 
+    def test_get_ut1_utc_offset_cache_hit(self) -> None:
+        # Ensure we hit the cache on subsequent calls:
+        _iers_cache.clear()
+
+        when = datetime(2023, 5, 15, 0, 0, 0, tzinfo=timezone.utc)
+
+        first = get_ut1_utc_offset(when)
+
+        (url, cache) = next(iter(_iers_cache.items()))
+
+        self.assertEqual(len(_iers_cache), 1)
+
+        self.assertTrue(url.startswith(IERS_EOP_BASE_URL))
+        self.assertIn("param=UT1-UTC", url)
+        self.assertIn("mjd=", url)
+        self.assertIn("series=", url)
+
+        first_cached_at = cache.at
+        first_cached_dut1 = float(cache.entry["dut1"])
+
+        second = get_ut1_utc_offset(when)
+        self.assertEqual(len(_iers_cache), 1)
+        self.assertIn(url, _iers_cache)
+
+        second_cached_at = _iers_cache[url].at
+        second_cached_dut1 = float(_iers_cache[url].entry["dut1"])
+        self.assertEqual(first_cached_at, second_cached_at)
+        self.assertAlmostEqual(first, second, places=12)
+        self.assertAlmostEqual(first, first_cached_dut1, places=12)
+        self.assertAlmostEqual(second, second_cached_dut1, places=12)
+
+    def test_get_ut1_utc_offset_cache_expiry(self) -> None:
+        _iers_cache.clear()
+
+        when = datetime(2023, 5, 15, 0, 0, 0, tzinfo=timezone.utc)
+
+        first = get_ut1_utc_offset(when)
+        self.assertEqual(len(_iers_cache), 1)
+
+        (cached_url, cached_record) = next(iter(_iers_cache.items()))
+        original_at = cached_record.at
+
+        # Force-expire the cache entry by moving its timestamp into the past:
+        cached_record.at = original_at - (MAX_CACHE_AGE_SECONDS + 1)
+
+        second = get_ut1_utc_offset(when)
+
+        self.assertEqual(len(_iers_cache), 1)
+        self.assertIn(cached_url, _iers_cache)
+        self.assertGreater(_iers_cache[cached_url].at, original_at)
+
+        # DUT1 should remain reasonable/close; we cannot guarantee identical because IERS
+        # can revise recent values, but for a historical date it should normally match:
+        self.assertAlmostEqual(first, second, places=6)
+
 
 # **************************************************************************************