yt-metrics-cli 0.2.0__py3-none-any.whl

src/__init__.py

@@ -0,0 +1,3 @@
+"""YT Metrics CLI - Channel analyzer and transcript downloader."""
+
+__version__ = "0.1.0"

src/analyzer.py

@@ -0,0 +1,314 @@
+"""YouTube channel analysis and API interaction."""
+
+import logging
+import time
+from typing import Any
+
+import googleapiclient.discovery
+from googleapiclient.errors import HttpError
+
+from .config import get_settings
+from .metrics import calculate_engagement_metrics
+
+logger = logging.getLogger(__name__)
+
+MAX_RETRIES = 3
+BASE_DELAY = 1.0
+
+
+def _execute_with_retry(request: Any) -> dict[str, Any]:
+    """Execute an API request with exponential backoff on quota/rate errors."""
+    for attempt in range(MAX_RETRIES + 1):
+        try:
+            result: dict[str, Any] = request.execute()
+            return result
+        except HttpError as e:
+            if e.resp.status in (403, 429) and attempt < MAX_RETRIES:
+                delay = BASE_DELAY * (2 ** attempt)
+                logger.warning(
+                    "API rate limit (HTTP %d), retry %d/%d in %.1fs...",
+                    e.resp.status, attempt + 1, MAX_RETRIES, delay,
+                )
+                time.sleep(delay)
+            else:
+                raise
+    return {}  # unreachable but satisfies mypy
+
+
+class YouTubeChannelAnalyzer:
+    def __init__(self, api_key: str | None = None) -> None:
+        settings = get_settings()
+        self.api_key = api_key or settings.youtube_api_key
+        if not self.api_key:
+            msg = (
+                "YouTube API key required. "
+                "Set YOUTUBE_API_KEY environment variable or pass it directly."
+            )
+            raise ValueError(msg)
+
+        self.youtube = googleapiclient.discovery.build(
+            "youtube", "v3", developerKey=self.api_key
+        )
+
+    def validate_api_key(self) -> bool:
+        """Validate the YouTube API key by making a minimal API call."""
+        try:
+            request = self.youtube.i18nRegions().list(part="snippet")
+            request.execute()
+            return True
+        except HttpError as e:
+            error_content = e.content.decode("utf-8") if e.content else str(e)
+            if e.resp.status == 400:
+                self._handle_400_error(error_content, e)
+            elif e.resp.status == 403:
+                self._handle_403_error(error_content, e)
+            else:
+                msg = f"API validation failed with status {e.resp.status}: {error_content}"
+                raise RuntimeError(msg) from e
+        except (ValueError, RuntimeError):
+            raise
+        except Exception as e:
+            msg = f"Unexpected error validating API key: {e}"
+            raise RuntimeError(msg) from e
+        return False  # unreachable but satisfies mypy
+
+    def get_channel_id_from_username(self, username: str) -> str:
+        """Resolve channel ID from legacy username."""
+        request = self.youtube.channels().list(part="id", forUsername=username)
+        response = _execute_with_retry(request)
+
+        if "items" in response and len(response["items"]) > 0:
+            return str(response["items"][0]["id"])
+        msg = f"No channel found with username: {username}"
+        raise ValueError(msg)
+
+    def get_channel_id_from_custom_url(self, custom_url: str) -> str:
+        """Resolve channel ID from custom URL (@handle)."""
+        if custom_url.startswith("@"):
+            custom_url = custom_url[1:]
+
+        request = self.youtube.search().list(
+            part="snippet", q=custom_url, type="channel", maxResults=1
+        )
+        response = _execute_with_retry(request)
+
+        if "items" in response and len(response["items"]) > 0:
+            return str(response["items"][0]["snippet"]["channelId"])
+        msg = f"No channel found with custom URL: @{custom_url}"
+        raise ValueError(msg)
+
+    def get_channel_info(self, channel_id: str) -> dict[str, Any]:
+        """Get channel metadata and statistics."""
+        request = self.youtube.channels().list(part="snippet,statistics", id=channel_id)
+        response = _execute_with_retry(request)
+
+        if "items" not in response or len(response["items"]) == 0:
+            msg = f"No channel found with ID: {channel_id}"
+            raise ValueError(msg)
+
+        channel_item = response["items"][0]
+        return {
+            "id": channel_id,
+            "title": channel_item["snippet"]["title"],
+            "description": channel_item["snippet"]["description"],
+            "subscriber_count": channel_item["statistics"].get("subscriberCount"),
+            "video_count": channel_item["statistics"].get("videoCount"),
+            "view_count": channel_item["statistics"].get("viewCount"),
+            "thumbnail": channel_item["snippet"]["thumbnails"]["default"]["url"],
+            "url": f"https://www.youtube.com/channel/{channel_id}",
+        }
+
+    def get_channel_videos(
+        self,
+        channel_id: str | None = None,
+        username: str | None = None,
+        custom_url: str | None = None,
+        max_results: int = 50,
+    ) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+        """Get videos from a channel with statistics."""
+        if channel_id is None and username is None and custom_url is None:
+            msg = "Must provide channel_id, username, or custom_url"
+            raise ValueError(msg)
+
+        if channel_id is None:
+            if username:
+                channel_id = self.get_channel_id_from_username(username)
+            elif custom_url:
+                channel_id = self.get_channel_id_from_custom_url(custom_url)
+
+        assert channel_id is not None  # guaranteed by logic above
+        channel_info = self.get_channel_info(channel_id)
+        uploads_playlist_id = self._get_uploads_playlist(channel_id)
+        videos = self._fetch_playlist_videos(uploads_playlist_id, max_results)
+        videos_with_stats = self._get_videos_statistics(videos)
+
+        return channel_info, videos_with_stats
+
+    def get_multiple_channels_videos(
+        self,
+        channel_list: list[dict[str, Any]],
+        max_results_per_channel: int = 20,
+    ) -> list[dict[str, Any]]:
+        """Get videos from multiple channels with engagement metrics."""
+        all_channels_data: list[dict[str, Any]] = []
+        failed_channels: list[dict[str, Any]] = []
+
+        for channel in channel_list:
+            try:
+                channel_info, videos = self.get_channel_videos(
+                    channel_id=channel.get("channel_id"),
+                    username=channel.get("username"),
+                    custom_url=channel.get("custom_url"),
+                    max_results=max_results_per_channel,
+                )
+
+                subscriber_count = int(channel_info.get("subscriber_count", 0) or 0)
+                videos_with_metrics = calculate_engagement_metrics(videos, subscriber_count)
+
+                all_channels_data.append({"channel": channel_info, "videos": videos_with_metrics})
+                logger.info("Retrieved %d videos from %s", len(videos), channel_info["title"])
+
+            except Exception as e:
+                failed_channels.append({"channel": channel, "error": str(e)})
+                logger.warning("Error retrieving channel %s: %s", channel, e)
+
+        if failed_channels:
+            logger.warning("Failed to retrieve %d channels", len(failed_channels))
+
+        return all_channels_data
+
+    # --- Private helpers ---
+
+    def _get_uploads_playlist(self, channel_id: str) -> str:
+        """Get the uploads playlist ID for a channel."""
+        request = self.youtube.channels().list(part="contentDetails", id=channel_id)
+        response = _execute_with_retry(request)
+
+        if "items" not in response or len(response["items"]) == 0:
+            msg = f"No channel found with ID: {channel_id}"
+            raise ValueError(msg)
+
+        return str(
+            response["items"][0]["contentDetails"]["relatedPlaylists"]["uploads"]
+        )
+
+    def _fetch_playlist_videos(
+        self, playlist_id: str, max_results: int
+    ) -> list[dict[str, Any]]:
+        """Fetch video IDs and metadata from a playlist."""
+        videos: list[dict[str, Any]] = []
+        next_page_token: str | None = None
+
+        while len(videos) < max_results:
+            request = self.youtube.playlistItems().list(
+                part="snippet,contentDetails",
+                playlistId=playlist_id,
+                maxResults=min(50, max_results - len(videos)),
+                pageToken=next_page_token,
+            )
+            response = _execute_with_retry(request)
+
+            for item in response["items"]:
+                video_id = item["contentDetails"]["videoId"]
+                videos.append(
+                    {
+                        "id": video_id,
+                        "title": item["snippet"]["title"],
+                        "published_at": item["snippet"]["publishedAt"],
+                        "url": f"https://www.youtube.com/watch?v={video_id}",
+                    }
+                )
+
+            next_page_token = response.get("nextPageToken")
+            if not next_page_token or len(videos) >= max_results:
+                break
+
+        return videos
+
+    def _get_videos_statistics(
+        self, videos: list[dict[str, Any]]
+    ) -> list[dict[str, Any]]:
+        """Fetch detailed statistics for videos in batches."""
+        if not videos:
+            return videos
+
+        settings = get_settings()
+        videos_with_stats: list[dict[str, Any]] = []
+
+        for i in range(0, len(videos), settings.api_batch_size):
+            batch = videos[i : i + settings.api_batch_size]
+            video_ids = [video["id"] for video in batch]
+
+            request = self.youtube.videos().list(
+                part="statistics,contentDetails", id=",".join(video_ids)
+            )
+            response = _execute_with_retry(request)
+
+            stats_map: dict[str, dict[str, Any]] = {}
+            for item in response.get("items", []):
+                stats_map[item["id"]] = {
+                    "statistics": item.get("statistics", {}),
+                    "contentDetails": item.get("contentDetails", {}),
+                }
+
+            for video in batch:
+                vid = video["id"]
+                if vid in stats_map:
+                    stats = stats_map[vid]["statistics"]
+                    content = stats_map[vid]["contentDetails"]
+                    video.update(
+                        {
+                            "view_count": int(stats.get("viewCount", 0)),
+                            "like_count": int(stats.get("likeCount", 0)),
+                            "comment_count": int(stats.get("commentCount", 0)),
+                            "duration": content.get("duration", "PT0S"),
+                        }
+                    )
+                else:
+                    video.update(
+                        {
+                            "view_count": 0,
+                            "like_count": 0,
+                            "comment_count": 0,
+                            "duration": "PT0S",
+                        }
+                    )
+                videos_with_stats.append(video)
+
+        return videos_with_stats
+
+    @staticmethod
+    def _handle_400_error(error_content: str, original: HttpError) -> None:
+        """Handle HTTP 400 errors from the YouTube API."""
+        if "API key not valid" in error_content or "invalid" in error_content.lower():
+            msg = (
+                "Invalid YouTube API key. Check your YOUTUBE_API_KEY in .env file.\n"
+                "Get a valid key: https://console.cloud.google.com/apis/credentials"
+            )
+            raise ValueError(msg) from original
+        if "API key expired" in error_content:
+            msg = (
+                "YouTube API key has expired. Generate a new key at:\n"
+                "https://console.cloud.google.com/apis/credentials"
+            )
+            raise ValueError(msg) from original
+        msg = f"API key validation failed: {error_content}"
+        raise ValueError(msg) from original
+
+    @staticmethod
+    def _handle_403_error(error_content: str, original: HttpError) -> None:
+        """Handle HTTP 403 errors from the YouTube API."""
+        if "quotaExceeded" in error_content:
+            msg = (
+                "YouTube API quota exceeded. Daily limit reached.\n"
+                "Quota resets at midnight Pacific Time. Try again later."
+            )
+            raise ValueError(msg) from original
+        if "accessNotConfigured" in error_content:
+            msg = (
+                "YouTube Data API v3 is not enabled for this key.\n"
+                "Enable: https://console.cloud.google.com/apis/library/youtube.googleapis.com"
+            )
+            raise ValueError(msg) from original
+        msg = f"API access forbidden: {error_content}"
+        raise ValueError(msg) from original

src/config.py

@@ -0,0 +1,62 @@
+"""Configuration via environment variables."""
+
+from pathlib import Path
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    # API credentials (empty = not set, validated per command)
+    youtube_api_key: str = ""
+
+    # API settings
+    max_results_per_channel: int = 50
+    api_batch_size: int = 50
+
+    # Output
+    output_dir: Path = Path("./output")
+
+    # Transcript
+    video_id: str = "tLkRAqmAEtE"
+    youtube_transcript_fixtures_dir: str = ""
+    transcript_languages: list[str] = ["es", "en"]  # noqa: B006
+
+    # Channels config
+    channels_file: Path = Path("channels.yml")
+
+    # Metric thresholds (for performance classification)
+    high_performance_multiplier: float = 1.5
+    low_performance_multiplier: float = 0.5
+
+    # Duration thresholds (seconds)
+    short_video_max: int = 300
+    long_video_min: int = 900
+
+
+_settings: Settings | None = None
+
+
+def get_settings() -> Settings:
+    """Load and cache settings from environment."""
+    global _settings  # noqa: PLW0603
+    if _settings is None:
+        _settings = Settings()
+    return _settings
+
+
+def reset_settings() -> None:
+    """Reset cached settings (useful for testing)."""
+    global _settings  # noqa: PLW0603
+    _settings = None
+
+
+def format_number(value: object) -> str:
+    """Format number with thousand separators or return 'N/A'."""
+    if value is None:
+        return "N/A"
+    try:
+        return f"{int(str(value)):,}"
+    except (ValueError, TypeError):
+        return "N/A"

src/exporters/__init__.py

@@ -0,0 +1,15 @@
+"""Report generators for yt-metrics-cli."""
+
+from src.exporters.csv_exporter import export_to_csv
+from src.exporters.readme_exporter import export_output_readme
+from src.exporters.text_exporter import export_channel_stats, export_engagement_trends_report
+from src.exporters.url_exporter import export_best_videos_report, export_latest_videos_report
+
+__all__ = [
+    "export_best_videos_report",
+    "export_channel_stats",
+    "export_engagement_trends_report",
+    "export_latest_videos_report",
+    "export_output_readme",
+    "export_to_csv",
+]

src/exporters/csv_exporter.py

@@ -0,0 +1,55 @@
+"""CSV export for channel and video data."""
+
+import csv
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def export_to_csv(channels_data: list[dict[str, Any]], filename: str | Path) -> None:
+    """Export channel and video data to CSV."""
+    if not channels_data:
+        logger.warning("No data to export.")
+        return
+
+    with open(filename, "w", newline="", encoding="utf-8") as csvfile:
+        writer = csv.writer(csvfile)
+
+        writer.writerow([
+            "Channel", "Subscribers", "Video Title", "Published Date", "Video URL",
+            "Views", "Likes", "Comments", "Duration (seconds)",
+            "Engagement Rate (Views %)", "Engagement Rate (Subscribers %)",
+            "View Rate (%)", "Like Rate (%)", "Comment Rate (%)", "Views per Minute",
+        ])
+
+        for channel_data in channels_data:
+            channel_info = channel_data["channel"]
+            channel_name = channel_info["title"]
+            subscriber_count = channel_info.get("subscriber_count", "N/A")
+
+            for video in channel_data["videos"]:
+                writer.writerow([
+                    channel_name,
+                    subscriber_count,
+                    video["title"],
+                    video["published_at"],
+                    video["url"],
+                    video.get("view_count", 0),
+                    video.get("like_count", 0),
+                    video.get("comment_count", 0),
+                    video.get("duration_seconds", 0),
+                    video.get("engagement_rate_views", 0),
+                    video.get("engagement_rate_subscribers", 0),
+                    video.get("view_rate", 0),
+                    video.get("like_rate", 0),
+                    video.get("comment_rate", 0),
+                    video.get("views_per_minute", 0),
+                ])
+
+    total_videos = sum(len(cd["videos"]) for cd in channels_data)
+    logger.info(
+        "Exported %d videos from %d channels to %s",
+        total_videos, len(channels_data), filename,
+    )

src/exporters/readme_exporter.py

@@ -0,0 +1,115 @@
+"""README generator for output directories."""
+
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from src.config import format_number
+
+logger = logging.getLogger(__name__)
+
+
+def export_output_readme(
+    output_dir: Path, timestamp: str, channels_data: list[dict[str, Any]]
+) -> None:
+    """Generate README.md in output directory explaining all generated files."""
+    readme_path = output_dir / "README.md"
+    total_channels = len(channels_data)
+    total_videos = sum(len(cd["videos"]) for cd in channels_data)
+    avg_videos = total_videos / total_channels if total_channels > 0 else 0
+
+    with open(readme_path, "w", encoding="utf-8") as f:
+        f.write(f"# YouTube Analysis Report - {timestamp}\n\n")
+        f.write(f"Generated on: {datetime.now().strftime('%Y-%m-%d at %H:%M:%S')}\n\n")
+
+        f.write("## Analysis Summary\n\n")
+        f.write(f"- **Channels Analyzed:** {total_channels}\n")
+        f.write(f"- **Total Videos:** {total_videos}\n")
+        f.write(f"- **Average Videos per Channel:** {avg_videos:.1f}\n\n")
+
+        _write_file_descriptions(f, timestamp)
+        _write_metrics_table(f)
+        _write_channels_list(f, channels_data)
+
+        f.write("\n---\n\n")
+        f.write("*Generated by YT Metrics CLI*\n")
+
+    logger.info("Generated README.md in output directory: %s", readme_path)
+
+
+def _write_file_descriptions(f: Any, timestamp: str) -> None:
+    """Write descriptions for each generated file."""
+    files = [
+        (
+            f"youtube_channels_videos_{timestamp}.csv",
+            "CSV (Comma-Separated Values)",
+            "Raw data export with complete metrics for all videos.",
+            ["Import into Excel/Google Sheets", "Data visualization with BI tools"],
+        ),
+        (
+            f"youtube_channel_stats_{timestamp}.txt",
+            "Plain text report",
+            "Per-channel statistics, top videos, and performance distribution.",
+            ["Quick overview of channel performance", "Identify content patterns"],
+        ),
+        (
+            f"youtube_engagement_trends_{timestamp}.txt",
+            "Plain text report",
+            "Cross-channel comparison, rankings, and trend analysis.",
+            ["Compare channels", "Discover viral content patterns"],
+        ),
+        (
+            f"youtube_best_videos_{timestamp}.txt",
+            "Plain text (URL list)",
+            "Top 15 videos with highest engagement rate from each channel.",
+            ["Quick access to best content", "Create playlists"],
+        ),
+        (
+            f"youtube_latest_videos_{timestamp}.txt",
+            "Plain text (URL list)",
+            "15 most recent videos from each channel.",
+            ["Track recent content", "Monitor channel activity"],
+        ),
+    ]
+
+    f.write("## Generated Files\n\n")
+    for name, fmt, desc, uses in files:
+        f.write(f"### `{name}`\n")
+        f.write(f"**Format:** {fmt}\n\n")
+        f.write(f"**Description:** {desc}\n\n")
+        f.write("**Use Cases:**\n")
+        for use in uses:
+            f.write(f"- {use}\n")
+        f.write("\n---\n\n")
+
+
+def _write_metrics_table(f: Any) -> None:
+    """Write engagement metrics explanation table."""
+    f.write("## Engagement Metrics Explained\n\n")
+    f.write("| Metric | Formula | Interpretation |\n")
+    f.write("|--------|---------|----------------|\n")
+    f.write(
+        "| **Engagement Rate (Views)** "
+        "| `(likes + comments) / views x 100` "
+        "| Audience interaction |\n"
+    )
+    f.write(
+        "| **Engagement Rate (Subs)** "
+        "| `(likes + comments) / subscribers x 100` "
+        "| Relative to size |\n"
+    )
+    f.write("| **View Rate** | `views / subscribers x 100` | >100% = viral potential |\n")
+    f.write("| **Like Rate** | `likes / views x 100` | Viewer satisfaction |\n")
+    f.write("| **Comment Rate** | `comments / views x 100` | Discussion level |\n")
+    f.write("| **Views per Minute** | `views / (duration / 60)` | Content efficiency |\n\n")
+
+
+def _write_channels_list(f: Any, channels_data: list[dict[str, Any]]) -> None:
+    """Write list of analyzed channels."""
+    f.write("## Channels Analyzed\n\n")
+    for i, cd in enumerate(channels_data, 1):
+        info = cd["channel"]
+        subs = format_number(info.get("subscriber_count"))
+        count = len(cd["videos"])
+        f.write(f"{i}. **{info['title']}** - {subs} subscribers ({count} videos analyzed)\n")