Added python docs for all methods.

YashPandit4u · YashPandit4u · commit 848972ef98c8 · 2024-06-01T21:33:23.000+05:30
diff --git a/ads/model/model_description.py b/ads/model/model_description.py
@@ -6,6 +6,7 @@
 import os
 from oci.data_science.models import Metadata
 import ads
+
 # from ads.common import logger
 import logging
 
@@ -14,6 +15,16 @@
 
 
 class ModelDescription:
+    """
+    Represents a model description for multi model artifacts. Provides methods to ease the process of creating such models.
+
+    Methods:
+    - add(namespace, bucket, prefix=None, files=None): Adds information about objects to the model description JSON.
+    - remove(namespace, bucket, prefix=None): Removes information about objects from the model description JSON.
+    - show(): Displays the current model description JSON in a human-readable format.
+    - build(): Builds the model description JSON and writes it to a file.
+    - save(project_ocid, compartment_ocid, display_name=None): Saves the model to the Model Catalog of OCI Data Science service.
+    """
 
     empty_json = {
         "version": "1.0",
@@ -22,6 +33,19 @@ class ModelDescription:
     }
 
     def auth(self):
+        """
+        Internal method that authenticates the model description instance by initializing OCI clients.
+
+        Parameters:
+        - None
+
+        Returns:
+        - None
+
+        Note:
+        - This method retrieves authentication data using default signer from the `ads.common.auth` module.
+        - The region information is extracted from the authentication data.
+        """
         authData = ads.common.auth.default_signer()
         signer = authData["signer"]
         self.region = authData["config"]["region"]
@@ -36,6 +60,29 @@ def auth(self):
         )
 
     def __init__(self, model_ocid=None):
+        """
+        Initializes a new instance of the ModelDescription class.
+
+        Parameters:
+        - model_ocid (str, optional): The OCID (Oracle Cloud Identifier) of the model.
+        If provided, retrieves the takes the model artifact content as starting point or else initializes from blank artifact.
+
+        Returns:
+        - None
+
+        Raises:
+        - json.JSONDecodeError: If there is an error decoding the JSON content retrieved
+        from the backend.
+        - Exception: If an unexpected error occurs while retrieving the model artifact content.
+
+        Note:
+        - If `model_ocid` is provided, this method attempts to retrieve the model artifact
+        content from the backend using the provided OCID. If successful, it initializes
+        `modelDescriptionJson` with the retrieved content. If unsuccessful, it logs the
+        error and raises an exception.
+        - If `model_ocid` is not provided, `modelDescriptionJson` is initialized with an
+        empty JSON structure.
+        """
 
         self.region = ""
         self.auth()
@@ -62,6 +109,28 @@ def __init__(self, model_ocid=None):
                 raise e
 
     def add(self, namespace, bucket, prefix=None, files=None):
+        """
+        Adds information about objects in a specified bucket to the model description JSON.
+
+        Parameters:
+        - namespace (str): The namespace of the object storage.
+        - bucket (str): The name of the bucket containing the objects.
+        - prefix (str, optional): The prefix used to filter objects within the bucket. Defaults to None.
+        - files (list of str, optional): A list of file names to include in the model description.
+        If provided, only objects with matching file names will be included. Defaults to None.
+
+        Returns:
+        - None
+
+        Raises:
+        - ValueError: If no files are found to add to the model description.
+
+        Note:
+        - If `files` is not provided, it retrieves information about all objects in the bucket.
+        If `files` is provided, it only retrieves information about objects with matching file names.
+        - If no objects are found to add to the model description, a ValueError is raised.
+        """
+
         # Remove if the model already exists
         self.remove(namespace, bucket, prefix)
 
@@ -137,6 +206,25 @@ def listObjectVersionsUnpaginated():
         )
 
     def remove(self, namespace, bucket, prefix=None):
+        """
+        Removes information about objects in a specified bucket from the model description JSON.
+
+        Parameters:
+        - namespace (str): The namespace of the object storage.
+        - bucket (str): The name of the bucket containing the objects.
+        - prefix (str, optional): The prefix used to filter objects within the bucket. Defaults to None.
+
+        Returns:
+        - None
+
+        Note:
+        - This method removes information about objects in the specified bucket from the
+        instance of the ModelDescription.
+        - If a matching model (with the specified namespace, bucket name, and prefix) is found
+        in the model description JSON, it is removed.
+        - If no matching model is found, the method returns without making any changes.
+        """
+
         def findModelIdx():
             for idx, model in enumerate(self.modelDescriptionJson["models"]):
                 if (
@@ -155,9 +243,34 @@ def findModelIdx():
             self.modelDescriptionJson["models"].pop(modelSearchIdx)
 
     def show(self):
+        """
+        Displays the current model description JSON in a human-readable format.
+
+        Parameters:
+        - None
+
+        Returns:
+        - None
+
+        Note:
+        - The JSON representation of the model description is formatted with an indentation
+        of 4 spaces.
+        """
         logger.info(json.dumps(self.modelDescriptionJson, indent=4))
 
     def build(self):
+        """
+        Builds the model description JSON and writes it to a file.
+
+        Parameters:
+        - None
+
+        Returns:
+        - str: The absolute file path where the model description JSON is stored.
+
+        Note:
+        - This method serializes the current model description attribute to a JSON file named 'resultModelDescription.json' with an indentation of 2 spaces.
+        """
         logger.info("Building...")
         file_path = "resultModelDescription.json"
         try:
@@ -171,10 +284,25 @@ def build(self):
             logger.error(
                 f"An unexpected error occurred: {e}"
             )  # Handle other unexpected exceptions
-        logger.info("Model Artifact stored at location: 'resultModelDescription.json'")
+        logger.info("Model Artifact stored successfully.")
         return os.path.abspath(file_path)
 
     def save(self, project_ocid, compartment_ocid, display_name=None):
+        """
+        Saves the model to the Model Catalog of Oracle Cloud Infrastructure (OCI) Data Science service.
+
+        Parameters:
+        - project_ocid (str): The OCID (Oracle Cloud Identifier) of the OCI Data Science project.
+        - compartment_ocid (str): The OCID of the compartment in which the model will be created.
+        - display_name (str, optional): The display name for the created model. If not provided,
+        a default display name indicating the creation timestamp is used. Defaults to None.
+
+        Returns:
+        - str: The OCID of the created model.
+
+        Note:
+        - The display name defaults to a string indicating the creation timestamp if not provided.
+        """
         display_name = (
             "Created by MMS SDK on "
             + datetime.datetime.now(pytz.utc).strftime("%Y-%m-%d %H:%M:%S %Z")
@@ -196,5 +324,5 @@ def save(self, project_ocid, compartment_ocid, display_name=None):
             json.dumps(self.modelDescriptionJson),
             content_disposition='attachment; filename="modelDescription.json"',
         )
-        logger.info("Successfully created model with OCID: ", model.data.id)
+        logger.info(f"Successfully created model with OCID: {model.data.id}")
         return model.data.id
