db version logging

Author: esoteric-ephemera

mp_api/client/core/settings.py

@@ -72,6 +72,11 @@ class MAPIClientSettings(BaseSettings):
         description="Angle tolerance for structure matching in degrees.",
     )
 
+    LOG_FILE : Path = Field(
+        Path("~/.mprester.log.yaml").expanduser(),
+        description = "Path for storing last accessed database version."
+    )
+
     LOCAL_DATASET_CACHE: Path = Field(
         Path("~/mp_datasets").expanduser(),
         description="Target directory for downloading full datasets",

mp_api/client/mprester.py

@@ -211,7 +211,7 @@ def __init__(
             )
 
         if notify_db_version:
-            raise NotImplementedError("This has not yet been implemented.")
+            self._db_version_check()
 
         # Dynamically set rester attributes.
         # First, materials and molecules top level resters are set.
@@ -298,6 +298,10 @@ def __dir__(self):
             + [r.split("/", 1)[0] for r in TOP_LEVEL_RESTERS if not r.startswith("_")]
         )
 
+    def __repr__(self) -> str:
+        db_version = self.get_database_version()
+        return f"MPRester({'v' + db_version if db_version else "unknown version"})"
+
     def get_task_ids_associated_with_material_id(
         self, material_id: str, calc_types: list[CalcType] | None = None
     ) -> list[str]:
@@ -369,7 +373,7 @@ def get_database_version(self) -> str | None:
         where "_DD" may be optional. An additional numerical suffix
         might be added if multiple releases happen on the same day.
 
-        Returns: database version as a string
+        Returns: database version as a string if accessible, None otherwise
         """
         if (get_resp := get(url=self.endpoint + "heartbeat")).status_code == 403:
             _emit_status_warning()
@@ -1615,3 +1619,33 @@ def get_oxygen_evolution(
             phase_diagram,
             unique_composition,
         )
+
+    def _db_version_check(self) -> None:
+        """Check if the database version has drifted."""
+
+        import yaml
+        db_version = self.get_database_version()
+        old_db_version = None
+        if MAPI_CLIENT_SETTINGS.LOG_FILE.exists():
+            old_db_version = (
+                yaml.safe_load(
+                    MAPI_CLIENT_SETTINGS.LOG_FILE.read_text()
+                ) or {}
+            ).get("MAPI_DB_VERSION",None)
+
+            # Handle legacy pymatgen behavior
+            if not isinstance(old_db_version,str):
+                old_db_version = None
+        
+        if old_db_version != db_version:
+            MAPI_CLIENT_SETTINGS.LOG_FILE.write_text(
+                yaml.safe_dump({"MAPI_DB_VERSION": db_version})
+            )
+
+            if old_db_version:
+                warnings.warn(
+                    "Materials Project database version has changed "
+                    f"from v{old_db_version} to v{db_version}.",
+                    category=MPRestWarning,
+                    stacklevel=2,
+                ) 

tests/client/test_mprester.py

@@ -625,3 +625,21 @@ def test_oxygen_evolution_bad_input(self, mpr):
     def test_monty_decode_warning(self):
         with pytest.warns(MPRestWarning, match="Ignoring `monty_decode`"):
             MPRester(monty_decode=False)
+
+    def test_db_warning(self, monkeypatch: pytest.MonkeyPatch):
+
+        from pathlib import Path
+        import yaml
+        from mp_api.client.core.settings import MAPI_CLIENT_SETTINGS
+
+        with NamedTemporaryFile(suffix=".yaml") as tmp_log:
+            monkeypatch.setattr(MAPI_CLIENT_SETTINGS,"LOG_FILE",Path(tmp_log.name))
+
+            with MPRester(notify_db_version = True) as mpr:
+                db_version = mpr.get_database_version()
+
+            parsed_db_ver = yaml.safe_load(
+                Path(tmp_log.name).read_text()
+            ).get("MAPI_DB_VERSION") 
+            assert parsed_db_ver == db_version
+            assert isinstance(parsed_db_ver,str)