uploadwhen 1.0.0__tar.gz

uploadwhen-1.0.0/LICENSE

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

uploadwhen-1.0.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: uploadwhen
+Version: 1.0.0
+Summary: Find out exactly when a YouTube video was uploaded — date & time in IST.
+Author: SoubhagyaSwain
+License: MIT
+Project-URL: Homepage, https://github.com/soubhagya2003jan/Uploadwhen
+Project-URL: Repository, https://github.com/soubhagya2003jan/Uploadwhen
+Keywords: youtube,upload-date,cli,yt-dlp,upload-time
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yt-dlp>=2024.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tzdata; sys_platform == "win32"
+Dynamic: license-file
+
+# uploadwhen
+
+> Find out **exactly** when a YouTube video was uploaded — date & time across multiple time zones.
+
+A Python CLI tool that extracts upload timestamps from YouTube videos, converts them to **IST, US/ET, AU/AEST, JP/JST, and UTC** (24-hour format). Also computes **upload consistency analytics** for any channel.
+
+Built with [yt-dlp](https://github.com/yt-dlp/yt-dlp) and [rich](https://github.com/Textualize/rich).
+
+---
+
+## Installation
+
+```bash
+pip install uploadwhen
+```
+
+## Quick Start
+
+```bash
+uploadwhen "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+```
+
+## Usage
+
+```
+uploadwhen [URL] [OPTIONS]
+```
+
+### Options
+
+| Flag | Short | Description |
+|---|---|---|
+| `--version` | `-V` | Show version |
+| `--help` | `-h` | Show help |
+| `--json` | | Export results to `uploadwhen_results.json` |
+| `--csv` | | Export results to `uploadwhen_results.csv` |
+| `--analyze` | | Fetch recent uploads and show consistency stats |
+| `--count N` | `-n N` | Number of uploads to analyze (default: 10) |
+| `--verbose` | `-v` | Show detailed yt-dlp output |
+
+### Examples
+
+```bash
+# Single video — shows upload date & time
+uploadwhen "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+
+# Analyze a channel's upload consistency (last 10 videos)
+uploadwhen "https://www.youtube.com/@theRadBrad" --analyze
+
+# Analyze last 25 uploads from a channel
+uploadwhen "https://www.youtube.com/@tseries" --analyze --count 25
+
+# Auto-detect channel from a video URL
+uploadwhen "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --analyze
+
+# Export to JSON and CSV
+uploadwhen "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --json --csv
+```
+
+## Time Zones
+
+| Zone | Region |
+|---|---|
+| **IST** | India / Asia/Kolkata (UTC+05:30) |
+| **ET** | US / New York (DST-aware) |
+| **AEST** | Australia / Sydney (DST-aware) |
+| **JST** | Japan / Tokyo (UTC+09:00) |
+| **UTC** | Reference time |
+
+## Upload Consistency Analytics
+
+The `--analyze` flag fetches recent uploads and computes:
+
+| Metric | Description |
+|---|---|
+| Avg gap | Average time between uploads |
+| Median gap | Middle value of all gaps |
+| Shortest / Longest gap | Extremes |
+| Std deviation | How much upload timing varies |
+| Consistency score (0–10) | Higher = more regular uploads |
+
+Gaps under 1 day are shown in hours for clarity.
+
+Use `--count N` to analyze more or fewer videos:
+
+```bash
+uploadwhen "https://www.youtube.com/@channel" --analyze --count 50
+```
+
+## Requirements
+
+- Python ≥ 3.9
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
+- [rich](https://github.com/Textualize/rich)
+
+## License
+
+MIT

uploadwhen-1.0.0/README.md

@@ -0,0 +1,98 @@
+# uploadwhen
+
+> Find out **exactly** when a YouTube video was uploaded — date & time across multiple time zones.
+
+A Python CLI tool that extracts upload timestamps from YouTube videos, converts them to **IST, US/ET, AU/AEST, JP/JST, and UTC** (24-hour format). Also computes **upload consistency analytics** for any channel.
+
+Built with [yt-dlp](https://github.com/yt-dlp/yt-dlp) and [rich](https://github.com/Textualize/rich).
+
+---
+
+## Installation
+
+```bash
+pip install uploadwhen
+```
+
+## Quick Start
+
+```bash
+uploadwhen "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+```
+
+## Usage
+
+```
+uploadwhen [URL] [OPTIONS]
+```
+
+### Options
+
+| Flag | Short | Description |
+|---|---|---|
+| `--version` | `-V` | Show version |
+| `--help` | `-h` | Show help |
+| `--json` | | Export results to `uploadwhen_results.json` |
+| `--csv` | | Export results to `uploadwhen_results.csv` |
+| `--analyze` | | Fetch recent uploads and show consistency stats |
+| `--count N` | `-n N` | Number of uploads to analyze (default: 10) |
+| `--verbose` | `-v` | Show detailed yt-dlp output |
+
+### Examples
+
+```bash
+# Single video — shows upload date & time
+uploadwhen "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+
+# Analyze a channel's upload consistency (last 10 videos)
+uploadwhen "https://www.youtube.com/@theRadBrad" --analyze
+
+# Analyze last 25 uploads from a channel
+uploadwhen "https://www.youtube.com/@tseries" --analyze --count 25
+
+# Auto-detect channel from a video URL
+uploadwhen "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --analyze
+
+# Export to JSON and CSV
+uploadwhen "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --json --csv
+```
+
+## Time Zones
+
+| Zone | Region |
+|---|---|
+| **IST** | India / Asia/Kolkata (UTC+05:30) |
+| **ET** | US / New York (DST-aware) |
+| **AEST** | Australia / Sydney (DST-aware) |
+| **JST** | Japan / Tokyo (UTC+09:00) |
+| **UTC** | Reference time |
+
+## Upload Consistency Analytics
+
+The `--analyze` flag fetches recent uploads and computes:
+
+| Metric | Description |
+|---|---|
+| Avg gap | Average time between uploads |
+| Median gap | Middle value of all gaps |
+| Shortest / Longest gap | Extremes |
+| Std deviation | How much upload timing varies |
+| Consistency score (0–10) | Higher = more regular uploads |
+
+Gaps under 1 day are shown in hours for clarity.
+
+Use `--count N` to analyze more or fewer videos:
+
+```bash
+uploadwhen "https://www.youtube.com/@channel" --analyze --count 50
+```
+
+## Requirements
+
+- Python ≥ 3.9
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
+- [rich](https://github.com/Textualize/rich)
+
+## License
+
+MIT

uploadwhen-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires      = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name        = "uploadwhen"
+version     = "1.0.0"
+description = "Find out exactly when a YouTube video was uploaded — date & time in IST."
+readme      = "README.md"
+license     = {text = "MIT"}
+requires-python = ">=3.9"
+authors     = [{name = "SoubhagyaSwain"}]
+keywords    = ["youtube", "upload-date", "cli", "yt-dlp", "upload-time"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "yt-dlp>=2024.0.0",
+    "rich>=13.0.0",
+    "tzdata; sys_platform == 'win32'",
+]
+
+[project.urls]
+Homepage   = "https://github.com/soubhagya2003jan/Uploadwhen"
+Repository = "https://github.com/soubhagya2003jan/Uploadwhen"
+
+[project.scripts]
+uploadwhen = "uploadwhen.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["uploadwhen*"]

uploadwhen-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uploadwhen-1.0.0/uploadwhen/__init__.py

@@ -0,0 +1,6 @@
+"""
+uploadwhen — Find out when a YouTube video was uploaded.
+"""
+
+__version__ = "1.0.0"
+__author__  = "SoubhagyaSwain"

uploadwhen-1.0.0/uploadwhen/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running with `python -m uploadwhen`."""
+
+from uploadwhen.cli import main
+
+if __name__ == "__main__":
+    main()

uploadwhen-1.0.0/uploadwhen/analyzer.py

@@ -0,0 +1,120 @@
+"""Channel upload-consistency analytics."""
+
+from __future__ import annotations
+import math
+from datetime import datetime
+
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+
+console = Console()
+
+
+def _sorted_dates(records: list[dict]) -> list[datetime]:
+    """Extract and sort UTC datetimes from records."""
+    dates = [r["datetime_utc"] for r in records if r.get("datetime_utc")]
+    dates.sort()
+    return dates
+
+
+def _gaps_in_days(dates: list[datetime]) -> list[float]:
+    """Compute inter-upload gaps in days."""
+    return [(dates[i + 1] - dates[i]).total_seconds() / 86400
+            for i in range(len(dates) - 1)]
+
+
+def _median(values: list[float]) -> float:
+    n = len(values)
+    s = sorted(values)
+    if n % 2 == 1:
+        return s[n // 2]
+    return (s[n // 2 - 1] + s[n // 2]) / 2
+
+
+def _std_dev(values: list[float], mean: float) -> float:
+    if len(values) < 2:
+        return 0.0
+    variance = sum((v - mean) ** 2 for v in values) / (len(values) - 1)
+    return math.sqrt(variance)
+
+
+def _consistency_score(std: float, mean: float) -> float:
+    """0–10 score using 10 / (1 + CV). Smoother curve that never hits zero."""
+    if mean == 0:
+        return 0.0
+    cv = std / mean
+    return round(10 / (1 + cv), 1)
+
+
+def _format_gap(days: float) -> str:
+    """Show hours when gap < 1 day, otherwise days."""
+    if days < 1:
+        hours = days * 24
+        return f"{round(hours, 1)} hours"
+    return f"{round(days, 2)} days"
+
+
+def analyze(records: list[dict]) -> dict | None:
+    """Compute upload-gap statistics. Returns None if < 2 dated videos."""
+    dates = _sorted_dates(records)
+    if len(dates) < 2:
+        return None
+
+    gaps     = _gaps_in_days(dates)
+    avg      = sum(gaps) / len(gaps)
+    med      = _median(gaps)
+    shortest = min(gaps)
+    longest  = max(gaps)
+    std      = _std_dev(gaps, avg)
+    score    = _consistency_score(std, avg)
+
+    return {
+        "channel":           records[0].get("channel", "Unknown"),
+        "total_videos":      len(dates),
+        "avg_gap":           _format_gap(avg),
+        "median_gap":        _format_gap(med),
+        "shortest_gap":      _format_gap(shortest),
+        "longest_gap":       _format_gap(longest),
+        "std_dev":           _format_gap(std),
+        "consistency_score": score,
+    }
+
+
+def _score_color(score: float) -> str:
+    """Pick a Rich color based on score (0–10)."""
+    if score >= 7.5:
+        return "green"
+    if score >= 4.0:
+        return "yellow"
+    return "red"
+
+
+def print_analysis(stats: dict | None) -> None:
+    """Render analysis stats as a Rich panel."""
+    if stats is None:
+        console.print("\n  [yellow]![/yellow] Need at least 2 dated videos for analytics.\n")
+        return
+
+    color = _score_color(stats["consistency_score"])
+
+    table = Table(show_header=False, box=None, padding=(0, 1), expand=False)
+    table.add_column("Metric", style="bold", width=26)
+    table.add_column("Value", justify="right")
+
+    table.add_row("Videos analysed",   str(stats["total_videos"]))
+    table.add_row("Avg gap",           stats["avg_gap"])
+    table.add_row("Median gap",        stats["median_gap"])
+    table.add_row("Shortest gap",      stats["shortest_gap"])
+    table.add_row("Longest gap",       stats["longest_gap"])
+    table.add_row("Std deviation",     stats["std_dev"])
+    table.add_row("Consistency score",
+                  f"[{color} bold]{stats['consistency_score']} / 10[/{color} bold]")
+
+    console.print()
+    console.print(Panel(
+        table,
+        title=f"[bold]Upload Consistency — {stats['channel']}[/bold]",
+        border_style=color,
+        expand=False,
+    ))

uploadwhen-1.0.0/uploadwhen/cli.py

@@ -0,0 +1,203 @@
+"""CLI interface for uploadwhen."""
+
+import sys
+import json
+import csv
+import argparse
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.text import Text
+from rich import box
+
+from uploadwhen import __version__
+from uploadwhen.fetcher import fetch_video, fetch_channel_videos, _is_channel_url
+from uploadwhen.analyzer import analyze, print_analysis
+
+console = Console()
+
+# Banner
+BANNER = """[bold cyan]
+  ██╗   ██╗██████╗ ██╗      ██████╗  █████╗ ██████╗ ██╗    ██╗██╗  ██╗███████╗███╗   ██╗
+  ██║   ██║██╔══██╗██║     ██╔═══██╗██╔══██╗██╔══██╗██║    ██║██║  ██║██╔════╝████╗  ██║
+  ██║   ██║██████╔╝██║     ██║   ██║███████║██║  ██║██║ █╗ ██║███████║█████╗  ██╔██╗ ██║
+  ██║   ██║██╔═══╝ ██║     ██║   ██║██╔══██║██║  ██║██║███╗██║██╔══██║██╔══╝  ██║╚██╗██║
+  ╚██████╔╝██║     ███████╗╚██████╔╝██║  ██║██████╔╝╚███╔███╔╝██║  ██║███████╗██║ ╚████║
+   ╚═════╝ ╚═╝     ╚══════╝ ╚═════╝ ╚═╝  ╚═╝╚═════╝  ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═══╝
+[/bold cyan][dim]  Find out exactly when any YouTube video was uploaded.
+  v""" + __version__ + "[/dim]"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="uploadwhen",
+        description=(
+            "uploadwhen — Find out exactly when a YouTube video was uploaded.\n"
+            "Supports video URLs and channel-level upload consistency analysis.\n"
+            "Times shown in IST, US/ET, AU/AEST, JP/JST, and UTC."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Example:\n"
+            '  uploadwhen "https://www.youtube.com/watch?v=dQw4w9WgXcQ"\n'
+            "\n"
+            "Tip: Wrap URLs in quotes so your shell doesn't break on & characters."
+        ),
+    )
+
+    parser.add_argument("url", nargs="?", metavar="URL",
+                        help="A YouTube video or channel URL.")
+    parser.add_argument("-V", "--version", action="version",
+                        version=f"%(prog)s {__version__}")
+    parser.add_argument("--json", action="store_true", dest="export_json",
+                        help="Export results to uploadwhen_results.json")
+    parser.add_argument("--csv", action="store_true", dest="export_csv",
+                        help="Export results to uploadwhen_results.csv")
+    parser.add_argument("--analyze", action="store_true",
+                        help="Fetch recent uploads from the channel and show consistency stats.")
+    parser.add_argument("-n", "--count", type=int, default=10, metavar="N",
+                        help="Number of uploads to analyze (default: 10).")
+    parser.add_argument("-v", "--verbose", action="store_true",
+                        help="Show detailed yt-dlp output.")
+    return parser
+
+
+# Display —————————————————————————————————————————————————————————————————
+
+def _print_video(rec: dict) -> None:
+    table = Table(show_header=False, box=None, padding=(0, 1),
+                  expand=False, show_edge=False)
+    table.add_column("Key", style="bold", width=14)
+    table.add_column("Value")
+
+    table.add_row("Channel",       rec["channel"])
+    table.add_row("Date",          rec["date"])
+    table.add_row("Time (IST)",    f"[green]{rec['time_ist']}[/green]  [dim]India[/dim]")
+    table.add_row("Time (ET)",     f"{rec['time_us']}   [dim]US / New York[/dim]")
+    table.add_row("Time (AEST)",   f"{rec['time_au']}  [dim]Australia / Sydney[/dim]")
+    table.add_row("Time (JST)",    f"{rec['time_jp']}   [dim]Japan / Tokyo[/dim]")
+    table.add_row("Time (UTC)",    f"[dim]{rec['time_utc']}[/dim]")
+    table.add_row("Duration",      rec["duration"])
+    table.add_row("URL",           f"[dim]{rec['video_url']}[/dim]")
+
+    console.print(Panel(table, title=f"[bold]{rec['title']}[/bold]",
+                        border_style="cyan", expand=False))
+
+
+def _print_channel_videos(records: list[dict]) -> None:
+    """Render a compact table of channel uploads."""
+    table = Table(title="Recent Uploads", box=box.ROUNDED,
+                  border_style="cyan", header_style="bold")
+    table.add_column("#", justify="right", style="dim", width=3)
+    table.add_column("Date", width=20)
+    table.add_column("Time (IST)", style="green", width=14)
+    table.add_column("Title", max_width=55, no_wrap=True)
+
+    for i, rec in enumerate(records, start=1):
+        table.add_row(str(i), rec["date"], rec["time_ist"],
+                      Text(rec["title"], overflow="ellipsis"))
+
+    console.print(table)
+
+
+# Export ——————————————————————————————————————————————————————————————————
+
+EXPORT_FIELDS = ["title", "channel", "date", "time_ist", "time_us",
+                 "time_au", "time_jp", "time_utc", "duration",
+                 "video_url", "video_id"]
+
+
+def _export_json(records: list[dict], path: Path) -> None:
+    clean = [{k: r[k] for k in EXPORT_FIELDS} for r in records]
+    path.write_text(json.dumps(clean, indent=2, ensure_ascii=False), encoding="utf-8")
+    console.print(f"\n  [green]✓[/green] JSON saved → [bold]{path}[/bold]")
+
+
+def _export_csv(records: list[dict], path: Path) -> None:
+    with open(path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=EXPORT_FIELDS)
+        writer.writeheader()
+        for r in records:
+            writer.writerow({k: r[k] for k in EXPORT_FIELDS})
+    console.print(f"\n  [green]✓[/green] CSV  saved → [bold]{path}[/bold]")
+
+
+# Entry point —————————————————————————————————————————————————————————————
+
+def main(argv: list[str] | None = None) -> None:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.url:
+        console.print(BANNER)
+        parser.print_help()
+        sys.exit(0)
+
+    console.print(BANNER)
+    url = args.url.strip()
+    is_channel = _is_channel_url(url)
+
+    # Channel URL path
+    if is_channel:
+        if not args.analyze:
+            console.print(
+                f"\n  [yellow]![/yellow] That looks like a channel URL. "
+                f"Add [bold]--analyze[/bold] to see upload consistency stats.\n"
+            )
+            sys.exit(0)
+
+        console.print(f"\n  [cyan]⟳[/cyan] Fetching last [bold]{args.count}[/bold] uploads from channel…\n")
+        records = fetch_channel_videos(url, count=args.count, verbose=args.verbose)
+
+        if not records:
+            console.print("  [red]✗[/red] Could not retrieve videos from this channel.")
+            sys.exit(1)
+
+        _print_channel_videos(records)
+        print_analysis(analyze(records))
+
+        if args.export_json:
+            _export_json(records, Path.cwd() / "uploadwhen_results.json")
+        if args.export_csv:
+            _export_csv(records, Path.cwd() / "uploadwhen_results.csv")
+
+        console.print()
+        return
+
+    # Single video URL path
+    console.print(f"\n  [cyan]⟳[/cyan] Fetching video info…\n")
+    video = fetch_video(url, verbose=args.verbose)
+
+    if not video:
+        console.print("  [red]✗[/red] Could not retrieve video info. Check the URL.")
+        sys.exit(1)
+
+    _print_video(video)
+
+    if args.export_json:
+        _export_json([video], Path.cwd() / "uploadwhen_results.json")
+    if args.export_csv:
+        _export_csv([video], Path.cwd() / "uploadwhen_results.csv")
+
+    # Auto-detect channel and run analysis
+    if args.analyze:
+        channel_url = video.get("channel_url")
+        if not channel_url:
+            console.print("\n  [yellow]![/yellow] Could not determine channel URL from this video.\n")
+        else:
+            channel = video.get("channel", "this channel")
+            console.print(
+                f"\n  [cyan]⟳[/cyan] Fetching last [bold]{args.count}[/bold] uploads "
+                f"from [bold]{channel}[/bold]…\n"
+            )
+            records = fetch_channel_videos(channel_url, count=args.count, verbose=args.verbose)
+
+            if not records:
+                console.print("  [red]✗[/red] Could not retrieve channel videos.")
+            else:
+                _print_channel_videos(records)
+                print_analysis(analyze(records))
+
+    console.print()

uploadwhen-1.0.0/uploadwhen/fetcher.py

@@ -0,0 +1,115 @@
+"""Fetch metadata from YouTube videos and channels via yt-dlp."""
+
+import yt_dlp
+from urllib.parse import urlparse
+from datetime import datetime, timezone, timedelta
+
+try:
+    from zoneinfo import ZoneInfo
+    IST    = ZoneInfo("Asia/Kolkata")
+    US_ET  = ZoneInfo("America/New_York")
+    AU_SYD = ZoneInfo("Australia/Sydney")
+    JP     = ZoneInfo("Asia/Tokyo")
+except ImportError:
+    IST    = timezone(timedelta(hours=5, minutes=30), name="IST")
+    US_ET  = timezone(timedelta(hours=-5),            name="ET")
+    AU_SYD = timezone(timedelta(hours=11),             name="AEDT")
+    JP     = timezone(timedelta(hours=9),              name="JST")
+
+
+def _extract_video_info(info: dict) -> dict:
+    """Parse a yt-dlp info dict into a clean record."""
+    title       = info.get("title", "Unknown")
+    channel     = info.get("channel") or info.get("uploader") or "Unknown"
+    channel_url = info.get("channel_url") or info.get("uploader_url") or ""
+    video_id    = info.get("id", "")
+    video_url   = info.get("webpage_url") or info.get("url") or ""
+    duration    = info.get("duration_string") or info.get("duration") or "Unknown"
+    timestamp   = info.get("timestamp")
+    upload_date = info.get("upload_date")
+
+    date_str = time_ist = time_utc = time_us = time_au = time_jp = dt_utc = None
+    na = "N/A"
+
+    if timestamp:
+        dt_utc   = datetime.fromtimestamp(timestamp, tz=timezone.utc)
+        dt_ist   = dt_utc.astimezone(IST)
+        dt_us    = dt_utc.astimezone(US_ET)
+        dt_au    = dt_utc.astimezone(AU_SYD)
+        dt_jp    = dt_utc.astimezone(JP)
+        date_str = dt_ist.strftime("%d %B %Y")
+        time_ist = dt_ist.strftime("%H:%M:%S IST")
+        time_utc = dt_utc.strftime("%H:%M:%S UTC")
+        time_us  = dt_us.strftime("%H:%M:%S ET")
+        time_au  = dt_au.strftime("%H:%M:%S AEST")
+        time_jp  = dt_jp.strftime("%H:%M:%S JST")
+    elif upload_date:
+        dt_utc   = datetime.strptime(upload_date, "%Y%m%d").replace(tzinfo=timezone.utc)
+        date_str = dt_utc.strftime("%d %B %Y")
+        time_ist = time_utc = time_us = time_au = time_jp = na
+    else:
+        date_str = time_ist = time_utc = time_us = time_au = time_jp = na
+
+    return {
+        "title": title, "channel": channel, "channel_url": channel_url,
+        "video_id": video_id, "video_url": video_url,
+        "date": date_str, "time_ist": time_ist, "time_us": time_us,
+        "time_au": time_au, "time_jp": time_jp, "time_utc": time_utc,
+        "duration": str(duration), "datetime_utc": dt_utc,
+    }
+
+
+def fetch_video(url: str, verbose: bool = False) -> dict | None:
+    """Fetch info for a single video URL."""
+    ydl_opts = {
+        "quiet": not verbose, "no_warnings": not verbose,
+        "skip_download": True,
+    }
+    try:
+        with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+            info = ydl.extract_info(url, download=False)
+            return _extract_video_info(info) if info else None
+    except Exception:
+        return None
+
+
+def _normalise_channel_url(url: str) -> str:
+    """Ensure channel URL points to /videos tab for yt-dlp."""
+    url = url.rstrip("/")
+    if url.endswith("/videos"):
+        return url
+    for suffix in ("/shorts", "/streams", "/playlists", "/community", "/about"):
+        if url.endswith(suffix):
+            url = url[: -len(suffix)]
+            break
+    return url + "/videos"
+
+
+def _is_channel_url(url: str) -> bool:
+    """Check if URL is a YouTube channel (not a video)."""
+    path = urlparse(url).path.lower()
+    if any(path.startswith(p) for p in ("/@", "/channel/", "/c/", "/user/")):
+        return True
+    return False
+
+
+def fetch_channel_videos(channel_url: str, count: int = 10,
+                         verbose: bool = False) -> list[dict]:
+    """Fetch the last N uploads from a YouTube channel."""
+    videos_url = _normalise_channel_url(channel_url)
+    ydl_opts = {
+        "quiet": not verbose, "no_warnings": not verbose,
+        "skip_download": True, "extract_flat": False,
+        "ignoreerrors": True, "playlistend": count,
+    }
+    results: list[dict] = []
+    try:
+        with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+            info = ydl.extract_info(videos_url, download=False)
+            if info:
+                for entry in (info.get("entries") or []):
+                    if entry is not None:
+                        results.append(_extract_video_info(entry))
+    except Exception:
+        pass
+    return results

uploadwhen-1.0.0/uploadwhen.egg-info/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: uploadwhen
+Version: 1.0.0
+Summary: Find out exactly when a YouTube video was uploaded — date & time in IST.
+Author: SoubhagyaSwain
+License: MIT
+Project-URL: Homepage, https://github.com/soubhagya2003jan/Uploadwhen
+Project-URL: Repository, https://github.com/soubhagya2003jan/Uploadwhen
+Keywords: youtube,upload-date,cli,yt-dlp,upload-time
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yt-dlp>=2024.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tzdata; sys_platform == "win32"
+Dynamic: license-file
+
+# uploadwhen
+
+> Find out **exactly** when a YouTube video was uploaded — date & time across multiple time zones.
+
+A Python CLI tool that extracts upload timestamps from YouTube videos, converts them to **IST, US/ET, AU/AEST, JP/JST, and UTC** (24-hour format). Also computes **upload consistency analytics** for any channel.
+
+Built with [yt-dlp](https://github.com/yt-dlp/yt-dlp) and [rich](https://github.com/Textualize/rich).
+
+---
+
+## Installation
+
+```bash
+pip install uploadwhen
+```
+
+## Quick Start
+
+```bash
+uploadwhen "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+```
+
+## Usage
+
+```
+uploadwhen [URL] [OPTIONS]
+```
+
+### Options
+
+| Flag | Short | Description |
+|---|---|---|
+| `--version` | `-V` | Show version |
+| `--help` | `-h` | Show help |
+| `--json` | | Export results to `uploadwhen_results.json` |
+| `--csv` | | Export results to `uploadwhen_results.csv` |
+| `--analyze` | | Fetch recent uploads and show consistency stats |
+| `--count N` | `-n N` | Number of uploads to analyze (default: 10) |
+| `--verbose` | `-v` | Show detailed yt-dlp output |
+
+### Examples
+
+```bash
+# Single video — shows upload date & time
+uploadwhen "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+
+# Analyze a channel's upload consistency (last 10 videos)
+uploadwhen "https://www.youtube.com/@theRadBrad" --analyze
+
+# Analyze last 25 uploads from a channel
+uploadwhen "https://www.youtube.com/@tseries" --analyze --count 25
+
+# Auto-detect channel from a video URL
+uploadwhen "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --analyze
+
+# Export to JSON and CSV
+uploadwhen "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --json --csv
+```
+
+## Time Zones
+
+| Zone | Region |
+|---|---|
+| **IST** | India / Asia/Kolkata (UTC+05:30) |
+| **ET** | US / New York (DST-aware) |
+| **AEST** | Australia / Sydney (DST-aware) |
+| **JST** | Japan / Tokyo (UTC+09:00) |
+| **UTC** | Reference time |
+
+## Upload Consistency Analytics
+
+The `--analyze` flag fetches recent uploads and computes:
+
+| Metric | Description |
+|---|---|
+| Avg gap | Average time between uploads |
+| Median gap | Middle value of all gaps |
+| Shortest / Longest gap | Extremes |
+| Std deviation | How much upload timing varies |
+| Consistency score (0–10) | Higher = more regular uploads |
+
+Gaps under 1 day are shown in hours for clarity.
+
+Use `--count N` to analyze more or fewer videos:
+
+```bash
+uploadwhen "https://www.youtube.com/@channel" --analyze --count 50
+```
+
+## Requirements
+
+- Python ≥ 3.9
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
+- [rich](https://github.com/Textualize/rich)
+
+## License
+
+MIT

uploadwhen-1.0.0/uploadwhen.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+uploadwhen/__init__.py
+uploadwhen/__main__.py
+uploadwhen/analyzer.py
+uploadwhen/cli.py
+uploadwhen/fetcher.py
+uploadwhen.egg-info/PKG-INFO
+uploadwhen.egg-info/SOURCES.txt
+uploadwhen.egg-info/dependency_links.txt
+uploadwhen.egg-info/entry_points.txt
+uploadwhen.egg-info/requires.txt
+uploadwhen.egg-info/top_level.txt

uploadwhen-1.0.0/uploadwhen.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

uploadwhen-1.0.0/uploadwhen.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+uploadwhen = uploadwhen.cli:main

uploadwhen-1.0.0/uploadwhen.egg-info/requires.txt

@@ -0,0 +1,5 @@
+yt-dlp>=2024.0.0
+rich>=13.0.0
+
+[:sys_platform == "win32"]
+tzdata

uploadwhen-1.0.0/uploadwhen.egg-info/top_level.txt

@@ -0,0 +1 @@
+uploadwhen