mp-api 0.47.0rc0__tar.gz → 0.47.1__tar.gz

{mp_api-0.47.0rc0 → mp_api-0.47.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mp-api
-Version: 0.47.0rc0
+Version: 0.47.1
 Summary: API Client for the Materials Project
 Author-email: The Materials Project <feedback@materialsproject.org>
 License-Expression: BSD-3-Clause-LBNL
@@ -16,18 +16,18 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.12
-Requires-Dist: boto3
+Requires-Dist: boto3>=1.34
 Requires-Dist: deltalake<1.6.0,>=1.4.0
-Requires-Dist: emmet-core<0.88.1,>=0.88.0rc
+Requires-Dist: emmet-core>=0.88.0
 Requires-Dist: monty>=2024.12.10
 Requires-Dist: orjson<4,>=3.10
 Requires-Dist: pyarrow>=20.0.0
-Requires-Dist: pymatgen>2024.2.20
+Requires-Dist: pymatgen>=2026.10.24
 Requires-Dist: requests>=2.23.0
 Requires-Dist: rich>=13.0
 Provides-Extra: all
 Requires-Dist: custodian; extra == 'all'
-Requires-Dist: emmet-core[all]<0.88.1,>=0.88.0rc; extra == 'all'
+Requires-Dist: emmet-core[all]>=0.88.0; extra == 'all'
 Requires-Dist: fastmcp; extra == 'all'
 Requires-Dist: flask; extra == 'all'
 Requires-Dist: ipywidgets; extra == 'all'

{mp_api-0.47.0rc0 → mp_api-0.47.1}/mp_api/client/contribs/_logger.py

@@ -9,9 +9,9 @@ from __future__ import annotations
 
 import logging
 import os
-import warnings
 
 from mp_api.client.contribs.settings import MPCC_SETTINGS
+from mp_api.client.core._display import mp_deprecation
 
 
 class CustomLoggerAdapter(logging.LoggerAdapter):
@@ -39,10 +39,9 @@ def get_logger(name: str = "mp_api.client.contribs") -> CustomLoggerAdapter:
 
 
 if MPCC_SETTINGS.CLIENT_LOG_LEVEL is not None:
-    warnings.warn(
+    mp_deprecation(
         "MPCONTRIBS_CLIENT_LOG_LEVEL is deprecated and ignored, use MPRESTER_LOG_LEVEL "
         "(which sets the level for the whole client) instead.",
-        FutureWarning,
         stacklevel=2,
     )
 

{mp_api-0.47.0rc0 → mp_api-0.47.1}/mp_api/client/contribs/client.py

@@ -8,7 +8,6 @@ import importlib.metadata
 import itertools
 import sys
 import time
-import warnings
 from base64 import urlsafe_b64encode
 from collections import defaultdict
 from concurrent.futures import as_completed
@@ -67,7 +66,8 @@ from mp_api.client.contribs.utils import (
     get_md5,
     unflatten_dict,
 )
-from mp_api.client.core._display import progress_bar
+from mp_api.client.core._display import mp_deprecation, progress_bar
+from mp_api.client.core._external import track_calls
 from mp_api.client.core.exceptions import MPContribsClientError
 from mp_api.client.core.schemas import _convert_to_model
 from mp_api.client.core.settings import MAPI_CLIENT_SETTINGS
@@ -444,6 +444,7 @@ def _version(url):
             time.sleep(30)
 
 
+@track_calls
 class ContribsClient(SwaggerClient):
     """client to connect to MPContribs API.
 
@@ -492,7 +493,7 @@ class ContribsClient(SwaggerClient):
                 )
             else:
                 api_key = kwargs.pop("apikey")
-            warnings.warn(api_key_warn, FutureWarning, stacklevel=2)
+            mp_deprecation(api_key_warn, stacklevel=2)
 
         if api_key and len(api_key) != 32:
             raise MPContribsClientError(f"Invalid API key: {api_key}")
@@ -542,10 +543,9 @@ class ContribsClient(SwaggerClient):
     @property
     def apikey(self) -> str | None:
         """Handle deprecated `apikey` attr."""
-        warnings.warn(
+        mp_deprecation(
             "`apikey` has been deprecated in favor of `api_key` for "
             "consistency with the Materials Project API client.",
-            FutureWarning,
             stacklevel=2,
         )
         return self.api_key
@@ -994,11 +994,14 @@ class ContribsClient(SwaggerClient):
             else MPCDict(contrib)
         )
 
-    def get_table(self, tid_or_md5: str) -> Table:
+    def get_table(self, tid_or_md5: str, timeout: int = -1) -> Table:
         """Retrieve full Pandas DataFrame for a table.
 
+        Data pages beyond the first are fetched concurrently.
+
         Args:
             tid_or_md5 (str): ObjectId or MD5 hash digest for table
+            timeout (int): cancel remaining requests if timeout exceeded (in seconds)
         """
         str_len = len(tid_or_md5)
         if str_len not in {24, 32}:
@@ -1016,23 +1019,36 @@ class ContribsClient(SwaggerClient):
 
         op = self.swagger_spec.resources["tables"].queryTables
         per_page = op.params["data_per_page"].param_spec["maximum"]
-        table: dict[str, list[str]] = {"data": []}
-        page, pages = 1, None
 
-        while pages is None or page <= pages:
-            resp = self.tables.getTableById(
-                pk=tid, _fields=["_all"], data_page=page, data_per_page=per_page
-            ).result()
-            table["data"].extend(resp["data"])
-            if pages is None:
-                pages = resp["total_data_pages"]
-                table["index"] = resp["index"]
-                table["columns"] = resp["columns"]
-                table_attrs: dict[str, str] = (resp.get("attrs") or {}) | {
-                    field: resp.get(field) for field in {"id", "name", "md5"}
-                }
+        # fetch the first page to learn the total number of data pages + metadata
+        resp = self.tables.getTableById(
+            pk=tid, _fields=["_all"], data_page=1, data_per_page=per_page
+        ).result()
+        pages = resp["total_data_pages"]
+        table: dict[str, Any] = {
+            "data": resp["data"],
+            "index": resp["index"],
+            "columns": resp["columns"],
+        }
+        table_attrs: dict[str, str] = (resp.get("attrs") or {}) | {
+            field: resp.get(field) for field in {"id", "name", "md5"}
+        }
 
-            page += 1
+        # fetch any remaining pages concurrently, then reassemble in page order
+        if pages > 1:
+            futures = [
+                self._get_future(
+                    page,
+                    {"_fields": "_all", "data_page": page, "data_per_page": per_page},
+                    rel_url=f"tables/{tid}",
+                )
+                for page in range(2, pages + 1)
+            ]
+            responses = _run_futures(
+                futures, timeout=timeout, disable=self.mute_progress_bars
+            )
+            for page in sorted(responses):
+                table["data"].extend(responses[page]["result"]["data"])
 
         return Table.from_dict(table | {"attrs": table_attrs})
 

{mp_api-0.47.0rc0 → mp_api-0.47.1}/mp_api/client/core/_display.py

@@ -29,20 +29,62 @@ level, handler or propagation setting, here. Child loggers (`mp_api.client.*`,
 including contribs) never set their own level, so one setting controls all of
 them. Use `MPRESTER_LOG_LEVEL` or `enable_logging(level)`.
 
+Messages are shown in the console's default style; only the level is
+coloured.
+
+The client's warnings
+---------------------
+The client's own warnings (`MPRestWarning`, its `FutureWarning` deprecations,
+the `MPDataset*Warning`s) are ordinary Python warnings, so filters
+(`warnings.filterwarnings`, `pytest.warns`, `logging.captureWarnings`) work
+as usual. In a terminal / notebook they are shown in the same layout as log
+records, with the warning class as the label and the caller's code below:
+
+```
+MPRestWarning  <message>
+               my_script.py:12
+```
+
+Elsewhere, or if the application installed its own warnings hook (e.g.
+`logging.captureWarnings(True)`), Python's usual format / the application's
+hook is used.
+
+Other libraries
+---------------
+Warnings from other libraries (pymatgen, emmet, ...) raised while a client
+method runs, and their log records that nothing else would handle, are shown
+as WARNING records on `mp_api.client.external.<library>`, naming the library
+code they came from. In a terminal / notebook:
+
+```
+WARNING  mp_api.client.external.pymatgen  <message>
+         pymatgen/analysis/compatibility/mixing_scheme.py:320
+```
+
+and on one line otherwise. Library deprecation warnings are left alone.
+Silence one library with e.g.
+`logging.getLogger("mp_api.client.external.pymatgen").setLevel(logging.ERROR)`.
+See `mp_api.client.core._external`.
+
 Quiet mode
 ----------
 `quiet()` (or `MPRESTER_QUIET=true`, or `MPRester(quiet=True)`) silences the
-client for the whole process: no log records, progress bars, status lines,
-notices or `MPRestWarning`s. Deprecation warnings (`FutureWarning`) and
-exceptions are still raised. It can be used as a context manager.
+client for the whole process: no log records (including those from other
+libraries, above), progress bars, status lines, notices, `MPRestWarning`s or
+`MPDataset*Warning`s.
+Exceptions are still raised, and the client's deprecation warnings
+(`FutureWarning`) are still shown unless `quiet(deprecations=True)` or
+`MPRESTER_QUIET_DEPRECATIONS=true`. It can be used as a context manager; see
+`quiet()` for exactly what is and isn't silenced.
 
 Which channel to use
 --------------------
 - The operation failed: raise an exception.
-- A deprecated API was used: `warnings.warn(..., FutureWarning)`, which is
-  shown by default, also when called from other libraries.
+- A deprecated API was used: `mp_deprecation(...)` (a `FutureWarning`), which
+  is shown by default, also when called from other libraries.
 - Something the caller can change in their call (an ignored argument, misuse,
-  a caveat about what the data means): `mp_warning(...)` (an `MPRestWarning`).
+  a caveat about what the data means): `mp_warning(...)` (an `MPRestWarning`),
+  or `mp_advice(..., category)` for a more specific warning class.
 - A runtime or data event the caller can't change in code (server
   unreachable, data missing, a local dataset reused): `logger.warning/info`.
 - Diagnostics: `logger.debug`.
@@ -81,11 +123,11 @@ import io
 import logging
 import threading
 import time
-import warnings
 from contextlib import contextmanager
 from typing import TYPE_CHECKING, Self
 
 from rich.console import Console
+from rich.highlighter import NullHighlighter
 from rich.logging import RichHandler
 from rich.progress import (
     BarColumn,
@@ -137,6 +179,8 @@ MP_THEME = Theme(
         "mp.error": "#F14668",  # Bulma danger
         "mp.muted": "#7A7A7A",  # Bulma .has-text-grey
         "mp.title": "bold underline",
+        "mp.logger.external": "#939FC8",  # mp.secondary: logger of a library record
+        "mp.warning.label": "#D69E00",  # class name of a client warning
         "mp.field": "bold",
         "mp.table.header": "bold #008F83",  # brand dark
         # database versions, relative to the one the API serves
@@ -200,6 +244,35 @@ def _can_draw_live(console: Console) -> bool:
     return console.is_terminal and not console.is_dumb_terminal
 
 
+def print_warning(label: str, message: str, location: str) -> bool:
+    """Show a client warning on the console, if it's interactive.
+
+    Rendered like the log records: the label (the warning's class name) in a
+    column of its own, the message in the default style, and where the
+    warning points to (the caller's code) on a muted line below it.
+
+    Args:
+        label (str) : e.g. "MPRestWarning"
+        message (str) : warning text
+        location (str) : "file:line"
+
+    Returns:
+        bool : False if nothing was shown (not an interactive console)
+    """
+    console = get_console()
+    if not _is_interactive(console):
+        return False
+    grid = Table.grid(padding=(0, 1), expand=True)
+    grid.add_column(style="mp.warning.label", no_wrap=True)
+    grid.add_column(ratio=1, overflow="fold")
+    grid.add_row(
+        Text(label),
+        Text.assemble(message.strip(), "\n", (location, "mp.muted")),
+    )
+    console.print(grid)
+    return True
+
+
 def print_notice(message: str, style: str | None = None) -> None:
     """Print a one-line notice to the console (stderr).
 
@@ -675,6 +748,25 @@ def _app_level(logger: logging.Logger) -> int:
     return logging.WARNING  # pragma: no cover - root always has a level
 
 
+class _MPRichHandler(RichHandler):
+    """`RichHandler` showing messages in the console's default style.
+
+    Only the level (and, for records re-emitted from other libraries, the
+    logger name and origin) is styled.
+    """
+
+    def render_message(self, record: logging.LogRecord, message: str) -> Text:
+        if (origin := getattr(record, "mp_origin", None)) is None:
+            return Text(message)
+        return Text.assemble(
+            (record.name, "mp.logger.external"),
+            "  ",
+            str(getattr(record, "mp_message", message)),
+            "\n",
+            (origin, "mp.muted"),
+        )
+
+
 class _MPDefaultHandler(logging.Handler):
     """Default handler for `mp_api.client`, see module docstring."""
 
@@ -686,12 +778,14 @@ class _MPDefaultHandler(logging.Handler):
 
     def _rich_handler(self, console: Console) -> RichHandler:
         if self._rich is None or self._rich.console is not console:
-            self._rich = RichHandler(
+            self._rich = _MPRichHandler(
                 console=console,
                 show_time=False,
                 show_path=False,
                 markup=False,
                 rich_tracebacks=False,
+                highlighter=NullHighlighter(),
+                keywords=[],
             )
         return self._rich
 
@@ -768,10 +862,11 @@ _SILENT = logging.CRITICAL + 1
 
 
 class _QuietState:
-    """Process-wide quiet flag. `saved_level` is the log level to restore."""
+    """Process-wide quiet flags. `saved_level` is the log level to restore."""
 
     def __init__(self) -> None:
         self.enabled = False
+        self.deprecations = False
         self.saved_level: int = logging.NOTSET
 
 
@@ -781,36 +876,58 @@ _QUIET = _QuietState()
 class _QuietContext:
     """Returned by `quiet()`; restores the previous state when used with `with`."""
 
-    def __init__(self, previous: bool) -> None:
+    def __init__(self, previous: tuple[bool, bool]) -> None:
         self._previous = previous
 
     def __enter__(self) -> Self:
         return self
 
     def __exit__(self, *exc_info: object) -> None:
-        _set_quiet(self._previous)
+        _set_quiet(*self._previous)
 
 
-def _set_quiet(enabled: bool) -> bool:
-    """Turn quiet mode on or off, returning the previous state."""
+def _set_quiet(enabled: bool, deprecations: bool = False) -> tuple[bool, bool]:
+    """Set quiet mode, returning the previous `(enabled, deprecations)`."""
     logger = logging.getLogger(LOGGER_NAME)
     with _handler_lock:
-        previous = _QUIET.enabled
-        if enabled and not previous:
+        previous = (_QUIET.enabled, _QUIET.deprecations)
+        if enabled and not _QUIET.enabled:
             _QUIET.saved_level = logger.level
             logger.setLevel(_SILENT)
-        elif previous and not enabled:
+        elif _QUIET.enabled and not enabled:
             logger.setLevel(_QUIET.saved_level)
         _QUIET.enabled = enabled
+        _QUIET.deprecations = enabled and deprecations
     return previous
 
 
-def quiet(enabled: bool = True) -> _QuietContext:
-    """Silence all output from the client in this process.
+def quiet(enabled: bool = True, *, deprecations: bool = False) -> _QuietContext:
+    """Silence output from the client in this process.
+
+    Silenced while quiet:
+
+    - the client's log records (they don't reach the application's handlers
+      either), progress bars, status lines and notices
+    - `MPRestWarning`s and the `MPDataset*Warning`s (slow indexing, slicing
+      or iteration of downloaded datasets)
+    - warnings and fallback log output from other libraries (e.g. pymatgen)
+      raised while a client method runs; these are otherwise shown as
+      WARNING records on `mp_api.client.external.<library>`
+    - with `deprecations=True`, also the client's deprecation warnings
+      (`FutureWarning`)
 
-    While quiet, the client emits no log records (they don't reach the
-    application's handlers either), progress bars, status lines, notices or
-    `MPRestWarning`s. Deprecation warnings and exceptions are unaffected.
+    Not silenced:
+
+    - exceptions
+    - deprecation warnings from other libraries
+    - output libraries print directly (`print()`, their own progress bars)
+      or write from compiled code
+    - log records sent to handlers that a library or the application set up
+    - library warnings raised outside client methods, e.g. on import, or when
+      using returned objects later
+    - warnings, if the application replaced `warnings.showwarning` itself
+      (e.g. `logging.captureWarnings(True)` after importing the client, or
+      `warnings.catch_warnings(record=True)`): they go where it sent them
 
     Takes effect immediately; as a context manager, the previous state is
     restored on exit:
@@ -821,15 +938,19 @@ def quiet(enabled: bool = True) -> _QuietContext:
     quiet()  # for the rest of the process
     with quiet():  # only within the block
         ...
+    with quiet(deprecations=True):  # also hide the client's deprecation warnings
+        ...
     ```
 
     Args:
         enabled (bool) : True to silence the client, False to restore output.
+        deprecations (bool) : also silence the client's deprecation warnings.
+            Only applies when `enabled` is True.
 
     Returns:
         a context manager that restores the previous state on exit
     """
-    return _QuietContext(_set_quiet(enabled))
+    return _QuietContext(_set_quiet(enabled, deprecations))
 
 
 def is_quiet() -> bool:
@@ -850,13 +971,50 @@ def mp_warning(message: str, stacklevel: int = 1) -> None:
         return
     from mp_api.client.core.exceptions import MPRestWarning
 
-    warnings.warn(message, MPRestWarning, stacklevel=stacklevel + 1)
+    _warn(message, MPRestWarning, stacklevel + 1)
+
+
+def mp_advice(message: str, category: type[Warning], stacklevel: int = 1) -> None:
+    """Like `mp_warning`, with another warning class, e.g. `MPDatasetIndexingWarning`.
+
+    Args:
+        message (str) : warning text
+        category (type[Warning]) : warning class
+        stacklevel (int) : as for `warnings.warn`, relative to the caller
+    """
+    if _QUIET.enabled:
+        return
+    _warn(message, category, stacklevel + 1)
+
+
+def mp_deprecation(message: str, stacklevel: int = 1) -> None:
+    """Emit a deprecation warning (`FutureWarning`) for the client's own API.
+
+    Shown by default; silenced by `quiet(deprecations=True)` or
+    `MPRESTER_QUIET_DEPRECATIONS`.
+
+    Args:
+        message (str) : warning text
+        stacklevel (int) : as for `warnings.warn`, relative to the caller
+    """
+    if _QUIET.deprecations:
+        return
+    _warn(message, FutureWarning, stacklevel + 1)
+
+
+def _warn(message: str, category: type[Warning], stacklevel: int) -> None:
+    """Warn as if from `_warn`'s caller, not counting public method wrappers."""
+    from mp_api.client.core._external import warn
+
+    warn(message, category, stacklevel + 1)
 
 
 def _configure_from_settings() -> None:
     """Configure client output from settings, on import of `mp_api.client`."""
+    from mp_api.client.core._external import install
     from mp_api.client.core.settings import MAPI_CLIENT_SETTINGS
 
+    install()
     enable_logging()
     if MAPI_CLIENT_SETTINGS.QUIET:
-        quiet(True)
+        quiet(True, deprecations=MAPI_CLIENT_SETTINGS.QUIET_DEPRECATIONS)

{mp_api-0.47.0rc0 → mp_api-0.47.1}/mp_api/client/core/_entries.py

@@ -33,11 +33,27 @@ if TYPE_CHECKING:
     from collections.abc import Callable, Iterator, Sequence
     from typing import Any
 
+    from pymatgen.analysis.compatibility.mixing_scheme import (
+        MaterialsProjectDFTMixingScheme,
+    )
     from pymatgen.entries.compatibility import Compatibility
 
     from mp_api.client.core._display import ProgressHandle
 
 
+def mixing_scheme_class() -> type[MaterialsProjectDFTMixingScheme]:
+    """The `MaterialsProjectDFTMixingScheme` class, wherever this pymatgen keeps it.
+
+    Newer pymatgen moved it to `pymatgen.analysis.compatibility.mixing_scheme`
+    and deprecated the old module.
+    """
+    try:
+        from pymatgen.analysis.compatibility import mixing_scheme
+    except ImportError:  # pragma: no cover - older pymatgen
+        from pymatgen.entries import mixing_scheme  # type: ignore[no-redef]
+    return mixing_scheme.MaterialsProjectDFTMixingScheme
+
+
 def _advance(handle: ProgressHandle, amount: float) -> None:
     """Advance `handle` by `amount`, without going past its total."""
     if handle.total is not None:
@@ -173,7 +189,8 @@ def apply_corrections(
         enabled (bool) : whether to show progress
     """
     from pymatgen.entries.compatibility import MaterialsProjectAqueousCompatibility
-    from pymatgen.entries.mixing_scheme import MaterialsProjectDFTMixingScheme
+
+    mixing_scheme = mixing_scheme_class()
 
     n = len(entries)
     corrector = _private_copy(corrector)
@@ -183,7 +200,7 @@ def apply_corrections(
         ) as handle,
         ExitStack() as stack,
     ):
-        if isinstance(corrector, MaterialsProjectDFTMixingScheme):
+        if isinstance(corrector, mixing_scheme):
             # passes: compat_1 corrections (run type 1 entries), structure
             # matching (all entries), then the mixing adjustments (all entries)
             n_1 = sum(