idm-cli 0.1.0__tar.gz

idm_cli-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: idm-cli
+Version: 0.1.0
+Requires-Dist: typer[all]>=0.9.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: yt-dlp>=2023.0.0
+Dynamic: requires-dist

idm_cli-0.1.0/README.md

@@ -0,0 +1,106 @@
+# IDM-CLI (CLI Internet Download Manager Clone)
+
+**IDM-CLI** is a blazing-fast, multi-threaded CLI download manager built in Python. Inspired by Internet Download Manager (IDM), it splits files into multiple segments and downloads them concurrently to maximize bandwidth, complete with a modern interactive prompt shell, auto-update checks, atomic state tracking, and ultra-safe chunk merging.
+
+---
+
+## ✨ Key Features
+
+1. **🚀 Segmented / Concurrent Downloads**: Splitting the file into up to 32 parallel streams (default 8) to download at the absolute maximum speed your bandwidth allows.
+2. **💬 Interactive Shell Mode (REPL)**: Run the simple command `idm` anywhere, and it opens a persistent, visual download shell prompt where you can copy/paste links sequentially.
+3. **⏯️ Robust Pause & Resume**: Supports pausing a download (using `Ctrl+C`) and resuming it exactly where it was left off. It even automatically refreshes expired YouTube temporary signatures in the background on resume!
+4. **🔔 Auto-Update Notification**: Clean, latency-free updates checks based on a 24-hour cache. Informs you when a new global release is available on PyPI.
+5. **🔒 Atomic State Management**: To prevent corruption in case of unexpected crashes or power outages, states are written using an atomic two-step file operation (`.tmp` write followed by safe replacement).
+6. **💾 RAM-Efficient Chunk Merging**: Uses $O(1)$ constant-memory buffered streaming (1MB blocks) to merge segments. Safely handles gigantic files (e.g., 10GB+) without lagging or crashing your system's RAM.
+7. **🎨 Beautiful Terminal UI**: Multi-progress bar dashboards built with `rich`, showing connection progress, total speed, ETAs, percentages, and clean summary tables.
+
+---
+
+## 📦 Installation & Setup
+
+Ensure you have **Python 3.8+** installed.
+
+### 1. Clone the repository & Navigate
+```bash
+cd IDM-Clone-CLI
+```
+
+### 2. Create and Activate Virtual Environment
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+```
+
+### 3. Install Globally (registers the `idm` command)
+To install the tool in editable development mode:
+```powershell
+pip install -e .
+```
+
+---
+
+## ⚡ CLI Usage & Commands
+
+Once installed globally, you can type **`idm`** from any terminal folder!
+
+### 1. Open the Interactive Shell (Recommended)
+Simply run:
+```bash
+idm
+```
+This opens the persistent prompt:
+```text
++------------------------------ idm shell ------------------------------+
+|                                                                       |
+|  IDM-CLI Interactive Shell Mode                                       |
+|                                                                       |
+|  • Paste any HTTP/HTTPS URL or YouTube URL to download instantly.     |
+|  • Type resume <metadata_file> to resume a paused download.           |
+|  • Type exit or press Ctrl+C to quit the application.                 |
+|                                                                       |
++-----------------------------------------------------------------------+
+idm> 
+```
+*Paste your links directly and hit Enter. Type `exit` or press `Ctrl+C` to quit.*
+
+---
+
+### 2. Standard One-Off Commands
+If you prefer single-line shell commands:
+
+#### Download a File:
+```bash
+idm download https://example.com/largefile.zip
+```
+
+#### Custom Connections & Output Path:
+To use 16 threads and save it to a custom directory:
+```bash
+idm download https://example.com/largefile.zip -c 16 -o C:\path\to\downloads
+```
+
+#### Resume a Download:
+```bash
+idm resume largefile.zip.dl.json
+```
+
+---
+
+## 🖥️ Standalone Bundling (Compile to `idm.exe`)
+
+If you want to package IDM-CLI as a single standalone executable that runs on any Windows machine (even if they don't have Python installed):
+
+1. **Install PyInstaller** inside your activated environment:
+   ```bash
+   pip install pyinstaller
+   ```
+
+2. **Bundle the application**:
+   ```bash
+   pyinstaller --onefile --name idm main.py
+   ```
+
+3. **Find the `.exe`**:
+   The standalone executable will be generated inside the `dist/` folder:
+   - File location: `dist/idm.exe`
+   - You can copy this `idm.exe` and distribute it to any other Windows PC. Just add it to your Windows PATH to run it globally!

idm_cli-0.1.0/idm_cli.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: idm-cli
+Version: 0.1.0
+Requires-Dist: typer[all]>=0.9.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: yt-dlp>=2023.0.0
+Dynamic: requires-dist

idm_cli-0.1.0/idm_cli.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+setup.py
+idm_cli.egg-info/PKG-INFO
+idm_cli.egg-info/SOURCES.txt
+idm_cli.egg-info/dependency_links.txt
+idm_cli.egg-info/entry_points.txt
+idm_cli.egg-info/requires.txt
+idm_cli.egg-info/top_level.txt
+speedy_dl/__init__.py
+speedy_dl/cli.py
+speedy_dl/downloader.py
+speedy_dl/extractor.py
+speedy_dl/state.py
+speedy_dl/ui.py
+speedy_dl/updater.py

idm_cli-0.1.0/idm_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

idm_cli-0.1.0/idm_cli.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+idm = speedy_dl.cli:app
+idm-cli = speedy_dl.cli:app

idm_cli-0.1.0/idm_cli.egg-info/requires.txt

@@ -0,0 +1,4 @@
+typer[all]>=0.9.0
+httpx>=0.24.0
+rich>=13.0.0
+yt-dlp>=2023.0.0

idm_cli-0.1.0/idm_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+speedy_dl

idm_cli-0.1.0/setup.cfg

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

idm_cli-0.1.0/setup.py

@@ -0,0 +1,19 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="idm-cli",
+    version="0.1.0",
+    packages=find_packages(),
+    install_requires=[
+        "typer[all]>=0.9.0",
+        "httpx>=0.24.0",
+        "rich>=13.0.0",
+        "yt-dlp>=2023.0.0",
+    ],
+    entry_points={
+        "console_scripts": [
+            "idm=speedy_dl.cli:app",      # Typing 'idm' starts the CLI globally!
+            "idm-cli=speedy_dl.cli:app",  # Typing 'idm-cli' also works!
+        ],
+    },
+)

idm_cli-0.1.0/speedy_dl/__init__.py

@@ -0,0 +1,2 @@
+# speedy_dl Package
+__version__ = "0.1.0"

idm_cli-0.1.0/speedy_dl/cli.py

@@ -0,0 +1,199 @@
+import os
+import sys
+import asyncio
+import logging
+import typer
+from typing import Optional
+from rich.console import Console
+from rich.panel import Panel
+
+from speedy_dl.downloader import SpeedyDownloader
+from speedy_dl.state import load_state
+from speedy_dl.updater import check_for_updates
+
+app = typer.Typer(
+    name="idm-cli",
+    help="IDM-CLI: A premium, blazing-fast multi-threaded CLI download manager (Internet Download Manager Clone) in Python.",
+    add_completion=True
+)
+
+console = Console()
+
+# Configure basic logging to avoid spam but print crucial internal details if needed
+logging.basicConfig(
+    level=logging.ERROR,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+
+def run_async_downloader(downloader: SpeedyDownloader):
+    """Runs the downloader asynchronously and handles Ctrl+C gracefully."""
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    
+    download_task = loop.create_task(downloader.start_download())
+    
+    try:
+        loop.run_until_complete(download_task)
+    except KeyboardInterrupt:
+        # Cancel the task on Ctrl+C to trigger the downloader's clean pause block
+        download_task.cancel()
+        try:
+            loop.run_until_complete(download_task)
+        except asyncio.CancelledError:
+            pass
+    except Exception as e:
+        console.print(f"[bold red]An unexpected error occurred: {e}[/bold red]")
+        sys.exit(1)
+    finally:
+        loop.close()
+
+@app.command()
+def download(
+    url: str = typer.Argument(..., help="The HTTP/HTTPS URL of the file to download."),
+    output_path: Optional[str] = typer.Option(
+        None, "--output-path", "-o",
+        help="Custom destination directory or full filename path."
+    ),
+    connections: int = typer.Option(
+        8, "--connections", "-c", min=1, max=32,
+        help="Number of concurrent connection threads (1-32)."
+    )
+):
+    """
+    Downloads a file using multi-threaded segmented requests.
+    Automatically checks if server supports resuming and generates status checkpoints.
+    """
+    if not url.startswith(("http://", "https://")):
+        console.print("[bold red]Error: Invalid URL protocol. Only http:// and https:// are supported.[/bold red]")
+        raise typer.Exit(code=1)
+
+    downloader = SpeedyDownloader(
+        url=url,
+        output_path=output_path,
+        connections=connections
+    )
+    
+    run_async_downloader(downloader)
+
+@app.command()
+def resume(
+    state_file: str = typer.Argument(
+        ...,
+        help="Path to the '.dl.json' status file generated by a paused download."
+    )
+):
+    """
+    Resumes a paused download using the saved metadata file.
+    """
+    if not os.path.exists(state_file):
+        console.print(f"[bold red]Error: The state file '{state_file}' does not exist.[/bold red]")
+        raise typer.Exit(code=1)
+
+    # Load state first to extract original URL
+    metadata = load_state(state_file)
+    if not metadata:
+        console.print(f"[bold red]Error: Could not parse or load state from '{state_file}'. It may be corrupted.[/bold red]")
+        raise typer.Exit(code=1)
+
+    url = metadata.get("url")
+    connections = metadata.get("connections", 8)
+    filepath = metadata.get("filepath")
+
+    if not url:
+        console.print("[bold red]Error: Invalid state file format. Missing original URL.[/bold red]")
+        raise typer.Exit(code=1)
+
+    console.print(f"[bold yellow]Found pause state for:[/bold yellow] [cyan]{os.path.basename(filepath)}[/cyan]")
+    
+    downloader = SpeedyDownloader(
+        url=url,
+        output_path=filepath,
+        connections=connections,
+        state_file=state_file
+    )
+    
+    run_async_downloader(downloader)
+
+def interactive_shell():
+    # 1. Run quick asynchronous/cached check for updates
+    try:
+        new_version = check_for_updates()
+        if new_version:
+            import speedy_dl
+            console.print(Panel(
+                f"[bold gold1]★ A new version of idm-cli is available![/bold gold1]\n"
+                f"[bold white]Local Version:[/bold white] [red]{speedy_dl.__version__}[/red] ➜ "
+                f"[bold white]Latest Version:[/bold white] [green]{new_version}[/green]\n"
+                f"Run [bold cyan]pip install --upgrade idm-cli[/bold cyan] to update globally!",
+                border_style="bold gold1",
+                title="[bold gold1]Update Available[/bold gold1]",
+                padding=(1, 2)
+            ))
+            console.print()  # Spacer
+    except Exception:
+        pass
+
+    console.print(Panel(
+        "[bold green]IDM-CLI Interactive Shell Mode[/bold green]\n\n"
+        "• Paste any HTTP/HTTPS URL or YouTube URL to download instantly.\n"
+        "• Type [bold yellow]resume <metadata_file>[/bold yellow] to resume a paused download.\n"
+        "• Type [bold red]exit[/bold bold red] or press [bold red]Ctrl+C[/bold red] to quit the application.",
+        title="[bold yellow]idm shell[/bold yellow]",
+        border_style="bold green",
+        padding=(1, 2)
+    ))
+    
+    while True:
+        try:
+            url_input = console.input("[bold cyan]idm>[/bold cyan] ").strip()
+            if not url_input:
+                continue
+                
+            if url_input.lower() in ("exit", "quit"):
+                console.print("[bold yellow]Goodbye![/bold yellow]")
+                break
+                
+            if url_input.startswith("resume "):
+                state_file = url_input[7:].strip()
+                if not os.path.exists(state_file):
+                    console.print(f"[bold red]Error: State file '{state_file}' does not exist.[/bold red]")
+                    continue
+                metadata = load_state(state_file)
+                if not metadata:
+                    console.print(f"[bold red]Error: Could not load state from '{state_file}'.[/bold red]")
+                    continue
+                url = metadata.get("url")
+                connections = metadata.get("connections", 8)
+                filepath = metadata.get("filepath")
+                downloader = SpeedyDownloader(
+                    url=url,
+                    output_path=filepath,
+                    connections=connections,
+                    state_file=state_file
+                )
+                run_async_downloader(downloader)
+                continue
+                
+            if not url_input.startswith(("http://", "https://")):
+                console.print("[bold red]Error: Please enter a valid HTTP/HTTPS URL or 'resume <state_file>'.[/bold red]")
+                continue
+                
+            downloader = SpeedyDownloader(url=url_input)
+            run_async_downloader(downloader)
+            
+        except KeyboardInterrupt:
+            console.print("\n[bold yellow]Exiting Interactive Shell. Goodbye![/bold yellow]")
+            break
+        except Exception as e:
+            console.print(f"[bold red]Error: {e}[/bold red]")
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context):
+    """
+    Main entry point. If no subcommand is specified, launches the interactive shell.
+    """
+    if ctx.invoked_subcommand is None:
+        interactive_shell()
+
+if __name__ == "__main__":
+    app()

idm_cli-0.1.0/speedy_dl/downloader.py

@@ -0,0 +1,408 @@
+import os
+import time
+import asyncio
+import logging
+from typing import Dict, Any, List, Optional
+from urllib.parse import urlparse, unquote
+import httpx
+from rich.console import Console
+
+from speedy_dl.state import save_state_atomic, load_state
+from speedy_dl.ui import SpeedyProgress
+from speedy_dl.extractor import is_streaming_url, extract_stream_info
+
+logger = logging.getLogger("speedy_dl.downloader")
+console = Console()
+
+class SpeedyDownloader:
+    def __init__(
+        self,
+        url: str,
+        output_path: Optional[str] = None,
+        connections: int = 8,
+        state_file: Optional[str] = None
+    ):
+        self.connections = connections
+        
+        # Recover original url / stream status if resuming from a saved state file
+        loaded = None
+        if state_file and os.path.exists(state_file):
+            loaded = load_state(state_file)
+            
+        if loaded:
+            self.url = loaded.get("url", url)
+            self.original_url = loaded.get("original_url", self.url)
+            self.is_stream = loaded.get("is_stream", is_streaming_url(self.original_url))
+        else:
+            self.url = url
+            self.original_url = url
+            self.is_stream = is_streaming_url(url)
+        
+        # We will determine these later
+        self.total_size = 0
+        self.resumable = False
+        self.filename = ""
+        self.filepath = ""
+        self.state_filepath = ""
+        self.segments: List[Dict[str, Any]] = []
+        self.state: Dict[str, Any] = {}
+        
+        # Downloader active flags
+        self.is_paused = False
+        self.is_completed = False
+        self._state_save_task: Optional[asyncio.Task] = None
+        self._download_tasks: List[asyncio.Task] = []
+        self._write_lock = asyncio.Lock()  # Ensure atomic memory updates
+
+        # Check details first to establish name/size
+        self._initialize_paths(output_path, state_file)
+
+    def _initialize_paths(self, output_path: Optional[str], state_file: Optional[str]):
+        """Resolves output filename, directory, and the metadata state path."""
+        # Parse URL for default filename
+        parsed_url = urlparse(self.url)
+        url_filename = os.path.basename(unquote(parsed_url.path))
+        
+        if self.is_stream:
+            self.filename = "streaming_video.mp4"
+        elif not url_filename or "." not in url_filename:
+            self.filename = "download_file"
+        else:
+            self.filename = url_filename
+
+        # Establish working output path
+        if output_path:
+            if os.path.isdir(output_path):
+                self.filepath = os.path.join(output_path, self.filename)
+            else:
+                self.filepath = output_path
+                self.filename = os.path.basename(self.filepath)
+        else:
+            # Dynamically resolve user's system "Downloads" directory (Cross-Platform)
+            downloads_dir = os.path.join(os.path.expanduser("~"), "Downloads")
+            if os.path.exists(downloads_dir) and os.path.isdir(downloads_dir):
+                self.filepath = os.path.join(downloads_dir, self.filename)
+            else:
+                # Fallback to current working directory if Downloads folder doesn't exist
+                self.filepath = os.path.abspath(self.filename)
+
+        # Establish state file path
+        if state_file:
+            self.state_filepath = state_file
+        else:
+            self.state_filepath = f"{self.filepath}.dl.json"
+
+    async def probe_server(self) -> Dict[str, Any]:
+        """Probes the server with HEAD/GET requests to determine size and Range support."""
+        if self.is_stream:
+            console.print("[bold cyan]Extracting streaming video link...[/bold cyan]")
+            loop = asyncio.get_running_loop()
+            info = await loop.run_in_executor(None, extract_stream_info, self.original_url)
+            if not info:
+                raise ValueError("Failed to extract streaming details from URL. The video may be private or restricted.")
+            
+            self.url = info["stream_url"]
+            self.filename = info["filename"]
+            self.total_size = info["size"]
+            self.resumable = True
+            
+            # Re-evaluate filepath and state paths based on fetched streaming name
+            dir_name = os.path.dirname(self.filepath) if self.filepath else os.getcwd()
+            self.filepath = os.path.join(dir_name, self.filename)
+            self.state_filepath = f"{self.filepath}.dl.json"
+            
+            return {
+                "filename": self.filename,
+                "size": self.total_size,
+                "resumable": self.resumable
+            }
+
+        async with httpx.AsyncClient(follow_redirects=True, timeout=15.0) as client:
+            try:
+                # 1. Try HEAD request
+                response = await client.head(self.url)
+                if response.status_code >= 400:
+                    # Fallback to GET for servers that block HEAD requests
+                    response = await client.get(self.url, headers={"Range": "bytes=0-0"})
+            except Exception as e:
+                # Direct GET fallback
+                async with httpx.AsyncClient(follow_redirects=True, timeout=15.0) as client2:
+                    response = await client2.get(self.url, headers={"Range": "bytes=0-0"})
+
+            # Handle response headers
+            headers = response.headers
+            
+            # Content-Disposition header filename extraction
+            cd_header = headers.get("content-disposition", "")
+            if "filename=" in cd_header:
+                parts = cd_header.split("filename=")
+                if len(parts) > 1:
+                    fname = parts[1].strip('"\'')
+                    if fname:
+                        self.filename = fname
+                        # Re-evaluate filepath based on extracted filename
+                        self.filepath = os.path.join(os.path.dirname(self.filepath), self.filename)
+                        if not self.state_filepath.endswith(".dl.json"):
+                            self.state_filepath = f"{self.filepath}.dl.json"
+
+            # Parse size
+            content_length = headers.get("content-length")
+            # If we requested range 0-0, content-range will have the total size
+            content_range = headers.get("content-range")
+            
+            if content_range and "bytes" in content_range:
+                # format: bytes 0-0/FILE_SIZE
+                try:
+                    self.total_size = int(content_range.split("/")[-1])
+                except (ValueError, IndexError):
+                    self.total_size = int(content_length) if content_length else 0
+            else:
+                self.total_size = int(content_length) if content_length else 0
+
+            # Check Range support (Resumable)
+            accept_ranges = headers.get("accept-ranges", "").lower()
+            self.resumable = (
+                accept_ranges == "bytes" or 
+                "content-range" in headers or 
+                response.status_code == 206
+            ) and self.total_size > 0
+
+            return {
+                "filename": self.filename,
+                "size": self.total_size,
+                "resumable": self.resumable
+            }
+
+    def prepare_segments(self):
+        """Calculates ranges and sets up temporary segment tracking structures."""
+        if not self.resumable or self.connections <= 1:
+            # Single connection segment
+            self.segments = [{
+                "id": 0,
+                "start": 0,
+                "end": self.total_size - 1 if self.total_size > 0 else -1,
+                "downloaded": 0,
+                "completed": False,
+                "part_path": f"{self.filepath}.part0"
+            }]
+            return
+
+        self.segments = []
+        chunk_size = self.total_size // self.connections
+        
+        for i in range(self.connections):
+            start = i * chunk_size
+            # The last segment consumes any remaining remainder bytes
+            end = self.total_size - 1 if i == self.connections - 1 else (start + chunk_size - 1)
+            self.segments.append({
+                "id": i,
+                "start": start,
+                "end": end,
+                "downloaded": 0,
+                "completed": False,
+                "part_path": f"{self.filepath}.part{i}"
+            })
+
+    def save_state(self):
+        """Saves current state snapshot to file atomically."""
+        self.state = {
+            "url": self.url,
+            "original_url": self.original_url,
+            "is_stream": self.is_stream,
+            "filepath": self.filepath,
+            "total_size": self.total_size,
+            "resumable": self.resumable,
+            "connections": self.connections,
+            "segments": self.segments
+        }
+        save_state_atomic(self.state_filepath, self.state)
+
+    async def _periodic_save(self):
+        """Asynchronous background task that periodically updates state on disk."""
+        while not self.is_paused and not self.is_completed:
+            await asyncio.sleep(1.5)
+            async with self._write_lock:
+                self.save_state()
+
+    async def download_segment(
+        self,
+        client: httpx.AsyncClient,
+        segment: Dict[str, Any],
+        ui: SpeedyProgress
+    ):
+        """Downloads a single file byte segment concurrently."""
+        seg_id = segment["id"]
+        part_path = segment["part_path"]
+        
+        # Check current progress on disk (for safety and resuming)
+        current_disk_bytes = 0
+        if os.path.exists(part_path):
+            current_disk_bytes = os.path.getsize(part_path)
+
+        async with self._write_lock:
+            segment["downloaded"] = current_disk_bytes
+            if segment["downloaded"] >= (segment["end"] - segment["start"] + 1) and segment["end"] > 0:
+                segment["completed"] = True
+                ui.set_segment_total(seg_id, segment["end"] - segment["start"] + 1, segment["downloaded"])
+                ui.mark_segment_completed(seg_id)
+                return
+
+        # Initialize progress bar for this segment
+        ui.set_segment_total(
+            seg_id, 
+            segment["end"] - segment["start"] + 1, 
+            segment["downloaded"]
+        )
+
+        headers = {}
+        if self.resumable:
+            start_range = segment["start"] + segment["downloaded"]
+            headers["Range"] = f"bytes={start_range}-{segment['end']}"
+
+        mode = "ab" if segment["downloaded"] > 0 else "wb"
+        
+        try:
+            async with client.stream("GET", self.url, headers=headers, timeout=30.0) as response:
+                if response.status_code not in (200, 206):
+                    raise httpx.HTTPStatusError(
+                        f"Bad status code {response.status_code}", 
+                        request=response.request, 
+                        response=response
+                    )
+                
+                # Dynamic write buffer matching
+                with open(part_path, mode) as f:
+                    async for chunk in response.aiter_bytes(chunk_size=16384):
+                        f.write(chunk)
+                        chunk_len = len(chunk)
+                        
+                        async with self._write_lock:
+                            segment["downloaded"] += chunk_len
+                        
+                        ui.update_segment(seg_id, chunk_len)
+
+            async with self._write_lock:
+                segment["completed"] = True
+            ui.mark_segment_completed(seg_id)
+
+        except asyncio.CancelledError:
+            # Handle graceful cancellation state updates
+            raise
+        except Exception as e:
+            logger.error(f"Error in connection {seg_id + 1}: {e}")
+            raise e
+
+    async def start_download(self):
+        """Orchestrates the entire multi-threaded download process."""
+        # 1. Server validation check
+        console.print("[bold cyan]Probing remote server...[/bold cyan]")
+        await self.probe_server()
+        
+        # 2. Check if a valid state already exists (Resume verification)
+        loaded = load_state(self.state_filepath)
+        if loaded and loaded.get("original_url") == self.original_url:
+            console.print("[bold yellow]Resuming existing download from saved checkpoints...[/bold yellow]")
+            self.segments = loaded["segments"]
+            self.connections = loaded["connections"]
+            self.is_stream = loaded.get("is_stream", False)
+            
+            # If it's a stream URL, refresh the potentially expired signature link!
+            if self.is_stream:
+                console.print("[bold yellow]Refreshing expired streaming signatures...[/bold yellow]")
+                loop = asyncio.get_running_loop()
+                info = await loop.run_in_executor(None, extract_stream_info, self.original_url)
+                if info:
+                    self.url = info["stream_url"]
+                else:
+                    console.print("[bold red]Warning: Failed to refresh streaming link. Trying with old URL...[/bold red]")
+        else:
+            self.prepare_segments()
+            self.save_state()
+
+        # 3. Create active workspace directory
+        os.makedirs(os.path.dirname(os.path.abspath(self.filepath)), exist_ok=True)
+
+        start_time = time.time()
+        
+        # 4. Start visual engine
+        with SpeedyProgress(len(self.segments), self.total_size, self.filename) as ui:
+            # Periodic state saver activation
+            self._state_save_task = asyncio.create_task(self._periodic_save())
+            
+            limits = httpx.Limits(max_keepalive_connections=self.connections, max_connections=self.connections)
+            async with httpx.AsyncClient(limits=limits, follow_redirects=True) as client:
+                self._download_tasks = []
+                for seg in self.segments:
+                    self._download_tasks.append(
+                        asyncio.create_task(self.download_segment(client, seg, ui))
+                    )
+
+                try:
+                    await asyncio.gather(*self._download_tasks)
+                    self.is_completed = True
+                except asyncio.CancelledError:
+                    self.is_paused = True
+                    # Cancel all workers cleanly
+                    for t in self._download_tasks:
+                        if not t.done():
+                            t.cancel()
+                    await asyncio.gather(*self._download_tasks, return_exceptions=True)
+                    # Force write current progress state
+                    self.save_state()
+                    console.print("\n[bold yellow]⚠ Download paused. Your progress has been saved atomically.[/bold yellow]")
+                    raise
+                except Exception as e:
+                    self.is_paused = True
+                    self.save_state()
+                    console.print(f"\n[bold red]✖ Download interrupted due to error: {e}[/bold red]")
+                    raise e
+                finally:
+                    # Clean up periodic saver task safely
+                    if self._state_save_task and not self._state_save_task.done():
+                        self._state_save_task.cancel()
+                        try:
+                            await self._state_save_task
+                        except asyncio.CancelledError:
+                            pass
+
+        if self.is_completed:
+            elapsed = time.time() - start_time
+            # 5. Cleanly assemble file segments with memory-safe streaming
+            console.print("[bold green]Merging segments into final output file...[/bold green]")
+            await self.merge_segments()
+            
+            # Clean state JSON files
+            if os.path.exists(self.state_filepath):
+                try:
+                    os.remove(self.state_filepath)
+                except OSError:
+                    pass
+            
+            # Display final success details
+            ui.print_summary(elapsed, self.total_size, self.filepath)
+
+    async def merge_segments(self):
+        """
+        Memory-safe O(1) chunk-by-chunk file merging. 
+        Reads parts sequentially using small buffers to prevent high RAM overhead.
+        """
+        # Create output file
+        with open(self.filepath, "wb") as outfile:
+            for seg in self.segments:
+                part_path = seg["part_path"]
+                if not os.path.exists(part_path):
+                    continue
+                
+                # Buffered streaming merge (1MB blocks)
+                with open(part_path, "rb") as infile:
+                    while True:
+                        chunk = infile.read(1024 * 1024)  # 1MB buffer
+                        if not chunk:
+                            break
+                        outfile.write(chunk)
+                
+                # Safely delete temporary part file once merged
+                try:
+                    os.remove(part_path)
+                except OSError:
+                    pass

idm_cli-0.1.0/speedy_dl/extractor.py

@@ -0,0 +1,88 @@
+import logging
+from typing import Dict, Any, Optional
+from urllib.parse import urlparse
+import yt_dlp
+
+logger = logging.getLogger("speedy_dl.extractor")
+
+def is_streaming_url(url: str) -> bool:
+    """
+    Checks if a URL belongs to a supported streaming site (YouTube, Vimeo, etc.).
+    This is a fast local check based on domains to avoid network delay.
+    """
+    streaming_domains = [
+        "youtube.com", "youtu.be", "vimeo.com", 
+        "dailymotion.com", "twitch.tv", "facebook.com",
+        "instagram.com", "tiktok.com"
+    ]
+    try:
+        parsed = urlparse(url)
+        netloc = parsed.netloc.lower()
+        return any(domain in netloc for domain in streaming_domains)
+    except Exception:
+        return False
+
+def extract_stream_info(url: str) -> Optional[Dict[str, Any]]:
+    """
+    Programmatically invokes yt-dlp to extract the video title and the direct 
+    HTTPS streaming URL for the best available format that contains both video and audio.
+    """
+    ydl_opts = {
+        "quiet": True,
+        "no_warnings": True,
+        "format": "best",  # yt-dlp default fallback
+    }
+    
+    try:
+        with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+            # Extract info without downloading the media
+            info = ydl.extract_info(url, download=False)
+            if not info:
+                return None
+            
+            title = info.get("title", "streaming_video")
+            # Sanitize title to make it a safe filename
+            safe_title = "".join(c for c in title if c.isalnum() or c in "._- ").strip()
+            if not safe_title:
+                safe_title = "streaming_video"
+            
+            formats = info.get("formats", [])
+            # Filter for formats containing BOTH video and audio so it plays out-of-the-box
+            combined_formats = [
+                f for f in formats 
+                if f.get("vcodec") != "none" 
+                and f.get("acodec") != "none" 
+                and f.get("url")
+            ]
+            
+            # Sort by resolution (height) then bitrate (tbr) descending
+            combined_formats.sort(
+                key=lambda x: (x.get("height", 0) or 0, x.get("tbr", 0) or 0), 
+                reverse=True
+            )
+            
+            if not combined_formats:
+                # Fallback to standard best format if no explicit combined filter matches
+                best_format = info
+                ext = info.get("ext", "mp4")
+            else:
+                best_format = combined_formats[0]
+                ext = best_format.get("ext", "mp4")
+                
+            stream_url = best_format.get("url")
+            size = best_format.get("filesize") or best_format.get("filesize_approx") or 0
+            
+            # Form clean filename
+            filename = f"{safe_title}.{ext}"
+            
+            return {
+                "title": title,
+                "filename": filename,
+                "stream_url": stream_url,
+                "size": size,
+                "ext": ext
+            }
+            
+    except Exception as e:
+        logger.error(f"Failed to extract stream info: {e}")
+        return None

idm_cli-0.1.0/speedy_dl/state.py

@@ -0,0 +1,55 @@
+import os
+import json
+import logging
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger("speedy_dl.state")
+
+def save_state_atomic(filepath: str, data: Dict[str, Any]) -> bool:
+    """
+    Saves metadata to a file atomically by first writing to a temporary file,
+    flushing to disk, and then replacing the target file.
+    This prevents corruption if the download is interrupted or the power cuts out.
+    """
+    temp_filepath = f"{filepath}.tmp"
+    try:
+        # Create directory if it doesn't exist
+        os.makedirs(os.path.dirname(os.path.abspath(filepath)), exist_ok=True)
+        
+        # Write to temp file
+        with open(temp_filepath, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=4, ensure_ascii=False)
+            f.flush()
+            # Force write to physical disk storage
+            try:
+                os.fsync(f.fileno())
+            except OSError:
+                # Some filesystems or OS layers don't support fsync on all descriptors
+                pass
+        
+        # Atomically replace target file
+        os.replace(temp_filepath, filepath)
+        return True
+    except Exception as e:
+        logger.error(f"Failed to save state atomically: {e}")
+        # Clean up temp file if it exists
+        if os.path.exists(temp_filepath):
+            try:
+                os.remove(temp_filepath)
+            except OSError:
+                pass
+        return False
+
+def load_state(filepath: str) -> Optional[Dict[str, Any]]:
+    """
+    Loads state metadata from the JSON file. Returns None if file does not exist or is corrupt.
+    """
+    if not os.path.exists(filepath):
+        return None
+    
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError) as e:
+        logger.error(f"Failed to load state from {filepath}: {e}")
+        return None

idm_cli-0.1.0/speedy_dl/ui.py

@@ -0,0 +1,119 @@
+from rich.progress import (
+    Progress,
+    TextColumn,
+    BarColumn,
+    DownloadColumn,
+    TransferSpeedColumn,
+    TimeRemainingColumn,
+    SpinnerColumn,
+    TaskID,
+)
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from typing import Dict
+
+console = Console()
+
+class SpeedyProgress:
+    def __init__(self, num_segments: int, total_size: int, filename: str):
+        self.num_segments = num_segments
+        self.total_size = total_size
+        self.filename = filename
+        self.segment_tasks: Dict[int, TaskID] = {}
+        
+        # Configure columns for a clean, premium dashboard
+        self.progress = Progress(
+            SpinnerColumn(spinner_name="dots", style="bold cyan"),
+            TextColumn("[bold blue]{task.description:<20}"),
+            BarColumn(bar_width=40, style="grey23", complete_style="bold green", finished_style="bold gold1"),
+            "[progress.percentage]{task.percentage:>3.0f}%",
+            DownloadColumn(),
+            TransferSpeedColumn(),
+            TimeRemainingColumn(),
+            console=console,
+            transient=True  # Clear progress display once finished to keep terminal clean
+        )
+        
+        self.master_task: TaskID = None
+
+    def __enter__(self):
+        self.progress.start()
+        
+        # Header banner
+        console.print(Panel(
+            f"[bold green]IDM-CLI Engine Activated[/bold green]\n"
+            f"[bold white]Downloading:[/bold white] [cyan]{self.filename}[/cyan]\n"
+            f"[bold white]Total Size:[/bold white] [yellow]{self._format_size(self.total_size)}[/yellow] | "
+            f"[bold white]Connections:[/bold white] [yellow]{self.num_segments}[/yellow]",
+            border_style="bold blue",
+            title="[bold yellow]idm-cli[/bold yellow]"
+        ))
+
+        # Add master overall task
+        self.master_task = self.progress.add_task(
+            "[bold gold1]Overall Progress[/bold gold1]",
+            total=self.total_size
+        )
+
+        # Add segment tasks if they aren't too crowded (max 16 tasks for screen space)
+        if self.num_segments <= 16:
+            for i in range(self.num_segments):
+                self.segment_tasks[i] = self.progress.add_task(
+                    f" ├── Connection {i+1}",
+                    total=0,  # Will be set when segment size is known
+                    visible=True
+                )
+        
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.progress.stop()
+
+    def set_segment_total(self, segment_id: int, total: int, completed: int = 0):
+        """Sets the total size for a segment's progress bar (and how much is already completed)."""
+        if segment_id in self.segment_tasks:
+            self.progress.update(self.segment_tasks[segment_id], total=total, completed=completed)
+            # Advance overall progress by the pre-completed amount
+            if completed > 0:
+                self.progress.advance(self.master_task, completed)
+
+    def update_segment(self, segment_id: int, bytes_downloaded: int):
+        """Updates both the segment progress and the overall master progress."""
+        if segment_id in self.segment_tasks:
+            self.progress.advance(self.segment_tasks[segment_id], bytes_downloaded)
+        self.progress.advance(self.master_task, bytes_downloaded)
+
+    def mark_segment_completed(self, segment_id: int):
+        """Marks a segment as fully finished and updates visual cues."""
+        if segment_id in self.segment_tasks:
+            task_id = self.segment_tasks[segment_id]
+            # Ensure it reaches 100%
+            self.progress.update(
+                task_id, 
+                completed=self.progress.tasks[task_id].total,
+                description=f" ├── [green]Connection {segment_id+1} [OK][/green]"
+            )
+
+    def print_summary(self, elapsed_time: float, final_size: int, saved_path: str):
+        """Prints a beautiful summary table upon successful download completion."""
+        avg_speed = final_size / elapsed_time if elapsed_time > 0 else 0
+        
+        summary_table = Table(title="[bold green]Download Summary[/bold green]", show_header=False, border_style="bold green")
+        summary_table.add_row("[bold white]File Saved To[/bold white]", f"[cyan]{saved_path}[/cyan]")
+        summary_table.add_row("[bold white]Downloaded Size[/bold white]", f"[yellow]{self._format_size(final_size)}[/yellow]")
+        summary_table.add_row("[bold white]Time Elapsed[/bold white]", f"{elapsed_time:.2f} seconds")
+        summary_table.add_row("[bold white]Average Speed[/bold white]", f"[bold yellow]{self._format_size(avg_speed)}/s[/bold yellow]")
+        
+        console.print()
+        console.print(Panel(summary_table, border_style="bold green"))
+        console.print("[bold gold1]* Download complete! Enjoy your speedy delivery.[/bold gold1]")
+
+    @staticmethod
+    def _format_size(size: float) -> str:
+        """Helper to format bytes into readable KB/MB/GB strings."""
+        for unit in ['B', 'KB', 'MB', 'GB', 'TB']:
+            if size < 1024.0:
+                return f"{size:.2f} {unit}"
+            size /= 1024.0
+        return f"{size:.2f} PB"

idm_cli-0.1.0/speedy_dl/updater.py

@@ -0,0 +1,71 @@
+import os
+import time
+import httpx
+import logging
+from typing import Optional
+
+import speedy_dl
+from speedy_dl.state import load_state, save_state_atomic
+
+logger = logging.getLogger("speedy_dl.updater")
+
+# Store cache in user's home directory so it persists across updates and system-wide calls
+CONFIG_PATH = os.path.join(os.path.expanduser("~"), ".speedy_dl_config.json")
+
+def get_latest_version_cached(package_name: str = "idm-cli", cache_expiry: int = 86400) -> Optional[str]:
+    """
+    Retrieves the latest published package version from the PyPI JSON API.
+    Caches results locally for 24 hours to ensure 0ms network latency on shell startup.
+    Fails silently in under 1 second if offline.
+    """
+    current_time = time.time()
+    config = load_state(CONFIG_PATH) or {}
+    
+    last_check = config.get("last_update_check", 0)
+    cached_version = config.get("latest_version")
+    
+    # If cached results exist and cache has not expired yet, use it immediately
+    if cached_version and (current_time - last_check < cache_expiry):
+        return cached_version
+        
+    # Cache is either missing or expired. Let's perform a fresh PyPI API check
+    try:
+        url = f"https://pypi.org/pypi/{package_name}/json"
+        # Strict 1.0 second timeout to prevent hanging on slow/offline connections
+        with httpx.Client(timeout=1.0) as client:
+            response = client.get(url)
+            if response.status_code == 200:
+                data = response.json()
+                latest_ver = data.get("info", {}).get("version")
+                if latest_ver:
+                    # Update local cache atomically
+                    config["last_update_check"] = current_time
+                    config["latest_version"] = latest_ver
+                    save_state_atomic(CONFIG_PATH, config)
+                    return latest_ver
+    except Exception:
+        # Network unreachable or timeout occurred - silently ignore and fallback to cached
+        pass
+        
+    return cached_version
+
+def check_for_updates() -> Optional[str]:
+    """
+    Compares the local version of speedy-dl with the latest version published on PyPI.
+    Returns the latest version string if a newer update is available, otherwise returns None.
+    """
+    local_ver = speedy_dl.__version__
+    latest_ver = get_latest_version_cached()
+    
+    if not latest_ver:
+        return None
+        
+    try:
+        # Convert semantic strings "0.1.0" into numeric tuples (0, 1, 0) for safe comparison
+        local_parts = tuple(map(int, local_ver.split(".")))
+        latest_parts = tuple(map(int, latest_ver.split(".")))
+        if latest_parts > local_parts:
+            return latest_ver
+    except Exception:
+        pass
+    return None