refactor more docs

Author: 0xrohitgarg

videodb/_constants.py

@@ -1,4 +1,5 @@
 """Constants used in the videodb package."""
+
 from typing import Union
 from dataclasses import dataclass
 

videodb/audio.py

@@ -4,7 +4,17 @@
 
 
 class Audio:
-    def __init__(self, _connection, id: str, collection_id: str, **kwargs) -> None:
+    """Audio class to interact with the Audio
+
+    :ivar str id: Unique identifier for the audio
+    :ivar str collection_id: ID of the collection this audio belongs to
+    :ivar str name: Name of the audio file
+    :ivar float length: Duration of the audio in seconds
+    """
+
+    def __init__(
+        self, _connection, id: str, collection_id: str, **kwargs
+    ) -> None:
         self._connection = _connection
         self.id = id
         self.collection_id = collection_id
@@ -21,6 +31,12 @@ def __repr__(self) -> str:
         )
 
     def generate_url(self) -> str:
+        """Generate the signed url of the audio.
+
+        :raises InvalidRequestError: If the get_url fails
+        :return: The signed url of the audio
+        :rtype: str
+        """
         url_data = self._connection.post(
             path=f"{ApiPath.audio}/{self.id}/{ApiPath.generate_url}",
             params={"collection_id": self.collection_id},

videodb/client.py

@@ -26,11 +26,14 @@
 class Connection(HttpClient):
     """Connection class to interact with the VideoDB"""
 
-    def __init__(self, api_key: str, base_url: str) -> None:
+    def __init__(self, api_key: str, base_url: str) -> "Connection":
         """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
+        Note: Users should not initialize this class directly.
+        Instead use :meth:`videodb.connect() <videodb.connect>`
+
+        :param str api_key: API key for authentication
+        :param str base_url: Base URL of the VideoDB API
         :raise ValueError: If the API key is not provided
         :return: :class:`Connection <Connection>` object, to interact with the VideoDB
         :rtype: :class:`videodb.client.Connection`
@@ -43,7 +46,7 @@ def __init__(self, api_key: str, base_url: str) -> None:
     def get_collection(self, collection_id: Optional[str] = "default") -> Collection:
         """Get a collection object by its ID.
 
-        :param collection_id: ID of the collection
+        :param str collection_id: ID of the collection (optional, default: "default")
         :return: :class:`Collection <Collection>` object
         :rtype: :class:`videodb.collection.Collection`
         """
@@ -80,9 +83,9 @@ def create_collection(
     ) -> Collection:
         """Create a new collection.
 
-        :param name: Name of the collection
-        :param description: Description of the collection
-        :param is_public: Make collection public
+        :param str name: Name of the collection
+        :param str description: Description of the collection
+        :param bool is_public: Make collection public (optional, default: False)
         :return: :class:`Collection <Collection>` object
         :rtype: :class:`videodb.collection.Collection`
         """
@@ -107,8 +110,8 @@ 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
+        :param str name: Name of the collection 
+        :param str description: Description of the collection
         :return: :class:`Collection <Collection>` object
         :rtype: :class:`videodb.collection.Collection`
         """
@@ -140,7 +143,7 @@ def get_invoices(self) -> List[dict]:
         """Get a list of all invoices.
 
         :return: List of invoices
-        :rtype: list of dict
+        :rtype: list[dict]
         """
         return self.get(path=f"{ApiPath.billing}/{ApiPath.invoices}")
 
@@ -171,12 +174,12 @@ def upload(
     ) -> 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) 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
+        :param str file_path: Path to the file to upload (optional)
+        :param str url: URL of the file to upload (optional)
+        :param MediaType media_type: MediaType object (optional)
+        :param str name: Name of the file (optional)
+        :param str description: Description of the file (optional)
+        :param str callback_url: URL to receive the callback (optional)
         :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`]
         """

videodb/collection.py

@@ -24,7 +24,11 @@
 
 
 class Collection:
-    """Collection class to interact with the Collection"""
+    """Collection class to interact with the Collection.
+
+    Note: Users should not initialize this class directly.
+    Instead use :meth:`Connection.get_collection() <videodb.client.Connection.get_collection>`
+    """
 
     def __init__(
         self,
@@ -179,11 +183,11 @@ def search(
         """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
+        :param SearchType search_type: Type of search to perform (optional)
+        :param IndexType index_type: Type of index to search (optional)
+        :param int result_threshold: Number of results to return (optional)
+        :param float score_threshold: Threshold score for the search (optional)
+        :param float dynamic_score_percentage: Percentage of dynamic score to consider (optional)
         :raise SearchError: If the search fails
         :return: :class:`SearchResult <SearchResult>` object
         :rtype: :class:`videodb.search.SearchResult`
@@ -226,12 +230,12 @@ def upload(
 
         :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
+        :param MediaType media_type: MediaType object (optional)
+        :param str name: Name of the file (optional)
+        :param str description: Description of the file (optional)
+        :param str callback_url: URL to receive the callback (optional)
         :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`]
+        :rtype: Union[ :class:`videodb.video.Video`, :class:`videodb.audio.Audio`, :class:`videodb.image.Image`]
         """
         upload_data = upload(
             self._connection,
@@ -251,12 +255,22 @@ def upload(
             return Image(self._connection, **upload_data)
 
     def make_public(self):
+        """Make the collection public.
+
+        :return: None
+        :rtype: None
+        """
         self._connection.patch(
             path=f"{ApiPath.collection}/{self.id}", data={"is_public": True}
         )
         self.is_public = True
 
     def make_private(self):
+        """Make the collection private.
+
+        :return: None
+        :rtype: None
+        """
         self._connection.patch(
             path=f"{ApiPath.collection}/{self.id}", data={"is_public": False}
         )

videodb/image.py

@@ -4,6 +4,14 @@
 
 
 class Image:
+    """Image class to interact with the Image
+
+    :ivar str id: Unique identifier for the image
+    :ivar str collection_id: ID of the collection this image belongs to 
+    :ivar str name: Name of the image file
+    :ivar str url: URL of the image
+    """
+
     def __init__(self, _connection, id: str, collection_id: str, **kwargs) -> None:
         self._connection = _connection
         self.id = id
@@ -21,6 +29,12 @@ def __repr__(self) -> str:
         )
 
     def generate_url(self) -> str:
+        """Generate the signed url of the image.
+
+        :raises InvalidRequestError: If the get_url fails
+        :return: The signed url of the image
+        :rtype: str
+        """
         url_data = self._connection.post(
             path=f"{ApiPath.image}/{self.id}/{ApiPath.generate_url}",
             params={"collection_id": self.collection_id},
@@ -38,6 +52,16 @@ def delete(self) -> None:
 
 
 class Frame(Image):
+    """Frame class to interact with video frames
+
+    :ivar str id: Unique identifier for the frame
+    :ivar str video_id: ID of the video this frame belongs to
+    :ivar str scene_id: ID of the scene this frame belongs to
+    :ivar str url: URL of the frame
+    :ivar float frame_time: Timestamp of the frame in the video
+    :ivar str description: Description of the frame contents
+    """
+
     def __init__(
         self,
         _connection,

videodb/scene.py

@@ -6,6 +6,16 @@
 
 
 class Scene:
+    """Scene class to interact with video scenes
+
+    :ivar str id: Unique identifier for the scene
+    :ivar str video_id: ID of the video this scene belongs to 
+    :ivar float start: Start time of the scene in seconds
+    :ivar float end: End time of the scene in seconds
+    :ivar List[Frame] frames: List of frames in the scene
+    :ivar str description: Description of the scene contents
+    """
+
     def __init__(
         self,
         video_id: str,
@@ -64,6 +74,14 @@ def describe(self, prompt: str = None, model_name=None) -> None:
 
 
 class SceneCollection:
+    """SceneCollection class to interact with collections of scenes
+
+    :ivar str id: Unique identifier for the scene collection
+    :ivar str video_id: ID of the video these scenes belong to
+    :ivar dict config: Configuration settings for the scene collection
+    :ivar List[Scene] scenes: List of scenes in the collection
+    """
+
     def __init__(
         self,
         _connection,

videodb/search.py

@@ -14,6 +14,14 @@
 
 
 class SearchResult:
+    """SearchResult class to interact with search results
+
+    :ivar str collection_id: ID of the collection this search result belongs to
+    :ivar str stream_url: URL to stream the search result
+    :ivar str player_url: URL to play the search result in a player
+    :ivar list[Shot] shots: List of shots in the search result
+    """
+
     def __init__(self, _connection, **kwargs):
         self._connection = _connection
         self.shots = []

videodb/shot.py

@@ -1,4 +1,3 @@
-"""This module contains the shot class"""
 
 
 from typing import Optional
@@ -9,7 +8,18 @@
 
 
 class Shot:
-    """A shot is a part of a video that contains a specific scene"""
+    """Shot class to interact with video shots
+
+    :ivar str video_id: Unique identifier for the video
+    :ivar float video_length: Duration of the video in seconds
+    :ivar str video_title: Title of the video
+    :ivar float start: Start time of the shot in seconds
+    :ivar float end: End time of the shot in seconds
+    :ivar str text: Text content of the shot
+    :ivar int search_score: Search relevance score
+    :ivar str stream_url: URL to stream the shot
+    :ivar str player_url: URL to play the shot in a player
+    """
 
     def __init__(
         self,