capslane 0.1.0__tar.gz

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

@@ -0,0 +1,23 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
+        with:
+          python-version: '3.13'
+      - run: python -m pip install build
+      - run: python -m unittest discover tests
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33

capslane-0.1.0/.github/workflows/quality.yml

@@ -0,0 +1,13 @@
+name: Quality
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+      - run: python3 -m unittest discover tests

capslane-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+*.egg-info/
+__pycache__/
+*.pyc
+.venv/

capslane-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Luca Deguin, Webba Creative Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files, to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and 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.

capslane-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: capslane
+Version: 0.1.0
+Summary: Python client for retrieving YouTube transcripts through the Capslane API.
+Project-URL: Documentation, https://capslane.com/docs
+Project-URL: Repository, https://github.com/Webba-Creative-Technologies/capslane-python
+Author-email: Webba Creative Technologies <luca.deguin@webba-creative.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,captions,transcript,video-to-text,youtube
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Capslane Python SDK
+
+The Capslane Python SDK retrieves YouTube transcripts from Python applications. It returns existing captions when available and can generate a transcript when a video has no usable caption track. The package uses the Python standard library and has no runtime dependency.
+
+## Requirements
+
+- Python 3.10 or later
+- A Capslane API key from the [dashboard](https://capslane.com/api-keys)
+
+## Installation
+
+```bash
+pip install capslane
+```
+
+## Retrieve a transcript
+
+```python
+import os
+
+from capslane import CapslaneClient
+
+capslane = CapslaneClient(os.environ["CAPSLANE_API_KEY"])
+
+result = capslane.transcript(
+    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+    mode="auto",
+)
+
+transcript = (
+    capslane.wait_for_transcript(result)
+    if "jobId" in result
+    else result
+)
+
+print(transcript["content"])
+```
+
+## Check a transcript job
+
+```python
+job = capslane.transcript_job(
+    "job_00000000-0000-0000-0000-000000000000"
+)
+```
+
+`wait_for_transcript` polls an accepted job until it completes, fails or reaches the timeout.
+
+```python
+transcript = capslane.wait_for_transcript(
+    job,
+    interval=2.0,
+    timeout=20 * 60,
+)
+```
+
+## Request options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `url` | `str` | Public YouTube URL or 11-character video ID. |
+| `lang` | `str` | Optional preferred language code. |
+| `mode` | `native`, `auto` or `generate` | Selects how Capslane obtains the transcript. |
+| `text` | `bool` | Returns one text string instead of timestamped segments. |
+| `chunk_size` | `int` | Groups transcript segments into larger chunks. |
+
+## Modes
+
+- `native` returns existing captions and never starts speech transcription.
+- `auto` uses existing captions first and generates a transcript only when needed.
+- `generate` creates a transcript from the video audio.
+
+## Errors
+
+Failed requests raise `CapslaneError`. The error includes the HTTP status, Capslane error code and request ID when available.
+
+```python
+from capslane import CapslaneError
+
+try:
+    capslane.transcript("invalid")
+except CapslaneError as error:
+    print(error.status, error.code, error.request_id)
+```
+
+## Security
+
+Use Capslane from a trusted server. Do not expose API keys in browser code, public repositories or client-side environment variables.
+
+## Links
+
+- [Documentation](https://capslane.com/docs)
+- [API reference](https://capslane.com/api-reference)
+- [Dashboard](https://capslane.com/dashboard)
+- [GitHub](https://github.com/Webba-Creative-Technologies/capslane-python)
+
+## License
+
+MIT

capslane-0.1.0/README.md

@@ -0,0 +1,99 @@
+# Capslane Python SDK
+
+The Capslane Python SDK retrieves YouTube transcripts from Python applications. It returns existing captions when available and can generate a transcript when a video has no usable caption track. The package uses the Python standard library and has no runtime dependency.
+
+## Requirements
+
+- Python 3.10 or later
+- A Capslane API key from the [dashboard](https://capslane.com/api-keys)
+
+## Installation
+
+```bash
+pip install capslane
+```
+
+## Retrieve a transcript
+
+```python
+import os
+
+from capslane import CapslaneClient
+
+capslane = CapslaneClient(os.environ["CAPSLANE_API_KEY"])
+
+result = capslane.transcript(
+    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+    mode="auto",
+)
+
+transcript = (
+    capslane.wait_for_transcript(result)
+    if "jobId" in result
+    else result
+)
+
+print(transcript["content"])
+```
+
+## Check a transcript job
+
+```python
+job = capslane.transcript_job(
+    "job_00000000-0000-0000-0000-000000000000"
+)
+```
+
+`wait_for_transcript` polls an accepted job until it completes, fails or reaches the timeout.
+
+```python
+transcript = capslane.wait_for_transcript(
+    job,
+    interval=2.0,
+    timeout=20 * 60,
+)
+```
+
+## Request options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `url` | `str` | Public YouTube URL or 11-character video ID. |
+| `lang` | `str` | Optional preferred language code. |
+| `mode` | `native`, `auto` or `generate` | Selects how Capslane obtains the transcript. |
+| `text` | `bool` | Returns one text string instead of timestamped segments. |
+| `chunk_size` | `int` | Groups transcript segments into larger chunks. |
+
+## Modes
+
+- `native` returns existing captions and never starts speech transcription.
+- `auto` uses existing captions first and generates a transcript only when needed.
+- `generate` creates a transcript from the video audio.
+
+## Errors
+
+Failed requests raise `CapslaneError`. The error includes the HTTP status, Capslane error code and request ID when available.
+
+```python
+from capslane import CapslaneError
+
+try:
+    capslane.transcript("invalid")
+except CapslaneError as error:
+    print(error.status, error.code, error.request_id)
+```
+
+## Security
+
+Use Capslane from a trusted server. Do not expose API keys in browser code, public repositories or client-side environment variables.
+
+## Links
+
+- [Documentation](https://capslane.com/docs)
+- [API reference](https://capslane.com/api-reference)
+- [Dashboard](https://capslane.com/dashboard)
+- [GitHub](https://github.com/Webba-Creative-Technologies/capslane-python)
+
+## License
+
+MIT

capslane-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "capslane"
+version = "0.1.0"
+description = "Python client for retrieving YouTube transcripts through the Capslane API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Webba Creative Technologies", email = "luca.deguin@webba-creative.com" }]
+keywords = ["youtube", "transcript", "captions", "video-to-text", "api"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://capslane.com/docs"
+Repository = "https://github.com/Webba-Creative-Technologies/capslane-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/capslane"]

capslane-0.1.0/src/capslane/__init__.py

@@ -0,0 +1,3 @@
+from .client import CapslaneClient, CapslaneError
+
+__all__ = ["CapslaneClient", "CapslaneError"]

capslane-0.1.0/src/capslane/client.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+
+@dataclass
+class CapslaneError(Exception):
+    status: int
+    code: str
+    message: str
+    request_id: str | None = None
+
+    def __str__(self) -> str:
+        return f"{self.code}: {self.message}"
+
+
+class CapslaneClient:
+    def __init__(self, api_key: str, base_url: str = "https://capslane.com", timeout: float = 20.0) -> None:
+        if not api_key.strip():
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def transcript(
+        self,
+        url: str,
+        *,
+        lang: str | None = None,
+        text: bool | None = None,
+        chunk_size: int | None = None,
+        mode: str | None = None,
+    ) -> dict[str, Any]:
+        query: dict[str, str] = {"url": url}
+        if lang:
+            query["lang"] = lang
+        if text is not None:
+            query["text"] = str(text).lower()
+        if chunk_size is not None:
+            query["chunkSize"] = str(chunk_size)
+        if mode:
+            query["mode"] = mode
+        return self._get(f"/v1/transcript?{urlencode(query)}")
+
+    def transcript_job(self, job_id: str) -> dict[str, Any]:
+        return self._get(f"/v1/transcript/{job_id}")
+
+    def wait_for_transcript(
+        self,
+        job: dict[str, Any] | str,
+        *,
+        interval: float = 2.0,
+        timeout: float = 20 * 60,
+    ) -> dict[str, Any]:
+        job_id = job if isinstance(job, str) else str(job["jobId"])
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            time.sleep(interval)
+            result = self.transcript_job(job_id)
+            if "content" in result:
+                return result
+            if result.get("status") in {"failed", "cancelled"}:
+                raise CapslaneError(422, str(result.get("error", result["status"])), f"Transcript job {result['status']}", result.get("requestId"))
+        raise CapslaneError(504, "processing_timeout", "Transcript job deadline exceeded")
+
+    def _get(self, path: str) -> dict[str, Any]:
+        request = Request(
+            f"{self.base_url}{path}",
+            headers={"x-api-key": self.api_key, "accept": "application/json"},
+        )
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except HTTPError as error:
+            body = self._error_body(error)
+            raise CapslaneError(error.code, str(body.get("error", "request_failed")), str(body.get("message", "Capslane request failed")), body.get("requestId")) from error
+        except URLError as error:
+            raise CapslaneError(0, "network_error", str(error.reason)) from error
+
+    @staticmethod
+    def _error_body(error: HTTPError) -> dict[str, Any]:
+        try:
+            return json.loads(error.read().decode("utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            return {"error": "request_failed", "message": "Capslane request failed"}

capslane-0.1.0/src/capslane/py.typed

@@ -0,0 +1 @@
+

capslane-0.1.0/tests/test_client.py

@@ -0,0 +1,35 @@
+import json
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).parents[1] / "src"))
+
+from capslane import CapslaneClient
+
+
+class FakeResponse:
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_args):
+        return None
+
+    def read(self):
+        return json.dumps({"content": [], "lang": "en", "requestId": "req_test"}).encode()
+
+
+class CapslaneClientTest(unittest.TestCase):
+    @patch("capslane.client.urlopen", return_value=FakeResponse())
+    def test_api_key_stays_in_header(self, mocked_urlopen):
+        client = CapslaneClient("vxl_test_secret")
+        result = client.transcript("dQw4w9WgXcQ", mode="native")
+        request = mocked_urlopen.call_args.args[0]
+        self.assertEqual(result["requestId"], "req_test")
+        self.assertNotIn("vxl_test_secret", request.full_url)
+        self.assertEqual(request.headers["X-api-key"], "vxl_test_secret")
+
+
+if __name__ == "__main__":
+    unittest.main()