Feature: HTTP DELETE node

src/cript/api/api.py

@@ -14,6 +14,7 @@
 
 from cript.api.api_config import _API_TIMEOUT
 from cript.api.exceptions import (
+    APIError,
     CRIPTAPIRequiredError,
     CRIPTAPISaveError,
     CRIPTConnectionError,
@@ -55,27 +56,11 @@ class API:
     """
     ## Definition
     API Client class to communicate with the CRIPT API
-
-    Attributes
-    ----------
-    verbose : bool
-        A boolean flag that controls whether verbose logging is enabled or not.
-
-        When `verbose` is set to `True`, the class will provide additional detailed logging
-        to the terminal. This can be useful for debugging and understanding the internal
-        workings of the class.
-
-        When `verbose` is set to `False`, the class will only provide essential and concise
-        logging information, making the terminal output less cluttered and more user-friendly.
-
-        ```python
-        # turn off the terminal logs
-        api.verbose = False
-        ```
     """
 
     # dictates whether the user wants to see terminal log statements or not
-    verbose: bool = True
+    _verbose: bool = True
+    logger: logging.Logger = None  # type: ignore
 
     _host: str = ""
     _api_token: str = ""
@@ -242,6 +227,9 @@ def __init__(self, host: Union[str, None] = None, api_token: Union[str, None] =
 
         self._get_db_schema()
 
+        # set a logger instance to use for the class logs
+        self._set_logger()
+
     def __str__(self) -> str:
         """
         States the host of the CRIPT API client
@@ -252,6 +240,93 @@ def __str__(self) -> str:
         """
         return f"CRIPT API Client - Host URL: '{self.host}'"
 
+    def _set_logger(self, verbose: bool = True) -> None:
+        """
+        Prepare and configure the logger for the API class.
+
+        This function creates and configures a logger instance associated with the current module (class).
+
+        Parameters
+        ----------
+        verbose: bool default True
+            set if you want `cript.API` to give logs to console or not
+
+        Returns
+        -------
+        logging.Logger
+            The configured logger instance.
+        """
+        # Create a logger instance associated with the current module
+        logger = logging.getLogger(__name__)
+
+        # Set the logger's level based on the verbose flag
+        if verbose:
+            logger.setLevel(logging.INFO)  # Display INFO logs
+        else:
+            logger.setLevel(logging.CRITICAL)  # Display no logs
+
+        # Create a console handler
+        console_handler = logging.StreamHandler()
+
+        # Create a formatter for log messages (customize the format as desired)
+        formatter = logging.Formatter("%(levelname)s: %(message)s")
+
+        # Associate the formatter with the console handler
+        console_handler.setFormatter(formatter)
+
+        # Add the console handler to the logger
+        logger.addHandler(console_handler)
+
+        # set logger for the class
+        self.logger = logger
+
+    @property
+    def verbose(self) -> bool:
+        """
+        A boolean flag that controls whether verbose logging is enabled or not.
+
+        When `verbose` is set to `True`, the class will provide additional detailed logging
+        to the terminal. This can be useful for debugging and understanding the internal
+        workings of the class.
+
+        ```bash
+        INFO: Validating Project graph...
+        ```
+
+        When `verbose` is set to `False`, the class will only provide essential logging information,
+        making the terminal output less cluttered and more user-friendly.
+
+        Examples
+        --------
+        ```python
+        # turn off the terminal logs
+        api.verbose = False
+        ```
+
+        Returns
+        -------
+        bool
+            verbose boolean value
+        """
+        return self._verbose
+
+    @verbose.setter
+    def verbose(self, new_verbose_value: bool) -> None:
+        """
+        sets the verbose value and then sets a new logger for the class
+
+        Parameters
+        ----------
+        new_verbose_value: bool
+            new verbose value to turn the logging ON or OFF
+
+        Returns
+        -------
+        None
+        """
+        self._verbose = new_verbose_value
+        self._set_logger(verbose=new_verbose_value)
+
     @beartype
     def _prepare_host(self, host: str) -> str:
         # strip ending slash to make host always uniform
@@ -349,10 +424,10 @@ def host(self):
 
         The term "host" designates the specific CRIPT instance to which you intend to upload your data.
 
-        For most users, the host will be `criptapp.org`
+        For most users, the host will be `api.criptapp.org`
 
         ```yaml
-        host: criptapp.org
+        host: api.criptapp.org
         ```
 
         Examples
@@ -572,11 +647,9 @@ def _is_node_schema_valid(self, node_json: str, is_patch: bool = False) -> bool:
 
         node_dict = json.loads(node_json)
 
-        if self.verbose:
-            # logging out info to the terminal for the user feedback
-            # (improve UX because the program is currently slow)
-            logging.basicConfig(format="%(levelname)s: %(message)s", level=logging.INFO)
-            logging.info(f"Validating {node_type} graph...")
+        # logging out info to the terminal for the user feedback
+        # (improve UX because the program is currently slow)
+        self.logger.info(f"Validating {node_type} graph...")
 
         # set the schema to test against http POST or PATCH of DB Schema
         schema_http_method: str
@@ -974,3 +1047,60 @@ def search(
             raise RuntimeError("Internal Error: Failed to recognize any search modes. Please report this bug on https://github.com/C-Accel-CRIPT/Python-SDK/issues.")
 
         return Paginator(http_headers=self._http_headers, api_endpoint=api_endpoint, query=value_to_search, current_page_number=page_number)
+
+    def delete(self, node) -> None:
+        """
+        Simply deletes the desired node from the CRIPT API and writes a log in the terminal that the node has been
+        successfully deleted.
+
+        Examples
+        --------
+        ```python
+        api.delete(node=my_material_node)
+        ```
+
+        Notes
+        -----
+        After the node has been successfully deleted, a log is written to the terminal if `cript.API.verbose = True`
+
+        ```bash
+        INFO: Deleted `Data` with UUID of `80bfc642-157e-4692-a547-97c470725397` from CRIPT API.
+        ```
+
+        Warnings
+        --------
+        After successfully deleting a node from the API, keep in mind that your local Project node in your script
+        may still contain outdated data as it has not been synced with the API.
+
+        To ensure you have the latest data, follow these steps:
+
+        1. Fetch the newest Project node from the API using the [`cript.API.search()`](./#cript.api.api.API.search) provided by the SDK.
+        1. Deserialize the retrieved data into a new Project node using the [`load_nodes_from_json`](../../utility_functions/#cript.nodes.util.load_nodes_from_json) utility function.
+        1. Replace your old Project node with the new one in your script for accurate and up-to-date information.
+
+        Parameters
+        ----------
+        node: UUIDBaseNode
+            The node that you want to delete
+
+        Raises
+        ------
+        APIError
+            If the API responds with anything other than HTTP status 200, then the CRIPT Python SDK raises `APIError`
+            `APIError` is raised in case the API cannot delete the specified node.
+            Such cases can happen if you do not have permission to delete the node
+            or if the node is actively being used elsewhere in CRIPT platform and the API cannot delete it.
+
+        Returns
+        -------
+        None
+        """
+
+        delete_node_api_url: str = f"{self._host}/{node.node_type_snake_case}/{node.uuid}/"
+
+        response: Dict = requests.delete(headers=self._http_headers, url=delete_node_api_url, timeout=_API_TIMEOUT).json()
+
+        if response["code"] != 200:
+            raise APIError(api_error=str(response), http_method="DELETE", api_url=delete_node_api_url)
+
+        self.logger.info(f"Deleted `{node.node_type}` with UUID of `{node.uuid}` from CRIPT API.")

src/cript/api/exceptions.py

@@ -1,5 +1,5 @@
 import json
-from typing import List, Set
+from typing import List, Optional, Set
 
 from cript.exceptions import CRIPTException
 
@@ -214,13 +214,28 @@ class APIError(CRIPTException):
 
     api_error: str = ""
 
-    def __init__(self, api_error: str) -> None:
+    # having the URL that the API gave an error for helps in debugging
+    api_url: Optional[str] = None
+    http_method: Optional[str] = None
+
+    def __init__(self, api_error: str, http_method: Optional[str] = None, api_url: Optional[str] = None) -> None:
         self.api_error = api_error
 
-    def __str__(self) -> str:
-        error_message: str = f"The API responded with {self.api_error}"
+        self.api_url = api_url
 
-        return error_message
+        # TODO consider having an enum for all the HTTP methods so they are easily entered and disallows anything
+        #   that would be not make sense
+        self.http_method = http_method
+
+    def __str__(self) -> str:
+        # TODO refactor all of SDK using this error to be used the same to avoid this logic and Optional attributes
+        # this logic currently exists to make previous SDK work
+
+        # if you have the URL then display it, otherwise just show the error message
+        if self.api_url and self.http_method:
+            return f"CRIPT Python SDK sent HTTP `{self.http_method.upper()}` request to URL: `{self.api_url}` and API responded with {self.api_error}"
+        else:
+            return f"The API responded with: {self.api_error}"
 
 
 class FileDownloadError(CRIPTException):

src/cript/api/paginator.py

@@ -6,6 +6,7 @@
 from beartype import beartype
 
 from cript.api.api_config import _API_TIMEOUT
+from cript.api.exceptions import APIError
 
 
 class Paginator:
@@ -225,8 +226,7 @@ def fetch_page_from_api(self) -> List[dict]:
             self.current_page_results = []
             return self.current_page_results
 
-        # TODO give a CRIPT error if HTTP response is anything other than 200
         if api_response["code"] != 200:
-            raise Exception(f"API responded with: {api_response['error']}")
+            raise APIError(api_error=str(response), http_method="GET", api_url=temp_api_endpoint)
 
         return self.current_page_results

tests/integration_test_helper.py

@@ -5,6 +5,7 @@
 from deepdiff import DeepDiff
 
 import cript
+from cript.nodes.uuid_base import UUIDBaseNode
 
 
 def integrate_nodes_helper(cript_api: cript.API, project_node: cript.Project):
@@ -96,3 +97,47 @@ def integrate_nodes_helper(cript_api: cript.API, project_node: cript.Project):
     print(my_project_from_api.get_json(sort_keys=False, condense_to_uuid={}, indent=2).json)
     print("==============================================================")
     print("\n\n\n######################################## TEST Passed ########################################\n\n\n")
+
+
+def delete_integration_node_helper(cript_api: cript.API, node_to_delete: UUIDBaseNode) -> None:
+    """
+    1. takes the node/sub-object that needs to be deleted
+    1. checks that it first exists on the API before deleting
+    1. sends an HTTP DELETE to API
+    1. asserts that the API response is 200
+        > This is done under the hood in the `cript.API.delete()`
+        method where at the end it checks that the response is 200, else raises an error
+    1. tries to get the same node via UUID from the API and expects that it should fail
+
+    Notes
+    ------
+    > for future this test should also take the project that the node was in, get the project again,
+    > and compare that the node was successfully deleted/missing from the project
+
+    > within search we can also add assert statements to be sure that the API gave the same node
+    > that we searched for. Not needed at the time of writing this test
+    """
+
+    if not HAS_INTEGRATION_TESTS_ENABLED:
+        pytest.skip("DELETE integration tests with API requires real API and Storage token")
+        return
+
+    # check that the node we want to delete first exists on the API
+    my_node_paginator = cript_api.search(
+        # passing in the full node to get the node type from
+        node_type=node_to_delete,
+        search_mode=cript.SearchModes.UUID,
+        value_to_search=str(node_to_delete.uuid),
+    )
+
+    # be sure API returned at least one result for the node that we searched for
+    assert len(my_node_paginator.current_page_results) == 1
+
+    # DELETE the node from the API
+    cript_api.delete(node=node_to_delete)
+
+    # should not be able to get node by UUID anymore because it is deleted
+    deleted_node_paginator = cript_api.search(node_type=node_to_delete, search_mode=cript.SearchModes.UUID, value_to_search=str(node_to_delete.uuid))
+
+    # be sure API responded with empty results
+    assert len(deleted_node_paginator.current_page_results) == 0

tests/nodes/primary_nodes/test_collection.py

@@ -2,7 +2,10 @@
 import json
 import uuid
 
-from integration_test_helper import integrate_nodes_helper
+from integration_test_helper import (
+    delete_integration_node_helper,
+    integrate_nodes_helper,
+)
 from util import strip_uid_from_dict
 
 import cript
@@ -182,3 +185,6 @@ def test_integration_collection(cript_api, simple_project_node, simple_collectio
     # simple_project_node.collection[0].notes = "my collection notes UPDATED"
 
     integrate_nodes_helper(cript_api=cript_api, project_node=simple_project_node)
+
+    # ========= test delete =========
+    delete_integration_node_helper(cript_api=cript_api, node_to_delete=simple_collection_node)

tests/nodes/primary_nodes/test_computation.py

@@ -2,7 +2,10 @@
 import json
 import uuid
 
-from integration_test_helper import integrate_nodes_helper
+from integration_test_helper import (
+    delete_integration_node_helper,
+    integrate_nodes_helper,
+)
 from util import strip_uid_from_dict
 
 import cript
@@ -143,3 +146,6 @@ def test_integration_computation(cript_api, simple_project_node, simple_computat
     simple_project_node.collection[0].experiment[0].computation[0].type = "data_fit"
 
     integrate_nodes_helper(cript_api=cript_api, project_node=simple_project_node)
+
+    # ========= test delete =========
+    delete_integration_node_helper(cript_api=cript_api, node_to_delete=simple_computation_node)