prisma-api 0.3.6__tar.gz → 0.3.8__tar.gz

{prisma_api-0.3.6 → prisma_api-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prisma_api
-Version: 0.3.6
+Version: 0.3.8
 Summary: A package for interacting with PrISMa Platform APIs. PrISMa is a holistic system for numerical synthesis and assessment of Metal-Organic Frameworks and their applications, for Direct Air Capture of CO2. For more information, see: https://prisma.hw.ac.uk.
 Author-email: RCCS-CaptureTeam <team@prisma-platform.org>
 License: GNUv3
@@ -20,8 +20,7 @@ Dynamic: license-file
 
 # PrISMa API
 
-![Tests](https://img.shields.io/badge/tests-passing-brightgreen)
-![Coverage](https://img.shields.io/badge/test%20coverage-passing-brightgreen)
+[![CI](https://github.com/RCCS-CaptureTeam/prisma_api/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/RCCS-CaptureTeam/prisma_api/actions/workflows/ci.yml)
 
 Python client for the PrISMa platform APIs.
 
@@ -195,10 +194,11 @@ All methods below are available on `api.v2`.
 ### Materials and bundles
 
 - `list_materials(name=None, limit=10000)`
-- `get_material(material_id)`
+- `get_material(material_id=None, name=None, bundle=['isotherms','zeopp','water_kpis','cif'])` (`bundle=None` returns root-only material detail)
 - `get_materials_psdi(name=None, limit=500, offset=0)`
 - `get_material_psdi(material_id)`
 - `get_material_property_bundle(mof, sim_or_exp=None, good_structure=None, limit=500, offset=0, query=None)`
+- `get_material_bundle(mof, sim_or_exp=None, good_structure=None, limit=500, offset=0, query=None, include_cif=False, include_cif_text=False, cif_timeout=60)`
 - `preflight_material_check(name)`
 
 ### Case bundles and pack builders

{prisma_api-0.3.6 → prisma_api-0.3.8}/README.md

@@ -1,7 +1,6 @@
 # PrISMa API
 
-![Tests](https://img.shields.io/badge/tests-passing-brightgreen)
-![Coverage](https://img.shields.io/badge/test%20coverage-passing-brightgreen)
+[![CI](https://github.com/RCCS-CaptureTeam/prisma_api/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/RCCS-CaptureTeam/prisma_api/actions/workflows/ci.yml)
 
 Python client for the PrISMa platform APIs.
 
@@ -175,10 +174,11 @@ All methods below are available on `api.v2`.
 ### Materials and bundles
 
 - `list_materials(name=None, limit=10000)`
-- `get_material(material_id)`
+- `get_material(material_id=None, name=None, bundle=['isotherms','zeopp','water_kpis','cif'])` (`bundle=None` returns root-only material detail)
 - `get_materials_psdi(name=None, limit=500, offset=0)`
 - `get_material_psdi(material_id)`
 - `get_material_property_bundle(mof, sim_or_exp=None, good_structure=None, limit=500, offset=0, query=None)`
+- `get_material_bundle(mof, sim_or_exp=None, good_structure=None, limit=500, offset=0, query=None, include_cif=False, include_cif_text=False, cif_timeout=60)`
 - `preflight_material_check(name)`
 
 ### Case bundles and pack builders

{prisma_api-0.3.6 → prisma_api-0.3.8}/prisma_api/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.3.6"
+__version__ = "0.3.8"
 
 
 from prisma_api.prisma_api import prisma_api as init        # Main prisma_api class for initialisation

{prisma_api-0.3.6 → prisma_api-0.3.8}/prisma_api/prisma_api_v2.py

@@ -19,10 +19,13 @@ from __future__ import annotations
 import pandas as pd
 import requests
 from typing import Any
+from pathlib import Path
 from urllib.parse import urlencode
+import warnings
 
 
 _BASE_PROD = "https://prisma-platform.org/api/v2"
+_DEFAULT_BUNDLE = object()
 
 
 class PrismaAPIv2:
@@ -119,6 +122,25 @@ class PrismaAPIv2:
             d = {**d, "cif_url": f"{base}{d['cif_url']}"}
         return d
 
+    def _parse_cif_text(self, cif_text: str) -> dict[str, Any]:
+        """Parse CIF text into a compact structured dict for notebook-friendly use."""
+        lines = cif_text.splitlines()
+        fields: dict[str, str] = {}
+        for line in lines:
+            s = line.strip()
+            if not s or not s.startswith("_") or " " not in s:
+                continue
+            key, value = s.split(None, 1)
+            fields[key] = value.strip()
+
+        return {
+            "line_count": len(lines),
+            "field_count": len(fields),
+            "fields": fields,
+            "preview": lines[:20],
+            "raw": cif_text,
+        }
+
     # ── Health ────────────────────────────────────────────────────────────────
 
     def health(self) -> dict:
@@ -144,7 +166,7 @@ class PrismaAPIv2:
     def upsert_flowsheets(
         self,
         flowsheets: pd.DataFrame | list[dict],
-        screening_analysis_name: str,
+        screening_analysis_name: str | None = None,
         on_exists: str = "append",
         appendix: str = "_v4",
     ) -> dict:
@@ -157,8 +179,10 @@ class PrismaAPIv2:
 
         Args:
             flowsheets: DataFrame or list of dict payload records.
-            screening_analysis_name: Required analysis identifier forwarded to the
-                API for upsert attribution/routing.
+            screening_analysis_name: Optional analysis identifier forwarded to the
+                API for upsert attribution/routing. For production uploads this
+                should be set and should match one of the nested screening
+                analysis names returned by ``list_case_studies()``.
             on_exists:  Conflict mode; one of ``'append'`` or ``'overwrite'``.
             appendix:   Suffix used only in append mode (default ``'_v4'``).
 
@@ -167,30 +191,33 @@ class PrismaAPIv2:
         """
         if on_exists not in ("append", "overwrite"):
             raise ValueError("on_exists must be 'append' or 'overwrite'")
-        if not screening_analysis_name or not screening_analysis_name.strip():
-            raise ValueError("screening_analysis_name must be a non-empty string")
 
         records = (
             flowsheets.to_dict(orient="records")
             if isinstance(flowsheets, pd.DataFrame)
             else flowsheets
         )
+        cleaned_screening_name = (screening_analysis_name or "").strip()
 
-        if on_exists == "overwrite":
-            query = urlencode(
-                {
-                    "on_exists": "overwrite",
-                    "screening_analysis_name": screening_analysis_name,
-                }
-            )
+        query_params: dict[str, str] = (
+            {"on_exists": "overwrite"}
+            if on_exists == "overwrite"
+            else {"on_exists": "append", "appendix": appendix}
+        )
+
+        if cleaned_screening_name:
+            query_params["screening_analysis_name"] = cleaned_screening_name
         else:
-            query = urlencode(
-                {
-                    "on_exists": "append",
-                    "appendix": appendix,
-                    "screening_analysis_name": screening_analysis_name,
-                }
+            warnings.warn(
+                "Uploading flowsheets without screening_analysis_name is intended "
+                "for experimentation only and is not recommended for production. "
+                "Provide screening_analysis_name matching one of the nested "
+                "screening analysis names returned by list_case_studies().",
+                UserWarning,
+                stacklevel=2,
             )
+
+        query = urlencode(query_params)
         path = f"/flowsheets/upsert/?{query}"
 
         return self._put(path, records)
@@ -244,13 +271,339 @@ class PrismaAPIv2:
         print(f"{len(all_records)} materials loaded from {server}")
         return self._resolve_cif_url_df(self._to_df({"results": all_records}))
 
-    def get_material(self, material_id: int) -> dict:
+    def list_cifs(self, tag: str | None = None) -> list[str]:
         """
-        GET /api/v2/materials/{material_id}/
+        GET /api/v2/list_cifs/
+
+        Dev-only endpoint (not yet available on the production server).
+
+        Args:
+            tag: Optional tag to filter CIFs by. If omitted, all CIFs are returned.
+
+        Returns:
+            List of MOF names matching ``tag``.
+        """
+        if not self._dev:
+            raise RuntimeError(
+                "list_cifs() is only available on the dev server. "
+                "Initialise with dev=True (e.g. prisma_api.init(local_dev=True))."
+            )
+        response = self._get("/cifs/", _compact(tag=tag))
+        records = response.get("results", response) if isinstance(response, dict) else response
+        records = records or []
+        return [r["mof"] if isinstance(r, dict) else r for r in records]
+
+    def get_cifs(self, mof: str | list[str],
+                 structured: bool = True,
+                 pandas: bool = True,
+                 save_dir: str | None = None) -> dict | list[dict] | requests.Response | list[requests.Response] | str | list[str]:
+        """
+        GET /api/v2/cifs/files/
+
+        Dev-only endpoint (not yet available on the production server).
+
+        Args:
+            mof: One MOF name (str) or list of MOF names.
+            structured: Request structured JSON response from the API.
+                        Defaults to ``True``.
+            pandas: Convert pandas-suitable structured fields to
+                    ``pd.DataFrame`` when ``structured=True``.
+                    Defaults to ``True``.
+            save_dir: Optional directory to save downloaded CIF attachment(s).
+                      Only used when ``structured=False``.
 
-        Returns a dict with material detail including element composition.
+        Returns:
+            If ``structured=True``: nested dict for single MOF or list of nested
+            dicts for multiple MOFs, with null-valued keys removed and tabular
+            list-of-dict sections converted to ``pd.DataFrame``.
+            If ``structured=False``: streamed CIF response(s), or saved path(s)
+            when ``save_dir`` is provided.
+        """
+        if not self._dev:
+            raise RuntimeError(
+                "get_cifs() is only available on the dev server. "
+                "Initialise with dev=True (e.g. prisma_api.init(local_dev=True))."
+            )
+
+        if structured and save_dir is not None:
+            raise ValueError("save_dir is only supported when structured=False.")
+
+        output_dir = Path(save_dir).expanduser() if save_dir is not None else None
+        if output_dir is not None:
+            output_dir.mkdir(parents=True, exist_ok=True)
+
+        # Field-aware conversion keeps nested structures readable while
+        # still promoting genuinely tabular sections to DataFrames.
+        _TABULAR_FIELD_NAMES = {
+            "tags",
+            "elements",
+            "citations",
+            "references",
+            "authors",
+            "atom_site",
+            "atom_sites",
+            "symmetry_operations",
+            "symmetry_equiv_pos",
+            "bonds",
+            "angles",
+            "torsions",
+            "contacts",
+            "void_fractions",
+            "channels",
+            "coordination",
+            "topology",
+        }
+
+        def _is_scalar(value: Any) -> bool:
+            return isinstance(value, (str, int, float, bool)) or value is None
+
+        def _looks_like_tabular_records(records: list[dict]) -> bool:
+            if not records:
+                return False
+            keys = [set(r.keys()) for r in records if isinstance(r, dict)]
+            if len(keys) != len(records):
+                return False
+            shared = set.intersection(*keys) if keys else set()
+            if not shared:
+                return False
+            scalar_hits = 0
+            total = 0
+            for row in records:
+                for value in row.values():
+                    total += 1
+                    if _is_scalar(value):
+                        scalar_hits += 1
+            return total > 0 and (scalar_hits / total) >= 0.8
+
+        def _should_convert_to_df(path: tuple[str, ...], records: list[dict]) -> bool:
+            if not pandas:
+                return False
+            if not _looks_like_tabular_records(records):
+                return False
+            field_name = path[-1].lower() if path else ""
+            if field_name in {"atoms", "geom_bonds", "commit_history"}:
+                return True
+            if field_name in _TABULAR_FIELD_NAMES:
+                return True
+            if field_name.endswith(("_table", "_rows", "_records", "_sites")):
+                return True
+            if field_name.startswith(("atoms_", "bond_", "symmetry_", "cell_")):
+                return True
+            return False
+
+        def _clean_and_convert(value: Any, path: tuple[str, ...] = ()) -> Any:
+            if isinstance(value, dict):
+                cleaned = {
+                    k: _clean_and_convert(v, path + (k,))
+                    for k, v in value.items()
+                    if v is not None
+                }
+                return cleaned
+            if isinstance(value, list):
+                cleaned_list = [_clean_and_convert(v, path) for v in value]
+                if cleaned_list and all(isinstance(x, dict) for x in cleaned_list):
+                    if _should_convert_to_df(path, cleaned_list):
+                        return pd.DataFrame(cleaned_list)
+                return cleaned_list
+            return value
+
+        def _extract_filename(resp: requests.Response, fallback_mof: str) -> str:
+            cd = resp.headers.get("Content-Disposition", "")
+            marker = "filename="
+            if marker in cd:
+                filename = cd.split(marker, 1)[1].strip().strip('"')
+                if filename:
+                    return filename
+            return f"{fallback_mof}.cif"
+
+        def _one(mof_name: str) -> dict | requests.Response | str:
+            if not isinstance(mof_name, str) or not mof_name.strip():
+                raise TypeError("Each 'mof' value must be a non-empty string.")
+            mof_name = mof_name.strip()
+            url = f"{self._base_url()}/cifs/files/"
+            resp = requests.get(
+                url,
+                params={"mof": mof_name, "structured": str(structured).lower()},
+                headers=self._headers(),
+                timeout=120,
+                stream=not structured,
+            )
+            resp.raise_for_status()
+
+            if structured:
+                return _clean_and_convert(resp.json())
+
+            if output_dir is not None:
+                filename = _extract_filename(resp, mof_name)
+                target = output_dir / filename
+                with target.open("wb") as f:
+                    for chunk in resp.iter_content(chunk_size=8192):
+                        if chunk:
+                            f.write(chunk)
+                resp.close()
+                return str(target)
+            return resp
+
+        if isinstance(mof, str):
+            return _one(mof)
+        if isinstance(mof, list):
+            return [_one(name) for name in mof]
+        raise TypeError("'mof' must be a string or list of strings.")
+
+    def get_material(
+        self,
+        material_id: int | None = None,
+        *,
+        name: str | list[str] | None = None,
+        bundle: list[str] | None | object = _DEFAULT_BUNDLE,
+        sim_or_exp: str | None = None,
+        good_structure: bool | None = None,
+        limit: int = 500,
+        offset: int = 0,
+        include_cif_text: bool = False,
+        cif_timeout: int = 60,
+    ) -> dict | list[dict]:
         """
-        return self._resolve_cif_url_dict(self._get(f"/materials/{material_id}/"))
+        GET /api/v2/materials/{material_id}/
+
+        Return one or more material detail records, optionally bundled with
+        related isotherms / Zeo++ / water KPIs / CIF metadata.
+
+        Resolution modes:
+            * ``material_id`` (int): fetch one material by PK.
+            * ``name`` (str): fetch one material by name match resolution.
+            * ``name`` (list[str]): fetch many materials, one per name.
+
+        Bundle behavior:
+            * omitted ``bundle``: include all bundles
+              ``['isotherms', 'zeopp', 'water_kpis', 'cif']``
+            * ``bundle=None``: include no additional bundled data (root only)
+            * explicit list: include only requested bundle sections.
+
+        Returns:
+            dict for a single material lookup; list[dict] for ``name=list[str]``.
+        """
+
+        def _resolve_one_by_name(material_name: str) -> dict:
+            matches = self._get(
+                "/materials/",
+                _compact(name=material_name, limit=50),
+            ).get("results", [])
+            exact_matches = [m for m in matches if m.get("name") == material_name]
+            candidates = exact_matches if exact_matches else matches
+            if len(candidates) > 1:
+                names = [m.get("name") for m in candidates]
+                raise ValueError(
+                    f"'{material_name}' matched {len(candidates)} materials: {names}. "
+                    "Use a more specific name."
+                )
+            if not candidates:
+                raise ValueError(f"No material matched '{material_name}'.")
+            return candidates[0]
+
+        def _as_records_local(result: Any) -> list[dict]:
+            if isinstance(result, pd.DataFrame):
+                return result.to_dict(orient="records")
+            if isinstance(result, list):
+                return result
+            return []
+
+        def _resolve_bundle_list(bundle_arg: list[str] | None | object) -> list[str]:
+            if bundle_arg is _DEFAULT_BUNDLE:
+                selected = ["isotherms", "zeopp", "water_kpis", "cif"]
+            elif bundle_arg is None:
+                selected = []
+            else:
+                selected = [str(b).strip().lower() for b in bundle_arg]
+            allowed = {"isotherms", "zeopp", "water_kpis", "cif"}
+            unknown = [b for b in selected if b not in allowed]
+            if unknown:
+                raise ValueError(
+                    f"Unknown bundle key(s): {unknown}. "
+                    "Allowed: ['isotherms','zeopp','water_kpis','cif']"
+                )
+            return selected
+
+        def _build_material_payload(base_record: dict, selected_bundles: list[str]) -> dict:
+            root = self._resolve_cif_url_dict(self._get(f"/materials/{int(base_record['id'])}/"))
+            out = dict(root)
+            mof_name = root.get("name")
+
+            if "isotherms" in selected_bundles:
+                out["isotherms"] = _as_records_local(self.get_isotherm(
+                    mof=mof_name,
+                    sim_or_exp=sim_or_exp,
+                    good_structure=good_structure,
+                    limit=limit,
+                    offset=offset,
+                ))
+
+            if "zeopp" in selected_bundles:
+                zeopp_sim = _as_records_local(self.get_carbon_zeopp(
+                    mof=mof_name,
+                    good_structure=good_structure,
+                    limit=limit,
+                    offset=offset,
+                ))
+                zeopp_exp = _as_records_local(self.get_carbon_zeopp_experimental(
+                    mof=mof_name,
+                    limit=limit,
+                    offset=offset,
+                ))
+                out["zeopp"] = [
+                    {**r, "_zeopp_source": "simulated"} for r in zeopp_sim
+                ] + [
+                    {**r, "_zeopp_source": "experimental"} for r in zeopp_exp
+                ]
+
+            if "water_kpis" in selected_bundles:
+                out["water_kpis"] = _as_records_local(self.get_water_kpis(
+                    mof=mof_name,
+                    sim_or_exp=sim_or_exp,
+                    good_structure=good_structure,
+                    limit=limit,
+                    offset=offset,
+                ))
+
+            if "cif" in selected_bundles:
+                material_psdi = self.get_material_psdi(int(base_record["id"]))
+                cif_url = material_psdi.get("cif_url") or root.get("cif_url")
+                cif_filename = material_psdi.get("cif_filename")
+                if not cif_filename and isinstance(cif_url, str) and cif_url:
+                    cif_filename = cif_url.rsplit("/", 1)[-1]
+
+                cif_payload: dict[str, Any] = {
+                    "url": cif_url,
+                    "filename": cif_filename,
+                }
+                if include_cif_text and isinstance(cif_url, str) and cif_url:
+                    resp = requests.get(cif_url, headers=self._headers(), timeout=cif_timeout)
+                    resp.raise_for_status()
+                    cif_payload["text"] = self._parse_cif_text(resp.text)
+                out["cif"] = cif_payload
+
+            return out
+
+        if (material_id is None) == (name is None):
+            raise ValueError("Provide exactly one of material_id or name")
+
+        selected_bundles = _resolve_bundle_list(bundle)
+
+        if material_id is not None:
+            base = {"id": int(material_id)}
+            return _build_material_payload(base, selected_bundles)
+
+        if isinstance(name, str):
+            base = _resolve_one_by_name(name)
+            return _build_material_payload(base, selected_bundles)
+
+        if isinstance(name, list):
+            if not all(isinstance(n, str) for n in name):
+                raise TypeError("name list must contain only strings")
+            bases = [_resolve_one_by_name(n) for n in name]
+            return [_build_material_payload(b, selected_bundles) for b in bases]
+
+        raise TypeError("name must be a string or list of strings")
 
     def get_materials_psdi(self, name: str | None = None,
                            limit: int = 500, offset: int = 0) -> pd.DataFrame:
@@ -287,12 +640,13 @@ class PrismaAPIv2:
         """
         return self._resolve_cif_url_dict(self._get(f"/materials-psdi/{material_id}/"))
 
-    def get_material_property_bundle(self, mof: str,
+    def get_material_property_bundle(self, mof: str | None = None,
                                      sim_or_exp: str | None = None,
                                      good_structure: bool | None = None,
                                      limit: int = 500,
                                      offset: int = 0,
-                                     query: dict[str, dict[str, Any]] | None = None) -> dict:
+                                     query: dict[str, dict[str, Any]] | None = None,
+                                     name: str | None = None) -> dict:
         """
         Fetch all science data for a given MOF in a single call.
 
@@ -302,6 +656,7 @@ class PrismaAPIv2:
 
         Args:
             mof:            MOF name (substring match applied to all sub-queries).
+                            Kept for backward compatibility; ``name`` is an alias.
             sim_or_exp:     'sim' or 'exp' filter for isotherms and water KPIs.
             good_structure: Good-structure filter for isotherms, water KPIs
                             and simulated Zeo++.
@@ -327,6 +682,12 @@ class PrismaAPIv2:
             ValueError: if the name matches more than one material — use an
                 exact name or a more specific substring.
         """
+        if mof is None and name is None:
+            raise TypeError("Provide either 'mof' or 'name'.")
+        if mof is not None and name is not None:
+            raise TypeError("Provide only one of 'mof' or 'name', not both.")
+        mof = name if mof is None else mof
+
         if query is not None and not isinstance(query, dict):
             raise TypeError("query must be a dict[str, dict] or None")
 
@@ -420,6 +781,101 @@ class PrismaAPIv2:
             print(f"  {key:25s}: {len(val)} records")
         return bundle
 
+    def get_material_bundle(
+        self,
+        mof: str,
+        sim_or_exp: str | None = None,
+        good_structure: bool | None = None,
+        limit: int = 500,
+        offset: int = 0,
+        query: dict[str, dict[str, Any]] | None = None,
+        include_cif: bool = False,
+        include_cif_text: bool = False,
+        cif_timeout: int = 60,
+    ) -> dict:
+        """
+        Fetch material detail, PSDI detail, and science bundle in one call flow.
+
+        Args:
+            mof:              MOF name.
+            sim_or_exp:       Optional 'sim' or 'exp' filter for bundle endpoints.
+            good_structure:   Optional structure-quality filter for bundle endpoints.
+            limit:            Max records per bundle endpoint.
+            offset:           Pagination offset for bundle endpoints.
+            query:            Advanced per-endpoint filters forwarded to
+                              ``get_material_property_bundle``.
+            include_cif:      If True, include CIF metadata (URL/filename).
+            include_cif_text: If True, download and include CIF text content.
+            cif_timeout:      Timeout in seconds for CIF download.
+
+        Returns:
+            dict with keys:
+                'material'        – output of ``get_material``
+                'material_psdi'   – output of ``get_material_psdi``
+                'property_bundle' – output of ``get_material_property_bundle``
+                'cif'             – optional CIF metadata plus structured text dict
+
+        Raises:
+            ValueError: if the name resolves to multiple materials or no material.
+        """
+        matches = self._get(
+            "/materials/",
+            _compact(name=mof, limit=50),
+        ).get("results", [])
+
+        exact_matches = [m for m in matches if m.get("name") == mof]
+        candidates = exact_matches if exact_matches else matches
+        if len(candidates) > 1:
+            names = [m.get("name") for m in candidates]
+            raise ValueError(
+                f"'{mof}' matched {len(candidates)} materials: {names}. "
+                "Use a more specific name."
+            )
+        if not candidates:
+            raise ValueError(f"No material matched '{mof}'.")
+
+        selected = candidates[0]
+        material_id = int(selected["id"])
+        true_name = selected.get("name", mof)
+
+        material = self.get_material(material_id, bundle=None)
+        material_psdi = self.get_material_psdi(material_id)
+        property_bundle = self.get_material_property_bundle(
+            true_name,
+            sim_or_exp=sim_or_exp,
+            good_structure=good_structure,
+            limit=limit,
+            offset=offset,
+            query=query,
+        )
+
+        result: dict[str, Any] = {
+            "material": material,
+            "material_psdi": material_psdi,
+            "property_bundle": property_bundle,
+        }
+
+        if include_cif:
+            cif_url = material_psdi.get("cif_url") or material.get("cif_url")
+            cif_filename = material_psdi.get("cif_filename")
+            if not cif_filename and isinstance(cif_url, str) and cif_url:
+                cif_filename = cif_url.rsplit("/", 1)[-1]
+
+            cif_payload: dict[str, Any] = {
+                "url": cif_url,
+                "filename": cif_filename,
+            }
+
+            if include_cif_text and isinstance(cif_url, str) and cif_url:
+                resp = requests.get(cif_url, headers=self._headers(), timeout=cif_timeout)
+                resp.raise_for_status()
+                cif_payload["text"] = self._parse_cif_text(resp.text)
+
+            result["cif"] = cif_payload
+        else:
+            result["cif"] = None
+        return result
+
     def preflight_material_check(self, name: str) -> bool:
         """
         Check whether a material with the given name exists in the database.

{prisma_api-0.3.6 → prisma_api-0.3.8}/prisma_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prisma_api
-Version: 0.3.6
+Version: 0.3.8
 Summary: A package for interacting with PrISMa Platform APIs. PrISMa is a holistic system for numerical synthesis and assessment of Metal-Organic Frameworks and their applications, for Direct Air Capture of CO2. For more information, see: https://prisma.hw.ac.uk.
 Author-email: RCCS-CaptureTeam <team@prisma-platform.org>
 License: GNUv3
@@ -20,8 +20,7 @@ Dynamic: license-file
 
 # PrISMa API
 
-![Tests](https://img.shields.io/badge/tests-passing-brightgreen)
-![Coverage](https://img.shields.io/badge/test%20coverage-passing-brightgreen)
+[![CI](https://github.com/RCCS-CaptureTeam/prisma_api/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/RCCS-CaptureTeam/prisma_api/actions/workflows/ci.yml)
 
 Python client for the PrISMa platform APIs.
 
@@ -195,10 +194,11 @@ All methods below are available on `api.v2`.
 ### Materials and bundles
 
 - `list_materials(name=None, limit=10000)`
-- `get_material(material_id)`
+- `get_material(material_id=None, name=None, bundle=['isotherms','zeopp','water_kpis','cif'])` (`bundle=None` returns root-only material detail)
 - `get_materials_psdi(name=None, limit=500, offset=0)`
 - `get_material_psdi(material_id)`
 - `get_material_property_bundle(mof, sim_or_exp=None, good_structure=None, limit=500, offset=0, query=None)`
+- `get_material_bundle(mof, sim_or_exp=None, good_structure=None, limit=500, offset=0, query=None, include_cif=False, include_cif_text=False, cif_timeout=60)`
 - `preflight_material_check(name)`
 
 ### Case bundles and pack builders

{prisma_api-0.3.6 → prisma_api-0.3.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "prisma_api"
-version = "0.3.6"
+version = "0.3.8"
 description = "A package for interacting with PrISMa Platform APIs. PrISMa is a holistic system for numerical synthesis and assessment of Metal-Organic Frameworks and their applications, for Direct Air Capture of CO2. For more information, see: https://prisma.hw.ac.uk."
 authors = [
     {name = "RCCS-CaptureTeam", email = "team@prisma-platform.org"}

{prisma_api-0.3.6 → prisma_api-0.3.8}/tests/test_prisma_api_v2.py

@@ -234,11 +234,66 @@ def test_get_material_detail(api):
     detail = {"id": 1, "name": "ABEXEM", "cif_url": "/media/ABEXEM.cif",
               "elements": [{"symbol": "C", "mass_fraction": 0.45}]}
     resp_lib.add(resp_lib.GET, f"{PROD_BASE}/materials/1/", json=detail, status=200)
-    result = api.get_material(1)
+    result = api.get_material(1, bundle=None)
     assert result["name"] == "ABEXEM"
     assert len(result["elements"]) == 1
 
 
+@resp_lib.activate
+def test_get_material_default_bundle_from_id(api):
+    detail = {"id": 1, "name": "HKUST", "cif_url": "/media/HKUST.cif", "elements": []}
+    resp_lib.add(resp_lib.GET, f"{PROD_BASE}/materials/1/", json=detail, status=200)
+    resp_lib.add(resp_lib.GET, f"{PROD_BASE}/isotherms/",
+                 json=_envelope([{"id": 10, "mof": "HKUST"}]), status=200)
+    resp_lib.add(resp_lib.GET, f"{PROD_BASE}/carbon-zeopp/",
+                 json=_envelope([{"id": 20, "mof": "HKUST"}]), status=200)
+    resp_lib.add(resp_lib.GET, f"{PROD_BASE}/carbon-zeopp-experimental/",
+                 json=_envelope([{"id": 21, "mof": "HKUST"}]), status=200)
+    resp_lib.add(resp_lib.GET, f"{PROD_BASE}/water-kpis/",
+                 json=_envelope([{"id": 30, "mof": "HKUST", "Molecule": 1}]), status=200)
+    resp_lib.add(resp_lib.GET, f"{PROD_BASE}/materials-psdi/1/",
+                 json={"id": 1, "name": "HKUST", "cif_url": "/media/HKUST.cif", "cif_filename": "HKUST.cif"},
+                 status=200)
+
+    result = api.get_material(1)
+    assert "isotherms" in result
+    assert "zeopp" in result
+    assert "water_kpis" in result
+    assert "cif" in result
+    assert result["zeopp"][0]["_zeopp_source"] in {"simulated", "experimental"}
+
+
+@resp_lib.activate
+def test_get_material_by_name_string_root_only(api):
+    resp_lib.add(resp_lib.GET, f"{PROD_BASE}/materials/",
+                 match=[matchers.query_param_matcher({"name": "HKUST", "limit": "50"})],
+                 json=_envelope([{"id": 1, "name": "HKUST"}]), status=200)
+    resp_lib.add(resp_lib.GET, f"{PROD_BASE}/materials/1/",
+                 json={"id": 1, "name": "HKUST", "cif_url": "/media/HKUST.cif", "elements": []}, status=200)
+
+    result = api.get_material(name="HKUST", bundle=None)
+    assert result["id"] == 1
+    assert result["name"] == "HKUST"
+
+
+@resp_lib.activate
+def test_get_material_by_name_list(api):
+    resp_lib.add(resp_lib.GET, f"{PROD_BASE}/materials/",
+                 match=[matchers.query_param_matcher({"name": "HKUST", "limit": "50"})],
+                 json=_envelope([{"id": 1, "name": "HKUST"}]), status=200)
+    resp_lib.add(resp_lib.GET, f"{PROD_BASE}/materials/",
+                 match=[matchers.query_param_matcher({"name": "ABEXEM", "limit": "50"})],
+                 json=_envelope([{"id": 2, "name": "ABEXEM"}]), status=200)
+    resp_lib.add(resp_lib.GET, f"{PROD_BASE}/materials/1/",
+                 json={"id": 1, "name": "HKUST", "cif_url": "/media/HKUST.cif", "elements": []}, status=200)
+    resp_lib.add(resp_lib.GET, f"{PROD_BASE}/materials/2/",
+                 json={"id": 2, "name": "ABEXEM", "cif_url": "/media/ABEXEM.cif", "elements": []}, status=200)
+
+    result = api.get_material(name=["HKUST", "ABEXEM"], bundle=None)
+    assert isinstance(result, list)
+    assert [r["name"] for r in result] == ["HKUST", "ABEXEM"]
+
+
 @resp_lib.activate
 def test_list_materials_empty(api):
     resp_lib.add(resp_lib.GET, f"{PROD_BASE}/materials/", json=_envelope([]), status=200)
@@ -855,6 +910,21 @@ def test_get_material_property_bundle_returns_dict(api):
     }
 
 
+@resp_lib.activate
+def test_get_material_property_bundle_accepts_name_keyword(api):
+    resp_lib.add(resp_lib.GET, f"{PROD_BASE}/materials/",
+                 json=_envelope([{"id": 1, "name": "HKUST"}]), status=200)
+    for path in ("/isotherms/", "/carbon-zeopp/",
+                 "/carbon-zeopp-experimental/", "/water-kpis/"):
+        resp_lib.add(resp_lib.GET, f"{PROD_BASE}{path}",
+                     json=_envelope([{"id": 1, "mof": "HKUST"}]), status=200)
+
+    bundle = api.get_material_property_bundle(name="HKUST")
+    assert set(bundle.keys()) == {
+        "isotherms", "zeopp_simulated", "zeopp_experimental", "water_kpis"
+    }
+
+
 @resp_lib.activate
 def test_get_material_property_bundle_filters_forwarded(api):
     """sim_or_exp and good_structure must be forwarded to isotherms and water KPIs."""
@@ -941,6 +1011,120 @@ def test_get_material_property_bundle_supports_query_dict(api):
     )
 
 
+@resp_lib.activate
+def test_get_material_bundle_includes_text(api, monkeypatch):
+    resp_lib.add(
+        resp_lib.GET,
+        f"{PROD_BASE}/materials/",
+        match=[matchers.query_param_matcher({"name": "HKUST", "limit": "50"})],
+        json=_envelope([{"id": 1, "name": "HKUST", "cif_url": "/media/HKUST.cif"}]),
+        status=200,
+    )
+    resp_lib.add(
+        resp_lib.GET,
+        f"{PROD_BASE}/materials/1/",
+        json={"id": 1, "name": "HKUST", "cif_url": "/media/HKUST.cif"},
+        status=200,
+    )
+    resp_lib.add(
+        resp_lib.GET,
+        f"{PROD_BASE}/materials-psdi/1/",
+        json={"id": 1, "name": "HKUST", "cif_url": "/media/HKUST.cif", "cif_filename": "HKUST.cif"},
+        status=200,
+    )
+    resp_lib.add(
+        resp_lib.GET,
+        "https://prisma-platform.org/media/HKUST.cif",
+        body="data_test\n_cell_length_a 10.0",
+        status=200,
+        content_type="text/plain",
+    )
+
+    expected_bundle = {
+        "isotherms": [],
+        "zeopp_simulated": [],
+        "zeopp_experimental": [],
+        "water_kpis": [],
+    }
+
+    def _fake_bundle(*args, **kwargs):
+        return expected_bundle
+
+    monkeypatch.setattr(api, "get_material_property_bundle", _fake_bundle)
+
+    result = api.get_material_bundle("HKUST", include_cif=True, include_cif_text=True)
+
+    assert result["material"]["id"] == 1
+    assert result["material_psdi"]["cif_filename"] == "HKUST.cif"
+    assert result["property_bundle"] == expected_bundle
+    assert result["cif"]["url"] == "https://prisma-platform.org/media/HKUST.cif"
+    assert isinstance(result["cif"]["text"], dict)
+    assert result["cif"]["text"]["line_count"] == 2
+    assert result["cif"]["text"]["fields"]["_cell_length_a"] == "10.0"
+    assert "data_test" in result["cif"]["text"]["raw"]
+
+
+@resp_lib.activate
+def test_get_material_bundle_raises_on_ambiguous_name(api):
+    resp_lib.add(
+        resp_lib.GET,
+        f"{PROD_BASE}/materials/",
+        match=[matchers.query_param_matcher({"name": "HK", "limit": "50"})],
+        json=_envelope([
+            {"id": 1, "name": "HKUST"},
+            {"id": 2, "name": "HK-MOF-2"},
+        ]),
+        status=200,
+    )
+
+    with pytest.raises(ValueError, match="matched 2 materials"):
+        api.get_material_bundle("HK")
+
+
+@resp_lib.activate
+def test_get_material_bundle_can_skip_cif(api, monkeypatch):
+    resp_lib.add(
+        resp_lib.GET,
+        f"{PROD_BASE}/materials/",
+        match=[matchers.query_param_matcher({"name": "HKUST", "limit": "50"})],
+        json=_envelope([{"id": 1, "name": "HKUST", "cif_url": "/media/HKUST.cif"}]),
+        status=200,
+    )
+    resp_lib.add(
+        resp_lib.GET,
+        f"{PROD_BASE}/materials/1/",
+        json={"id": 1, "name": "HKUST", "cif_url": "/media/HKUST.cif"},
+        status=200,
+    )
+    resp_lib.add(
+        resp_lib.GET,
+        f"{PROD_BASE}/materials-psdi/1/",
+        json={"id": 1, "name": "HKUST", "cif_url": "/media/HKUST.cif", "cif_filename": "HKUST.cif"},
+        status=200,
+    )
+
+    expected_bundle = {
+        "isotherms": [],
+        "zeopp_simulated": [],
+        "zeopp_experimental": [],
+        "water_kpis": [],
+    }
+
+    def _fake_bundle(*args, **kwargs):
+        return expected_bundle
+
+    monkeypatch.setattr(api, "get_material_property_bundle", _fake_bundle)
+
+    result = api.get_material_bundle(
+        "HKUST",
+        include_cif=False,
+        include_cif_text=True,
+    )
+
+    assert result["property_bundle"] == expected_bundle
+    assert result["cif"] is None
+
+
 # ── preflight_material_check ──────────────────────────────────────────────────
 
 @resp_lib.activate
@@ -1451,6 +1635,10 @@ def test_api_key_header_sent(api):
 # ── Flowsheets ────────────────────────────────────────────────────────────────
 
 _UPSERT_FLOWSHEET_FIXTURE = "reference_data/prisma_v2/dac_min_2026-07-01.json"
+_SKIP_UPSERT_FLOWSHEET_IN_CI = pytest.mark.skipif(
+    os.getenv("CI", "").lower() == "true",
+    reason="Upsert flowsheet fixture tests are disabled in CI",
+)
 
 
 def _load_upsert_flowsheet_payload() -> list[dict]:
@@ -1515,6 +1703,7 @@ def test_get_flowsheet_bundle_custom_name_routes_path(api):
 
 
 @resp_lib.activate
+@_SKIP_UPSERT_FLOWSHEET_IN_CI
 def test_upsert_flowsheets_default_append_mode(api):
     resp_lib.add(
         resp_lib.PUT,
@@ -1528,6 +1717,7 @@ def test_upsert_flowsheets_default_append_mode(api):
 
 
 @resp_lib.activate
+@_SKIP_UPSERT_FLOWSHEET_IN_CI
 def test_upsert_flowsheets_overwrite_mode(api):
     resp_lib.add(
         resp_lib.PUT,
@@ -1545,6 +1735,7 @@ def test_upsert_flowsheets_overwrite_mode(api):
 
 
 @resp_lib.activate
+@_SKIP_UPSERT_FLOWSHEET_IN_CI
 def test_upsert_flowsheets_uses_dev_mode_base_url(dev_api):
     resp_lib.add(
         resp_lib.PUT,
@@ -1561,6 +1752,7 @@ def test_upsert_flowsheets_uses_dev_mode_base_url(dev_api):
     assert result["created"] == 1
 
 
+@_SKIP_UPSERT_FLOWSHEET_IN_CI
 def test_upsert_flowsheets_rejects_invalid_on_exists(api):
     payload = _load_upsert_flowsheet_payload()
     with pytest.raises(ValueError):
@@ -1571,11 +1763,31 @@ def test_upsert_flowsheets_rejects_invalid_on_exists(api):
         )
 
 
-@pytest.mark.skipif(
-    os.getenv("PRISMA_API_PRODUCTION_BYPASS", "").lower() == "true",
-    reason="Bypassed in production mode",
-)
-def test_upsert_flowsheets_rejects_empty_screening_analysis_name(api):
+@resp_lib.activate
+@_SKIP_UPSERT_FLOWSHEET_IN_CI
+def test_upsert_flowsheets_allows_missing_screening_analysis_name_with_warning(api):
+    resp_lib.add(
+        resp_lib.PUT,
+        f"{PROD_BASE}/flowsheets/upsert/?on_exists=append&appendix=_v4",
+        json={"created": 1, "updated": 0},
+        status=200,
+    )
     payload = _load_upsert_flowsheet_payload()
-    with pytest.raises(ValueError):
-        api.upsert_flowsheets(payload, screening_analysis_name="   ")
+    with pytest.warns(UserWarning, match="for experimentation only"):
+        result = api.upsert_flowsheets(payload)
+    assert result["created"] == 1
+
+
+@resp_lib.activate
+@_SKIP_UPSERT_FLOWSHEET_IN_CI
+def test_upsert_flowsheets_blank_screening_analysis_name_warns_and_omits_query_param(api):
+    resp_lib.add(
+        resp_lib.PUT,
+        f"{PROD_BASE}/flowsheets/upsert/?on_exists=overwrite",
+        json={"created": 0, "updated": 1},
+        status=200,
+    )
+    payload = _load_upsert_flowsheet_payload()
+    with pytest.warns(UserWarning, match="list_case_studies"):
+        result = api.upsert_flowsheets(payload, screening_analysis_name="   ", on_exists="overwrite")
+    assert result["updated"] == 1