cli-web-youtube 0.1.0__tar.gz

cli_web_youtube-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: cli-web-youtube
+Version: 0.1.0
+Summary: CLI for YouTube — search videos, get details, browse trending, explore channels
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: httpx
+Requires-Dist: prompt_toolkit>=3.0
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

cli_web_youtube-0.1.0/cli_web/youtube/README.md

@@ -0,0 +1,49 @@
+# cli-web-youtube
+
+> Generated by [CLI-Anything-Web](../../../../cli-anything-web-plugin/) from [youtube.com](https://www.youtube.com)
+
+Search YouTube videos, get video details, browse trending content, and explore channels — all from the command line.
+
+## Installation
+
+```bash
+pip install cli-web-youtube
+```
+
+## Usage
+
+```bash
+# Search for videos
+cli-web-youtube search videos "python tutorial" --limit 10
+
+# Get video details
+cli-web-youtube video get dQw4w9WgXcQ --json
+
+# Browse trending
+cli-web-youtube trending list --category music --limit 10
+
+# Channel info
+cli-web-youtube channel get @MrBeast --json
+
+# Interactive REPL
+cli-web-youtube
+```
+
+## Auth
+
+No authentication required — all commands access public YouTube content.
+
+## JSON Output
+
+All commands support `--json` for structured output:
+
+```bash
+cli-web-youtube search videos "AI" --limit 3 --json
+cli-web-youtube video get dQw4w9WgXcQ --json
+```
+
+## Testing
+
+```bash
+python -m pytest cli_web/youtube/tests/ -v
+```

cli_web_youtube-0.1.0/cli_web/youtube/__init__.py

@@ -0,0 +1,3 @@
+"""cli-web-youtube — CLI for YouTube video search and browsing."""
+
+__version__ = "0.1.0"

cli_web_youtube-0.1.0/cli_web/youtube/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as python -m cli_web.youtube."""
+
+from cli_web.youtube.youtube_cli import main
+
+if __name__ == "__main__":
+    main()

cli_web_youtube-0.1.0/cli_web/youtube/commands/channel.py

@@ -0,0 +1,42 @@
+"""Channel command for cli-web-youtube."""
+
+from __future__ import annotations
+
+import click
+
+from ..core.client import YouTubeClient
+from ..utils.helpers import handle_errors, print_json, resolve_json_mode
+from ..utils.output import print_channel_detail
+
+
+@click.group("channel")
+def channel_group():
+    """Browse YouTube channels."""
+
+
+@channel_group.command("get")
+@click.argument("handle")
+@click.option("--json", "use_json", is_flag=True, help="Output as JSON.")
+def channel_get(handle, use_json):
+    """Get channel info and recent videos.
+
+    HANDLE can be @username, channel ID (UC...), or URL.
+
+    Example: channel get @MrBeast
+    """
+    # Extract handle from URL if needed
+    if "youtube.com" in handle:
+        if "/@" in handle:
+            handle = handle.split("/@")[1].split("/")[0]
+            handle = f"@{handle}"
+        elif "/channel/" in handle:
+            handle = handle.split("/channel/")[1].split("/")[0]
+
+    use_json = resolve_json_mode(use_json)
+    with handle_errors(json_mode=use_json):
+        client = YouTubeClient()
+        result = client.channel(handle)
+        if use_json:
+            print_json(result)
+        else:
+            print_channel_detail(result)

cli_web_youtube-0.1.0/cli_web/youtube/commands/search.py

@@ -0,0 +1,34 @@
+"""Search command for cli-web-youtube."""
+
+from __future__ import annotations
+
+import click
+
+from ..core.client import YouTubeClient
+from ..utils.helpers import handle_errors, print_json, resolve_json_mode
+from ..utils.output import print_videos_table
+
+
+@click.group("search")
+def search_group():
+    """Search YouTube videos."""
+
+
+@search_group.command("videos")
+@click.argument("query")
+@click.option("--limit", "-l", default=10, type=int, help="Max results (default 10).")
+@click.option("--json", "use_json", is_flag=True, help="Output as JSON.")
+def search_videos(query, limit, use_json):
+    """Search for videos by query.
+
+    Example: search videos "python tutorial"
+    """
+    use_json = resolve_json_mode(use_json)
+    with handle_errors(json_mode=use_json):
+        client = YouTubeClient()
+        result = client.search(query, limit=limit)
+        if use_json:
+            print_json(result)
+        else:
+            click.echo(f'\n  Search: "{query}" ({result["estimated_results"]:,} results)\n')
+            print_videos_table(result["videos"])

cli_web_youtube-0.1.0/cli_web/youtube/commands/trending.py

@@ -0,0 +1,41 @@
+"""Trending command for cli-web-youtube."""
+
+from __future__ import annotations
+
+import click
+
+from ..core.client import YouTubeClient
+from ..utils.helpers import handle_errors, print_json, resolve_json_mode
+from ..utils.output import print_videos_table
+
+
+@click.group("trending")
+def trending_group():
+    """Browse trending YouTube videos."""
+
+
+@trending_group.command("list")
+@click.option(
+    "--category",
+    "-c",
+    default="now",
+    type=click.Choice(["now", "music", "gaming", "movies"], case_sensitive=False),
+    help="Category filter (default: now).",
+)
+@click.option("--limit", "-l", default=20, type=int, help="Max results (default 20).")
+@click.option("--json", "use_json", is_flag=True, help="Output as JSON.")
+def trending_list(category, limit, use_json):
+    """List trending/popular videos.
+
+    Example: trending list --category music --limit 10
+    """
+    use_json = resolve_json_mode(use_json)
+    with handle_errors(json_mode=use_json):
+        client = YouTubeClient()
+        videos = client.trending(category=category)
+        videos = videos[:limit]
+        if use_json:
+            print_json({"videos": videos, "count": len(videos), "category": category})
+        else:
+            click.echo(f"\n  Trending on YouTube — {category.title()} ({len(videos)} videos)\n")
+            print_videos_table(videos)

cli_web_youtube-0.1.0/cli_web/youtube/commands/video.py

@@ -0,0 +1,41 @@
+"""Video command for cli-web-youtube."""
+
+from __future__ import annotations
+
+import click
+
+from ..core.client import YouTubeClient
+from ..utils.helpers import handle_errors, print_json, resolve_json_mode
+from ..utils.output import print_video_detail
+
+
+@click.group("video")
+def video_group():
+    """Get video details."""
+
+
+@video_group.command("get")
+@click.argument("video_id")
+@click.option("--json", "use_json", is_flag=True, help="Output as JSON.")
+def video_get(video_id, use_json):
+    """Get details for a specific video.
+
+    VIDEO_ID can be the 11-character ID or a full YouTube URL.
+
+    Example: video get dQw4w9WgXcQ
+    """
+    # Extract video ID from URL if needed
+    if "youtube.com" in video_id or "youtu.be" in video_id:
+        if "v=" in video_id:
+            video_id = video_id.split("v=")[1].split("&")[0]
+        elif "youtu.be/" in video_id:
+            video_id = video_id.split("youtu.be/")[1].split("?")[0]
+
+    use_json = resolve_json_mode(use_json)
+    with handle_errors(json_mode=use_json):
+        client = YouTubeClient()
+        result = client.video_detail(video_id)
+        if use_json:
+            print_json(result)
+        else:
+            print_video_detail(result)

cli_web_youtube-0.1.0/cli_web/youtube/core/client.py

@@ -0,0 +1,244 @@
+"""HTTP client for YouTube InnerTube API."""
+
+from __future__ import annotations
+
+import httpx
+
+from .exceptions import (
+    NetworkError,
+    NotFoundError,
+    ParseError,
+    RateLimitError,
+    ServerError,
+    YouTubeError,
+)
+from .models import (
+    format_channel,
+    format_video_detail,
+    format_video_from_renderer,
+)
+
+INNERTUBE_URL = "https://www.youtube.com/youtubei/v1"
+INNERTUBE_CONTEXT = {
+    "client": {
+        "clientName": "WEB",
+        "clientVersion": "2.20260326.01.00",
+        "hl": "en",
+        "gl": "US",
+    }
+}
+
+
+class YouTubeClient:
+    """Client for YouTube's InnerTube API."""
+
+    def __init__(self):
+        self._session = httpx.Client(
+            timeout=15.0,
+            headers={
+                "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            follow_redirects=True,
+        )
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self._session.close()
+
+    def close(self):
+        self._session.close()
+
+    # ── Internal ──────────────────────────────────────────────
+
+    def _post(self, endpoint: str, body: dict) -> dict:
+        """POST to InnerTube API with context."""
+        url = f"{INNERTUBE_URL}/{endpoint}?prettyPrint=false"
+        payload = {"context": INNERTUBE_CONTEXT, **body}
+        try:
+            resp = self._session.post(url, json=payload)
+        except httpx.TimeoutException as exc:
+            raise NetworkError(f"Request timed out: {exc}") from exc
+        except Exception as exc:
+            raise NetworkError(f"Request failed: {exc}") from exc
+        return self._handle_response(resp, endpoint)
+
+    def _handle_response(self, resp: httpx.Response, endpoint: str = "") -> dict:
+        if resp.status_code == 404:
+            raise NotFoundError(f"Not found: {endpoint}")
+        if resp.status_code == 429:
+            retry = resp.headers.get("retry-after")
+            raise RateLimitError(
+                retry_after=float(retry) if retry else None,
+            )
+        if resp.status_code >= 500:
+            raise ServerError(
+                f"YouTube server error: HTTP {resp.status_code}",
+                status_code=resp.status_code,
+            )
+        if resp.status_code >= 400:
+            raise YouTubeError(f"HTTP {resp.status_code}: {resp.text[:200]}")
+        try:
+            return resp.json()
+        except Exception as exc:
+            raise ParseError(f"Failed to parse response: {exc}") from exc
+
+    # ── Search ────────────────────────────────────────────────
+
+    def search(self, query: str, limit: int = 20) -> dict:
+        """Search YouTube videos."""
+        resp = self._post("search", {"query": query})
+
+        contents = (
+            resp.get("contents", {})
+            .get("twoColumnSearchResultsRenderer", {})
+            .get("primaryContents", {})
+            .get("sectionListRenderer", {})
+            .get("contents", [])
+        )
+
+        videos = []
+        for section in contents:
+            items = section.get("itemSectionRenderer", {}).get("contents", [])
+            for item in items:
+                renderer = item.get("videoRenderer")
+                if renderer:
+                    videos.append(format_video_from_renderer(renderer))
+                    if len(videos) >= limit:
+                        break
+            if len(videos) >= limit:
+                break
+
+        estimated = resp.get("estimatedResults", "0")
+
+        return {
+            "query": query,
+            "estimated_results": int(estimated),
+            "videos": videos,
+        }
+
+    # ── Video detail ──────────────────────────────────────────
+
+    def video_detail(self, video_id: str) -> dict:
+        """Get video details via player endpoint."""
+        resp = self._post("player", {"videoId": video_id})
+        video_details = resp.get("videoDetails")
+        if not video_details:
+            raise NotFoundError(f"Video not found: {video_id}")
+        microformat = resp.get("microformat")
+        return format_video_detail(video_details, microformat)
+
+    # ── Trending ──────────────────────────────────────────────
+
+    def trending(self, category: str = "now") -> list[dict]:
+        """Get trending/popular videos via search with sort by view count.
+
+        YouTube's trending page requires auth for non-logged-in users,
+        so we use the search API with popular sort filters as a proxy.
+        """
+        # Map categories to search queries that surface popular content
+        queries = {
+            "now": "",  # empty query with sort=viewCount returns popular recent videos
+            "music": "music",
+            "gaming": "gaming",
+            "movies": "movies",
+        }
+        query = queries.get(category, category)
+
+        # Use search with empty/broad query — returns popular videos
+        resp = self._post(
+            "search",
+            {
+                "query": query if query else "trending",
+                "params": "CAMSAhAB",  # sort by upload date, filter videos only
+            },
+        )
+
+        contents = (
+            resp.get("contents", {})
+            .get("twoColumnSearchResultsRenderer", {})
+            .get("primaryContents", {})
+            .get("sectionListRenderer", {})
+            .get("contents", [])
+        )
+
+        videos = []
+        for section in contents:
+            items = section.get("itemSectionRenderer", {}).get("contents", [])
+            for item in items:
+                renderer = item.get("videoRenderer")
+                if renderer:
+                    videos.append(format_video_from_renderer(renderer))
+
+        return videos
+
+    # ── Channel ───────────────────────────────────────────────
+
+    def channel(self, handle: str) -> dict:
+        """Get channel info via browse endpoint.
+
+        Accepts @handle, channel ID (UC...), or /c/name format.
+        """
+        # For @handles, scrape the channel page HTML to get ytInitialData
+        # This is more reliable than the browse API which needs an API key
+        import json as _json
+
+        clean = handle.lstrip("@")
+        if handle.startswith("UC"):
+            channel_url = f"https://www.youtube.com/channel/{handle}"
+        else:
+            channel_url = f"https://www.youtube.com/@{clean}"
+
+        try:
+            page_resp = self._session.get(channel_url)
+        except Exception as exc:
+            raise NetworkError(f"Failed to fetch channel: {exc}") from exc
+
+        if page_resp.status_code == 404:
+            raise NotFoundError(f"Channel not found: {handle}")
+
+        text = page_resp.text
+        marker = "var ytInitialData = "
+        idx = text.find(marker)
+        if idx < 0:
+            raise ParseError(f"Could not find channel data for: {handle}")
+
+        start = idx + len(marker)
+        end = text.find(";</script>", start)
+        if end < 0:
+            end = text.find(";\n", start)
+
+        try:
+            resp = _json.loads(text[start:end])
+        except _json.JSONDecodeError as exc:
+            raise ParseError(f"Failed to parse channel data: {exc}") from exc
+        header = resp.get("header", {})
+        metadata = resp.get("metadata", {}).get("channelMetadataRenderer", {})
+        result = format_channel(header)
+        if "channel_id" in result and not result["channel_id"]:
+            result["channel_id"] = metadata.get("externalId", "")
+        if not result.get("url"):
+            result["url"] = metadata.get("channelUrl", channel_url)
+
+        # Extract recent videos from tabs
+        tabs = resp.get("contents", {}).get("twoColumnBrowseResultsRenderer", {}).get("tabs", [])
+        recent_videos = []
+        for tab in tabs:
+            tab_content = tab.get("tabRenderer", {}).get("content", {})
+            sections = tab_content.get("sectionListRenderer", {}).get(
+                "contents", []
+            ) or tab_content.get("richGridRenderer", {}).get("contents", [])
+            for section in sections[:10]:
+                # richItemRenderer wraps videoRenderer in newer layouts
+                rich = section.get("richItemRenderer", {}).get("content", {})
+                renderer = rich.get("videoRenderer") or section.get("videoRenderer")
+                if renderer:
+                    recent_videos.append(format_video_from_renderer(renderer))
+            if recent_videos:
+                break
+
+        result["recent_videos"] = recent_videos[:10]
+        return result

cli_web_youtube-0.1.0/cli_web/youtube/core/exceptions.py

@@ -0,0 +1,63 @@
+"""Domain exception hierarchy for cli-web-youtube."""
+
+
+class YouTubeError(Exception):
+    """Base for all YouTube CLI errors."""
+
+    def __init__(self, message: str, code: str = "YOUTUBE_ERROR"):
+        self.message = message
+        self.code = code
+        super().__init__(message)
+
+    def to_dict(self) -> dict:
+        return {"error": True, "code": self.code, "message": self.message}
+
+
+class AuthError(YouTubeError):
+    """Authentication required or expired."""
+
+    def __init__(self, message: str = "Authentication required.", recoverable: bool = False):
+        self.recoverable = recoverable
+        super().__init__(message, "AUTH_EXPIRED")
+
+
+class RateLimitError(YouTubeError):
+    """429 — retry with backoff."""
+
+    def __init__(self, message: str = "Rate limited by YouTube.", retry_after: float | None = None):
+        self.retry_after = retry_after
+        super().__init__(message, "RATE_LIMITED")
+
+    def to_dict(self) -> dict:
+        d = super().to_dict()
+        d["retry_after"] = self.retry_after
+        return d
+
+
+class NetworkError(YouTubeError):
+    """Connection/DNS/timeout errors."""
+
+    def __init__(self, message: str):
+        super().__init__(message, "NETWORK_ERROR")
+
+
+class ServerError(YouTubeError):
+    """5xx responses."""
+
+    def __init__(self, message: str, status_code: int = 500):
+        self.status_code = status_code
+        super().__init__(message, "SERVER_ERROR")
+
+
+class NotFoundError(YouTubeError):
+    """404 — resource not found."""
+
+    def __init__(self, message: str = "Resource not found"):
+        super().__init__(message, "NOT_FOUND")
+
+
+class ParseError(YouTubeError):
+    """Failed to parse YouTube response."""
+
+    def __init__(self, message: str = "Failed to parse YouTube response"):
+        super().__init__(message, "PARSE_ERROR")