Bump test coverage, revise absorption rester, remove deprecated methods (#1042)

Author: esoteric-ephemera

mp_api/client/core/utils.py

@@ -1,17 +1,17 @@
 from __future__ import annotations
 
-import re
 from typing import TYPE_CHECKING, Literal
 
 import orjson
 from emmet.core import __version__ as _EMMET_CORE_VER
+from emmet.core.mpid_ext import validate_identifier
 from monty.json import MontyDecoder
 from packaging.version import parse as parse_version
 
 from mp_api.client.core.settings import MAPIClientSettings
 
 if TYPE_CHECKING:
-    from monty.json import MSONable
+    from typing import Any
 
 
 def _compare_emmet_ver(
@@ -23,6 +23,10 @@ def _compare_emmet_ver(
         _compare_emmet_ver("0.84.0rc0","<") returns
         emmet.core.__version__ < "0.84.0rc0"
 
+    This function may not be used anywhere in the client, but it should
+    be preserved for future use, in case some degree of backwards
+    compatibility or feature buy-in is needed.
+
     Parameters
     -----------
     ref_version : str
@@ -36,41 +40,17 @@ def _compare_emmet_ver(
     )(parse_version(ref_version))
 
 
-if _compare_emmet_ver("0.85.0", ">="):
-    from emmet.core.mpid_ext import validate_identifier
-else:
-    validate_identifier = None
-
-
-def load_json(json_like: str | bytes, deser: bool = False, encoding: str = "utf-8"):
+def load_json(
+    json_like: str | bytes, deser: bool = False, encoding: str = "utf-8"
+) -> Any:
     """Utility to load json in consistent manner."""
     data = orjson.loads(
         json_like if isinstance(json_like, bytes) else json_like.encode(encoding)
     )
     return MontyDecoder().process_decoded(data) if deser else data
 
 
-def _legacy_id_validation(id_list: list[str]) -> list[str]:
-    """Legacy utility to validate IDs, pre-AlphaID transition.
-
-    This function is temporarily maintained to allow for
-    backwards compatibility with older versions of emmet, and will
-    not be preserved.
-    """
-    pattern = "(mp|mvc|mol|mpcule)-.*"
-    if malformed_ids := {
-        entry for entry in id_list if re.match(pattern, entry) is None
-    }:
-        raise ValueError(
-            f"{'Entry' if len(malformed_ids) == 1 else 'Entries'}"
-            f" {', '.join(malformed_ids)}"
-            f"{'is' if len(malformed_ids) == 1 else 'are'} not formatted correctly!"
-        )
-
-    return id_list
-
-
-def validate_ids(id_list: list[str]):
+def validate_ids(id_list: list[str]) -> list[str]:
     """Function to validate material and task IDs.
 
     Args:
@@ -91,36 +71,4 @@ def validate_ids(id_list: list[str]):
     # TODO: after the transition to AlphaID in the document models,
     # The following line should be changed to
     # return [validate_identifier(idx,serialize=True) for idx in id_list]
-    if validate_identifier:
-        return [str(validate_identifier(idx)) for idx in id_list]
-    return _legacy_id_validation(id_list)
-
-
-def allow_msonable_dict(monty_cls: type[MSONable]):
-    """Patch Monty to allow for dict values for MSONable."""
-
-    def validate_monty(cls, v, _):
-        """Stub validator for MSONable as a dictionary only."""
-        if isinstance(v, cls):
-            return v
-        elif isinstance(v, dict):
-            # Just validate the simple Monty Dict Model
-            errors = []
-            if v.get("@module", "") != monty_cls.__module__:
-                errors.append("@module")
-
-            if v.get("@class", "") != monty_cls.__name__:
-                errors.append("@class")
-
-            if len(errors) > 0:
-                raise ValueError(
-                    "Missing Monty seriailzation fields in dictionary: {errors}"
-                )
-
-            return v
-        else:
-            raise ValueError(f"Must provide {cls.__name__} or MSONable dictionary")
-
-    monty_cls.validate_monty_v2 = classmethod(validate_monty)
-
-    return monty_cls
+    return [str(validate_identifier(idx)) for idx in id_list]

mp_api/client/mprester.py

@@ -11,6 +11,7 @@
 from emmet.core.mpid import MPID, AlphaID
 from emmet.core.settings import EmmetSettings
 from emmet.core.tasks import TaskDoc
+from emmet.core.types.enums import ThermoType
 from emmet.core.vasp.calc_types import CalcType
 from packaging import version
 from pymatgen.analysis.phase_diagram import PhaseDiagram
@@ -25,7 +26,7 @@
 from mp_api.client.core import BaseRester, MPRestError
 from mp_api.client.core._oxygen_evolution import OxygenEvolution
 from mp_api.client.core.settings import MAPIClientSettings
-from mp_api.client.core.utils import _compare_emmet_ver, load_json, validate_ids
+from mp_api.client.core.utils import load_json, validate_ids
 from mp_api.client.routes import GeneralStoreRester, MessagesRester, UserSettingsRester
 from mp_api.client.routes.materials import (
     AbsorptionRester,
@@ -60,11 +61,6 @@
 from mp_api.client.routes.materials.materials import MaterialsRester
 from mp_api.client.routes.molecules import MoleculeRester
 
-if _compare_emmet_ver("0.85.0", ">="):
-    from emmet.core.types.enums import ThermoType
-else:
-    from emmet.core.thermo import ThermoType
-
 if TYPE_CHECKING:
     from typing import Any, Literal
 
@@ -225,6 +221,9 @@ def __init__(
             "chemenv",
         ]
 
+        if not self.endpoint.endswith("/"):
+            self.endpoint += "/"
+
         # Check if emmet version of server is compatible
         emmet_version = MPRester.get_emmet_version(self.endpoint)
 
@@ -239,9 +238,6 @@ def __init__(
         if notify_db_version:
             raise NotImplementedError("This has not yet been implemented.")
 
-        if not self.endpoint.endswith("/"):
-            self.endpoint += "/"
-
         # Dynamically set rester attributes.
         # First, materials and molecules top level resters are set.
         # Nested rested are then setup to be loaded dynamically with custom __getattr__ functions.

mp_api/client/routes/materials/absorption.py

@@ -16,10 +16,11 @@ class AbsorptionRester(BaseRester):
     def search(
         self,
         material_ids: str | list[str] | None = None,
-        chemsys: str | list[str] | None = None,
-        elements: list[str] | None = None,
-        exclude_elements: list[str] | None = None,
-        formula: list[str] | None = None,
+        num_sites: int | tuple[int, int] | None = None,
+        num_elements: int | tuple[int, int] | None = None,
+        volume: float | tuple[float, float] | None = None,
+        density: float | tuple[float, float] | None = None,
+        band_gap: float | tuple[float, float] | None = None,
         num_chunks: int | None = None,
         chunk_size: int = 1000,
         all_fields: bool = True,
@@ -28,14 +29,26 @@ def search(
         """Query for optical absorption spectra data.
 
         Arguments:
-            material_ids (str, List[str]): Search for optical absorption data associated with the specified Material IDs
-            chemsys (str, List[str]): A chemical system or list of chemical systems
-                (e.g., Li-Fe-O, Si-*, [Si-O, Li-Fe-P]).
-            elements (List[str]): A list of elements.
-            exclude_elements (List[str]): A list of elements to exclude.
-            formula (str, List[str]): A formula including anonymized formula
-                or wild cards (e.g., Fe2O3, ABO3, Si*). A list of chemical formulas can also be passed
-                (e.g., [Fe2O3, ABO3]).
+            material_ids (str, List[str]):
+                Search for optical absorption data associated with the
+                specified Material ID(s)
+            num_sites (int, tuple[int, int]):
+                Search with a single number or a range of number of sites
+                in the structure.
+            num_elements (int, tuple[int, int]):
+                Search with a single number or a range of number of distinct
+                elements in the structure.
+            volume (float, tuple[float, float]):
+                Search with a single number or a range of structural
+                (lattice) volumes in ų.
+                If a single number, an uncertainty of ±0.01 is automatically used.
+            density (float, tuple[float, float]):
+                Search with a single number or a range of structural
+                (lattice) densities, in g/cm³.
+                If a single number, an uncertainty of ±0.01 is automatically used.
+            band_gap (float, tuple[float, float]):
+                Search with a single number or a range of band gaps in eV.
+                If a single number, an uncertainty of ±0.01 is automatically used.
             num_chunks (int): Maximum number of chunks of data to yield. None will yield all possible.
             chunk_size (int): Number of data entries per chunk.
             all_fields (bool): Whether to return all fields in the document. Defaults to True.
@@ -46,23 +59,27 @@ def search(
         """
         query_params = defaultdict(dict)  # type: dict
 
-        if formula:
-            if isinstance(formula, str):
-                formula = [formula]
-
-            query_params.update({"formula": ",".join(formula)})
-
-        if chemsys:
-            if isinstance(chemsys, str):
-                chemsys = [chemsys]
-
-            query_params.update({"chemsys": ",".join(chemsys)})
-
-        if elements:
-            query_params.update({"elements": ",".join(elements)})
-
-        if exclude_elements:
-            query_params.update({"exclude_elements": ",".join(exclude_elements)})
+        aliased = {
+            "num_sites": "nsites",
+            "num_elements": "nelements",
+            "band_gap": "bandgap",
+        }
+        user_query = locals()
+        for k in ("num_sites", "num_elements", "volume", "density", "band_gap"):
+            if (value := user_query.get(k)) is not None:
+                if k in ("num_sites", "num_elements") and isinstance(value, int):
+                    value = (value, value)
+                elif k in ("volume", "density", "band_gap") and isinstance(
+                    value, int | float
+                ):
+                    value = (value - 1e-2, value + 1e-2)
+
+                query_params.update(
+                    {
+                        f"{aliased.get(k,k)}_min": value[0],
+                        f"{aliased.get(k,k)}_max": value[1],
+                    }
+                )
 
         if material_ids:
             if isinstance(material_ids, str):
@@ -77,7 +94,6 @@ def search(
         }
 
         return super()._search(
-            formulae=formula,
             num_chunks=num_chunks,
             chunk_size=chunk_size,
             all_fields=all_fields,