Skip to content

Commit b7d7a66

Browse files
0xrohitgarg0xrohitgarg
authored
Merge pull request #1 from 0xrohitgarg/rohit/refactor-docstrings
Rohit/refactor docstrings
2 parents fbc857b + 401101d commit b7d7a66

File tree

9 files changed

+304
-11
lines changed

9 files changed

+304
-11
lines changed

‎videodb/audio.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,4 +28,10 @@ def generate_url(self) -> str:
2828
return url_data.get("signed_url", None)
2929

3030
def delete(self) -> None:
31+
"""Delete the audio.
32+
33+
:raises InvalidRequestError: If the delete fails
34+
:return: None if the delete is successful
35+
:rtype: None
36+
"""
3137
self._connection.delete(f"{ApiPath.audio}/{self.id}")

‎videodb/client.py‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,13 +24,29 @@
2424

2525

2626
class Connection(HttpClient):
27+
"""Connection class to interact with the VideoDB"""
28+
2729
def __init__(self, api_key: str, base_url: str) -> None:
30+
"""Initializes a new instance of the Connection class with specified API credentials.
31+
32+
:param api_key: API key for authentication
33+
:param str base_url: (optional) Base URL of the VideoDB API
34+
:raise ValueError: If the API key is not provided
35+
:return: :class:`Connection <Connection>` object, to interact with the VideoDB
36+
:rtype: :class:`videodb.client.Connection`
37+
"""
2838
self.api_key = api_key
2939
self.base_url = base_url
3040
self.collection_id = "default"
3141
super().__init__(api_key=api_key, base_url=base_url, version=__version__)
3242

3343
def get_collection(self, collection_id: Optional[str] = "default") -> Collection:
44+
"""Get a collection object by its ID.
45+
46+
:param collection_id: ID of the collection
47+
:return: :class:`Collection <Collection>` object
48+
:rtype: :class:`videodb.collection.Collection`
49+
"""
3450
collection_data = self.get(path=f"{ApiPath.collection}/{collection_id}")
3551
self.collection_id = collection_data.get("id", "default")
3652
return Collection(
@@ -42,6 +58,11 @@ def get_collection(self, collection_id: Optional[str] = "default") -> Collection
4258
)
4359

4460
def get_collections(self) -> List[Collection]:
61+
"""Get a list of all collections.
62+
63+
:return: List of :class:`Collection <Collection>` objects
64+
:rtype: list[:class:`videodb.collection.Collection`]
65+
"""
4566
collections_data = self.get(path=ApiPath.collection)
4667
return [
4768
Collection(
@@ -57,6 +78,14 @@ def get_collections(self) -> List[Collection]:
5778
def create_collection(
5879
self, name: str, description: str, is_public: bool = False
5980
) -> Collection:
81+
"""Create a new collection.
82+
83+
:param name: Name of the collection
84+
:param description: Description of the collection
85+
:param is_public: Make collection public
86+
:return: :class:`Collection <Collection>` object
87+
:rtype: :class:`videodb.collection.Collection`
88+
"""
6089
collection_data = self.post(
6190
path=ApiPath.collection,
6291
data={
@@ -75,6 +104,14 @@ def create_collection(
75104
)
76105

77106
def update_collection(self, id: str, name: str, description: str) -> Collection:
107+
"""Update an existing collection.
108+
109+
:param str id: ID of the collection
110+
:param name: Name of the collection
111+
:param description: Description of the collection
112+
:return: :class:`Collection <Collection>` object
113+
:rtype: :class:`videodb.collection.Collection`
114+
"""
78115
collection_data = self.patch(
79116
path=f"{ApiPath.collection}/{id}",
80117
data={
@@ -92,9 +129,19 @@ def update_collection(self, id: str, name: str, description: str) -> Collection:
92129
)
93130

94131
def check_usage(self) -> dict:
132+
"""Check the usage.
133+
134+
:return: Usage data
135+
:rtype: dict
136+
"""
95137
return self.get(path=f"{ApiPath.billing}/{ApiPath.usage}")
96138

97139
def get_invoices(self) -> List[dict]:
140+
"""Get a list of all invoices.
141+
142+
:return: List of invoices
143+
:rtype: list of dict
144+
"""
98145
return self.get(path=f"{ApiPath.billing}/{ApiPath.invoices}")
99146

100147
def download(self, stream_link: str, name: str) -> dict:
@@ -115,6 +162,17 @@ def upload(
115162
description: Optional[str] = None,
116163
callback_url: Optional[str] = None,
117164
) -> Union[Video, Audio, Image, None]:
165+
"""Upload a file.
166+
167+
:param file_path: Path to the file to upload
168+
:param url: URL of the file to upload
169+
:param MediaType media_type:(optional):class:`MediaType <MediaType>` object
170+
:param name:(optional) Name of the file
171+
:param description:(optional) Description of the file
172+
:param callback_url:(optional) URL to receive the callback
173+
:return: :class:`Video <Video>`, or :class:`Audio <Audio>`, or :class:`Image <Image>` object
174+
:rtype: Union[ :class:`videodb.video.Video`, :class:`videodb.audio.Audio`, :class:`videodb.image.Image`]
175+
"""
118176
upload_data = upload(
119177
self,
120178
file_path,

‎videodb/collection.py‎

Lines changed: 73 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@
2424

2525

2626
class Collection:
27+
"""Collection class to interact with the Collection"""
28+
2729
def __init__(
2830
self,
2931
_connection,
@@ -57,20 +59,31 @@ def delete(self) -> None:
5759
self._connection.delete(path=f"{ApiPath.collection}/{self.id}")
5860

5961
def get_videos(self) -> List[Video]:
62+
"""Get all the videos in the collection.
63+
64+
:return: List of :class:`Video <Video>` objects
65+
:rtype: List[:class:`videodb.video.Video`]
66+
"""
6067
videos_data = self._connection.get(
6168
path=f"{ApiPath.video}",
6269
params={"collection_id": self.id},
6370
)
6471
return [Video(self._connection, **video) for video in videos_data.get("videos")]
6572

6673
def get_video(self, video_id: str) -> Video:
74+
"""Get a video by its ID.
75+
76+
:param str video_id: ID of the video
77+
:return: :class:`Video <Video>` object
78+
:rtype: :class:`videodb.video.Video`
79+
"""
6780
video_data = self._connection.get(
6881
path=f"{ApiPath.video}/{video_id}", params={"collection_id": self.id}
6982
)
7083
return Video(self._connection, **video_data)
7184

7285
def delete_video(self, video_id: str) -> None:
73-
"""Delete the video
86+
"""Delete the video.
7487
7588
:param str video_id: The id of the video to be deleted
7689
:raises InvalidRequestError: If the delete fails
@@ -82,37 +95,73 @@ def delete_video(self, video_id: str) -> None:
8295
)
8396

8497
def get_audios(self) -> List[Audio]:
98+
"""Get all the audios in the collection.
99+
100+
:return: List of :class:`Audio <Audio>` objects
101+
:rtype: List[:class:`videodb.audio.Audio`]
102+
"""
85103
audios_data = self._connection.get(
86104
path=f"{ApiPath.audio}",
87105
params={"collection_id": self.id},
88106
)
89107
return [Audio(self._connection, **audio) for audio in audios_data.get("audios")]
90108

91109
def get_audio(self, audio_id: str) -> Audio:
110+
"""Get an audio by its ID.
111+
112+
:param str audio_id: ID of the audio
113+
:return: :class:`Audio <Audio>` object
114+
:rtype: :class:`videodb.audio.Audio`
115+
"""
92116
audio_data = self._connection.get(
93117
path=f"{ApiPath.audio}/{audio_id}", params={"collection_id": self.id}
94118
)
95119
return Audio(self._connection, **audio_data)
96120

97121
def delete_audio(self, audio_id: str) -> None:
122+
"""Delete the audio.
123+
124+
:param str audio_id: The id of the audio to be deleted
125+
:raises InvalidRequestError: If the delete fails
126+
:return: None if the delete is successful
127+
:rtype: None
128+
"""
98129
return self._connection.delete(
99130
path=f"{ApiPath.audio}/{audio_id}", params={"collection_id": self.id}
100131
)
101132

102133
def get_images(self) -> List[Image]:
134+
"""Get all the images in the collection.
135+
136+
:return: List of :class:`Image <Image>` objects
137+
:rtype: List[:class:`videodb.image.Image`]
138+
"""
103139
images_data = self._connection.get(
104140
path=f"{ApiPath.image}",
105141
params={"collection_id": self.id},
106142
)
107143
return [Image(self._connection, **image) for image in images_data.get("images")]
108144

109145
def get_image(self, image_id: str) -> Image:
146+
"""Get an image by its ID.
147+
148+
:param str image_id: ID of the image
149+
:return: :class:`Image <Image>` object
150+
:rtype: :class:`videodb.image.Image`
151+
"""
110152
image_data = self._connection.get(
111153
path=f"{ApiPath.image}/{image_id}", params={"collection_id": self.id}
112154
)
113155
return Image(self._connection, **image_data)
114156

115157
def delete_image(self, image_id: str) -> None:
158+
"""Delete the image.
159+
160+
:param str image_id: The id of the image to be deleted
161+
:raises InvalidRequestError: If the delete fails
162+
:return: None if the delete is successful
163+
:rtype: None
164+
"""
116165
return self._connection.delete(
117166
path=f"{ApiPath.image}/{image_id}", params={"collection_id": self.id}
118167
)
@@ -127,6 +176,18 @@ def search(
127176
dynamic_score_percentage: Optional[float] = None,
128177
filter: List[Dict[str, Any]] = [],
129178
) -> SearchResult:
179+
"""Search for a query in the collection.
180+
181+
:param str query: Query to search for
182+
:param search_type:(optional) Type of search to perform :class:`SearchType <SearchType>` object
183+
:param index_type:(optional) Type of index to search :class:`IndexType <IndexType>` object
184+
:param int result_threshold:(optional) Number of results to return
185+
:param float score_threshold:(optional) Threshold score for the search
186+
:param float dynamic_score_percentage:(optional) Percentage of dynamic score to consider
187+
:raise SearchError: If the search fails
188+
:return: :class:`SearchResult <SearchResult>` object
189+
:rtype: :class:`videodb.search.SearchResult`
190+
"""
130191
search = SearchFactory(self._connection).get_search(search_type)
131192
return search.search_inside_collection(
132193
collection_id=self.id,
@@ -161,6 +222,17 @@ def upload(
161222
description: Optional[str] = None,
162223
callback_url: Optional[str] = None,
163224
) -> Union[Video, Audio, Image, None]:
225+
"""Upload a file to the collection.
226+
227+
:param str file_path: Path to the file to be uploaded
228+
:param str url: URL of the file to be uploaded
229+
:param MediaType media_type:(optional):class:`MediaType <MediaType>` object
230+
:param name:(optional) Name of the file
231+
:param description:(optional) Description of the file
232+
:param callback_url:(optional) URL to receive the callback
233+
:return: :class:`Video <Video>`, or :class:`Audio <Audio>`, or :class:`Image <Image>` object
234+
Union[ :class:`videodb.video.Video`, :class:`videodb.audio.Audio`, :class:`videodb.image.Image`]
235+
"""
164236
upload_data = upload(
165237
self._connection,
166238
file_path,

‎videodb/image.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,12 @@ def generate_url(self) -> str:
2828
return url_data.get("signed_url", None)
2929

3030
def delete(self) -> None:
31+
"""Delete the image.
32+
33+
:raises InvalidRequestError: If the delete fails
34+
:return: None if the delete is successful
35+
:rtype: None
36+
"""
3137
self._connection.delete(f"{ApiPath.image}/{self.id}")
3238

3339

@@ -70,6 +76,13 @@ def to_json(self):
7076
}
7177

7278
def describe(self, prompt: str = None, model_name=None):
79+
"""Describe the frame.
80+
81+
:param str prompt: (optional) The prompt to use for the description
82+
:param str model_name: (optional) The model to use for the description
83+
:return: The description of the frame
84+
:rtype: str
85+
"""
7386
description_data = self._connection.post(
7487
path=f"{ApiPath.video}/{self.video_id}/{ApiPath.frame}/{self.id}/{ApiPath.describe}",
7588
data={"prompt": prompt, "model_name": model_name},

‎videodb/scene.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,13 @@ def to_json(self):
4646
}
4747

4848
def describe(self, prompt: str = None, model_name=None) -> None:
49+
"""Describe the scene.
50+
51+
:param str prompt: (optional) The prompt to use for the description
52+
:param str model_name: (optional) The model to use for the description
53+
:return: The description of the scene
54+
:rtype: str
55+
"""
4956
if self._connection is None:
5057
raise ValueError("Connection is required to describe a scene")
5158
description_data = self._connection.post(
@@ -81,6 +88,12 @@ def __repr__(self) -> str:
8188
)
8289

8390
def delete(self) -> None:
91+
"""Delete the scene collection.
92+
93+
:raises InvalidRequestError: If the delete fails
94+
:return: None if the delete is successful
95+
:rtype: None
96+
"""
8497
self._connection.delete(
8598
path=f"{ApiPath.video}/{self.video_id}/{ApiPath.scenes}/{self.id}"
8699
)

‎videodb/search.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ def get_shots(self) -> List[Shot]:
5353
return self.shots
5454

5555
def compile(self) -> str:
56-
"""Compile the search result shots into a stream url
56+
"""Compile the search result shots into a stream url.
5757
5858
:raises SearchError: If no shots are found in the search results
5959
:return: The stream url
@@ -81,7 +81,7 @@ def compile(self) -> str:
8181
raise SearchError("No shots found in search results to compile")
8282

8383
def play(self) -> str:
84-
"""Generate a stream url for the shot and open it in the default browser
84+
"""Generate a stream url for the shot and open it in the default browser.
8585
8686
:return: The stream url
8787
:rtype: str

‎videodb/shot.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ def __getitem__(self, key):
5151
return self.__dict__[key]
5252

5353
def generate_stream(self) -> str:
54-
"""Generate a stream url for the shot
54+
"""Generate a stream url for the shot.
5555
5656
:return: The stream url
5757
:rtype: str
@@ -72,7 +72,7 @@ def generate_stream(self) -> str:
7272
return self.stream_url
7373

7474
def play(self) -> str:
75-
"""Generate a stream url for the shot and open it in the default browser/ notebook
75+
"""Generate a stream url for the shot and open it in the default browser/ notebook.
7676
7777
:return: The stream url
7878
:rtype: str

0 commit comments

Comments
 (0)