Create wiki page 'API'

2026-05-27 14:53:12 +00:00
parent d0f4d5dfa9
commit 0b6f59ebdc
1 changed files with 86 additions and 0 deletions
@@ -0,0 +1,86 @@
+# API
+
+## Exported objects
+
+The package exports:
+
+- `download`
+- `download_short`
+- `download_to_path`
+- `validate_session_file`
+- `DownloadedVideo`
+- `SessionValidation`
+- `InvalidUrlError`
+- `InvalidSessionError`
+- `JsRuntimeUnavailableError`
+- `VideoDownloadError`
+- `YtShortsDownloaderError`
+
+## download
+
+```python
+from yt_shorts_downloader import download
+
+video = download(url, session_path)
+```
+
+Behavior:
+
+- validates the YouTube URL
+- validates the cookie file
+- downloads into a temporary directory
+- ensures the final file is MP4
+- returns a `DownloadedVideo`
+
+`DownloadedVideo` fields:
+
+- `filename`
+- `content`
+- `media_type`
+
+## download_short
+
+Alias for `download`.
+
+## download_to_path
+
+```python
+from yt_shorts_downloader import download_to_path
+
+path = download_to_path(url, session_path, output_dir='downloads')
+```
+
+Behavior:
+
+- validates the URL and session file
+- downloads directly into the target output directory
+- returns the saved file path
+
+## validate_session_file
+
+```python
+from pathlib import Path
+from yt_shorts_downloader import validate_session_file
+
+result = validate_session_file(Path('cookies.txt'))
+```
+
+`SessionValidation` fields:
+
+- `exists`
+- `structurally_valid`
+- `fresh`
+- `is_usable`
+- `message`
+
+## Exceptions
+
+- `InvalidUrlError`: unsupported or malformed URL
+- `InvalidSessionError`: invalid or stale cookie file
+- `JsRuntimeUnavailableError`: Deno or Node.js 22+ not found
+- `VideoDownloadError`: yt-dlp failed or did not produce MP4
+- `YtShortsDownloaderError`: base package exception
+
+## Notes
+
+The public API is designed so that server-side integrations can immediately return MP4 bytes without managing temporary files themselves.