merge conf

Author: esoteric-ephemera

README.md

@@ -1,7 +1,7 @@
 # The Materials Project API
 
-[![testing](https://github.com/materialsproject/api/workflows/testing/badge.svg)](https://github.com/materialsproject/api/actions?query=workflow%3Atesting)
+[![testing](https://github.com/materialsproject/api/actions/workflows/testing.yml/badge.svg?branch=main)](https://github.com/materialsproject/api/actions?query=workflow%3Atesting+branch%3Amain)
 [![codecov](https://codecov.io/gh/materialsproject/api/branch/main/graph/badge.svg)](https://codecov.io/gh/materialsproject/api)
-![python](https://img.shields.io/badge/Python-3.9+-blue.svg?logo=python&logoColor=white)
+![python](https://img.shields.io/badge/Python-3.11+-blue.svg?logo=python&logoColor=white)
 
 This repository is the development environment for the new Materials Project API. A core client implementation will reside here. For information on how to use the API, please see the updated [documentation](https://docs.materialsproject.org/downloading-data/how-do-i-download-the-materials-project-database).

mp_api/client/core/__init__.py

@@ -1,4 +1,5 @@
 from __future__ import annotations
 
-from .client import BaseRester, MPRestError, MPRestWarning
+from .client import BaseRester
+from .exceptions import MPRestError, MPRestWarning
 from .settings import MAPIClientSettings

mp_api/client/core/client.py

@@ -30,6 +30,7 @@
 from tqdm.auto import tqdm
 from urllib3.util.retry import Retry
 
+from mp_api.client.core.exceptions import MPRestError
 from mp_api.client.core.settings import MAPIClientSettings
 from mp_api.client.core.utils import load_json, validate_ids
 
@@ -94,11 +95,11 @@ def __init__(
         session: requests.Session | None = None,
         s3_client: Any | None = None,
         debug: bool = False,
-        monty_decode: bool = True,
         use_document_model: bool = True,
         timeout: int = 20,
         headers: dict | None = None,
         mute_progress_bars: bool = SETTINGS.MUTE_PROGRESS_BARS,
+        **kwargs,
     ):
         """Initialize the REST API helper class.
 
@@ -123,13 +124,13 @@ def __init__(
                 advanced usage only.
             s3_client: boto3 S3 client object with which to connect to the object stores.ct to the object stores.ct to the object stores.
             debug: if True, print the URL for every request
-            monty_decode: Decode the data using monty into python objects
             use_document_model: If False, skip the creating the document model and return data
                 as a dictionary. This can be simpler to work with but bypasses data validation
                 and will not give auto-complete for available fields.
             timeout: Time in seconds to wait until a request timeout error is thrown
             headers: Custom headers for localhost connections.
             mute_progress_bars: Whether to disable progress bars.
+            **kwargs: access to legacy kwargs that may be in the process of being deprecated
         """
         # TODO: think about how to migrate from PMG_MAPI_KEY
         self.api_key = api_key or os.getenv("MP_API_KEY")
@@ -138,7 +139,6 @@ def __init__(
         )
         self.debug = debug
         self.include_user_agent = include_user_agent
-        self.monty_decode = monty_decode
         self.use_document_model = use_document_model
         self.timeout = timeout
         self.headers = headers or {}
@@ -153,6 +153,12 @@ def __init__(
         self._session = session
         self._s3_client = s3_client
 
+        if "monty_decode" in kwargs:
+            warnings.warn(
+                "Ignoring `monty_decode`, as it is no longer a supported option in `mp_api`."
+                "The client by default returns results consistent with `monty_decode=True`."
+            )
+
     @property
     def session(self) -> requests.Session:
         if not self._session:
@@ -267,7 +273,7 @@ def _post_resource(
             response = self.session.post(url, json=payload, verify=True, params=params)
 
             if response.status_code == 200:
-                data = load_json(response.text, deser=self.monty_decode)
+                data = load_json(response.text)
                 if self.document_model and use_document_model:
                     if isinstance(data["data"], dict):
                         data["data"] = self.document_model.model_validate(data["data"])  # type: ignore
@@ -335,7 +341,7 @@ def _patch_resource(
             response = self.session.patch(url, json=payload, verify=True, params=params)
 
             if response.status_code == 200:
-                data = load_json(response.text, deser=self.monty_decode)
+                data = load_json(response.text)
                 if self.document_model and use_document_model:
                     if isinstance(data["data"], dict):
                         data["data"] = self.document_model.model_validate(data["data"])  # type: ignore
@@ -386,10 +392,7 @@ def _query_open_data(
         Returns:
             dict: MontyDecoded data
         """
-        if not decoder:
-
-            def decoder(x):
-                return load_json(x, deser=self.monty_decode)
+        decoder = decoder or load_json
 
         file = open(
             f"s3://{bucket}/{key}",
@@ -999,7 +1002,7 @@ def _submit_request_and_process(
             )
 
         if response.status_code == 200:
-            data = load_json(response.text, deser=self.monty_decode)
+            data = load_json(response.text)
             # other sub-urls may use different document models
             # the client does not handle this in a particularly smart way currently
             if self.document_model and use_document_model:
@@ -1304,12 +1307,10 @@ def count(self, criteria: dict | None = None) -> int | str:
         """
         criteria = criteria or {}
         user_preferences = (
-            self.monty_decode,
             self.use_document_model,
             self.mute_progress_bars,
         )
-        self.monty_decode, self.use_document_model, self.mute_progress_bars = (
-            False,
+        self.use_document_model, self.mute_progress_bars = (
             False,
             True,
         )  # do not waste cycles decoding
@@ -1331,7 +1332,6 @@ def count(self, criteria: dict | None = None) -> int | str:
                 )
 
         (
-            self.monty_decode,
             self.use_document_model,
             self.mute_progress_bars,
         ) = user_preferences
@@ -1389,11 +1389,3 @@ def __getattr__(self, v: str):
 
     def __dir__(self):
         return dir(self.__class__) + list(self._sub_resters)
-
-
-class MPRestError(Exception):
-    """Raised when the query has problems, e.g., bad query format."""
-
-
-class MPRestWarning(Warning):
-    """Raised when a query is malformed but interpretable."""

mp_api/client/core/exceptions.py

@@ -0,0 +1,10 @@
+"""Define custom exceptions and warnings for the client."""
+from __future__ import annotations
+
+
+class MPRestError(Exception):
+    """Raised when the query has problems, e.g., bad query format."""
+
+
+class MPRestWarning(Warning):
+    """Raised when a query is malformed but interpretable."""

mp_api/client/core/settings.py

@@ -2,7 +2,7 @@
 from multiprocessing import cpu_count
 from typing import List
 
-from pydantic import Field
+from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from pymatgen.core import _load_pmg_settings
 
@@ -14,6 +14,7 @@
 _MUTE_PROGRESS_BAR = PMG_SETTINGS.get("MPRESTER_MUTE_PROGRESS_BARS", False)
 _MAX_HTTP_URL_LENGTH = PMG_SETTINGS.get("MPRESTER_MAX_HTTP_URL_LENGTH", 2000)
 _MAX_LIST_LENGTH = min(PMG_SETTINGS.get("MPRESTER_MAX_LIST_LENGTH", 10000), 10000)
+_DEFAULT_ENDPOINT = "https://api.materialsproject.org/"
 
 try:
     CPU_COUNT = cpu_count()
@@ -80,11 +81,21 @@ class MAPIClientSettings(BaseSettings):
     )
 
     MIN_EMMET_VERSION: str = Field(
-        "0.54.0", description="Minimum compatible version of emmet-core for the client."
+        "0.86.3rc0",
+        description="Minimum compatible version of emmet-core for the client.",
     )
 
     MAX_LIST_LENGTH: int = Field(
         _MAX_LIST_LENGTH, description="Maximum length of query parameter list"
     )
 
+    ENDPOINT: str = Field(
+        _DEFAULT_ENDPOINT, description="The default API endpoint to use."
+    )
+
     model_config = SettingsConfigDict(env_prefix="MPRESTER_")
+
+    @field_validator("ENDPOINT", mode="before")
+    def _get_endpoint_from_env(cls, v: str | None) -> str:
+        """Support setting endpoint via MP_API_ENDPOINT environment variable."""
+        return v or os.environ.get("MP_API_ENDPOINT") or _DEFAULT_ENDPOINT

mp_api/client/core/utils.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 from importlib import import_module
 from typing import TYPE_CHECKING, Literal
 
@@ -9,6 +10,7 @@
 from monty.json import MontyDecoder
 from packaging.version import parse as parse_version
 
+from mp_api.client.core.exceptions import MPRestError
 from mp_api.client.core.settings import MAPIClientSettings
 
 if TYPE_CHECKING:
@@ -51,20 +53,39 @@ def load_json(
     return MontyDecoder().process_decoded(data) if deser else data
 
 
+def validate_api_key(api_key: str | None = None) -> str:
+    """Find and validate an API key."""
+    # SETTINGS tries to read API key from ~/.config/.pmgrc.yaml
+    api_key = api_key or os.getenv("MP_API_KEY")
+    if not api_key:
+        from pymatgen.core import SETTINGS
+
+        api_key = SETTINGS.get("PMG_MAPI_KEY")
+
+    if not api_key or len(api_key) != 32:
+        addendum = " Valid API keys are 32 characters." if api_key else ""
+        raise MPRestError(
+            "Please obtain a valid API key from https://materialsproject.org/api "
+            f"and export it as an environment variable `MP_API_KEY`.{addendum}"
+        )
+
+    return api_key
+
+
 def validate_ids(id_list: list[str]) -> list[str]:
     """Function to validate material and task IDs.
 
     Args:
         id_list (List[str]): List of material or task IDs.
 
     Raises:
-        ValueError: If at least one ID is not formatted correctly.
+        MPRestError: If at least one ID is not formatted correctly.
 
     Returns:
         id_list: Returns original ID list if everything is formatted correctly.
     """
     if len(id_list) > MAPIClientSettings().MAX_LIST_LENGTH:
-        raise ValueError(
+        raise MPRestError(
             "List of material/molecule IDs provided is too long. Consider removing the ID filter to automatically pull"
             " data for all IDs and filter locally."
         )