docs: add docstrings

Author: ankit-v2-3

videodb/audio.py

@@ -21,4 +21,10 @@ def __repr__(self) -> str:
         )
 
     def delete(self) -> None:
+        """Delete the audio.
+
+        :raises InvalidRequestError: If the delete fails
+        :return: None if the delete is successful
+        :rtype: None
+        """
         self._connection.delete(f"{ApiPath.audio}/{self.id}")

videodb/client.py

@@ -24,13 +24,29 @@
 
 
 class Connection(HttpClient):
+    """Connection class to interact with the VideoDB"""
+
     def __init__(self, api_key: str, base_url: str) -> None:
+        """Initializes a new instance of the Connection class with specified API credentials.
+
+        :param api_key: API key for authentication
+        :param str base_url: (optional) Base URL of the VideoDB API
+        :raise ValueError: If the API key is not provided
+        :return: connection object
+        :rtype: str
+        """
         self.api_key = api_key
         self.base_url = base_url
         self.collection_id = "default"
         super().__init__(api_key=api_key, base_url=base_url, version=__version__)
 
     def get_collection(self, collection_id: Optional[str] = "default") -> Collection:
+        """Get a collection object by its ID.
+
+        :param collection_id: ID of the collection
+        :return: :class:`Collection <Collection>` object
+        :rtype: :class:`videodb.collection.Collection`
+        """
         collection_data = self.get(path=f"{ApiPath.collection}/{collection_id}")
         self.collection_id = collection_data.get("id", "default")
         return Collection(
@@ -41,6 +57,11 @@ def get_collection(self, collection_id: Optional[str] = "default") -> Collection
         )
 
     def get_collections(self) -> List[Collection]:
+        """Get a list of all collections.
+
+        :return: List of :class:`Collection <Collection>` objects
+        :rtype: list[:class:`videodb.collection.Collection`]
+        """
         collections_data = self.get(path=ApiPath.collection)
         return [
             Collection(
@@ -53,6 +74,13 @@ def get_collections(self) -> List[Collection]:
         ]
 
     def create_collection(self, name: str, description: str) -> Collection:
+        """Create a new collection.
+
+        :param name: Name of the collection
+        :param description: Description of the collection
+        :return: :class:`Collection <Collection>` object
+        :rtype: :class:`videodb.collection.Collection`
+        """
         collection_data = self.post(
             path=ApiPath.collection,
             data={
@@ -69,6 +97,14 @@ def create_collection(self, name: str, description: str) -> Collection:
         )
 
     def update_collection(self, id: str, name: str, description: str) -> Collection:
+        """Update an existing collection.
+
+        :param str id: ID of the collection
+        :param name: Name of the collection
+        :param description: Description of the collection
+        :return: :class:`Collection <Collection>` object
+        :rtype: :class:`videodb.collection.Collection`
+        """
         collection_data = self.patch(
             path=f"{ApiPath.collection}/{id}",
             data={
@@ -85,9 +121,19 @@ def update_collection(self, id: str, name: str, description: str) -> Collection:
         )
 
     def check_usage(self) -> dict:
+        """Check the usage.
+
+        :return: Usage data
+        :rtype: dict
+        """
         return self.get(path=f"{ApiPath.billing}/{ApiPath.usage}")
 
     def get_invoices(self) -> List[dict]:
+        """Get a list of all invoices.
+
+        :return: List of invoices
+        :rtype: list of dict
+        """
         return self.get(path=f"{ApiPath.billing}/{ApiPath.invoices}")
 
     def upload(
@@ -99,6 +145,17 @@ def upload(
         description: Optional[str] = None,
         callback_url: Optional[str] = None,
     ) -> Union[Video, Audio, Image, None]:
+        """Upload a file.
+
+        :param file_path: Path to the file to upload
+        :param url: URL of the file to upload
+        :param MediaType media_type:(optional):class:`MediaType <MediaType>` object
+        :param name:(optional) Name of the file
+        :param description:(optional) Description of the file
+        :param callback_url:(optional) URL to receive the callback
+        :return: :class:`Video <Video>`, or :class:`Audio <Audio>`, or :class:`Image <Image>` object
+        :rtype: Union[ :class:`videodb.video.Video`, :class:`videodb.audio.Audio`, :class:`videodb.image.Image`]
+        """
         upload_data = upload(
             self,
             file_path,

videodb/collection.py

@@ -22,6 +22,8 @@
 
 
 class Collection:
+    """Collection class to interact with the Collection"""
+
     def __init__(self, _connection, id: str, name: str = None, description: str = None):
         self._connection = _connection
         self.id = id
@@ -37,20 +39,31 @@ def __repr__(self) -> str:
         )
 
     def get_videos(self) -> List[Video]:
+        """Get all the videos in the collection.
+
+        :return: List of :class:`Video <Video>` objects
+        :rtype: List[:class:`videodb.video.Video`]
+        """
         videos_data = self._connection.get(
             path=f"{ApiPath.video}",
             params={"collection_id": self.id},
         )
         return [Video(self._connection, **video) for video in videos_data.get("videos")]
 
     def get_video(self, video_id: str) -> Video:
+        """Get a video by its ID.
+
+        :param str video_id: ID of the video
+        :return: :class:`Video <Video>` object
+        :rtype: :class:`videodb.video.Video`
+        """
         video_data = self._connection.get(
             path=f"{ApiPath.video}/{video_id}", params={"collection_id": self.id}
         )
         return Video(self._connection, **video_data)
 
     def delete_video(self, video_id: str) -> None:
-        """Delete the video
+        """Delete the video.
 
         :param str video_id: The id of the video to be deleted
         :raises InvalidRequestError: If the delete fails
@@ -62,37 +75,73 @@ def delete_video(self, video_id: str) -> None:
         )
 
     def get_audios(self) -> List[Audio]:
+        """Get all the audios in the collection.
+
+        :return: List of :class:`Audio <Audio>` objects
+        :rtype: List[:class:`videodb.audio.Audio`]
+        """
         audios_data = self._connection.get(
             path=f"{ApiPath.audio}",
             params={"collection_id": self.id},
         )
         return [Audio(self._connection, **audio) for audio in audios_data.get("audios")]
 
     def get_audio(self, audio_id: str) -> Audio:
+        """Get an audio by its ID.
+
+        :param str audio_id: ID of the audio
+        :return: :class:`Audio <Audio>` object
+        :rtype: :class:`videodb.audio.Audio`
+        """
         audio_data = self._connection.get(
             path=f"{ApiPath.audio}/{audio_id}", params={"collection_id": self.id}
         )
         return Audio(self._connection, **audio_data)
 
     def delete_audio(self, audio_id: str) -> None:
+        """Delete the audio.
+
+        :param str audio_id: The id of the audio to be deleted
+        :raises InvalidRequestError: If the delete fails
+        :return: None if the delete is successful
+        :rtype: None
+        """
         return self._connection.delete(
             path=f"{ApiPath.audio}/{audio_id}", params={"collection_id": self.id}
         )
 
     def get_images(self) -> List[Image]:
+        """Get all the images in the collection.
+
+        :return: List of :class:`Image <Image>` objects
+        :rtype: List[:class:`videodb.image.Image`]
+        """
         images_data = self._connection.get(
             path=f"{ApiPath.image}",
             params={"collection_id": self.id},
         )
         return [Image(self._connection, **image) for image in images_data.get("images")]
 
     def get_image(self, image_id: str) -> Image:
+        """Get an image by its ID.
+
+        :param str image_id: ID of the image
+        :return: :class:`Image <Image>` object
+        :rtype: :class:`videodb.image.Image`
+        """
         image_data = self._connection.get(
             path=f"{ApiPath.image}/{image_id}", params={"collection_id": self.id}
         )
         return Image(self._connection, **image_data)
 
     def delete_image(self, image_id: str) -> None:
+        """Delete the image.
+
+        :param str image_id: The id of the image to be deleted
+        :raises InvalidRequestError: If the delete fails
+        :return: None if the delete is successful
+        :rtype: None
+        """
         return self._connection.delete(
             path=f"{ApiPath.image}/{image_id}", params={"collection_id": self.id}
         )
@@ -106,6 +155,18 @@ def search(
         score_threshold: Optional[float] = None,
         dynamic_score_percentage: Optional[float] = None,
     ) -> SearchResult:
+        """Search for a query in the collection.
+
+        :param str query: Query to search for
+        :param search_type:(optional) Type of search to perform :class:`SearchType <SearchType>` object
+        :param index_type:(optional) Type of index to search :class:`IndexType <IndexType>` object
+        :param int result_threshold:(optional) Number of results to return
+        :param float score_threshold:(optional) Threshold score for the search
+        :param float dynamic_score_percentage:(optional) Percentage of dynamic score to consider
+        :raise SearchError: If the search fails
+        :return: :class:`SearchResult <SearchResult>` object
+        :rtype: :class:`videodb.search.SearchResult`
+        """
         search = SearchFactory(self._connection).get_search(search_type)
         return search.search_inside_collection(
             collection_id=self.id,
@@ -126,6 +187,17 @@ def upload(
         description: Optional[str] = None,
         callback_url: Optional[str] = None,
     ) -> Union[Video, Audio, Image, None]:
+        """Upload a file to the collection.
+
+        :param str file_path: Path to the file to be uploaded
+        :param str url: URL of the file to be uploaded
+        :param MediaType media_type:(optional):class:`MediaType <MediaType>` object
+        :param name:(optional) Name of the file
+        :param description:(optional) Description of the file
+        :param callback_url:(optional) URL to receive the callback
+        :return: :class:`Video <Video>`, or :class:`Audio <Audio>`, or :class:`Image <Image>` object
+        Union[ :class:`videodb.video.Video`, :class:`videodb.audio.Audio`, :class:`videodb.image.Image`]
+        """
         upload_data = upload(
             self._connection,
             file_path,

videodb/image.py

@@ -21,6 +21,12 @@ def __repr__(self) -> str:
         )
 
     def delete(self) -> None:
+        """Delete the image.
+
+        :raises InvalidRequestError: If the delete fails
+        :return: None if the delete is successful
+        :rtype: None
+        """
         self._connection.delete(f"{ApiPath.image}/{self.id}")
 
 
@@ -63,6 +69,13 @@ def to_json(self):
         }
 
     def describe(self, prompt: str = None, model_name=None):
+        """Describe the frame.
+
+        :param str prompt: (optional) The prompt to use for the description
+        :param str model_name: (optional) The model to use for the description
+        :return: The description of the frame
+        :rtype: str
+        """
         description_data = self._connection.post(
             path=f"{ApiPath.video}/{self.video_id}/{ApiPath.frame}/{self.id}/{ApiPath.describe}",
             data={"prompt": prompt, "model_name": model_name},

videodb/scene.py

@@ -46,6 +46,13 @@ def to_json(self):
         }
 
     def describe(self, prompt: str = None, model_name=None) -> None:
+        """Describe the scene.
+
+        :param str prompt: (optional) The prompt to use for the description
+        :param str model_name: (optional) The model to use for the description
+        :return: The description of the scene
+        :rtype: str
+        """
         if self._connection is None:
             raise ValueError("Connection is required to describe a scene")
         description_data = self._connection.post(
@@ -81,6 +88,12 @@ def __repr__(self) -> str:
         )
 
     def delete(self) -> None:
+        """Delete the scene collection.
+
+        :raises InvalidRequestError: If the delete fails
+        :return: None if the delete is successful
+        :rtype: None
+        """
         self._connection.delete(
             path=f"{ApiPath.video}/{self.video_id}/{ApiPath.scenes}/{self.id}"
         )

videodb/search.py

@@ -53,7 +53,7 @@ def get_shots(self) -> List[Shot]:
         return self.shots
 
     def compile(self) -> str:
-        """Compile the search result shots into a stream url
+        """Compile the search result shots into a stream url.
 
         :raises SearchError: If no shots are found in the search results
         :return: The stream url
@@ -81,7 +81,7 @@ def compile(self) -> str:
             raise SearchError("No shots found in search results to compile")
 
     def play(self) -> str:
-        """Generate a stream url for the shot and open it in the default browser
+        """Generate a stream url for the shot and open it in the default browser.
 
         :return: The stream url
         :rtype: str

videodb/shot.py

@@ -51,7 +51,7 @@ def __getitem__(self, key):
         return self.__dict__[key]
 
     def generate_stream(self) -> str:
-        """Generate a stream url for the shot
+        """Generate a stream url for the shot.
 
         :return: The stream url
         :rtype: str
@@ -72,7 +72,7 @@ def generate_stream(self) -> str:
             return self.stream_url
 
     def play(self) -> str:
-        """Generate a stream url for the shot and open it in the default browser/ notebook
+        """Generate a stream url for the shot and open it in the default browser/ notebook.
 
         :return: The stream url
         :rtype: str