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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mp-api
-Version: 0.47.1
+Version: 0.47.2rc0
 Summary: API Client for the Materials Project
 Author-email: The Materials Project <feedback@materialsproject.org>
 License-Expression: BSD-3-Clause-LBNL

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

@@ -89,6 +89,10 @@ Which channel to use
   unreachable, data missing, a local dataset reused): `logger.warning/info`.
 - Diagnostics: `logger.debug`.
 - Transient progress: `progress_bar` / `status`, interactive output only.
+  Bars and summary lines report work the caller asked for: lookups the client
+  makes on its own behalf (resolving IDs, then fetching the data) run inside a
+  `status()`, which describes the whole operation and keeps the bars inside it
+  from drawing or printing anything.
 - Output the user explicitly asked for (`notify_db_version`): `print_notice`.
 
 So WARNING-level log records always mean something went wrong, and
@@ -119,6 +123,7 @@ Python shows a given warning once per code location; use
 
 from __future__ import annotations
 
+import contextvars
 import io
 import logging
 import threading
@@ -446,6 +451,13 @@ class ProgressHandle:
         self._progress.advance(self._task_id, advance)
 
 
+# Whether a `status()` block is running in this context. Contextvars are copied
+# into worker threads by `_external.in_current_context`, so those inherit it.
+_IN_OPERATION: contextvars.ContextVar[bool] = contextvars.ContextVar(
+    "mp_api_client_in_operation", default=False
+)
+
+
 def _as_int(value: float | None) -> float | None:
     """Show (near) whole-number counts as ints, without a trailing `.0`."""
     if isinstance(value, float) and abs(value - round(value)) < 1e-6:
@@ -469,7 +481,9 @@ def progress_bar(
     Args:
         description (str) : label shown next to the bar
         total (float or None) : expected number of units, None if unknown
-        enabled (bool) : if False, nothing is shown (a no-op handle is yielded)
+        enabled (bool) : if False, nothing is shown (a no-op handle is yielded).
+            Nothing is shown either inside a `status()` block, which describes
+            the whole operation itself.
         delay (float) : seconds before the bar is shown, so quick
             operations stay silent. Checked on each update.
         unit (str) : unit name for the rate column
@@ -487,7 +501,7 @@ def progress_bar(
         ProgressHandle
     """
     console = get_console()
-    if not enabled or is_quiet():
+    if not enabled or is_quiet() or _IN_OPERATION.get():
         yield ProgressHandle(total, summary=summary)
         return
     if not _is_interactive(console):
@@ -705,25 +719,41 @@ def status(message: str, *, enabled: bool = True) -> Iterator[None]:
     of WARNING-level logs). If disabled (muted progress bars) or in quiet mode,
     nothing is shown or logged.
 
+    The status describes the whole operation the caller asked for, so
+    everything inside it stays quiet:
+
+    - `progress_bar`s inside the block draw nothing, print no summary line and
+      log nothing (e.g. the lookup of a material's IDs the client makes on
+      its own behalf);
+    - a `status` nested in another one shows and logs nothing.
+
+    Work with countable progress that the caller should watch (a multi-page
+    download) needs a `progress_bar` instead of a `status`.
+
     Args:
         message (str) : what is happening, e.g. "Counting documents..."
         enabled (bool) : if False, show nothing
     """
     console = get_console()
-    if not enabled or is_quiet():
-        yield
-        return
-    if not (_is_interactive(console) and _can_draw_live(console)):
-        logging.getLogger(LOGGER_NAME).info(message)
+    if not enabled or is_quiet() or _IN_OPERATION.get():
         yield
         return
 
-    progress = _STATE.acquire(console)
-    task_id = progress.add_task(message, total=None, status=True)
+    token = _IN_OPERATION.set(True)
     try:
-        yield
+        if not (_is_interactive(console) and _can_draw_live(console)):
+            logging.getLogger(LOGGER_NAME).info(message)
+            yield
+            return
+
+        progress = _STATE.acquire(console)
+        task_id = progress.add_task(message, total=None, status=True)
+        try:
+            yield
+        finally:
+            _STATE.release(task_id)
     finally:
-        _STATE.release(task_id)
+        _IN_OPERATION.reset(token)
 
 
 def _app_handlers(logger: logging.Logger) -> list[logging.Handler]:

{mp_api-0.47.1 → mp_api-0.47.2rc0}/mp_api/client/core/_external.py

@@ -154,6 +154,8 @@ def _tracked(fn: Callable[..., Any]) -> Callable[..., Any]:
 
     @functools.wraps(fn)
     def wrapper(*args: Any, **kwargs: Any) -> Any:
+        # keep this frame out of tracebacks in IPython, Jupyter and pytest
+        __tracebackhide__ = True
         with capturing():
             return fn(*args, **kwargs)
 

{mp_api-0.47.1 → mp_api-0.47.2rc0}/mp_api/client/mprester.py

@@ -74,6 +74,7 @@ if TYPE_CHECKING:
     from typing import Any, Literal
 
     import numpy as np
+    from emmet.core.phonon import PhononBS, PhononDOS
     from emmet.core.tasks import CoreTaskDoc
     from packaging.version import Version
     from pymatgen.analysis.phase_diagram import PDEntry
@@ -1514,31 +1515,52 @@ class MPRester(_Rester):
             load_projections=load_projections,
         )
 
-    def get_phonon_dos_by_material_id(self, material_id: str):
+    def get_phonon_dos_by_material_id(
+        self,
+        material_id: str,
+        phonon_method: Literal["pheasy", "dfpt"] | None = None,
+    ) -> PhononDOS | dict[str, Any]:
         """Get phonon density of states data corresponding to a material_id.
 
         Args:
             material_id (str): Materials Project material_id.
+            phonon_method (str or None): phonon method, i.e. pheasy or dfpt. By default,
+                the method is chosen from the material's data: pheasy if it has it,
+                otherwise dfpt. If the pheasy calculation has no DOS, the dfpt one
+                is used (with a warning). A method passed explicitly is never replaced.
 
         Returns:
-             CompletePhononDos: A phonon DOS object.
-
+            dos (PhononDOS): PhononDOS object
         """
         return self.materials.phonon.get_dos_from_material_id(
-            material_id=material_id, phonon_method="dfpt"
+            material_id=material_id, phonon_method=phonon_method
         )
 
-    def get_phonon_bandstructure_by_material_id(self, material_id: str):
+    def get_phonon_bandstructure_by_material_id(
+        self,
+        material_id: str,
+        phonon_method: Literal["pheasy", "dfpt"] | None = None,
+        path_type: str | BSPathType = BSPathType.setyawan_curtarolo,
+    ) -> PhononBS | dict[str, Any]:
         """Get phonon dispersion data corresponding to a material_id.
 
         Args:
             material_id (str): Materials Project material_id.
+            phonon_method (str or None): phonon method, i.e. pheasy or dfpt. By default,
+                the method is chosen from the material's data: pheasy if it has it,
+                otherwise dfpt. If the pheasy calculation has no band structure,
+                the dfpt one is used (with a warning). A method passed explicitly
+                is never replaced.
+            path_type (BSPathType or str): k-path selection convention for the band structure.
+                pheasy has all conventions; dfpt only has setyawan_curtarolo.
 
         Returns:
-            PhononBandStructureSymmLine:  phonon band structure.
+            bandstructure (PhononBS): PhononBS object
         """
         return self.materials.phonon.get_bandstructure_from_material_id(
-            material_id=material_id, phonon_method="dfpt"
+            material_id=material_id,
+            phonon_method=phonon_method,
+            path_type=path_type,
         )
 
     def get_wulff_shape(self, material_id: str):
@@ -1796,8 +1818,7 @@ class MPRester(_Rester):
         # Prevent user error
         if isinstance(material_ids, str | MPID):
             raise MPRestError(
-                "Input material IDs (even a single ID) as a list: "
-                f"`[{material_ids}]`"
+                f"Input material IDs (even a single ID) as a list: `[{material_ids}]`"
             )
 
         entry_preference = {

{mp_api-0.47.1 → mp_api-0.47.2rc0}/mp_api/client/routes/materials/electronic_structure.py

@@ -16,7 +16,7 @@ from pymatgen.electronic_structure.bandstructure import (
 from pymatgen.electronic_structure.core import OrbitalType, Spin
 
 from mp_api.client.core import BaseRester, MPRestError
-from mp_api.client.core._display import mp_deprecation
+from mp_api.client.core._display import mp_deprecation, status
 from mp_api.client.core.utils import validate_ids
 
 if TYPE_CHECKING:
@@ -284,48 +284,57 @@ class BandStructureRester(BaseESPropertyRester):
         Returns:
             bandstructure (BandStructure): BandStructure or BandStructureSymmLine object
         """
-        bs_lbl, _ = self._get_delta_table(
-            "materialsproject-parsed",
-            "core/electronic-structure/bandstructures/",
-            label="bandstructure",
-        )
-
-        query = f"""
-            SELECT *
-            FROM   {bs_lbl}
-            WHERE  identifier='{str(AlphaID(task_id.split("-")[-1],padlen=8))}'
-        """
+        with status(
+            f"Fetching the band structure for {task_id}...",
+            enabled=not self.mute_progress_bars,
+        ):
+            bs_lbl, _ = self._get_delta_table(
+                "materialsproject-parsed",
+                "core/electronic-structure/bandstructures/",
+                label="bandstructure",
+            )
 
-        if run_type:
-            rt = RunType(run_type) if isinstance(run_type, str) else run_type
-            query += f"\nAND run_type='{rt.value}'"
-        if path_type:
-            query += f"\nAND path_convention='{path_type}'"
-
-        table = self._query_delta_single(query, label=bs_lbl)
-        if len(deser := table.to_pylist(maps_as_pydicts="strict")) > 0:
-            if load_projections:
-                proj_bs_label, _ = self._get_delta_table(
-                    "materialsproject-parsed",
-                    "core/electronic-structure/projected-bandstructures/",
-                    label="bandstructure_projections",
-                )
-                proj_table = self._query_delta_single(
-                    query.replace(bs_lbl, proj_bs_label), label=proj_bs_label
+            query = f"""
+                SELECT *
+                FROM   {bs_lbl}
+                WHERE  identifier='{str(AlphaID(task_id.split("-")[-1],padlen=8))}'
+            """
+
+            if run_type:
+                rt = RunType(run_type) if isinstance(run_type, str) else run_type
+                query += f"\nAND run_type='{rt.value}'"
+            if path_type:
+                query += f"\nAND path_convention='{path_type}'"
+
+            table = self._query_delta_single(query, label=bs_lbl)
+            if len(deser := table.to_pylist(maps_as_pydicts="strict")) > 0:
+                if load_projections:
+                    proj_bs_label, _ = self._get_delta_table(
+                        "materialsproject-parsed",
+                        "core/electronic-structure/projected-bandstructures/",
+                        label="bandstructure_projections",
+                    )
+                    proj_table = self._query_delta_single(
+                        query.replace(bs_lbl, proj_bs_label), label=proj_bs_label
+                    )
+                    if (
+                        len(
+                            deser_proj := proj_table.to_pylist(maps_as_pydicts="strict")
+                        )
+                        > 0
+                    ):
+                        deser[0]["projections"] = deser_proj[0]
+                emmet_bs = ElectronicBS(**deser[0])
+                return emmet_bs.to_pmg(
+                    pmg_cls=(
+                        BandStructureSymmLine if emmet_bs.labels_dict else BandStructure
+                    )
                 )
-                if (
-                    len(deser_proj := proj_table.to_pylist(maps_as_pydicts="strict"))
-                    > 0
-                ):
-                    deser[0]["projections"] = deser_proj[0]
-            emmet_bs = ElectronicBS(**deser[0])
-            return emmet_bs.to_pmg(
-                pmg_cls=BandStructureSymmLine if emmet_bs.labels_dict else BandStructure
+            raise MPRestError(
+                f"No bandstructure data found for {task_id=}"
+                + (f" and run_type={rt.value}" if run_type else "")
+                + (f" and path_type={path_type}" if path_type else "")
             )
-        raise MPRestError(
-            f"No bandstructure data found for {task_id=}"
-            + (f"run_type={rt}" if run_type else "")
-        )
 
     def get_bandstructure_from_material_id(
         self,
@@ -349,62 +358,73 @@ class BandStructureRester(BaseESPropertyRester):
         pt: BSPathType = (
             BSPathType(path_type) if isinstance(path_type, str) else path_type
         )
-        if line_mode:
-            bs_doc = self.es_rester.search(
-                material_ids=material_id, fields=["bandstructure"]
-            )
-            if not bs_doc:
-                raise MPRestError(
-                    f"No electronic structure data found for material ID {material_id}."
+        kind = f"{pt.value} band structure" if line_mode else "uniform band structure"
+        with status(
+            f"Fetching the {kind} for {material_id}...",
+            enabled=not self.mute_progress_bars,
+        ):
+            if line_mode:
+                bs_doc = self.es_rester.search(
+                    material_ids=material_id, fields=["bandstructure"]
                 )
-
-            if (_bs_data := bs_doc[0]["bandstructure"]) is None:
-                raise MPRestError(
-                    f"No {pt.value} band structure data found for {material_id}"
+                if not bs_doc:
+                    raise MPRestError(
+                        f"No electronic structure data found for material ID {material_id}."
+                    )
+
+                if (_bs_data := bs_doc[0]["bandstructure"]) is None:
+                    raise MPRestError(
+                        f"No {pt.value} band structure data found for {material_id}"
+                    )
+
+                bs_data = (
+                    _bs_data.model_dump() if self.use_document_model else _bs_data  # type: ignore
                 )
 
-            bs_data = (
-                _bs_data.model_dump() if self.use_document_model else _bs_data  # type: ignore
+                if bs_data.get(pt.value, None) is None:
+                    available = sorted(k for k, v in bs_data.items() if v is not None)
+                    raise MPRestError(
+                        f"No {pt.value} band structure data found for {material_id}"
+                        + (
+                            f" (available: {', '.join(available)})."
+                            if available
+                            else "."
+                        )
+                    )
+                bs_task_id = bs_data[pt.value]["task_id"]
+
+            else:
+                if not (
+                    bs_doc := self.es_rester.search(
+                        material_ids=material_id, fields=["dos"]
+                    )
+                ):
+                    raise MPRestError(
+                        f"No electronic structure data found for material ID {material_id}."
+                    )
+
+                if (_bs_data := bs_doc[0]["dos"]) is None:
+                    raise MPRestError(
+                        f"No uniform band structure data found for {material_id}"
+                    )
+
+                bs_data = _bs_data.model_dump() if self.use_document_model else _bs_data
+
+                if bs_data.get("total", None) is None:
+                    raise MPRestError(
+                        f"No uniform band structure data found for {material_id}"
+                    )
+                bs_task_id = bs_data["task_id"]
+
+            bs_obj = self.get_bandstructure_from_task_id(
+                bs_task_id,
+                path_type=pt if line_mode else BSPathType.unknown,
+                load_projections=load_projections,
             )
 
-            if bs_data.get(pt.value, None) is None:
-                raise MPRestError(
-                    f"No {pt.value} band structure data found for {material_id}"
-                )
-            bs_task_id = bs_data[pt.value]["task_id"]
-
-        else:
-            if not (
-                bs_doc := self.es_rester.search(
-                    material_ids=material_id, fields=["dos"]
-                )
-            ):
-                raise MPRestError(
-                    f"No electronic structure data found for material ID {material_id}."
-                )
-
-            if (_bs_data := bs_doc[0]["dos"]) is None:
-                raise MPRestError(
-                    f"No uniform band structure data found for {material_id}"
-                )
-
-            bs_data = _bs_data.model_dump() if self.use_document_model else _bs_data
-
-            if bs_data.get("total", None) is None:
-                raise MPRestError(
-                    f"No uniform band structure data found for {material_id}"
-                )
-            bs_task_id = bs_data["task_id"]
-
-        bs_obj = self.get_bandstructure_from_task_id(
-            bs_task_id,
-            path_type=pt if line_mode else BSPathType.unknown,
-            load_projections=load_projections,
-        )
-
-        if bs_obj:
-            return bs_obj
-        raise MPRestError("No band structure object found.")
+            if bs_obj:
+                return bs_obj
+            raise MPRestError("No band structure object found.")
 
 
 class DosRester(BaseESPropertyRester):
@@ -540,42 +560,49 @@ class DosRester(BaseESPropertyRester):
         Returns:
             pymatgen Dos
         """
-        dos_lbl, _ = self._get_delta_table(
-            "materialsproject-parsed",
-            "core/electronic-structure/total-dos/",
-            label="total_dos",
-        )
-
-        query = f"""
-            SELECT *
-            FROM   {dos_lbl}
-            WHERE  identifier='{str(AlphaID(task_id.split("-")[-1],padlen=8))}'
-        """
+        with status(
+            f"Fetching the density of states for {task_id}...",
+            enabled=not self.mute_progress_bars,
+        ):
+            dos_lbl, _ = self._get_delta_table(
+                "materialsproject-parsed",
+                "core/electronic-structure/total-dos/",
+                label="total_dos",
+            )
 
-        if run_type:
-            rt = RunType(run_type) if isinstance(run_type, str) else run_type
-            query += f"\nAND run_type='{rt.value}'"
-
-        table = self._query_delta_single(query, label=dos_lbl)
-        if len(deser := table.to_pylist(maps_as_pydicts="strict")) > 0:
-            if load_projections:
-                proj_dos_label, _ = self._get_delta_table(
-                    "materialsproject-parsed",
-                    "core/electronic-structure/projected-dos/",
-                    label="dos_projections",
-                )
-                proj_table = self._query_delta_single(
-                    query.replace(dos_lbl, proj_dos_label), label=proj_dos_label
-                )
-                if (
-                    len(deser_proj := proj_table.to_pylist(maps_as_pydicts="strict"))
-                    > 0
-                ):
-                    deser[0]["projected_densities"] = deser_proj[0]
-            return ElectronicDos(**deser[0]).to_pmg()
-        raise MPRestError(
-            f"No DOS data found for {task_id=}" + (f"run_type={rt}" if run_type else "")
-        )
+            query = f"""
+                SELECT *
+                FROM   {dos_lbl}
+                WHERE  identifier='{str(AlphaID(task_id.split("-")[-1],padlen=8))}'
+            """
+
+            if run_type:
+                rt = RunType(run_type) if isinstance(run_type, str) else run_type
+                query += f"\nAND run_type='{rt.value}'"
+
+            table = self._query_delta_single(query, label=dos_lbl)
+            if len(deser := table.to_pylist(maps_as_pydicts="strict")) > 0:
+                if load_projections:
+                    proj_dos_label, _ = self._get_delta_table(
+                        "materialsproject-parsed",
+                        "core/electronic-structure/projected-dos/",
+                        label="dos_projections",
+                    )
+                    proj_table = self._query_delta_single(
+                        query.replace(dos_lbl, proj_dos_label), label=proj_dos_label
+                    )
+                    if (
+                        len(
+                            deser_proj := proj_table.to_pylist(maps_as_pydicts="strict")
+                        )
+                        > 0
+                    ):
+                        deser[0]["projected_densities"] = deser_proj[0]
+                return ElectronicDos(**deser[0]).to_pmg()
+            raise MPRestError(
+                f"No DOS data found for {task_id=}"
+                + (f" and run_type={rt.value}" if run_type else "")
+            )
 
     def get_dos_from_material_id(
         self, material_id: str, load_projections: bool = False
@@ -590,17 +617,25 @@ class DosRester(BaseESPropertyRester):
         Returns:
             pymatgen Dos
         """
-        if not (
-            dos_doc := self.es_rester.search(material_ids=material_id, fields=["dos"])
+        with status(
+            f"Fetching the density of states for {material_id}...",
+            enabled=not self.mute_progress_bars,
         ):
-            raise MPRestError(
-                f"No electronic structure data found for material ID {material_id}."
-            )
+            if not (
+                dos_doc := self.es_rester.search(
+                    material_ids=material_id, fields=["dos"]
+                )
+            ):
+                raise MPRestError(
+                    f"No electronic structure data found for material ID {material_id}."
+                )
 
-        if not (dos_data := dos_doc[0].get("dos")):
-            raise MPRestError(f"No density of states data found for {material_id}")
+            if not (dos_data := dos_doc[0].get("dos")):
+                raise MPRestError(f"No density of states data found for {material_id}")
 
-        dos_task_id = (dos_data.model_dump() if self.use_document_model else dos_data)[
-            "task_id"
-        ]
-        return self.get_dos_from_task_id(dos_task_id, load_projections=load_projections)
+            dos_task_id = (
+                dos_data.model_dump() if self.use_document_model else dos_data
+            )["task_id"]
+            return self.get_dos_from_task_id(
+                dos_task_id, load_projections=load_projections
+            )