dadascribe 0.1.0__tar.gz

dadascribe-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish Python Package to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+      - name: Build release distributions
+        run: python -m build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dadascribe
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

dadascribe-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.env
+*__pycache__
+*.DS_Store
+
+dist/
+
+examples/

dadascribe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PatzEdi, Fabrizio Ferrari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dadascribe-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: dadascribe
+Version: 0.1.0
+Summary: Python wrapper for the DaDaScribe API
+Project-URL: Homepage, https://api.dadascribe.com/
+Project-URL: Repository, https://github.com/PatzEdi/dadascribe-api-python/
+Project-URL: Bug Tracker, https://github.com/PatzEdi/dadascribe-api-python/issues
+Author-email: PatzEdi <patzedigithub@gmail.com>, Fabrizio Ferrari <fabriziovsm@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: diarization,transcriptions,whisper
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.13
+Requires-Dist: requests
+Description-Content-Type: text/markdown
+
+# Python wrapper for the DaDaScribe API
+
+The official DaDaScribe API wrapper in Python.
+
+![DaDaScribe Logo](https://www.dadascribe.com/images/DaDaScribeLogo.svg)
+
+## CLI Interface
+The wrapper offers a CLI interface.
+
+To start a job, for example:
+```bash
+$ dadascribe --source "link/to/youtube/or/path/to/file"
+{
+  "status": "ok",
+  "id": "a7wuTaPrebOqheE0",
+  "count": 1
+}
+```
+
+Check a job status:
+```bash
+$ dadascribe --status a7wuTaPrebOqheE0
+```
+
+Easily download results of a completed job:
+```bash
+$ dadadascribe --download a7wuTaPrebOqheE0
+```
+
+## Python API
+The wrapper offers a Python API.
+
+```python
+from dadascribe import ScribeAPIWrapper
+api_key = ... # e.g. from an environment variable, as str
+w = ScribeAPIWrapper(api_key)
+
+# Example transcription:
+trsc_result = w.transcribe(
+    source="youtube/link/or/path/to/file",
+    source_language="en",
+    destination_language="es,it",
+)
+```
+
+
+## Development
+```bash
+pip3 install -e .
+```
+
+Make sure to run the tests as well via the run_tests.sh script:
+```bash
+chmod +x run_tests.sh
+./run_tests.sh
+```

dadascribe-0.1.0/README.md

@@ -0,0 +1,56 @@
+# Python wrapper for the DaDaScribe API
+
+The official DaDaScribe API wrapper in Python.
+
+![DaDaScribe Logo](https://www.dadascribe.com/images/DaDaScribeLogo.svg)
+
+## CLI Interface
+The wrapper offers a CLI interface.
+
+To start a job, for example:
+```bash
+$ dadascribe --source "link/to/youtube/or/path/to/file"
+{
+  "status": "ok",
+  "id": "a7wuTaPrebOqheE0",
+  "count": 1
+}
+```
+
+Check a job status:
+```bash
+$ dadascribe --status a7wuTaPrebOqheE0
+```
+
+Easily download results of a completed job:
+```bash
+$ dadadascribe --download a7wuTaPrebOqheE0
+```
+
+## Python API
+The wrapper offers a Python API.
+
+```python
+from dadascribe import ScribeAPIWrapper
+api_key = ... # e.g. from an environment variable, as str
+w = ScribeAPIWrapper(api_key)
+
+# Example transcription:
+trsc_result = w.transcribe(
+    source="youtube/link/or/path/to/file",
+    source_language="en",
+    destination_language="es,it",
+)
+```
+
+
+## Development
+```bash
+pip3 install -e .
+```
+
+Make sure to run the tests as well via the run_tests.sh script:
+```bash
+chmod +x run_tests.sh
+./run_tests.sh
+```

dadascribe-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dadascribe"
+version = "0.1.0"
+authors = [
+    { name = "PatzEdi", email = "patzedigithub@gmail.com" },
+    { name = "Fabrizio Ferrari", email = "fabriziovsm@gmail.com" }
+]
+description = "Python wrapper for the DaDaScribe API"
+readme = "README.md"
+keywords = ["transcriptions", "diarization", "whisper"]
+requires-python = ">=3.13"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+license="MIT"
+license-files=["LICENSE"]
+
+dependencies = ["requests"]
+
+[project.scripts]
+dadascribe = "dadascribe.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dadascribe"]
+
+[project.urls]
+"Homepage" = "https://api.dadascribe.com/"
+"Repository" = "https://github.com/PatzEdi/dadascribe-api-python/"
+"Bug Tracker" = "https://github.com/PatzEdi/dadascribe-api-python/issues"

dadascribe-0.1.0/run_tests.sh

@@ -0,0 +1,2 @@
+
+python -m unittest discover -s tests -v

dadascribe-0.1.0/src/dadascribe/__init__.py

@@ -0,0 +1,2 @@
+
+from .wrapper import ScribeAPIWrapper

dadascribe-0.1.0/src/dadascribe/cli.py

@@ -0,0 +1,127 @@
+
+import argparse
+import os
+import sys
+import json
+
+from .internal_globals import ENV_API_NAME
+from .wrapper import ScribeAPIWrapper, DownloadError
+from .request_utils import InternalRequestError, InvalidFileError
+
+
+def _check_api_key_presence(args) -> str:
+    api_key = args.api_key or os.getenv(ENV_API_NAME)
+    if not api_key:
+        print(
+            "Error: API key required. Provide --api-key " \
+            "or set DADASCRIBE_API_KEY env var.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    return api_key
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        description="Interact with the DaDaScribe API through the CLI."
+    )
+    p.add_argument(
+        "--api-key",
+        help="Dadascribe API key (or set DADASCRIBE_API_KEY env var).",
+    )
+    p.add_argument(
+        "--source",
+        default="https://www.youtube.com/watch?v=VIDEO_ID",
+        help="Source media URL (e.g. YouTube link) OR file path.",
+    )
+    p.add_argument(
+        "--source-language", default="en", help="Source language (e.g. 'en')."
+    )
+    p.add_argument(
+        "--destination-language",
+        default="",
+        help="Comma-separated destination languages (e.g. 'it,fr').",
+    )
+    p.add_argument(
+        "--diarization",
+        default="",
+        help="Comma-separated diarization labels (e.g. 'Alice,Bob').",
+    )
+    p.add_argument(
+        "--timeout", type=int, default=60, help="Request timeout in seconds."
+    )
+    p.add_argument(
+        "--dump-response",
+        help="File to save JSON response (optional). "
+            "If omitted, prints to stdout.",
+    )
+
+    p.add_argument(
+        "--status-id",
+        help="Check status for a previously submitted job ID (e.g. " \
+        "a1B2c3D4e5F6g7H8). If provided, transcribe will not run.",
+    )
+
+    # For downloading transcription files:
+
+    p.add_argument(
+        "--download",
+        help="Download generated files given a job ID " \
+            "& an optional output dir path" \
+    )
+
+    p.add_argument(
+        "--download-output-dir",
+        default=None,
+        help="Directory to save downloaded files (optional). " \
+            "If omitted, saves to current directory."
+    )
+    
+    return p.parse_args()
+
+
+def _handle_args(args: argparse.Namespace, api_key: str) -> None:
+    wrapper = ScribeAPIWrapper(api_key=api_key, req_timeout=args.timeout)
+    try:
+        if args.status_id:
+            # If a status ID is provided, perform a status
+            # check and ignore other transcribe options.
+            result = wrapper.retrieve_status(id=args.status_id)
+        elif args.download:
+            result = wrapper.download_transcription_output(
+                id=args.download,
+                output_dir=args.download_output_dir or os.getcwd(),
+            )
+        else:
+            result = wrapper.transcribe(
+                source=args.source,
+                source_language=args.source_language,
+                destination_language=args.destination_language,
+                diarization=args.diarization,
+            )
+    except (InternalRequestError, InvalidFileError, DownloadError) as e:
+        if isinstance(e, DownloadError) or isinstance(e, InvalidFileError):
+            print(f"Error: {e.message}", file=sys.stderr)
+        elif isinstance(e, InternalRequestError):
+            print(f"Error during request: {e.resp_body}", file=sys.stderr)
+
+        sys.exit(1)
+
+    if args.dump_response:
+        with open(args.dump_response, "w", encoding="utf-8") as f:
+            json.dump(result, f, ensure_ascii=False, indent=2)
+        print(f"Saved response to {args.dump_response}")
+    else:
+        # Pretty-print JSON or text
+        if isinstance(result, (dict, list)):
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+        elif result is not None:
+            print(result)
+
+
+
+def main() -> None:
+    parsed_args = parse_args()
+    api_key = _check_api_key_presence(parsed_args)
+    _handle_args(parsed_args, api_key)

dadascribe-0.1.0/src/dadascribe/internal_globals.py

@@ -0,0 +1,4 @@
+
+# Stores important global constants used across the package.
+
+ENV_API_NAME: str = "DADASCRIBE_API_KEY"

dadascribe-0.1.0/src/dadascribe/request_utils.py

@@ -0,0 +1,173 @@
+# Stores global constants & utils related to requests.
+from enum import StrEnum
+from io import BufferedReader
+from typing import Optional, Any
+from urllib.parse import urlparse
+from pathlib import Path
+from os import PathLike
+
+import requests
+import json
+
+BASE_API_URL: str = "https://api.dadascribe.com/v1/"
+
+
+class EndPoints(StrEnum):
+    """Common endpoint names for the API."""
+
+    STATUS = "status"
+    TRANSCRIBE = "transcribe"
+
+
+class PayLoadKeys(StrEnum):
+    """Common payload keys for the API."""
+
+    ID = "id"
+    SOURCE = "source"
+    SOURCE_LANGUAGE = "source-language"
+    DEST_LANGUAGE = "destination-language"
+    DIARIZATION = "diarization"
+
+
+class ResponseKeys(StrEnum):
+    """Common response keys for the API."""
+
+    STATUS = "status"
+    URLS = "urls"
+
+
+class Status(StrEnum):
+    """Common status values for the API."""
+
+    COMPLETE = "complete"
+    PROCESSING = "processing"
+    ERROR = "error"
+
+
+def extract_response_content(resp: requests.Response) -> str:
+    """Helper to extract the response content as JSON or raw text."""
+    try:
+        return resp.json()
+    except ValueError:
+        return resp.text
+
+
+class InternalRequestError(Exception):
+    """Raised when a request fails with a non-200 status code.
+    Contains the response object for debugging and other useful
+    information about the failure."""
+
+    def __init__(self, response: requests.Response):
+        self._response = response
+        self._message = (
+            f"Request failed: {response.status_code} {response.reason}"
+        )
+
+        super().__init__(self.message)
+
+    @property
+    def response(self) -> requests.Response:
+        return self._response
+
+    @property
+    def message(self) -> str:
+        return self._message
+
+    @property
+    def resp_body(self) -> str:
+        return extract_response_content(self._response)
+
+
+class InvalidFileError(Exception):
+    """Raised when an inputted file is not valid."""
+
+    def __init__(self, message: str):
+        self._message = message
+        super().__init__(self._message)
+
+    @property
+    def message(self) -> str:
+        return self._message
+
+
+class RequestUtils:
+    """Utility class for making HTTP requests,
+    handling common request logic."""
+
+    def exec_request(
+        self,
+        api_key: str,
+        url: str,
+        payload: Optional[dict],
+        timeout: int = 0,
+        get: bool = False,
+        file: Optional[PathLike] | Optional[str] = None
+    ) -> str | None:
+        """Executes a POST/GET request to the given URL with the given headers
+        and payload, and returns the response as JSON or raw text."""
+        req_fn = requests.get if get else requests.post
+        if file is not None:
+            headers = self.construct_headers(api_key, include_content=False)
+            payload, file_obj = self.construct_file_payload(file, payload)
+            resp = req_fn(
+                url,
+                headers=headers,
+                files=payload, timeout=timeout
+            )
+            file_obj.close()
+        else:
+            headers = self.construct_headers(api_key)
+            resp = req_fn(
+                url,
+                headers=headers,
+                json=payload, timeout=timeout
+            )
+
+        try:
+            resp.raise_for_status()
+        except requests.HTTPError:
+            raise InternalRequestError(resp)
+
+        # Return JSON if possible, otherwise raw text
+        return extract_response_content(resp)
+
+
+    def construct_headers(
+        self,
+        api_key: str,
+        include_content: bool = True
+    ) -> dict:
+        """Contructs a commonly used headers dict with the given API key."""
+        headers = {
+            "Authorization": f"Bearer {api_key}",
+        }
+        if include_content:
+            headers["Content-Type"] = "application/json"
+        return headers
+
+    def is_link(self, object: Any) -> bool:
+        """Returns whether a given string is a link or not."""
+        try:
+            stringed = str(object)
+            result = urlparse(stringed)
+            return all([result.scheme, result.netloc])
+        except ValueError:
+            return False
+
+
+    def construct_file_payload(
+        self,
+        file: PathLike | str,
+        params: Optional[dict] = None
+    ) -> tuple[dict, BufferedReader]:
+        """Constructs a file payload dict from the given file path."""
+        file = Path(file)
+        if not file.is_file():
+            raise InvalidFileError(f"File not found or is not a file: {file}")
+            
+        file_obj = open(file, "rb")
+        file_payload = {
+            "file": (file.name, file_obj),
+            "data": (None, json.dumps(params or {}), "application/json"),
+        }
+        return file_payload, file_obj

dadascribe-0.1.0/src/dadascribe/wrapper.py

@@ -0,0 +1,116 @@
+import os
+from os import PathLike
+from typing import Any, Optional
+
+from .request_utils import (
+    BASE_API_URL,
+    EndPoints,
+    PayLoadKeys,
+    RequestUtils,
+    ResponseKeys,
+    Status,
+)
+
+
+class DownloadError(Exception):
+    """Raised when download fails."""
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(self.message)
+
+
+class ScribeAPIWrapper:
+    def __init__(self, api_key: str, req_timeout: int = 60):
+        self._request_utils = RequestUtils()
+        self._api_key = api_key
+        self._req_timeout = req_timeout
+
+    def transcribe(
+        self,
+        source: str | list[str] | PathLike,
+        source_language: str,
+        destination_language: str,
+        diarization: Optional[str] = None,
+    ) -> Any:
+        """Send a POST request to the Dadascribe /v1/transcribe
+        endpoint and return the parsed response.
+
+        Raises InvalidRequestError on failing requests.
+        """
+        url = BASE_API_URL + EndPoints.TRANSCRIBE
+        payload: dict[str, Any] = {
+            PayLoadKeys.SOURCE_LANGUAGE: source_language,
+            PayLoadKeys.DEST_LANGUAGE: destination_language,
+        }
+        if diarization is not None:
+            payload[PayLoadKeys.DIARIZATION] = diarization
+        file_source = None
+        if isinstance(source, list) or self._request_utils.is_link(source):
+            print("Source detected as LINK or LIST of LINKS.")
+            payload[PayLoadKeys.SOURCE] = source
+        else:
+            print("Source detected as FILE.")
+            # Construct files data:
+            file_source = source
+
+        return self._api_request(url, payload=payload, file=file_source)
+
+    def retrieve_status(self, id: str) -> Any:
+        """Send a POST request to the Dadascribe /v1/status endpoint
+        and return the parsed response.
+
+        Raises InvalidRequestError on failing requests.
+        """
+        url = BASE_API_URL + EndPoints.STATUS
+        payload = {PayLoadKeys.ID: id}
+
+        return self._api_request(url, payload=payload)
+
+    def download_transcription_output(
+        self,
+        id: str,
+        output_dir: str | PathLike,
+    ) -> None:
+        """Download the transcription output for the given job ID
+        to the specified directory. If no directory is specified,
+        saves to the current directory.
+        """
+        if not os.path.exists(output_dir):
+            raise DownloadError(
+                f'Output directory "{output_dir}" does not exist.'
+            )
+
+        status_info = self.retrieve_status(id)
+        if status_info[ResponseKeys.STATUS] != Status.COMPLETE:
+            raise DownloadError(
+                "Job is not completed yet. Cannot download output."
+            )
+
+        for file_url in status_info.get(ResponseKeys.URLS, []):
+            file_name = os.path.basename(file_url)
+            file_content = self._api_request(file_url, get=True)
+            with open(os.path.join(output_dir, file_name), "w") as f:
+                f.write(file_content)
+
+    def _api_request(
+        self,
+        url: str,
+        payload: Optional[dict] = None,
+        get: bool = False,
+        file: Optional[Any] = None,
+    ) -> Any:
+        """Send a POST request to the given URL with the given payload
+        and return the parsed response. Higher level version of exec_request
+        found in RequestUtils.
+
+        Raises InvalidRequestError on failing requests.
+        """
+        return self._request_utils.exec_request(
+            self._api_key,
+            url,
+            payload=payload,
+            timeout=self._req_timeout,
+            get=get,
+            file=file,
+        )

dadascribe-0.1.0/tests/test_internal_globals.py

@@ -0,0 +1,14 @@
+
+import unittest
+from dadascribe.internal_globals import ENV_API_NAME
+
+# Mostly just checking that when we modify these, we
+# really want to modify them.
+
+class TestInternalGlobals(unittest.TestCase):
+    def test_env_api_name(self):
+        self.assertEqual(ENV_API_NAME, "DADASCRIBE_API_KEY")
+
+
+if __name__ == "__main__":
+    unittest.main()

dadascribe-0.1.0/tests/test_request_utils.py

@@ -0,0 +1,175 @@
+import unittest
+from unittest.mock import patch, mock_open
+
+import requests
+from src.dadascribe.request_utils import (
+    InternalRequestError,
+    InvalidFileError,
+    RequestUtils,
+    extract_response_content,
+)
+
+
+class TestRequestUtils(unittest.TestCase):
+    def setUp(self):
+        self._request_utils = RequestUtils()
+
+    def test_extract_response_content(self):
+        resp = requests.Response()
+        resp._content = b'{"key": "value"}'
+        result = extract_response_content(resp)
+        self.assertIsInstance(result, dict)
+        self.assertEqual(result, {"key": "value"})
+
+        # Now with a list:
+        resp._content = b'["response", "content", "as", "list"]'
+        result = extract_response_content(resp)
+        self.assertIsInstance(result, list)
+        self.assertEqual(result, ["response", "content", "as", "list"])
+
+        # Now with a string:
+        resp._content = b"response as a string"
+        result = extract_response_content(resp)
+        self.assertIsInstance(result, str)
+        self.assertEqual(result, "response as a string")
+
+    def test_construct_headers(self):
+        """Makes sure that the headers we construct
+        are of the expected form. This is more of a confirmation
+        that we want to change this header format in the code."""
+        headers = self._request_utils.construct_headers("dummy_api_key")
+        self.assertIsInstance(headers, dict)
+        self.assertEqual(
+            headers,
+            {
+                "Authorization": "Bearer dummy_api_key",
+                "Content-Type": "application/json",
+            },
+        )
+
+    @patch("requests.post", return_value=requests.Response())
+    def test_exec_request_calls_post_correctly(self, mock_post):
+        resp = mock_post.return_value
+        resp._content = b'{"dummy": "response"}'
+        resp.status_code = 200
+        self._request_utils.exec_request(
+            "dummy_api_key", "https://dummy.url", {}
+        )
+        mock_post.assert_called_once()
+        mock_post.assert_called_with(
+            "https://dummy.url",
+            headers={
+                "Authorization": "Bearer dummy_api_key",
+                "Content-Type": "application/json",
+            },
+            json={},
+            timeout=0,
+        )
+
+    @patch("requests.post", return_value=requests.Response())
+    def test_exec_request_raises_internal_request_error_on_status_raised(
+        self, mock_post
+    ):
+        resp = mock_post.return_value
+        resp.status_code = 500
+        resp.reason = "Bad Request"
+        with self.assertRaises(InternalRequestError) as context:
+            self._request_utils.exec_request(
+                "dummy_api_key", "https://dummy.url", {}
+            )
+        self.assertEqual(
+            str(context.exception), "Request failed: 500 Bad Request"
+        )
+
+    @patch("requests.post", return_value=requests.Response())
+    def test_exec_request_returns_formatted_extraction_content_output(
+        self, mock_post
+    ):
+        resp = mock_post.return_value
+        resp._content = b'["response", "content", "as", "list"]'
+        resp.status_code = 200
+        result = self._request_utils.exec_request(
+            "dummy_api_key", "https://dummy.url", {}
+        )
+        self.assertIsInstance(result, list)
+        self.assertEqual(result, ["response", "content", "as", "list"])
+
+    def test_is_link(self):
+        """Test is_link correctly identifies URLs and non-URLs."""
+        # Valid URLs
+        self.assertTrue(self._request_utils.is_link("https://example.com"))
+        self.assertTrue(self._request_utils.is_link("http://example.com"))
+        self.assertTrue(
+            self._request_utils.is_link("https://example.com/path/to/file.mp3")
+        )
+        self.assertTrue(self._request_utils.is_link("ftp://example.com"))
+
+        # Not valid URLs (no scheme or no netloc)
+        self.assertFalse(self._request_utils.is_link("example.com"))
+        self.assertFalse(self._request_utils.is_link("/path/to/file.mp3"))
+        self.assertFalse(self._request_utils.is_link("file.mp3"))
+        self.assertFalse(self._request_utils.is_link("just_a_string"))
+        self.assertFalse(self._request_utils.is_link(""))
+
+    @patch(
+        "builtins.open",
+        new_callable=mock_open,
+        read_data=b"file content",
+    )
+    @patch("pathlib.Path.is_file", return_value=True)
+    @patch("pathlib.Path.exists", return_value=True)
+    @patch("requests.post", return_value=requests.Response())
+    def test_exec_request_with_file(
+        self, mock_post, mock_exists, mock_is_file, mock_open_file
+    ):
+        """Test that exec_request correctly handles file uploads."""
+        resp = mock_post.return_value
+        resp._content = b'{"id": "test_id"}'
+        resp.status_code = 200
+
+        result = self._request_utils.exec_request(
+            "dummy_api_key",
+            "https://dummy.url",
+            {"key": "value"},
+            file="/path/to/test.mp3",
+        )
+
+        mock_post.assert_called_once()
+        call_args = mock_post.call_args
+
+        # Verify headers don't include Content-Type (multipart/form-data is automatic)
+        self.assertEqual(
+            call_args.kwargs["headers"],
+            {"Authorization": "Bearer dummy_api_key"},
+        )
+
+        # Verify files parameter is present
+        self.assertIn("files", call_args.kwargs)
+        self.assertEqual(result, {"id": "test_id"})
+
+    @patch("pathlib.Path.is_file", return_value=False)
+    def test_construct_file_payload_raises_on_non_file(
+        self, mock_is_file
+    ):
+        """Test that construct_file_payload raises InvalidFileError for non-files."""
+        with self.assertRaises(InvalidFileError) as context:
+            self._request_utils.construct_file_payload("/path/to/directory")
+        self.assertIn(
+            "File not found or is not a file", str(context.exception)
+        )
+
+    def test_construct_headers_with_include_content_false(self):
+        """Test construct_headers without Content-Type for file uploads."""
+        headers = self._request_utils.construct_headers(
+            "dummy_api_key", include_content=False
+        )
+        self.assertIsInstance(headers, dict)
+        self.assertEqual(
+            headers,
+            {"Authorization": "Bearer dummy_api_key"},
+        )
+        self.assertNotIn("Content-Type", headers)
+
+
+if __name__ == "__main__":
+    unittest.main()

dadascribe-0.1.0/tests/test_wrapper.py

@@ -0,0 +1,203 @@
+import unittest
+from unittest.mock import MagicMock, mock_open, patch
+
+from src.dadascribe.request_utils import (
+    BASE_API_URL,
+    EndPoints,
+    PayLoadKeys,
+    ResponseKeys,
+    Status,
+)
+from src.dadascribe.wrapper import DownloadError, ScribeAPIWrapper
+
+
+class TestWrapper(unittest.TestCase):
+    def setUp(self):
+        self._wrapper = ScribeAPIWrapper(api_key="")
+
+    @patch("src.dadascribe.wrapper.ScribeAPIWrapper._api_request")
+    def test_transcribe_calls_api_request_correctly(self, mock_api_request):
+        """Checks that the transcribe function calls _api_request
+        with the correct arguments, such as the payload."""
+        self._wrapper.transcribe(
+            source="https://example_source_url.com",
+            source_language="en",
+            destination_language="it",
+        )
+        mock_api_request.assert_called_once()
+        mock_api_request.assert_called_with(
+            BASE_API_URL + EndPoints.TRANSCRIBE,
+            payload={
+                PayLoadKeys.SOURCE_LANGUAGE: "en",
+                PayLoadKeys.DEST_LANGUAGE: "it",
+                PayLoadKeys.SOURCE: "https://example_source_url.com",
+            },
+            file=None,
+        )
+
+        mock_api_request.reset_mock()
+        # Make sure it works out with diarization as well:
+        # Note: "example_source_url" without a protocol is treated as a file
+        self._wrapper.transcribe(
+            source="example_source_url",
+            source_language="en",
+            destination_language="it",
+            diarization="speaker1,speaker2",
+        )
+        mock_api_request.assert_called_once()
+        mock_api_request.assert_called_with(
+            BASE_API_URL + EndPoints.TRANSCRIBE,
+            payload={
+                PayLoadKeys.SOURCE_LANGUAGE: "en",
+                PayLoadKeys.DEST_LANGUAGE: "it",
+                PayLoadKeys.DIARIZATION: "speaker1,speaker2",
+            },
+            file="example_source_url",
+        )
+
+        # As a list for the source:
+        mock_api_request.reset_mock()
+        self._wrapper.transcribe(
+            source=["example_source_url", "example_source_url2"],
+            source_language="en",
+            destination_language="it",
+            diarization="speaker1,speaker2",
+        )
+        mock_api_request.assert_called_once()
+        mock_api_request.assert_called_with(
+            BASE_API_URL + EndPoints.TRANSCRIBE,
+            payload={
+                PayLoadKeys.SOURCE: [
+                    "example_source_url",
+                    "example_source_url2",
+                ],
+                PayLoadKeys.SOURCE_LANGUAGE: "en",
+                PayLoadKeys.DEST_LANGUAGE: "it",
+                PayLoadKeys.DIARIZATION: "speaker1,speaker2",
+            },
+            file=None,
+        )
+
+    @patch("src.dadascribe.wrapper.ScribeAPIWrapper._api_request")
+    def test_transcribe_with_file_path(self, mock_api_request):
+        """Test that transcribe correctly handles file paths."""
+        # Test with a file path (no protocol scheme)
+        self._wrapper.transcribe(
+            source="/path/to/audio.mp3",
+            source_language="en",
+            destination_language="fr",
+        )
+        mock_api_request.assert_called_once()
+        mock_api_request.assert_called_with(
+            BASE_API_URL + EndPoints.TRANSCRIBE,
+            payload={
+                PayLoadKeys.SOURCE_LANGUAGE: "en",
+                PayLoadKeys.DEST_LANGUAGE: "fr",
+            },
+            file="/path/to/audio.mp3",
+        )
+
+    @patch("src.dadascribe.wrapper.ScribeAPIWrapper._api_request")
+    def test_transcribe_with_http_url(self, mock_api_request):
+        """Test that transcribe correctly handles HTTP URLs."""
+        self._wrapper.transcribe(
+            source="http://example.com/audio.mp3",
+            source_language="en",
+            destination_language="es",
+        )
+        mock_api_request.assert_called_once()
+        mock_api_request.assert_called_with(
+            BASE_API_URL + EndPoints.TRANSCRIBE,
+            payload={
+                PayLoadKeys.SOURCE_LANGUAGE: "en",
+                PayLoadKeys.DEST_LANGUAGE: "es",
+                PayLoadKeys.SOURCE: "http://example.com/audio.mp3",
+            },
+            file=None,
+        )
+
+    @patch("src.dadascribe.wrapper.ScribeAPIWrapper._api_request")
+    def test_transcribe_with_relative_file_path(self, mock_api_request):
+        """Test that transcribe correctly handles relative file paths."""
+        self._wrapper.transcribe(
+            source="audio_files/recording.wav",
+            source_language="de",
+            destination_language="en",
+        )
+        mock_api_request.assert_called_once()
+        mock_api_request.assert_called_with(
+            BASE_API_URL + EndPoints.TRANSCRIBE,
+            payload={
+                PayLoadKeys.SOURCE_LANGUAGE: "de",
+                PayLoadKeys.DEST_LANGUAGE: "en",
+            },
+            file="audio_files/recording.wav",
+        )
+
+    @patch("src.dadascribe.wrapper.ScribeAPIWrapper._api_request")
+    def test_transcribe_with_list_of_urls(self, mock_api_request):
+        """Test that transcribe handles a list of URLs correctly."""
+        self._wrapper.transcribe(
+            source=[
+                "https://example.com/audio1.mp3",
+                "https://example.com/audio2.mp3",
+            ],
+            source_language="en",
+            destination_language="es",
+        )
+        mock_api_request.assert_called_once()
+        mock_api_request.assert_called_with(
+            BASE_API_URL + EndPoints.TRANSCRIBE,
+            payload={
+                PayLoadKeys.SOURCE: [
+                    "https://example.com/audio1.mp3",
+                    "https://example.com/audio2.mp3",
+                ],
+                PayLoadKeys.SOURCE_LANGUAGE: "en",
+                PayLoadKeys.DEST_LANGUAGE: "es",
+            },
+            file=None,
+        )
+
+    @patch("src.dadascribe.wrapper.ScribeAPIWrapper._api_request")
+    def test_retrieve_status_calls_api_request_correctly(
+        self, mock_api_request
+    ):
+        """Checks that the retrieve_transcription function calls _api_request
+        with the correct arguments, such as the payload."""
+        self._wrapper.retrieve_status(id="example_id")
+        mock_api_request.assert_called_once()
+        mock_api_request.assert_called_with(
+            BASE_API_URL + EndPoints.STATUS,
+            payload={
+                PayLoadKeys.ID: "example_id",
+            },
+        )
+
+    @patch("os.path.exists")
+    def test_download_trsc_raises_err_when_output_dir_dne(self, mock_exists):
+        """When the output dir does not exist, should raise DownloadError."""
+        mock_exists.return_value = False
+        with self.assertRaises(DownloadError):
+            self._wrapper.download_transcription_output(
+                id="example_id", output_dir="example_path"
+            )
+
+    @patch("os.path.exists")
+    @patch("src.dadascribe.wrapper.ScribeAPIWrapper.retrieve_status")
+    def test_download_trsc_raises_err_when_status_not_complete(
+        self, mock_retrieve_status, mock_exists
+    ):
+        """When the output dir does not exist, should raise DownloadError."""
+        mock_exists.return_value = True
+        mock_retrieve_status.return_value = {
+            ResponseKeys.STATUS: Status.PROCESSING
+        }
+        with self.assertRaises(DownloadError):
+            self._wrapper.download_transcription_output(
+                id="example_id", output_dir="example_path"
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()