rowan-python 2.1.11__py3-none-any.whl

rowan/__init__.py

@@ -0,0 +1,9 @@
+# ruff: noqa
+from . import constants
+
+from .folder import *
+from .workflow import *
+from .project import *
+from .protein import *
+from .user import *
+from .utils import *

rowan/constants.py

@@ -0,0 +1,3 @@
+import os
+
+API_URL = os.getenv("ROWAN_API_URL", default="https://api.rowansci.com")

rowan/folder.py

@@ -0,0 +1,228 @@
+from datetime import datetime
+from typing import Any, Self
+
+from pydantic import BaseModel
+
+from .utils import api_client
+
+
+class Folder(BaseModel):
+    """
+    A class representing a folder in the Rowan API.
+
+    :ivar uuid: The UUID of the folder.
+    :ivar name: The name of the folder.
+    :ivar parent_uuid: The UUID of the parent folder.
+    :ivar notes: Folder notes.
+    :ivar starred: Whether the folder is starred.
+    :ivar public: Whether the folder is public.
+    :ivar created_at: The date and time the folder was created.
+    """
+
+    uuid: str
+    name: str | None = None
+    parent_uuid: str | None = None
+    notes: str = ""
+    starred: bool = False
+    public: bool = False
+    created_at: datetime | None = None
+
+    def __repr__(self) -> str:
+        return f"<Folder name='{self.name}' created_at='{self.created_at}' uuid='{self.uuid}'>"
+
+    def fetch_latest(self, in_place: bool = False) -> Self:
+        """
+        Fetch the latest folder data from the API.
+
+        This method refreshes the folder object with the latest data from the API.
+
+        :param in_place: Whether to update the current instance in-place.
+        :return: The updated instance (self).
+        :raises HTTPError: If the API request fails.
+        """
+        with api_client() as client:
+            response = client.get(f"/folder/{self.uuid}")
+            response.raise_for_status()
+            data = response.json()
+
+        if not in_place:
+            return self.__class__.model_validate(data)
+
+        updated_folder = self.model_validate(data)
+
+        # Update current instance with new data using class-level model_fields
+        for field_name in self.__class__.model_fields:
+            setattr(self, field_name, getattr(updated_folder, field_name))
+
+        self.model_rebuild()
+
+        return self
+
+
+    def update(
+        self,
+        name: str | None = None,
+        parent_uuid: str | None = None,
+        notes: str | None = None,
+        starred: bool | None = None,
+        public: bool | None = None,
+    ) -> Self:
+        """
+        Update a folder.
+
+        :param name: The new name of the folder.
+        :param parent_uuid: The UUID of the new parent folder.
+        :param notes: A description of the folder.
+        :param starred: Whether the folder is starred.
+        :param public: Whether the folder is public.
+
+        :return: The updated folder object.
+        """
+        payload = {
+            "name": name if name is not None else self.name,
+            "parent_uuid": parent_uuid if parent_uuid is not None else self.parent_uuid,
+            "notes": notes if notes is not None else self.notes,
+            "starred": starred if starred is not None else self.starred,
+            "public": public if public is not None else self.public,
+        }
+
+        with api_client() as client:
+            response = client.post(f"/folder/{self.uuid}", json=payload)
+            response.raise_for_status()
+            updated_data = response.json()
+
+        self.name = updated_data.get("name")
+        self.parent_uuid = updated_data.get("parent_uuid")
+        self.notes = updated_data.get("notes")
+        self.starred = updated_data.get("starred")
+        self.public = updated_data.get("public")
+        return self
+
+    def delete(self) -> None:
+        """
+        Delete the folder and all its contents.
+
+        This is a destructive action, it will delete all the folders and
+        workflows that are inside this folder.
+
+        :raises requests.HTTPError: if the request to the API fails.
+        """
+        with api_client() as client:
+            response = client.delete(f"/folder/{self.uuid}")
+            response.raise_for_status()
+
+    def print_folder_tree(self, max_depth: int = 10, show_uuids: bool = False) -> None:
+        """
+        Retrieves a folder tree from the API.
+
+        :param max_depth: The maximum depth of the folder tree.
+        :param show_uuids: Whether to show the UUIDs of the folders.
+        :raises HTTPError: If the API request fails.
+        """
+        print_folder_tree(self.uuid, max_depth, show_uuids)
+
+def retrieve_folder(uuid: str) -> Folder:
+    """
+    Retrieves a folder from the API by UUID. Folder UUID can be found in the folder's URL.
+
+    :param uuid: The UUID of the folder to retrieve.
+    :return: A Folder object representing the retrieved folder.
+    :raises HTTPError: If the API request fails.
+    """
+    with api_client() as client:
+        response = client.get(f"/folder/{uuid}")
+        response.raise_for_status()
+        return Folder(**response.json())
+
+
+def list_folders(
+    parent_uuid: str | None = None,
+    name_contains: str | None = None,
+    public: bool | None = None,
+    starred: bool | None = None,
+    page: int = 0,
+    size: int = 10,
+) -> list[Folder]:
+    """
+    Retrieve a list of folders based on the specified criteria.
+
+    :param parent_uuid: UUID of the parent folder to filter by.
+    :param name_contains: Substring to search for in folder names.
+    :param public: Filter folders by their public status.
+    :param starred: Filter folders by their starred status.
+    :param page: Pagination parameter to specify the page number.
+    :param size: Pagination parameter to specify the number of items per page.
+    :return: A list of Folder objects that match the search criteria.
+    :raises requests.HTTPError: if the request to the API fails.
+    """
+
+    params: dict[str, Any] = {
+        "page": page,
+        "size": size,
+    }
+
+    if parent_uuid is not None:
+        params["parent_uuid"] = parent_uuid
+    if name_contains is not None:
+        params["name_contains"] = name_contains
+    if public is not None:
+        params["public"] = public
+    if starred is not None:
+        params["starred"] = starred
+
+    with api_client() as client:
+        response = client.get("/folder", params=params)
+        response.raise_for_status()
+        items = response.json()["folders"]
+
+    return [Folder(**item) for item in items]
+
+
+def create_folder(
+    name: str,
+    parent_uuid: str | None = None,
+    notes: str = "",
+    starred: bool = False,
+    public: bool = False,
+) -> Folder:
+    """
+    Create a new folder.
+
+    :param name: The name of the folder.
+    :param parent_uuid: The UUID of the parent folder.
+    :param notes: A description of the folder.
+    :param starred: Whether the folder is starred.
+    :param public: Whether the folder is public.
+    :return: The newly created folder.
+    """
+    data = {
+        "name": name,
+        "parent_uuid": parent_uuid,
+        "notes": notes,
+        "starred": starred,
+        "public": public,
+    }
+    with api_client() as client:
+        response = client.post("/folder", json=data)
+        response.raise_for_status()
+        folder_data = response.json()
+    return Folder(**folder_data)
+
+def print_folder_tree(uuid: str, max_depth: int = 10, show_uuids: bool = False) -> None:
+    """
+    Retrieves a folder tree from the API.
+
+    :param uuid: The UUID of the root of the folder tree.
+    :param max_depth: The maximum depth of the folder tree.
+    :param show_uuids: Whether to show the UUIDs of the folders.
+    :raises HTTPError: If the API request fails.
+    """
+    params: dict[str, Any] = {
+        "max_depth": max_depth,
+        "show_uuids": show_uuids,
+    }
+    with api_client() as client:
+        response = client.get(f"/folder/{uuid}/folder_tree", params=params)
+        response.raise_for_status()
+        folder_data = response.json()
+    print(folder_data)

rowan/project.py

@@ -0,0 +1,136 @@
+from datetime import datetime
+from typing import Any, Self
+
+from pydantic import BaseModel
+
+from .utils import api_client
+
+
+class Project(BaseModel):
+    """
+    A class representing a project in the Rowan API.
+
+    :ivar uuid: The UUID of the project.
+    :ivar name: The name of the project.
+    :ivar created_at: The date and time the project was created.
+    """
+
+    uuid: str
+    name: str | None = None
+    created_at: datetime | None = None
+
+    def __repr__(self) -> str:
+        return f"<Project name='{self.name}' created_at='{self.created_at}' uuid='{self.uuid}'>"
+
+    def update(
+        self,
+        name: str | None = None,
+    ) -> Self:
+        """
+        Update a project.
+
+        :param name: The new name of the project.
+
+        :return: The updated project object.
+        """
+        payload = {
+            "name": name if name is not None else self.name,
+        }
+
+        with api_client() as client:
+            response = client.post(f"/project/{self.uuid}", json=payload)
+            response.raise_for_status()
+            updated_data = response.json()
+
+        self.name = updated_data.get("name")
+        return self
+
+    def delete(self) -> None:
+        """
+        Delete the project.
+
+        This is a destructive action, it will delete all the folders and
+        workflows that are inside this project.
+
+        :raises requests.HTTPError: if the request to the API fails.
+        """
+        with api_client() as client:
+            response = client.delete(f"/project/{self.uuid}")
+            response.raise_for_status()
+
+
+def retrieve_project(uuid: str) -> Project:
+    """
+    Retrieves a project from the API by UUID. Project UUID can be found in the project's URL.
+
+    :param uuid: The UUID of the project to retrieve.
+    :return: A Project object representing the retrieved project.
+    :raises HTTPError: If the API request fails.
+    """
+    with api_client() as client:
+        response = client.get(f"/project/{uuid}")
+        response.raise_for_status()
+        return Project(**response.json())
+
+
+def list_projects(
+    name_contains: str | None = None,
+    page: int = 0,
+    size: int = 10,
+) -> list[Project]:
+    """
+    Retrieve a list of projects based on the specified criteria.
+
+    :param name_contains: Substring to search for in project names.
+    :param page: Pagination parameter to specify the page number.
+    :param size: Pagination parameter to specify the number of items per page.
+    :return: A list of Folder objects that match the search criteria.
+    :raises requests.HTTPError: if the request to the API fails.
+    """
+
+    params: dict[str, Any] = {
+        "page": page,
+        "size": size,
+    }
+
+    if name_contains is not None:
+        params["name_contains"] = name_contains
+
+    with api_client() as client:
+        response = client.get("/project", params=params)
+        response.raise_for_status()
+        items = response.json()
+
+    return [Project(**item) for item in items]
+
+
+def create_project(
+    name: str,
+) -> Project:
+    """
+    Create a new project.
+
+    :param name: The name of the project.
+    :return: The newly created project.
+    """
+    data = {
+        "name": name,
+    }
+    with api_client() as client:
+        response = client.post("/project", json=data)
+        response.raise_for_status()
+        project_data = response.json()
+    return Project(**project_data)
+
+
+def default_project() -> Project:
+    """
+    Retrieves the default project from the API.
+
+    :return: A Project object representing the default project.
+    :raises HTTPError: If the API request fails.
+    """
+    with api_client() as client:
+        response = client.get("/user/me/default_project")
+        response.raise_for_status()
+        return Project(**response.json())

rowan/protein.py

@@ -0,0 +1,245 @@
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Self
+
+from pydantic import BaseModel
+
+from .utils import api_client
+
+
+class Protein(BaseModel):
+    """
+    A Rowan protein.
+
+    Data is not loaded by default to avoid unnecessary downloads that could impact performance.
+    Call `load_data()` to fetch and attach the protein data to this `Protein` object.
+
+    :ivar uuid: The UUID of the protein
+    :ivar created_at: The creation date of the protein
+    :ivar used_in_workflow: Whether the protein is used in a workflow
+    :ivar ancestor_uuid: The UUID of the ancestor protein
+    :ivar sanitized: Whether the protein is sanitized
+    :ivar name: The name of the protein
+    :ivar data: The data of the protein
+    :ivar public: Whether the protein is public
+    """
+
+    uuid: str
+    created_at: datetime | None = None
+    used_in_workflow: bool | None = None
+    ancestor_uuid: str | None = None
+    sanitized: int | None = None
+    name: str | None = None
+    data: dict | None = None
+    public: bool | None = None
+    pocket: list[list[float]] | None = None
+
+    def __repr__(self):
+        return f"<Protein name='{self.name}' created_at='{self.created_at}' uuid='{self.uuid}'>"
+
+    def refresh(self, in_place: bool = True) -> Self:
+        """
+        Loads protein data
+
+        :return: protein with loaded data
+        """
+        with api_client() as client:
+            response = client.get(f"/protein/{self.uuid}")
+            response.raise_for_status()
+            protein_data = response.json()
+            if not in_place:
+                return self.__class__.model_validate(protein_data)
+
+        self.name = protein_data.get("name")
+        self.data = protein_data.get("data")
+        self.public = protein_data.get("public")
+        self.pocket = protein_data.get("pocket")
+        self.sanitized = protein_data.get("sanitized")
+        self.used_in_workflow = protein_data.get("used_in_workflow")
+        return self
+
+    def update(
+        self,
+        name: str | None = None,
+        data: dict | None = None,
+        public: bool | None = None,
+        pocket: list[list[float]] | None = None,
+    ) -> Self:
+        # Use current values unless new ones are passed in
+        """
+        Updates protein data
+
+        :param name: The new name of the protein
+        :param data: The new data of the protein
+        :param public: Whether the protein is public
+        :param pocket: The new pocket of the protein
+        :return: The updated protein object
+        """
+        updated_payload = {
+            "name": name if name is not None else self.name,
+            "data": data if data is not None else self.data,
+            "public": public if public is not None else self.public,
+            "pocket": pocket if pocket is not None else self.pocket,
+        }
+
+        with api_client() as client:
+            response = client.post(f"/protein/{self.uuid}", json=updated_payload)
+            response.raise_for_status()
+            updated_data = response.json()
+
+        # Update attributes
+        self.name = updated_data.get("name")
+        self.data = updated_data.get("data")
+        self.public = updated_data.get("public")
+        self.pocket = updated_data.get("pocket")
+        return self
+
+    def delete(self) -> None:
+        """
+        Deletes a protein
+
+        :raises requests.HTTPError: if the request to the API fails
+        """
+        with api_client() as client:
+            response = client.delete(f"/protein/{self.uuid}")
+            response.raise_for_status()
+
+    def sanitize(self) -> None:
+        """
+        Sanitizes a protein
+
+        :raises requests.HTTPError: if the request to the API fails
+        """
+        with api_client() as client:
+            response = client.post(f"/protein/sanitize/{self.uuid}")
+            response.raise_for_status()
+
+    def download_pdb_file(self, path: Path | None = None, name: str | None = None) -> None:
+        """
+        Downloads the PDB file for a protein
+
+        :param path: Directory to save the file to (defaults to current directory)
+        :param name: Optional custom name for the file (defaults to protein name)
+        :raises requests.HTTPError: if the request to the API fails
+        """
+        if path is None:
+            path = Path.cwd()
+
+        path.mkdir(parents=True, exist_ok=True)
+
+        with api_client() as client:
+            response = client.get(f"/protein/{self.uuid}/get_pdb_file")
+            response.raise_for_status()
+
+        file_path = path / f"{name or self.name}.pdb"
+        with open(file_path, "wb") as f:
+            f.write(response.content)
+
+
+def retrieve_protein(uuid: str) -> Protein:
+    """
+    Retrieves a protein from the API using its UUID.
+
+    :param uuid: The UUID of the protein to retrieve.
+    :return: A Protein object representing the retrieved protein.
+    :raises requests.HTTPError: if the request to the API fails.
+    """
+
+    with api_client() as client:
+        response = client.get(f"/protein/{uuid}")
+        response.raise_for_status()
+        protein_data = response.json()
+
+    return Protein(**protein_data)
+
+
+def list_proteins(
+    ancestor_uuid: str | None = None,
+    name_contains: str | None = None,
+    page: int = 0,
+    size: int = 20,
+) -> list[Protein]:
+    """
+    List proteins
+
+    :param ancestor_uuid: The UUID of the ancestor protein to filter by
+    :param name_contains: Substring to search for in protein names
+    :param page: The page number to retrieve
+    :param size: The number of items per page
+    :return: A list of Protein objects that match the search criteria
+    :raises requests.HTTPError: if the request to the API fails
+    """
+    params: dict[str, Any] = {"page": page, "size": size}
+    if ancestor_uuid is not None:
+        params["ancestor_uuid"] = ancestor_uuid
+    if name_contains is not None:
+        params["name_contains"] = name_contains
+
+    with api_client() as client:
+        response = client.get("/protein", params=params)
+        response.raise_for_status()
+        results = response.json()["proteins"]
+
+    return [Protein(**item) for item in results]
+
+
+def upload_protein(name: str, file_path: Path, project_uuid: str | None = None) -> Protein:
+    """
+    Uploads a protein from a PDB file to the API.
+
+    :param name: The name of the protein to create
+    :param file_path: The path to the PDB file to upload
+    :return: A Protein object representing the uploaded protein
+    :raises requests.HTTPError: if the request to the API fails
+    """
+    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()  # Ensure the request was successful
+
+        # 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())
+
+
+def create_protein_from_pdb_id(name: str, code: str, project_uuid: str | None = None) -> Protein:
+    """
+    Creates a protein from a PDB ID.
+
+    :param name: The name of the protein to create
+    :param code: The PDB ID of the protein to create
+    :param project_uuid: The UUID of the project to create the protein in
+    :return: A Protein object representing the created protein
+    :raises requests.HTTPError: if the request to the API fails
+    """
+    with api_client() as client:
+        # Step 1: Read the file and post it to the conversion endpoint.
+        conversion_response = client.post(f"/convert/pdb_id_to_protein?pdb_id={code}")
+        conversion_response.raise_for_status()  # Ensure the request was successful
+
+        # 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/rowan_rdkit/__init__.py

@@ -0,0 +1,29 @@
+from .chem_utils import (
+    batch_charges,
+    batch_conformers,
+    batch_energy,
+    batch_optimize,
+    batch_pka,
+    batch_tautomers,
+    run_charges,
+    run_conformers,
+    run_energy,
+    run_optimize,
+    run_pka,
+    run_tautomers,
+)
+
+__all__ = [
+    "batch_charges",
+    "batch_conformers",
+    "batch_energy",
+    "batch_optimize",
+    "batch_pka",
+    "batch_tautomers",
+    "run_charges",
+    "run_conformers",
+    "run_energy",
+    "run_optimize",
+    "run_pka",
+    "run_tautomers",
+]