dadascribe 0.1.0__py3-none-any.whl

dadascribe/__init__.py

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

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/internal_globals.py

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

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+dadascribe/__init__.py,sha256=QJsTVPXQJ-3Wqfdl-bkXJd07boanNiJjFHfQlO1mYoc,38
+dadascribe/cli.py,sha256=7Mg7cZbdp5A2_72wU4Fq_a-AtAU6pU1G1o7LS-v8Zyw,4013
+dadascribe/internal_globals.py,sha256=Cs1gUEqdHHNAp9Bwu7ELVcjbTpLvCYlRdvM2GW0HIaM,104
+dadascribe/request_utils.py,sha256=NQEx0VO_2n4uF6ZqYQuFDolFioR4PLflL4aYXp1beg4,4752
+dadascribe/wrapper.py,sha256=_t8vqZH56ZTqL2dctVQCKk-4sYSMvzQ3gEChB131O-g,3674
+dadascribe-0.1.0.dist-info/METADATA,sha256=yE6uyvLRWmpucyjkP_1CwxWlgII2lkVG1Qjejerh95A,1785
+dadascribe-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+dadascribe-0.1.0.dist-info/entry_points.txt,sha256=y7OxHUdmxvz3IWFr6iWycgzJmVrLb4jR3CThx7Ta5wk,51
+dadascribe-0.1.0.dist-info/licenses/LICENSE,sha256=v4gcvKFNHtlz30THehoOU7sWNZrnvnAYMPmUfD3bX9I,1081
+dadascribe-0.1.0.dist-info/RECORD,,

dadascribe-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

dadascribe-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dadascribe = dadascribe.cli:main

dadascribe-0.1.0.dist-info/licenses/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.