Namespace package, material_ids parameters (#659)

* Add client as namespace package to mp_api

* Fix tests

* Move test

* Fix tests

* Add mpid list query params

* Fix tests

* Add custom test cases

* Re-commit github workflows

* Fix linting

* Remove blank line

* Move tests back to root dir

* Change route imports

* Fix mypy linting

* Fix tests

* Ignore mpcontribs tests

.github/dependabot.yml

@@ -6,4 +6,4 @@ updates:
     interval: weekly
     time: '08:00'
     timezone: US/Pacific
-  open-pull-requests-limit: 10
+  open-pull-requests-limit: 10

.github/workflows/testing.yml

@@ -30,19 +30,19 @@ jobs:
       - name: Lint with pycodestyle
         run: |
           pip install pycodestyle
-          pycodestyle src/mp_api
+          pycodestyle mp_api
 
       - name: Lint with mypy
         run: |
-          mypy src/mp_api
+          mypy --namespace-packages --explicit-package-bases mp_api
 
       - name: Lint with flake8
         run: |
           pip install flake8
           # stop the build if there are Python syntax errors or undefined names
-          flake8 --count --show-source --statistics src/mp_api
+          flake8 --count --show-source --statistics mp_api
           # exit-zero treats all errors as warnings.
-          flake8 --count --exit-zero --max-complexity=20 --statistics src/mp_api
+          flake8 --count --exit-zero --max-complexity=20 --statistics mp_api
 
   test:
     strategy:
@@ -97,4 +97,4 @@ jobs:
     steps:
       - uses: rymndhng/release-on-push-action@v0.20.0
         with:
-          bump_version_scheme: norelease
+          bump_version_scheme: norelease

src/mp_api/__init__.py → mp_api/client/__init__.py

@@ -2,7 +2,7 @@
 """ Primary MAPI module """
 import os
 from pkg_resources import get_distribution, DistributionNotFound
-from mp_api.client import MPRester
+from .client import MPRester
 
 try:  # pragma: no cover
     from setuptools_scm import get_version

src/mp_api/client.py → mp_api/client/client.py

@@ -23,8 +23,8 @@
 from requests import get
 from typing_extensions import Literal
 
-from mp_api.core.client import BaseRester, MPRestError
-from mp_api.routes import *
+from mp_api.client.core import BaseRester, MPRestError
+from mp_api.client.routes import *
 
 _DEPRECATION_WARNING = (
     "MPRester is being modernized. Please use the new method suggested and "
@@ -421,9 +421,7 @@ def find_structure(
         )
 
     def get_entries(
-        self,
-        chemsys_formula: Union[str, List[str]],
-        sort_by_e_above_hull=False,
+        self, chemsys_formula: Union[str, List[str]], sort_by_e_above_hull=False,
     ):
         """
         Get a list of ComputedEntries or ComputedStructureEntries corresponding
@@ -786,9 +784,7 @@ def get_entry_by_material_id(self, material_id: str):
         )
 
     def get_entries_in_chemsys(
-        self,
-        elements: Union[str, List[str]],
-        use_gibbs: Optional[int] = None,
+        self, elements: Union[str, List[str]], use_gibbs: Optional[int] = None,
     ):
         """
         Helper method to get a list of ComputedEntries in a chemical system.

mp_api/client/core/__init__.py

@@ -0,0 +1,2 @@
+from .client import BaseRester, MPRestError
+from .settings import MAPIClientSettings

src/mp_api/core/client.py → mp_api/client/core/client.py

@@ -24,9 +24,9 @@
 from maggma.api.utils import api_sanitize
 from matplotlib import use
 from monty.json import MontyDecoder
-from mp_api.core.settings import MAPIClientSettings
+from mp_api.client.core.settings import MAPIClientSettings
 from pydantic import BaseModel, create_model
-from mp_api.core.utils import validate_ids
+from mp_api.client.core.utils import validate_ids
 from requests.adapters import HTTPAdapter
 from requests.exceptions import RequestException
 from tqdm.auto import tqdm
@@ -857,7 +857,7 @@ def get_data_by_id(
             if self.primary_key == "material_id":
                 # see if the material_id has changed, perhaps a task_id was supplied
                 # this should likely be re-thought
-                from mp_api import MPRester
+                from mp_api.client import MPRester
 
                 with MPRester(api_key=self.api_key, endpoint=self.base_endpoint) as mpr:
                     new_document_id = mpr.get_materials_id_from_task_id(document_id)

src/mp_api/core/settings.py → mp_api/client/core/settings.py

@@ -1,5 +1,5 @@
 from pydantic import BaseSettings, Field
-from mp_api import __file__ as root_dir
+from mp_api.client import __file__ as root_dir
 from typing import List
 import os
 

src/mp_api/matproj.py → mp_api/client/matproj.py

@@ -5,5 +5,5 @@
 from warnings import warn
 
 warn(
-    "The MPRester class has been moved. You can now use `from mp_api import MPRester`."
+    "The MPRester class has been moved. You can now use `from mp_api.client import MPRester`."
 )

mp_api/client/routes/__init__.py

@@ -0,0 +1,33 @@
+from .eos import EOSRester
+from .materials import MaterialsRester
+from .similarity import SimilarityRester
+from .tasks import TaskRester
+from .xas import XASRester
+from .fermi import FermiRester
+from .grain_boundary import GrainBoundaryRester
+from .substrates import SubstratesRester
+from .surface_properties import SurfacePropertiesRester
+from .phonon import PhononRester
+from .elasticity import ElasticityRester
+from .thermo import ThermoRester
+from .dielectric import DielectricRester
+from .doi import DOIRester
+from .piezo import PiezoRester
+from .magnetism import MagnetismRester
+from .summary import SummaryRester
+from .robocrys import RobocrysRester
+from .molecules import MoleculesRester
+from .synthesis import SynthesisRester
+from .electrodes import ElectrodeRester
+from .charge_density import ChargeDensityRester
+from .electronic_structure import (
+    ElectronicStructureRester,
+    BandStructureRester,
+    DosRester,
+)
+from .oxidation_states import OxidationStatesRester
+from .provenance import ProvenanceRester
+from ._user_settings import UserSettingsRester
+from ._general_store import GeneralStoreRester
+from .bonds import BondsRester
+from .alloys import AlloysRester

src/mp_api/routes/_general_store.py → mp_api/client/routes/_general_store.py

@@ -1,6 +1,6 @@
 from typing import Dict
 
-from mp_api.core.client import BaseRester
+from mp_api.client.core import BaseRester
 from emmet.core._general_store import GeneralStoreDoc
 
 

src/mp_api/routes/_user_settings.py → mp_api/client/routes/_user_settings.py

@@ -1,5 +1,5 @@
 from emmet.core._user_settings import UserSettingsDoc
-from mp_api.core.client import BaseRester
+from mp_api.client.core import BaseRester
 
 
 class UserSettingsRester(BaseRester[UserSettingsDoc]):  # pragma: no cover

src/mp_api/routes/alloys.py → mp_api/client/routes/alloys.py

@@ -1,7 +1,8 @@
-from typing import List, Optional, Tuple
+from typing import List, Optional, Union
 from collections import defaultdict
 
-from mp_api.core.client import BaseRester
+from mp_api.client.core import BaseRester
+from mp_api.client.core.utils import validate_ids
 from emmet.core.alloys import AlloyPairDoc
 
 import warnings
@@ -15,7 +16,7 @@ class AlloysRester(BaseRester[AlloyPairDoc]):
 
     def search(
         self,
-        material_ids: Optional[List[str]] = None,
+        material_ids: Optional[Union[str, List[str]]] = None,
         formulae: Optional[List[str]] = None,
         sort_fields: Optional[List[str]] = None,
         num_chunks: Optional[int] = None,
@@ -32,7 +33,7 @@ def search(
         endpoint is useful.
 
         Arguments:
-            material_ids (List[str]): Search for alloys containing the specified Material IDs
+            material_ids (str, List[str]): Search for alloys containing the specified Material IDs
             formulae (List[str]): Search for alloys containing the specified formulae
             sort_fields (List[str]): Fields used to sort results. Prefix with '-' to sort in descending order.
             num_chunks (int): Maximum number of chunks of data to yield. None will yield all possible.
@@ -52,8 +53,13 @@ def search(
             if query_params[entry] is not None
         }
 
+        if material_ids:
+            if isinstance(material_ids, str):
+                material_ids = [material_ids]
+
+            query_params.update({"material_ids": ",".join(validate_ids(material_ids))})
+
         return super()._search(
-            material_ids=material_ids,
             formulae=formulae,
             num_chunks=num_chunks,
             chunk_size=chunk_size,

src/mp_api/routes/bonds.py → mp_api/client/routes/bonds.py

@@ -1,7 +1,8 @@
-from typing import List, Optional, Tuple
+from typing import List, Optional, Tuple, Union
 from collections import defaultdict
 
-from mp_api.core.client import BaseRester
+from mp_api.client.core import BaseRester
+from mp_api.client.core.utils import validate_ids
 from emmet.core.bonds import BondingDoc
 
 import warnings
@@ -28,6 +29,7 @@ def search_bonds_docs(self, *args, **kwargs):  # pragma: no cover
 
     def search(
         self,
+        material_ids: Optional[Union[str, List[str]]] = None,
         coordination_envs: Optional[List[str]] = None,
         coordination_envs_anonymous: Optional[List[str]] = None,
         max_bond_length: Optional[Tuple[float, float]] = None,
@@ -43,6 +45,7 @@ def search(
         Query bonding docs using a variety of search criteria.
 
         Arguments:
+            material_ids (str, List[str]): Search for bonding data for the specified Material IDs
             coordination_envs (List[str]): List of coordination environments to consider (e.g. ['Mo-S(6)', 'S-Mo(3)']).
             coordination_envs_anonymous (List[str]): List of anonymous coordination environments to consider
                  (e.g. ['A-B(6)', 'A-B(3)']).
@@ -65,6 +68,12 @@ def search(
 
         query_params = defaultdict(dict)  # type: dict
 
+        if material_ids:
+            if isinstance(material_ids, str):
+                material_ids = [material_ids]
+
+            query_params.update({"material_ids": ",".join(validate_ids(material_ids))})
+
         if max_bond_length:
             query_params.update(
                 {

src/mp_api/routes/charge_density.py → mp_api/client/routes/charge_density.py

@@ -16,7 +16,7 @@
 
 from emmet.core.charge_density import ChgcarDataDoc
 from monty.serialization import MontyDecoder, dumpfn
-from mp_api.core.client import BaseRester
+from mp_api.client.core import BaseRester
 
 
 class ChargeDensityRester(BaseRester[ChgcarDataDoc]):

src/mp_api/routes/dielectric.py → mp_api/client/routes/dielectric.py

@@ -1,8 +1,9 @@
 from collections import defaultdict
-from typing import List, Optional, Tuple
+from typing import List, Optional, Tuple, Union
 
 from emmet.core.polar import DielectricDoc
-from mp_api.core.client import BaseRester
+from mp_api.client.core import BaseRester
+from mp_api.client.core.utils import validate_ids
 
 import warnings
 
@@ -28,6 +29,7 @@ def search_dielectric_docs(self, *args, **kwargs):  # pragma: no cover
 
     def search(
         self,
+        material_ids: Optional[Union[str, List[str]]] = None,
         e_total: Optional[Tuple[float, float]] = None,
         e_ionic: Optional[Tuple[float, float]] = None,
         e_electronic: Optional[Tuple[float, float]] = None,
@@ -42,6 +44,8 @@ def search(
         Query dielectric docs using a variety of search criteria.
 
         Arguments:
+            material_ids (str, List[str]): A single Material ID string or list of strings
+                (e.g., mp-149, [mp-149, mp-13]).
             e_total (Tuple[float,float]): Minimum and maximum total dielectric constant to consider.
             e_ionic (Tuple[float,float]): Minimum and maximum ionic dielectric constant to consider.
             e_electronic (Tuple[float,float]): Minimum and maximum electronic dielectric constant to consider.
@@ -59,6 +63,12 @@ def search(
 
         query_params = defaultdict(dict)  # type: dict
 
+        if material_ids:
+            if isinstance(material_ids, str):
+                material_ids = [material_ids]
+
+            query_params.update({"material_ids": ",".join(validate_ids(material_ids))})
+
         if e_total:
             query_params.update({"e_total_min": e_total[0], "e_total_max": e_total[1]})
 

src/mp_api/routes/doi.py → mp_api/client/routes/doi.py

@@ -1,4 +1,4 @@
-from mp_api.core.client import BaseRester
+from mp_api.client.core import BaseRester
 from emmet.core.dois import DOIDoc
 
 

src/mp_api/routes/elasticity.py → mp_api/client/routes/elasticity.py

@@ -2,7 +2,7 @@
 from typing import List, Optional, Tuple
 
 from emmet.core.elasticity_legacy import ElasticityDoc
-from mp_api.core.client import BaseRester
+from mp_api.client.core import BaseRester
 
 import warnings
 

src/mp_api/routes/electrodes.py → mp_api/client/routes/electrodes.py

@@ -1,10 +1,11 @@
-from pymatgen.core.periodic_table import Element
-from mp_api.core.client import BaseRester
-from emmet.core.electrode import InsertionElectrodeDoc
-from typing import Optional, Tuple, List, Union
+import warnings
 from collections import defaultdict
+from typing import List, Optional, Tuple, Union
 
-import warnings
+from emmet.core.electrode import InsertionElectrodeDoc
+from mp_api.client.core import BaseRester
+from mp_api.client.core.utils import validate_ids
+from pymatgen.core.periodic_table import Element
 
 
 class ElectrodeRester(BaseRester[InsertionElectrodeDoc]):
@@ -28,6 +29,8 @@ def search_electrode_docs(self, *args, **kwargs):  # pragma: no cover
 
     def search(  # pragma: ignore
         self,
+        material_ids: Optional[Union[str, List[str]]] = None,
+        battery_ids: Optional[Union[str, List[str]]] = None,
         average_voltage: Optional[Tuple[float, float]] = None,
         capacity_grav: Optional[Tuple[float, float]] = None,
         capacity_vol: Optional[Tuple[float, float]] = None,
@@ -55,6 +58,10 @@ def search(  # pragma: ignore
         Query equations of state docs using a variety of search criteria.
 
         Arguments:
+            material_ids (str, List[str]): A single Material ID string or list of strings
+                (e.g., mp-149, [mp-149, mp-13]).
+            battery_ids (str, List[str]): A single battery ID string or list of strings
+                (e.g., mp-22526_Li, [mp-22526_Li, mp-22526_Ca]).
             average_voltage (Tuple[float,float]): Minimum and maximum value of the average voltage for a particular
                 voltage step in V.
             capacity_grav (Tuple[float,float]): Minimum and maximum value of the gravimetric capacity in maH/g.
@@ -94,6 +101,18 @@ def search(  # pragma: ignore
         """
         query_params = defaultdict(dict)  # type: dict
 
+        if material_ids:
+            if isinstance(material_ids, str):
+                material_ids = [material_ids]
+
+            query_params.update({"material_ids": ",".join(validate_ids(material_ids))})
+
+        if battery_ids:
+            if isinstance(battery_ids, str):
+                battery_ids = [battery_ids]
+
+            query_params.update({"battery_ids": ",".join(validate_ids(battery_ids))})
+
         if working_ion:
             if isinstance(working_ion, str) or isinstance(working_ion, Element):
                 working_ion = [working_ion]  # type: ignore