rowan-python 3.1.6__py3-none-any.whl → 3.1.8__py3-none-any.whl

rowan/__init__.py

@@ -38,7 +38,11 @@ from stjames import (
     VibrationalMode,
     VinaSettings,
 )
-from stjames.workflows.relative_binding_free_energy_perturbation import RBFEGraph, RBFEGraphEdge
+from stjames.workflows.relative_binding_free_energy_perturbation import (
+    RBFEGraph,
+    RBFEGraphEdge,
+    TMDRBFESettings,
+)
 from stjames.excited_state_settings import TDDFTSettings
 from stjames.pbc_dft_settings import PBCDFTSmearing
 from stjames.engine_compatibility import (

rowan/molecule.py

@@ -144,6 +144,15 @@ class Molecule(BaseModel):
 
     # -- Properties --
 
+    @property
+    def name(self) -> str | None:
+        """Optional molecule name."""
+        return self._stjames.name
+
+    @name.setter
+    def name(self, value: str | None) -> None:
+        self._stjames.name = value
+
     @property
     def charge(self) -> int:
         """Molecular charge."""

rowan/project.py

@@ -126,6 +126,29 @@ def create_project(
     return Project(**project_data)
 
 
+def get_project(name: str, create: bool = False) -> Project:
+    """
+    Get a project by exact name, optionally creating it if it does not exist.
+
+    The project analogue of :func:`get_folder`. Unlike ``get_folder``, ``create``
+    defaults to ``False``: a project is a top-level container, so a typo should
+    raise rather than silently spawn a new one. Does not change the active project -
+    assign ``rowan.project_uuid`` or use :func:`set_project` for that.
+
+    :param name: Exact name of the project.
+    :param create: If True, create the project when no exact match exists.
+    :returns: Matched (or newly created) project.
+    :raises ValueError: If no match is found and ``create`` is False.
+    """
+    matches = list_projects(name_contains=name, size=100)
+    project = next((p for p in matches if p.name == name), None)
+    if project is not None:
+        return project
+    if create:
+        return create_project(name)
+    raise ValueError(f"Project {name!r} not found")
+
+
 def set_project(name: str) -> Project:
     """
     Set the active project by name for all subsequent API calls.
@@ -142,10 +165,7 @@ def set_project(name: str) -> Project:
     :returns: Matched project.
     :raises ValueError: If no project with that name is found.
     """
-    matches = list_projects(name_contains=name, size=100)
-    project = next((p for p in matches if p.name == name), None)
-    if project is None:
-        raise ValueError(f"Project {name!r} not found")
+    project = get_project(name)
     rowan.project_uuid = project.uuid
     return project
 

rowan/protein.py

@@ -400,22 +400,20 @@ def upload_protein(
     if isinstance(project_uuid, Project):
         project_uuid = project_uuid.uuid
     with api_client() as client:
-        # Step 1: Read the file and post it to the conversion endpoint.
         conversion_payload = {"name": name, "text": file_path.read_text()}
         conversion_response = client.post("/convert/pdb_file_to_protein", json=conversion_payload)
+        conversion_response.raise_for_status()
 
-        # Extract the JSON data from the conversion response.
         protein_data = conversion_response.json()
 
-        # Step 2: Use the converted data to create the final protein object.
         creation_payload = {
             "name": name,
             "protein_data": protein_data,
             "project_uuid": project_uuid,
         }
         final_response = client.post("/protein", json=creation_payload)
+        final_response.raise_for_status()
 
-        # Deserialize the final JSON response into a Protein object and return it.
         return Protein(**final_response.json())
 
 

rowan/test_utils.py

@@ -0,0 +1,54 @@
+"""Tests for Rowan request utilities."""
+
+import asyncio
+
+from pytest import MonkeyPatch, raises
+
+import rowan
+from rowan.utils import api_credentials, get_api_key, get_project_uuid
+
+
+def test_api_credentials_override_global_configuration(monkeypatch: MonkeyPatch) -> None:
+    """Prefer context-local credentials without changing global configuration."""
+    monkeypatch.setattr(rowan, "api_key", "global-key")
+    monkeypatch.setattr(rowan, "project_uuid", "global-project")
+    monkeypatch.setenv("ROWAN_API_KEY", "environment-key")
+
+    with api_credentials("context-key", project_uuid="context-project"):
+        assert get_api_key() == "context-key"
+        assert get_project_uuid() == "context-project"
+
+    assert get_api_key() == "global-key"
+    assert get_project_uuid() == "global-project"
+
+
+def test_api_credentials_restore_nested_context() -> None:
+    """Restore outer credentials after a nested context exits."""
+    with api_credentials("outer-key", project_uuid="outer-project"):
+        with api_credentials("inner-key"):
+            assert get_api_key() == "inner-key"
+            assert get_project_uuid() is None
+
+        assert get_api_key() == "outer-key"
+        assert get_project_uuid() == "outer-project"
+
+
+def test_api_credentials_isolate_async_tasks() -> None:
+    """Keep credentials isolated across concurrent asynchronous tasks."""
+
+    async def read_after_yield(api_key: str) -> str:
+        with api_credentials(api_key):
+            await asyncio.sleep(0)
+            return get_api_key()
+
+    async def run_workers() -> list[str]:
+        return list(await asyncio.gather(read_after_yield("first"), read_after_yield("second")))
+
+    assert asyncio.run(run_workers()) == ["first", "second"]
+
+
+def test_api_credentials_reject_empty_key() -> None:
+    """Reject empty context-local API keys."""
+    with raises(ValueError, match="cannot be empty"):
+        with api_credentials(""):
+            pass

rowan/utils.py

@@ -1,5 +1,7 @@
 import os
 from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
 from typing import Generator
 
 import httpx
@@ -10,6 +12,40 @@ import rowan
 from .constants import API_URL
 
 
+@dataclass(frozen=True, slots=True)
+class _APIContext:
+    """Store credentials isolated to the current execution context."""
+
+    api_key: str
+    project_uuid: str | None
+
+
+_api_context: ContextVar[_APIContext | None] = ContextVar("rowan_api_context", default=None)
+
+
+@contextmanager
+def api_credentials(api_key: str, project_uuid: str | None = None) -> Generator[None, None, None]:
+    """Temporarily use Rowan credentials in the current execution context.
+
+    Context-local credentials take precedence over module-level and environment configuration.
+    Nested contexts restore the previous credentials when they exit, and concurrent threads or
+    asynchronous tasks remain isolated from one another.
+
+    :param api_key: Rowan API key
+    :param project_uuid: active project UUID, if any
+    :yields: control while the credentials are active
+    :raises ValueError: API key is empty
+    """
+    if not api_key:
+        raise ValueError("API key cannot be empty.")
+
+    token = _api_context.set(_APIContext(api_key=api_key, project_uuid=project_uuid))
+    try:
+        yield
+    finally:
+        _api_context.reset(token)
+
+
 def get_api_key() -> str:
     """
     Get the API key from the environment variable ROWAN_API_KEY or the module-level attribute
@@ -19,6 +55,8 @@ def get_api_key() -> str:
 
     :returns: API key.
     """
+    if (context := _api_context.get()) is not None:
+        return context.api_key
     if hasattr(rowan, "api_key") and rowan.api_key:
         return rowan.api_key
     elif (api_key := os.environ.get("ROWAN_API_KEY")) is not None:
@@ -36,6 +74,8 @@ def get_project_uuid() -> str | None:
 
     :returns: Project UUID string, or None if not set.
     """
+    if (context := _api_context.get()) is not None:
+        return context.project_uuid
     if hasattr(rowan, "project_uuid") and rowan.project_uuid:
         return rowan.project_uuid
     return None

rowan/workflows/analogue_docking.py

@@ -98,15 +98,26 @@ class AnalogueDockingResult(WorkflowResult):
         Best docked pose per analogue, keyed by SMILES.
 
         Fetches the final geometry from each analogue's top-scoring pose.
-        Analogues with no successful poses are excluded.
+        Analogues with no successful poses are excluded. When ``analogue_names``
+        were supplied at submission, each pose's ``name`` is set to the analogue
+        name, so poses can be re-keyed by name (e.g. ``{p.name: p for p in ...}``).
 
         :returns: Dictionary mapping SMILES to docked ``Molecule`` with 3D coordinates.
         """
-        return {
-            smiles: self.get_pose(smiles).molecules[-1]
-            for smiles, scores in self.analogue_scores.items()
-            if scores
-        }
+        # analogue_names is empty or parallel to analogues; zip drops the tail when empty.
+        name_by_smiles = dict(
+            zip(self._workflow.analogues, self._workflow.analogue_names, strict=False)
+        )
+        poses = {}
+        for smiles, scores in self.analogue_scores.items():
+            if not scores:
+                continue
+            pose = self.get_pose(smiles).molecules[-1]
+            # Keep any name the pose already carries; otherwise fall back to analogue_names.
+            if not pose.name:
+                pose.name = name_by_smiles.get(smiles)
+            poses[smiles] = pose
+        return poses
 
     def get_poses(self, smiles: str) -> list[Calculation]:
         """
@@ -175,6 +186,7 @@ def submit_analogue_docking_workflow(
     analogues: list[str],
     initial_molecule: StructureInput,
     protein: str | Protein,
+    analogue_names: list[str] | None = None,
     scoring_function: Literal["vina", "vinardo"] = "vinardo",
     exhaustiveness: int = 8,
     max_poses: int = 4,
@@ -194,6 +206,9 @@ def submit_analogue_docking_workflow(
     :param analogues: SMILES strings to dock.
     :param initial_molecule: Template to which to align molecules to.
     :param protein: Protein to dock. Can be input as a uuid or a Protein object.
+    :param analogue_names: Names parallel to `analogues`. When provided, each docked
+        pose's `Molecule.name` is set to its analogue name (see `best_poses`), and must
+        be the same length as `analogues`. If omitted, poses are identified by SMILES.
     :param scoring_function: Docking scoring function: "vina" or "vinardo".
     :param exhaustiveness: How many times Vina attempts to find a pose for each conformer.
     :param max_poses: Maximum number of poses generated per input conformer.
@@ -210,6 +225,11 @@ def submit_analogue_docking_workflow(
     :raises requests.HTTPError: if the request to the API fails.
     """
     require_coordinates(initial_molecule)
+    if analogue_names is not None and len(analogue_names) != len(analogues):
+        raise ValueError(
+            f"analogue_names must match analogues in length "
+            f"(got {len(analogue_names)} names for {len(analogues)} analogues)."
+        )
     if folder and folder_uuid:
         raise ValueError("Provide either `folder` or `folder_uuid`, not both.")
     if folder:
@@ -228,6 +248,7 @@ def submit_analogue_docking_workflow(
 
     workflow = stjames.AnalogueDockingWorkflow(
         analogues=analogues,
+        analogue_names=analogue_names or [],
         initial_molecule=mol_dict,
         protein=protein,
         docking_settings=docking_settings,

rowan/workflows/relative_binding_free_energy_perturbation.py

@@ -1,5 +1,6 @@
 """RBFE perturbation workflow - run relative binding free energy FEP simulations."""
 
+import csv
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Literal
@@ -91,6 +92,11 @@ class RelativeBindingFreeEnergyPerturbationResult(WorkflowResult):
         """Prepared protein structure used as the simulation target."""
         return Protein(uuid=str(self._workflow.protein))
 
+    @property
+    def settings(self) -> TMDRBFESettings:
+        """FEP settings used for the simulation."""
+        return self._workflow.settings
+
     @property
     def graph(self) -> RBFEGraph | None:
         """The RBFE graph with per-edge results, or None if not constructed."""
@@ -187,6 +193,34 @@ class RelativeBindingFreeEnergyPerturbationResult(WorkflowResult):
             k: RelativeBindingFreeEnergyResult(dg=v.dg, dg_err=v.dg_err) for k, v in raw.items()
         }
 
+    def write_ligand_results_csv(self, path: Path | str = "ligand_results.csv") -> Path:
+        """
+        Write per-ligand results to a CSV, matching the platform's ligand-results export.
+
+        Columns are ``Ligand name``, ``ΔG``, ``ΔG error``, ``SMILES``, quoted and
+        BOM-prefixed for spreadsheet compatibility, identical to the download in the web UI.
+
+        :param path: destination CSV path.
+        :returns: path written to.
+        :raises ValueError: if per-ligand results are not yet available.
+        """
+        if (results := self.ligand_dg_results) is None:
+            raise ValueError("No per-ligand results yet - has the workflow completed?")
+
+        # Match JS Number->string: whole numbers render without a trailing ".0" (0.0 -> "0").
+        def num(x: float) -> str:
+            return str(int(x)) if x == int(x) else str(x)
+
+        ligands = self.ligands
+        path = Path(path)
+        with path.open("w", newline="", encoding="utf-8-sig") as f:
+            writer = csv.writer(f, quoting=csv.QUOTE_ALL, lineterminator="\n")
+            writer.writerow(["Ligand name", "ΔG", "ΔG error", "SMILES"])
+            for name, res in results.items():
+                smiles = ligands[name].smiles if name in ligands else None
+                writer.writerow([name, num(res.dg), num(res.dg_err), smiles or ""])
+        return path
+
     @property
     def diagnostics(self) -> RelativeBindingFreeEnergyDiagnostics | None:
         """Aggregate QC metrics from the FEP simulation."""

{rowan_python-3.1.6.dist-info → rowan_python-3.1.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rowan-python
-Version: 3.1.6
+Version: 3.1.8
 Summary: Rowan Python Library
 Project-URL: Homepage, https://github.com/rowansci/rowan-client
 Project-URL: Bug Tracker, https://github.com/rowansci/rowan-client/issues
@@ -30,9 +30,27 @@ The documentation is available [here](https://docs.rowansci.com/python-api).
 
 ## Agent skill
 
-Ships with a [skill](skills/computational-chemistry-and-biology/) that makes it easy for coding agents to use Rowan's tools to power chemistry and biology tasks. To use it, copy the directory into your agent's skills folder.
+Ships with a [computational chemistry and biology skill](skills/computational-chemistry-and-biology/)
+that helps coding agents choose and run Rowan workflows through either Rowan MCP tools or the
+Rowan Python SDK.
 
-Download the latest skill as a zip [here](https://github.com/rowansci/rowan-python/releases/download/skill-latest/computational-chemistry-and-biology-skill.zip), then unzip it into your agent's skills folder.
+### Claude Code
+
+```bash
+claude plugin marketplace add https://github.com/rowansci/rowan-python.git
+claude plugin install computational-chemistry-and-biology@rowan
+```
+
+### Codex
+
+```bash
+codex plugin marketplace add rowansci/rowan-python --ref master
+codex plugin add computational-chemistry-and-biology@rowan
+```
+
+Start a new Claude Code or Codex session after installation. For manual installation, download the
+[latest skill ZIP](https://github.com/rowansci/rowan-python/releases/download/skill-latest/computational-chemistry-and-biology-skill.zip)
+and extract it into your agent's skills directory.
 
 ## Running examples
 

{rowan_python-3.1.6.dist-info → rowan_python-3.1.8.dist-info}/RECORD

@@ -1,19 +1,20 @@
-rowan/__init__.py,sha256=95VjN9XTgEICFLCcB4oUbT_nsU_EvulDqMDJjBuSTI8,1714
+rowan/__init__.py,sha256=J1u---gqVAI_LMJatslW1LiYKAhQVGjyUrR7FH1B5as,1748
 rowan/api_keys.py,sha256=TvG5l5MmQ3Qt8Z3Y7jCA_lcrwEHuI7xHy-KLbIdQ8_A,4793
 rowan/calculation.py,sha256=nuUtLTtn9D-FCM9TJl3h5euBgIYqa5fr5r_PSNBS7Xo,3809
 rowan/config.py,sha256=TejQKSxnzNKKTNL9-2bCLq6RvAh54oVA5Ivl1p_ZT8Q,20899
 rowan/constants.py,sha256=emCH4m9OL2Hm5E-6mJGM_FgzrK_JrZT-FiKJ6pMNQ4Y,84
 rowan/folder.py,sha256=RRg68dObluJ2RCTKX3rb7RxziOXOQUYxkfQSU2R5VMk,13708
-rowan/molecule.py,sha256=1l-3YCN_A75Uz_Q-dMWuhkeF8rhD1z2JQM7AENyjKYM,15512
-rowan/project.py,sha256=RtxYE9jv3Yz6fH5I56iDGRG5EbwlOHiSK-HF1uxc0d4,4582
-rowan/protein.py,sha256=T2JAqfncP80yV5gEWYA-TlpNY3WeWaNHPE0Xg5voU24,17968
+rowan/molecule.py,sha256=MFx0D3_LJm1G3UiDogkfCHvae31gR6xo_N0LzrNC-ks,15733
+rowan/project.py,sha256=4f1XGRe_EADjbd5uFGPvsVXz9s3t4ZiL8loTBlahn7A,5404
+rowan/protein.py,sha256=uFMF2BXgIvn6KOw3cdE-LDvZPPbjAxqqwgxakLd85XA,17763
 rowan/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rowan/test_utils.py,sha256=DTuZqftx6ycIatajAxSGWgDaGglLvTw2TYnVJHiiNdo,1936
 rowan/types.py,sha256=MvcYvEYr6N9RXLal44MqsnMxoWfcBa-VLD_rGsW4HOc,591
 rowan/user.py,sha256=rOCYVhSoRY71fCG_OCSD7cLAWWnAMANWGitF3ogfq30,6212
-rowan/utils.py,sha256=DBphY1he8Vl3RNf6CbLp5BSX9RG5EfHzhMs-9TmcE_g,4299
+rowan/utils.py,sha256=J-3o9_ZlOrl4_ZuuC1yjEOPdD1IkKO0BOXBncV3Ij7c,5670
 rowan/workflows/__init__.py,sha256=pkmAl8aPDznu15bSuRW0j8id-B7Xmzy_tq3LgZfQ7NQ,4786
 rowan/workflows/admet.py,sha256=jDx1Kkgmp0XaeojPzaCFY_yUwvqtSM7Cezps-93cqPw,2865
-rowan/workflows/analogue_docking.py,sha256=TshOw71RmK5XaaTIHz_Q1opiDU9x1L38tXwxoYUZaxY,9756
+rowan/workflows/analogue_docking.py,sha256=ngv5IFbOVFe42uSFkeEtM2qt-zAJFfJyF8ducexGK5U,11020
 rowan/workflows/base.py,sha256=k858otXLuorw4MZ1hvqZI_m0n_38htC7Hy3OMCX1TOA,32961
 rowan/workflows/basic_calculation.py,sha256=EovymT6fV6mxmt4G4kRtiskSPGB7w7KAHqBaGtgQI2Q,12941
 rowan/workflows/batch_docking.py,sha256=ePnb1hcsmnUfffl1-k9HNkOC09RjY9bZS9XcqAGNeFs,3621
@@ -44,14 +45,14 @@ rowan/workflows/protein_cofolding.py,sha256=haT0liJorxyHgO02WX8WslqAu7Dc7QOSs6Vb
 rowan/workflows/protein_md.py,sha256=zqKEtL514uchgbxsyO4vhokzTU-X4lTFA1BM5O8HvTU,10117
 rowan/workflows/rbfe_graph.py,sha256=0eMfvwtQhyajUC8T-bhdcYNKi6Pkja6x6dHjCnEwxPw,8081
 rowan/workflows/redox_potential.py,sha256=bBeT1K9XGVpjCFZeeuv7Vtr3EYHN2okJ4LqYc3gMV04,5427
-rowan/workflows/relative_binding_free_energy_perturbation.py,sha256=vi5Qj5aDAERtjcHDsgzI6vRV_BZJnJ8boOj5aG6GXzo,13817
+rowan/workflows/relative_binding_free_energy_perturbation.py,sha256=D8WNFWAm4VwO_Gn50XHQS4kUAqu-KiJFHAOLx5VGvdk,15347
 rowan/workflows/scan.py,sha256=R5Y6Md3ohPoFVJ4NYvx3_k3JNwMnVw1CDsNPD9S8sr4,7518
 rowan/workflows/solubility.py,sha256=ulZwdG8JRl0RCwWPatYUZGMhlAZeb6wqjVbvzQYFKmE,8555
 rowan/workflows/solvent_dependent_conformers.py,sha256=Z2xESmcM8WcTsR2TSTUa--RrhrQ-5ri_WagD9wJeVwc,6812
 rowan/workflows/spin_states.py,sha256=rjkgie2-XVNIN7O6P93yn6EPv9Ogjy8iTj3ufZIsUgY,9331
 rowan/workflows/strain.py,sha256=kCW_BlX__sdQG1JVbFZuB-57rkpnxa_JCw3h4uKdGDk,6425
 rowan/workflows/tautomer_search.py,sha256=mbRl0ZJ7wibueRF8c8_idhXJ1rtwg7LBt--5QwQ_Cck,5767
-rowan_python-3.1.6.dist-info/METADATA,sha256=DNhG5-OE8U_DwL4OgWgBf3tKivdvSYRMW9kmh_kq48g,2052
-rowan_python-3.1.6.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-rowan_python-3.1.6.dist-info/licenses/LICENSE,sha256=i05z7xEhyrg6f8j0lR3XYjShnF-MJGFQ-DnpsZ8yiVI,1084
-rowan_python-3.1.6.dist-info/RECORD,,
+rowan_python-3.1.8.dist-info/METADATA,sha256=I21zA1ConlWw06jgs294uPgw5-L97vflydhXYQk1D3Q,2436
+rowan_python-3.1.8.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+rowan_python-3.1.8.dist-info/licenses/LICENSE,sha256=i05z7xEhyrg6f8j0lR3XYjShnF-MJGFQ-DnpsZ8yiVI,1084
+rowan_python-3.1.8.dist-info/RECORD,,