Skip to content

Commit f77ef48

Browse files
0xrohitgarg0xrohitgarg
committed
refactor more docs
1 parent 1950349 commit f77ef48

File tree

9 files changed

+181
-68
lines changed

9 files changed

+181
-68
lines changed

‎videodb/_constants.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
"""Constants used in the videodb package."""
2+
23
from typing import Union
34
from dataclasses import dataclass
45

‎videodb/audio.py

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,17 @@
44

55

66
class Audio:
7-
def __init__(self, _connection, id: str, collection_id: str, **kwargs) -> None:
7+
"""Audio class to interact with the Audio
8+
9+
:ivar str id: Unique identifier for the audio
10+
:ivar str collection_id: ID of the collection this audio belongs to
11+
:ivar str name: Name of the audio file
12+
:ivar float length: Duration of the audio in seconds
13+
"""
14+
15+
def __init__(
16+
self, _connection, id: str, collection_id: str, **kwargs
17+
) -> None:
818
self._connection = _connection
919
self.id = id
1020
self.collection_id = collection_id
@@ -21,6 +31,12 @@ def __repr__(self) -> str:
2131
)
2232

2333
def generate_url(self) -> str:
34+
"""Generate the signed url of the audio.
35+
36+
:raises InvalidRequestError: If the get_url fails
37+
:return: The signed url of the audio
38+
:rtype: str
39+
"""
2440
url_data = self._connection.post(
2541
path=f"{ApiPath.audio}/{self.id}/{ApiPath.generate_url}",
2642
params={"collection_id": self.collection_id},

‎videodb/client.py

Lines changed: 19 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,14 @@
2626
class Connection(HttpClient):
2727
"""Connection class to interact with the VideoDB"""
2828

29-
def __init__(self, api_key: str, base_url: str) -> None:
29+
def __init__(self, api_key: str, base_url: str) -> "Connection":
3030
"""Initializes a new instance of the Connection class with specified API credentials.
3131
32-
:param api_key: API key for authentication
33-
:param str base_url: (optional) Base URL of the VideoDB API
32+
Note: Users should not initialize this class directly.
33+
Instead use :meth:`videodb.connect() <videodb.connect>`
34+
35+
:param str api_key: API key for authentication
36+
:param str base_url: Base URL of the VideoDB API
3437
:raise ValueError: If the API key is not provided
3538
:return: :class:`Connection <Connection>` object, to interact with the VideoDB
3639
:rtype: :class:`videodb.client.Connection`
@@ -43,7 +46,7 @@ def __init__(self, api_key: str, base_url: str) -> None:
4346
def get_collection(self, collection_id: Optional[str] = "default") -> Collection:
4447
"""Get a collection object by its ID.
4548
46-
:param collection_id: ID of the collection
49+
:param str collection_id: ID of the collection (optional, default: "default")
4750
:return: :class:`Collection <Collection>` object
4851
:rtype: :class:`videodb.collection.Collection`
4952
"""
@@ -80,9 +83,9 @@ def create_collection(
8083
) -> Collection:
8184
"""Create a new collection.
8285
83-
:param name: Name of the collection
84-
:param description: Description of the collection
85-
:param is_public: Make collection public
86+
:param str name: Name of the collection
87+
:param str description: Description of the collection
88+
:param bool is_public: Make collection public (optional, default: False)
8689
:return: :class:`Collection <Collection>` object
8790
:rtype: :class:`videodb.collection.Collection`
8891
"""
@@ -107,8 +110,8 @@ def update_collection(self, id: str, name: str, description: str) -> Collection:
107110
"""Update an existing collection.
108111
109112
:param str id: ID of the collection
110-
:param name: Name of the collection
111-
:param description: Description of the collection
113+
:param str name: Name of the collection
114+
:param str description: Description of the collection
112115
:return: :class:`Collection <Collection>` object
113116
:rtype: :class:`videodb.collection.Collection`
114117
"""
@@ -140,7 +143,7 @@ def get_invoices(self) -> List[dict]:
140143
"""Get a list of all invoices.
141144
142145
:return: List of invoices
143-
:rtype: list of dict
146+
:rtype: list[dict]
144147
"""
145148
return self.get(path=f"{ApiPath.billing}/{ApiPath.invoices}")
146149

@@ -171,12 +174,12 @@ def upload(
171174
) -> Union[Video, Audio, Image, None]:
172175
"""Upload a file.
173176
174-
:param file_path: Path to the file to upload
175-
:param url: URL of the file to upload
176-
:param MediaType media_type:(optional) MediaType object
177-
:param name:(optional) Name of the file
178-
:param description:(optional) Description of the file
179-
:param callback_url:(optional) URL to receive the callback
177+
:param str file_path: Path to the file to upload (optional)
178+
:param str url: URL of the file to upload (optional)
179+
:param MediaType media_type: MediaType object (optional)
180+
:param str name: Name of the file (optional)
181+
:param str description: Description of the file (optional)
182+
:param str callback_url: URL to receive the callback (optional)
180183
:return: :class:`Video <Video>`, or :class:`Audio <Audio>`, or :class:`Image <Image>` object
181184
:rtype: Union[ :class:`videodb.video.Video`, :class:`videodb.audio.Audio`, :class:`videodb.image.Image`]
182185
"""

‎videodb/collection.py

Lines changed: 25 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,11 @@
2424

2525

2626
class Collection:
27-
"""Collection class to interact with the Collection"""
27+
"""Collection class to interact with the Collection.
28+
29+
Note: Users should not initialize this class directly.
30+
Instead use :meth:`Connection.get_collection() <videodb.client.Connection.get_collection>`
31+
"""
2832

2933
def __init__(
3034
self,
@@ -179,11 +183,11 @@ def search(
179183
"""Search for a query in the collection.
180184
181185
: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
186+
:param SearchType search_type: Type of search to perform (optional)
187+
:param IndexType index_type: Type of index to search (optional)
188+
:param int result_threshold: Number of results to return (optional)
189+
:param float score_threshold: Threshold score for the search (optional)
190+
:param float dynamic_score_percentage: Percentage of dynamic score to consider (optional)
187191
:raise SearchError: If the search fails
188192
:return: :class:`SearchResult <SearchResult>` object
189193
:rtype: :class:`videodb.search.SearchResult`
@@ -226,12 +230,12 @@ def upload(
226230
227231
:param str file_path: Path to the file to be uploaded
228232
: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+
:param MediaType media_type: MediaType object (optional)
234+
:param str name: Name of the file (optional)
235+
:param str description: Description of the file (optional)
236+
:param str callback_url: URL to receive the callback (optional)
233237
: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`]
238+
:rtype: Union[ :class:`videodb.video.Video`, :class:`videodb.audio.Audio`, :class:`videodb.image.Image`]
235239
"""
236240
upload_data = upload(
237241
self._connection,
@@ -251,12 +255,22 @@ def upload(
251255
return Image(self._connection, **upload_data)
252256

253257
def make_public(self):
258+
"""Make the collection public.
259+
260+
:return: None
261+
:rtype: None
262+
"""
254263
self._connection.patch(
255264
path=f"{ApiPath.collection}/{self.id}", data={"is_public": True}
256265
)
257266
self.is_public = True
258267

259268
def make_private(self):
269+
"""Make the collection private.
270+
271+
:return: None
272+
:rtype: None
273+
"""
260274
self._connection.patch(
261275
path=f"{ApiPath.collection}/{self.id}", data={"is_public": False}
262276
)

‎videodb/image.py

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,14 @@
44

55

66
class Image:
7+
"""Image class to interact with the Image
8+
9+
:ivar str id: Unique identifier for the image
10+
:ivar str collection_id: ID of the collection this image belongs to
11+
:ivar str name: Name of the image file
12+
:ivar str url: URL of the image
13+
"""
14+
715
def __init__(self, _connection, id: str, collection_id: str, **kwargs) -> None:
816
self._connection = _connection
917
self.id = id
@@ -21,6 +29,12 @@ def __repr__(self) -> str:
2129
)
2230

2331
def generate_url(self) -> str:
32+
"""Generate the signed url of the image.
33+
34+
:raises InvalidRequestError: If the get_url fails
35+
:return: The signed url of the image
36+
:rtype: str
37+
"""
2438
url_data = self._connection.post(
2539
path=f"{ApiPath.image}/{self.id}/{ApiPath.generate_url}",
2640
params={"collection_id": self.collection_id},
@@ -38,6 +52,16 @@ def delete(self) -> None:
3852

3953

4054
class Frame(Image):
55+
"""Frame class to interact with video frames
56+
57+
:ivar str id: Unique identifier for the frame
58+
:ivar str video_id: ID of the video this frame belongs to
59+
:ivar str scene_id: ID of the scene this frame belongs to
60+
:ivar str url: URL of the frame
61+
:ivar float frame_time: Timestamp of the frame in the video
62+
:ivar str description: Description of the frame contents
63+
"""
64+
4165
def __init__(
4266
self,
4367
_connection,

‎videodb/scene.py

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,16 @@
66

77

88
class Scene:
9+
"""Scene class to interact with video scenes
10+
11+
:ivar str id: Unique identifier for the scene
12+
:ivar str video_id: ID of the video this scene belongs to
13+
:ivar float start: Start time of the scene in seconds
14+
:ivar float end: End time of the scene in seconds
15+
:ivar List[Frame] frames: List of frames in the scene
16+
:ivar str description: Description of the scene contents
17+
"""
18+
919
def __init__(
1020
self,
1121
video_id: str,
@@ -64,6 +74,14 @@ def describe(self, prompt: str = None, model_name=None) -> None:
6474

6575

6676
class SceneCollection:
77+
"""SceneCollection class to interact with collections of scenes
78+
79+
:ivar str id: Unique identifier for the scene collection
80+
:ivar str video_id: ID of the video these scenes belong to
81+
:ivar dict config: Configuration settings for the scene collection
82+
:ivar List[Scene] scenes: List of scenes in the collection
83+
"""
84+
6785
def __init__(
6886
self,
6987
_connection,

‎videodb/search.py

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,14 @@
1414

1515

1616
class SearchResult:
17+
"""SearchResult class to interact with search results
18+
19+
:ivar str collection_id: ID of the collection this search result belongs to
20+
:ivar str stream_url: URL to stream the search result
21+
:ivar str player_url: URL to play the search result in a player
22+
:ivar list[Shot] shots: List of shots in the search result
23+
"""
24+
1725
def __init__(self, _connection, **kwargs):
1826
self._connection = _connection
1927
self.shots = []

‎videodb/shot.py

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
"""This module contains the shot class"""
21

32

43
from typing import Optional
@@ -9,7 +8,18 @@
98

109

1110
class Shot:
12-
"""A shot is a part of a video that contains a specific scene"""
11+
"""Shot class to interact with video shots
12+
13+
:ivar str video_id: Unique identifier for the video
14+
:ivar float video_length: Duration of the video in seconds
15+
:ivar str video_title: Title of the video
16+
:ivar float start: Start time of the shot in seconds
17+
:ivar float end: End time of the shot in seconds
18+
:ivar str text: Text content of the shot
19+
:ivar int search_score: Search relevance score
20+
:ivar str stream_url: URL to stream the shot
21+
:ivar str player_url: URL to play the shot in a player
22+
"""
1323

1424
def __init__(
1525
self,

0 commit comments

Comments
 (0)