Add source parameter for upload

Author: ashish-spext

README.md

@@ -74,7 +74,9 @@ conn = videodb.connect(api_key="YOUR_API_KEY")
 Now that you have established a connection to VideoDB, you can upload your videos using `conn.upload()`.
 You can directly upload from `youtube`, `any public url`, `S3 bucket` or a `local file path`. A default collection is created when you create your first connection.
 
-`upload` method returns a `Video` object.
+`upload` method returns a `Video` object. You can simply pass a single string
+representing either a local file path or a URL. For explicit calls, use the
+``source`` parameter.
 
 ```python
 # Upload a video by url

tests/test_upload.py

@@ -1,4 +1,4 @@
-from videodb._upload import upload
+from videodb._upload import upload, VideodbError
 
 
 class DummyConn:
@@ -16,7 +16,17 @@ def post(self, path, data=None, show_progress=False):
         return {"id": "m-1", **(data or {})}
 
 
-def test_upload_infers_url():
+def test_upload_infers_url_from_source():
     conn = DummyConn()
-    upload(conn, file_path="https://example.com/video.mp4")
+    upload(conn, source="https://example.com/video.mp4")
     assert conn.data["url"] == "https://example.com/video.mp4"
+
+
+def test_upload_source_conflict():
+    conn = DummyConn()
+    try:
+        upload(conn, source="/tmp/file.mp4", file_path="/tmp/file.mp4")
+    except VideodbError:
+        assert True
+    else:
+        assert False, "Expected VideodbError"

videodb/__about__.py

@@ -1,6 +1,6 @@
 """About information for videodb sdk"""
 
-__version__ = "0.2.16"
+__version__ = "0.2.17"
 __title__ = "videodb"
 __author__ = "videodb"
 __email__ = "contact@videodb.io"

videodb/_upload.py

@@ -22,13 +22,28 @@ def _is_url(path: str) -> bool:
 
 def upload(
     _connection,
-    file_path: str = None,
-    url: str = None,
+    source: str | None = None,
+    file_path: str | None = None,
+    url: str | None = None,
     media_type: Optional[str] = None,
     name: Optional[str] = None,
     description: Optional[str] = None,
     callback_url: Optional[str] = None,
 ) -> dict:
+    """Upload a file or URL.
+
+    ``source`` can be used as a generic argument which accepts either a local
+    file path or a URL. ``file_path`` and ``url`` remain for backward
+    compatibility and should not be used together with ``source``.
+    """
+    if source and (file_path or url):
+        raise VideodbError("source cannot be used with file_path or url")
+
+    if source and not file_path and not url:
+        if _is_url(source):
+            url = source
+        else:
+            file_path = source
     if file_path and not url and _is_url(file_path):
         url = file_path
         file_path = None

videodb/client.py

@@ -256,18 +256,20 @@ def get_transcode_details(self, job_id: str) -> dict:
 
     def upload(
         self,
-        file_path: str = None,
-        url: str = None,
+        source: str | None = None,
+        file_path: str | None = None,
+        url: str | None = None,
         media_type: Optional[str] = None,
         name: Optional[str] = None,
         description: Optional[str] = None,
         callback_url: Optional[str] = None,
     ) -> Union[Video, Audio, Image, None]:
         """Upload a file.
 
-        The method automatically detects if ``file_path`` is a URL or a local
-        path when only one of ``file_path`` or ``url`` is provided.
+        The method automatically detects if ``source``/``file_path`` is a URL
+        or a local path when only one of ``file_path`` or ``url`` is provided.
 
+        :param str source: Local path or URL of the file to upload (optional)
         :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)
@@ -279,12 +281,13 @@ def upload(
         """
         upload_data = upload(
             self,
-            file_path,
-            url,
-            media_type,
-            name,
-            description,
-            callback_url,
+            source,
+            file_path=file_path,
+            url=url,
+            media_type=media_type,
+            name=name,
+            description=description,
+            callback_url=callback_url,
         )
         media_id = upload_data.get("id", "")
         if media_id.startswith("m-"):

videodb/collection.py

@@ -428,6 +428,7 @@ def search_title(self, query) -> List[Video]:
 
     def upload(
         self,
+        source: str | None = None,
         file_path: str = None,
         url: Optional[str] = None,
         media_type: Optional[str] = None,
@@ -437,9 +438,10 @@ def upload(
     ) -> Union[Video, Audio, Image, None]:
         """Upload a file to the collection.
 
-        The method automatically detects if ``file_path`` is a URL or a local
-        path when only one of ``file_path`` or ``url`` is provided.
+        The method automatically detects if ``source``/``file_path`` is a URL
+        or a local path when only one of ``file_path`` or ``url`` is provided.
 
+        :param str source: Local path or URL of the file to be uploaded
         :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: MediaType object (optional)
@@ -451,12 +453,13 @@ def upload(
         """
         upload_data = upload(
             self._connection,
-            file_path,
-            url,
-            media_type,
-            name,
-            description,
-            callback_url,
+            source,
+            file_path=file_path,
+            url=url,
+            media_type=media_type,
+            name=name,
+            description=description,
+            callback_url=callback_url,
         )
         media_id = upload_data.get("id", "")
         if media_id.startswith("m-"):