cli-web-youtube 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,3 @@
+"""cli-web-youtube — CLI for YouTube video search and browsing."""
+
+__version__ = "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/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/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/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/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/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/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")

cli_web/youtube/core/models.py

@@ -0,0 +1,149 @@
+"""Data models for cli-web-youtube — normalize InnerTube responses."""
+
+from __future__ import annotations
+
+
+def format_video_from_renderer(renderer: dict) -> dict:
+    """Extract video data from a videoRenderer object."""
+    title_runs = renderer.get("title", {}).get("runs", [])
+    title = title_runs[0].get("text", "") if title_runs else ""
+
+    owner_runs = renderer.get("ownerText", {}).get("runs", [])
+    channel = owner_runs[0].get("text", "") if owner_runs else ""
+    channel_id = ""
+    if owner_runs:
+        nav = owner_runs[0].get("navigationEndpoint", {})
+        channel_id = nav.get("browseEndpoint", {}).get("browseId", "")
+
+    views_text = renderer.get("viewCountText", {}).get("simpleText", "")
+    length_text = renderer.get("lengthText", {}).get("simpleText", "")
+    published = renderer.get("publishedTimeText", {}).get("simpleText", "")
+
+    thumbs = renderer.get("thumbnail", {}).get("thumbnails", [])
+    thumbnail = thumbs[-1].get("url", "") if thumbs else ""
+
+    desc_runs = renderer.get("detailedMetadataSnippets", [])
+    description = ""
+    if desc_runs:
+        snippet_runs = desc_runs[0].get("snippetText", {}).get("runs", [])
+        description = "".join(r.get("text", "") for r in snippet_runs)
+
+    return {
+        "id": renderer.get("videoId", ""),
+        "title": title,
+        "channel": channel,
+        "channel_id": channel_id,
+        "views": views_text,
+        "duration": length_text,
+        "published": published,
+        "thumbnail": thumbnail,
+        "description": description,
+        "url": f"https://www.youtube.com/watch?v={renderer.get('videoId', '')}",
+    }
+
+
+def format_video_detail(video_details: dict, microformat: dict | None = None) -> dict:
+    """Extract full video details from player response."""
+    thumbs = video_details.get("thumbnail", {}).get("thumbnails", [])
+    thumbnail = thumbs[-1].get("url", "") if thumbs else ""
+
+    result = {
+        "id": video_details.get("videoId", ""),
+        "title": video_details.get("title", ""),
+        "channel": video_details.get("author", ""),
+        "channel_id": video_details.get("channelId", ""),
+        "views": int(video_details.get("viewCount", 0)),
+        "duration_seconds": int(video_details.get("lengthSeconds", 0)),
+        "description": video_details.get("shortDescription", ""),
+        "keywords": video_details.get("keywords", []),
+        "thumbnail": thumbnail,
+        "is_live": video_details.get("isLiveContent", False),
+        "url": f"https://www.youtube.com/watch?v={video_details.get('videoId', '')}",
+    }
+
+    if microformat:
+        mf = microformat.get("playerMicroformatRenderer", {})
+        result["publish_date"] = mf.get("publishDate", "")
+        result["category"] = mf.get("category", "")
+        result["is_family_safe"] = mf.get("isFamilySafe", True)
+
+    return result
+
+
+def format_channel(header: dict, metadata: dict | None = None) -> dict:
+    """Extract channel info from browse response."""
+    # Try c4TabbedHeaderRenderer (standard channels)
+    c4 = header.get("c4TabbedHeaderRenderer", {})
+    if c4:
+        thumbs = c4.get("avatar", {}).get("thumbnails", [])
+        avatar = thumbs[-1].get("url", "") if thumbs else ""
+        banner_thumbs = c4.get("banner", {}).get("thumbnails", [])
+        banner = banner_thumbs[-1].get("url", "") if banner_thumbs else ""
+
+        sub_text = c4.get("subscriberCountText", {}).get("simpleText", "")
+
+        return {
+            "channel_id": c4.get("channelId", ""),
+            "title": c4.get("title", ""),
+            "subscriber_count": sub_text,
+            "avatar": avatar,
+            "banner": banner,
+            "url": f"https://www.youtube.com/channel/{c4.get('channelId', '')}",
+        }
+
+    # Try pageHeaderRenderer (newer layout)
+    ph = header.get("pageHeaderRenderer", {})
+    if ph:
+        title = ph.get("pageTitle", "")
+        content = ph.get("content", {}).get("pageHeaderViewModel", {})
+        desc = content.get("description", {}).get("descriptionPreviewViewModel", {})
+        desc_text = desc.get("description", {}).get("content", "")
+
+        image = (
+            content.get("image", {})
+            .get("decoratedAvatarViewModel", {})
+            .get("avatar", {})
+            .get("avatarViewModel", {})
+            .get("image", {})
+            .get("sources", [])
+        )
+        avatar = image[-1].get("url", "") if image else ""
+
+        metadata_row = (
+            content.get("metadata", {}).get("contentMetadataViewModel", {}).get("metadataRows", [])
+        )
+        subs = ""
+        videos = ""
+        for row in metadata_row:
+            for part in row.get("metadataParts", []):
+                text = part.get("text", {}).get("content", "")
+                if "subscriber" in text.lower():
+                    subs = text
+                elif "video" in text.lower():
+                    videos = text
+
+        return {
+            "channel_id": "",
+            "title": title,
+            "description": desc_text,
+            "subscriber_count": subs,
+            "video_count": videos,
+            "avatar": avatar,
+            "url": "",
+        }
+
+    return {"error": "Unknown header format", "keys": list(header.keys())}
+
+
+def format_trending_videos(contents: list) -> list[dict]:
+    """Extract videos from trending browse response."""
+    videos = []
+    for section in contents:
+        items = section.get("itemSectionRenderer", {}).get("contents", []) or section.get(
+            "shelfRenderer", {}
+        ).get("content", {}).get("expandedShelfContentsRenderer", {}).get("items", [])
+        for item in items:
+            renderer = item.get("videoRenderer")
+            if renderer:
+                videos.append(format_video_from_renderer(renderer))
+    return videos