rowan-python 1.1.13__py3-none-any.whl → 2.0.0__py3-none-any.whl

rowan/__init__.py

@@ -1,12 +1,10 @@
 # ruff: noqa
 
 from . import utils
-from .client import compute
 
 from . import constants
 
-from .folder import Folder
-from .workflow import Workflow
-from .calculation import Calculation
-from .protein import Protein
-from .protein_cofolding import *
+from .folder import *
+from .workflow import *
+from .protein import *
+from .user import *

rowan/folder.py

@@ -1,95 +1,212 @@
-from typing import Any, Optional
+from datetime import datetime
+from typing import Any, Self
 
-import stjames
+from pydantic import BaseModel
 
 from .utils import api_client
 
 
-class Folder:
-    @classmethod
-    def create(
-        cls,
-        name: str,
-        parent_uuid: Optional[stjames.UUID] = None,
-        notes: str = "",
-        starred: bool = False,
-        public: bool = False,
-    ) -> dict[str, Any]:
-        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()
-            return response.json()
+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
 
-    @classmethod
-    def retrieve(cls, uuid: stjames.UUID) -> dict[str, Any]:
+    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/{uuid}")
+            response = client.get(f"/folder/{self.uuid}")
             response.raise_for_status()
-            return response.json()
+            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
 
-    @classmethod
     def update(
-        cls,
-        uuid: stjames.UUID,
-        name: Optional[str] = None,
-        parent_uuid: Optional[stjames.UUID] = None,
-        notes: Optional[str] = None,
-        starred: Optional[bool] = None,
-        public: Optional[bool] = None,
-    ) -> None:
-        old_data = cls.retrieve(uuid)
-
-        new_data = {
-            "name": name if name is not None else old_data["name"],
-            "parent_uuid": parent_uuid if parent_uuid is not None else old_data["parent_uuid"],
-            "notes": notes if notes is not None else old_data["notes"],
-            "starred": starred if starred is not None else old_data["starred"],
-            "public": public if public is not None else old_data["public"],
+        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/{uuid}", json=new_data)
+            response = client.post(f"/folder/{self.uuid}", json=payload)
             response.raise_for_status()
-            return response.json()
+            updated_data = response.json()
 
-    @classmethod
-    def delete(cls, uuid: stjames.UUID) -> None:
-        with api_client() as client:
-            response = client.delete(f"/folder/{uuid}")
-            response.raise_for_status()
+        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
 
-    @classmethod
-    def list(
-        cls,
-        parent_uuid: Optional[stjames.UUID] = None,
-        name_contains: Optional[str] = None,
-        public: Optional[bool] = None,
-        starred: Optional[bool] = None,
-        page: int = 0,
-        size: int = 10,
-    ) -> dict[str, Any]:
-        params: dict[str, Any] = {
-            "page": page,
-            "size": size,
-        }
-        # Only add optional parameters if they are not None
-        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
+    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.get("/folder", params=params)
+            response = client.delete(f"/folder/{self.uuid}")
             response.raise_for_status()
-            return response.json()
+
+
+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 home_folder() -> Folder:
+    """
+    Retrieves the home folder from the API.
+
+    :return: A Folder object representing the home folder.
+    :raises HTTPError: If the API request fails.
+    """
+    with api_client() as client:
+        response = client.get("/user/me/root_folders")
+        response.raise_for_status()
+        return Folder(**response.json()["user_root"])
+
+
+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)

rowan/protein.py

@@ -1,63 +1,215 @@
-from typing import Any, Optional
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Self
 
-import stjames
+from pydantic import BaseModel
 
 from .utils import api_client
 
 
-class Protein:
-    @classmethod
-    def retrieve(cls, uuid: stjames.UUID) -> dict:
+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/{uuid}")
+            response = client.get(f"/protein/{self.uuid}")
             response.raise_for_status()
-            return response.json()
+            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
 
-    @classmethod
     def update(
-        cls,
-        uuid: stjames.UUID,
-        name: Optional[str] = None,
-        data: Optional[dict] = None,
-        public: Optional[bool] = None,
-        pocket: Optional[list[list[float]]] = None,
-    ) -> None:
-        old_data = cls.retrieve(uuid)
-
-        new_data = {}
-        new_data["name"] = name if name is not None else old_data["name"]
-        new_data["data"] = data if data is not None else old_data["data"]
-        new_data["public"] = public if public is not None else old_data["public"]
-        new_data["pocket"] = pocket if pocket is not None else old_data["pocket"]
+        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
 
-        with api_client() as client:
-            response = client.post(f"/protein/{uuid}", json=new_data)
-            response.raise_for_status()
-            return response.json()
+        :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,
+        }
 
-    @classmethod
-    def delete(cls, uuid: stjames.UUID) -> None:
         with api_client() as client:
-            response = client.delete(f"/protein/{uuid}")
+            response = client.post(f"/protein/{self.uuid}", json=updated_payload)
             response.raise_for_status()
+            updated_data = response.json()
 
-    @classmethod
-    def list(
-        cls,
-        ancestor_uuid: Optional[stjames.UUID] = None,
-        name_contains: Optional[str] = None,
-        page: int = 0,
-        size: int = 20,
-    ):
-        params: dict[str, Any] = {"page": page, "size": size}
+        # 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
 
-        if ancestor_uuid is not None:
-            params["ancestor_uuid"] = ancestor_uuid
+    def delete(self) -> None:
+        """
+        Deletes a protein
 
-        if name_contains is not None:
-            params["name_contains"] = name_contains
+        :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.get("/protein", params=params)
+            response = client.post(f"/protein/sanitize/{self.uuid}")
             response.raise_for_status()
-            return response.json()
+
+
+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) -> 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, "ancestor_uuid": None}
+        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) -> 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
+    :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, "ancestor_uuid": None}
+        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())