pinak-cli 1.0.0__tar.gz

pinak_cli-1.0.0/CLI_README.md

@@ -0,0 +1,168 @@
+# 🔱 PINAK CLI — Media Content Downloader
+
+PINAK CLI is a powerful, highly aesthetic command-line media downloader wrapper around `yt-dlp` and `ffmpeg`. It features a rich, interactive REPL shell with auto-completions, suggestions, customized banners, diagnostic tools, and automatic download tracking.
+
+---
+
+## 🚀 Key Features
+
+*   **Interactive REPL Shell**: Features a terminal command prompt with auto-completions, command suggestions, and command history.
+*   **Aesthetic UI**: Powered by `rich` and `prompt-toolkit` with vibrant color themes, tables, custom progress bars, and desktop toast notifications.
+*   **Media Formats**: Download as best-quality video, select resolutions (360p, 720p, 1080p, etc.), or convert directly to high-quality MP3 audio.
+*   **Local-First & Private**: All data, settings, and download histories remain strictly local on your machine with zero remote tracking.
+*   **Self-Diagnostics**: High-detail environmental doctor checks (`/doctor`) to verify internet, dependencies, rate limits, and configuration.
+*   **Local SQLite History**: Keeps record of your download URLs, sizes, durations, and output paths in a local SQLite database (`history.db`).
+
+---
+
+## 📦 Directory Structure
+
+```text
+cli/
+├── pinak/                      # Core Package Folder
+│   ├── __init__.py
+│   ├── __main__.py             # Entry point (python -m pinak)
+│   ├── cli.py                  # REPL Interactive Shell & Typer CLI handler
+│   ├── commands/               # Modular REPL & info subcommands
+│   ├── downloader.py           # yt-dlp & FFmpeg downloader logic
+│   ├── config.py               # Application configurations (Pydantic-Settings)
+│   ├── history.py              # SQLite storage & local tracking
+│   ├── doctor.py               # Dependencies & connection diagnostics
+│   ├── ffmpeg_setup.py         # Static FFmpeg installer utility
+│   ├── notify.py               # Desktop notifications & terminal banners
+│   ├── updater.py              # Update checker
+│   └── utils.py                # Formatting & utility helpers
+├── tests/                      # Automated test suite (pytest)
+├── pyproject.toml              # Pyproject packaging config
+├── requirements-lock.txt       # Locked dependencies for reproducible installs
+├── Dockerfile                  # Container image (ffmpeg included)
+├── .dockerignore               # Docker build ignore patterns
+└── LICENSE                     # MIT license
+```
+
+> **Note:** FFmpeg is *not* bundled with the PyPI package. See
+> [FFmpeg setup](#-ffmpeg-setup) below — one command installs it.
+
+---
+
+## 🛠️ Installation & Setup
+
+### Requirements
+*   Python 3.10 or higher.
+*   FFmpeg (see [FFmpeg setup](#-ffmpeg-setup) — one command).
+
+### Step 1: Install from PyPI
+
+```bash
+pip install pinak-cli
+# recommended (isolated, always on PATH):
+pipx install pinak-cli
+```
+
+This registers the global `pinak` command. From source (developers):
+
+```bash
+cd cli
+pip install -e ".[dev]"
+```
+
+### Step 2: Test Command
+
+```bash
+pinak --doctor
+pinak
+```
+
+> **`pinak` not found after install?** Your Python Scripts folder isn't on
+> PATH. Either add it, use `pipx install pinak-cli`, or run
+> `python -m pinak` instead — it works identically. `pinak --doctor`
+> includes a "CLI on PATH" check that tells you exactly what to do.
+
+---
+
+## 🎞️ FFmpeg setup
+
+FFmpeg merges formats and extracts MP3s. Pick one option:
+
+```bash
+pinak --install-ffmpeg        # single-command mode: downloads a static build
+/ffmpeg                        # same thing, inside the interactive REPL
+pip install "pinak-cli[ffmpeg]"  # manual equivalent (static-ffmpeg extra)
+```
+
+Or install FFmpeg system-wide ([ffmpeg.org/download](https://ffmpeg.org/download.html))
+and make sure it is on PATH. Docker users already have it (`cli/Dockerfile`).
+
+---
+
+## 🔄 Keeping everything fresh
+
+Sites change often; an outdated `yt-dlp` is the #1 cause of sudden failures.
+Pinak checks PyPI in the background (max once per day) and notifies you —
+about new `yt-dlp` **and** new Pinak releases. Inside the REPL, update both
+any time with:
+
+```
+/update
+```
+
+This runs `pip install --upgrade yt-dlp` and `pip install --upgrade
+pinak-cli`, tells you exactly what changed (`Updated … 1.0.0 → 1.1.0` vs
+`already the latest`), and — if Pinak itself was upgraded — asks you to
+restart the CLI (`/exit`, then run `pinak` again) so the new version loads.
+
+---
+
+## 💻 CLI Commands
+
+When running the interactive REPL shell (`pinak`), the following commands are available:
+
+| Command | Description |
+| :--- | :--- |
+| `/help` | Display the list of all available commands and shortcuts |
+| `/doctor` | Run comprehensive environment and connectivity checks |
+| `/audio <url>` | Download the media from the URL as an MP3 audio track |
+| `/video <url>` | Download video from a URL |
+| `/instagram <url>` | Download Instagram post, reel, or IGTV with metadata |
+| `/batch <file>` | Download multiple URLs from a text file |
+| `/history` | View a list of recent downloads from your history database |
+| `/config` | Print out the current config settings and environment |
+| `/setout <dir>` | Change the output downloads directory |
+| `/open` | Open the downloads directory in File Explorer |
+| `/platform [q]` | List supported platforms or search filter them |
+| `/update` | Update yt-dlp and Pinak CLI to the latest versions |
+| `/ffmpeg` | Download a static FFmpeg build automatically |
+| `/exit` | Terminate the interactive REPL shell |
+
+---
+
+## ⚙️ Configuration File
+
+Pinak CLI saves user-specific configuration (like download directory, quality, retry counts) in a standard configuration folder (via `platformdirs`).
+
+- **Windows**: `%LOCALAPPDATA%\pinak\pinak-cli\config.json`
+- **macOS**: `~/Library/Application Support/pinak-cli/config.json`
+- **Linux**: `~/.config/pinak-cli/config.json`
+- **SQLite history**: alongside it (`history.db`)
+
+Run `pinak --config-path` anywhere to print your exact path, or `/config`
+inside the REPL (the path is shown above the table). Change the output
+folder with `/setout <absolute_path>`.
+
+---
+
+## 🔒 Privacy & Local-First
+
+Pinak CLI is strictly local-first and privacy-focused. All configuration, download history, and media files remain on your local machine. No external tracking or telemetry is performed.
+
+---
+
+## ⚖️ Educational Purpose & Legal Disclaimer
+
+Pinak CLI is developed as an **educational project, technical study of CLI architecture, and personal-archiving tool** wrapper around `yt-dlp` and `ffmpeg`. You are solely responsible for how you use it:
+
+- **Personal Archival Only:** Only download content you own, that is freely licensed (e.g., Creative Commons), or that you have explicit permission to save.
+- **Terms of Service:** Automated downloading may violate the Terms of Service of platforms such as YouTube, Instagram, or TikTok; your account or IP could be restricted by those platforms. Use at your own risk.
+- **Be Excellent to Creators:** Do not use this tool to pirate, redistribute, or monetize copyrighted material without authorization. Always support and respect creators.
+- **No DRM Circumvention:** Pinak CLI does not bypass or defeat Digital Rights Management (DRM) or access restrictions.
+- **Limitation of Liability:** The authors provide this software "as is" under the [MIT License](LICENSE) and accept no liability for misuse.

pinak_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pinak Team
+
+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.

pinak_cli-1.0.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: pinak-cli
+Version: 1.0.0
+Summary: A powerful, aesthetic command-line media downloader using yt-dlp
+Author: Pinak Team
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pinak-project/pinak-cli
+Project-URL: Repository, https://github.com/pinak-project/pinak-cli
+Keywords: yt-dlp,downloader,cli,video,media,instagram
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+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.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yt-dlp>=2025.1.1
+Requires-Dist: rich>=13.0.0
+Requires-Dist: prompt-toolkit>=3.0.0
+Requires-Dist: win11toast; sys_platform == "win32"
+Requires-Dist: questionary
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: platformdirs
+Requires-Dist: typer
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: mutagen>=1.47
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: bandit>=1.7; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Requires-Dist: cyclonedx-bom>=7.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: pytest-mock>=3.12; extra == "test"
+Requires-Dist: hypothesis>=6.0; extra == "test"
+Provides-Extra: ffmpeg
+Requires-Dist: static-ffmpeg>=2.5; extra == "ffmpeg"
+Dynamic: license-file
+
+# 🔱 PINAK CLI — Media Content Downloader
+
+PINAK CLI is a powerful, highly aesthetic command-line media downloader wrapper around `yt-dlp` and `ffmpeg`. It features a rich, interactive REPL shell with auto-completions, suggestions, customized banners, diagnostic tools, and automatic download tracking.
+
+---
+
+## 🚀 Key Features
+
+*   **Interactive REPL Shell**: Features a terminal command prompt with auto-completions, command suggestions, and command history.
+*   **Aesthetic UI**: Powered by `rich` and `prompt-toolkit` with vibrant color themes, tables, custom progress bars, and desktop toast notifications.
+*   **Media Formats**: Download as best-quality video, select resolutions (360p, 720p, 1080p, etc.), or convert directly to high-quality MP3 audio.
+*   **Local-First & Private**: All data, settings, and download histories remain strictly local on your machine with zero remote tracking.
+*   **Self-Diagnostics**: High-detail environmental doctor checks (`/doctor`) to verify internet, dependencies, rate limits, and configuration.
+*   **Local SQLite History**: Keeps record of your download URLs, sizes, durations, and output paths in a local SQLite database (`history.db`).
+
+---
+
+## 📦 Directory Structure
+
+```text
+cli/
+├── pinak/                      # Core Package Folder
+│   ├── __init__.py
+│   ├── __main__.py             # Entry point (python -m pinak)
+│   ├── cli.py                  # REPL Interactive Shell & Typer CLI handler
+│   ├── commands/               # Modular REPL & info subcommands
+│   ├── downloader.py           # yt-dlp & FFmpeg downloader logic
+│   ├── config.py               # Application configurations (Pydantic-Settings)
+│   ├── history.py              # SQLite storage & local tracking
+│   ├── doctor.py               # Dependencies & connection diagnostics
+│   ├── ffmpeg_setup.py         # Static FFmpeg installer utility
+│   ├── notify.py               # Desktop notifications & terminal banners
+│   ├── updater.py              # Update checker
+│   └── utils.py                # Formatting & utility helpers
+├── tests/                      # Automated test suite (pytest)
+├── pyproject.toml              # Pyproject packaging config
+├── requirements-lock.txt       # Locked dependencies for reproducible installs
+├── Dockerfile                  # Container image (ffmpeg included)
+├── .dockerignore               # Docker build ignore patterns
+└── LICENSE                     # MIT license
+```
+
+> **Note:** FFmpeg is *not* bundled with the PyPI package. See
+> [FFmpeg setup](#-ffmpeg-setup) below — one command installs it.
+
+---
+
+## 🛠️ Installation & Setup
+
+### Requirements
+*   Python 3.10 or higher.
+*   FFmpeg (see [FFmpeg setup](#-ffmpeg-setup) — one command).
+
+### Step 1: Install from PyPI
+
+```bash
+pip install pinak-cli
+# recommended (isolated, always on PATH):
+pipx install pinak-cli
+```
+
+This registers the global `pinak` command. From source (developers):
+
+```bash
+cd cli
+pip install -e ".[dev]"
+```
+
+### Step 2: Test Command
+
+```bash
+pinak --doctor
+pinak
+```
+
+> **`pinak` not found after install?** Your Python Scripts folder isn't on
+> PATH. Either add it, use `pipx install pinak-cli`, or run
+> `python -m pinak` instead — it works identically. `pinak --doctor`
+> includes a "CLI on PATH" check that tells you exactly what to do.
+
+---
+
+## 🎞️ FFmpeg setup
+
+FFmpeg merges formats and extracts MP3s. Pick one option:
+
+```bash
+pinak --install-ffmpeg        # single-command mode: downloads a static build
+/ffmpeg                        # same thing, inside the interactive REPL
+pip install "pinak-cli[ffmpeg]"  # manual equivalent (static-ffmpeg extra)
+```
+
+Or install FFmpeg system-wide ([ffmpeg.org/download](https://ffmpeg.org/download.html))
+and make sure it is on PATH. Docker users already have it (`cli/Dockerfile`).
+
+---
+
+## 🔄 Keeping everything fresh
+
+Sites change often; an outdated `yt-dlp` is the #1 cause of sudden failures.
+Pinak checks PyPI in the background (max once per day) and notifies you —
+about new `yt-dlp` **and** new Pinak releases. Inside the REPL, update both
+any time with:
+
+```
+/update
+```
+
+This runs `pip install --upgrade yt-dlp` and `pip install --upgrade
+pinak-cli`, tells you exactly what changed (`Updated … 1.0.0 → 1.1.0` vs
+`already the latest`), and — if Pinak itself was upgraded — asks you to
+restart the CLI (`/exit`, then run `pinak` again) so the new version loads.
+
+---
+
+## 💻 CLI Commands
+
+When running the interactive REPL shell (`pinak`), the following commands are available:
+
+| Command | Description |
+| :--- | :--- |
+| `/help` | Display the list of all available commands and shortcuts |
+| `/doctor` | Run comprehensive environment and connectivity checks |
+| `/audio <url>` | Download the media from the URL as an MP3 audio track |
+| `/video <url>` | Download video from a URL |
+| `/instagram <url>` | Download Instagram post, reel, or IGTV with metadata |
+| `/batch <file>` | Download multiple URLs from a text file |
+| `/history` | View a list of recent downloads from your history database |
+| `/config` | Print out the current config settings and environment |
+| `/setout <dir>` | Change the output downloads directory |
+| `/open` | Open the downloads directory in File Explorer |
+| `/platform [q]` | List supported platforms or search filter them |
+| `/update` | Update yt-dlp and Pinak CLI to the latest versions |
+| `/ffmpeg` | Download a static FFmpeg build automatically |
+| `/exit` | Terminate the interactive REPL shell |
+
+---
+
+## ⚙️ Configuration File
+
+Pinak CLI saves user-specific configuration (like download directory, quality, retry counts) in a standard configuration folder (via `platformdirs`).
+
+- **Windows**: `%LOCALAPPDATA%\pinak\pinak-cli\config.json`
+- **macOS**: `~/Library/Application Support/pinak-cli/config.json`
+- **Linux**: `~/.config/pinak-cli/config.json`
+- **SQLite history**: alongside it (`history.db`)
+
+Run `pinak --config-path` anywhere to print your exact path, or `/config`
+inside the REPL (the path is shown above the table). Change the output
+folder with `/setout <absolute_path>`.
+
+---
+
+## 🔒 Privacy & Local-First
+
+Pinak CLI is strictly local-first and privacy-focused. All configuration, download history, and media files remain on your local machine. No external tracking or telemetry is performed.
+
+---
+
+## ⚖️ Educational Purpose & Legal Disclaimer
+
+Pinak CLI is developed as an **educational project, technical study of CLI architecture, and personal-archiving tool** wrapper around `yt-dlp` and `ffmpeg`. You are solely responsible for how you use it:
+
+- **Personal Archival Only:** Only download content you own, that is freely licensed (e.g., Creative Commons), or that you have explicit permission to save.
+- **Terms of Service:** Automated downloading may violate the Terms of Service of platforms such as YouTube, Instagram, or TikTok; your account or IP could be restricted by those platforms. Use at your own risk.
+- **Be Excellent to Creators:** Do not use this tool to pirate, redistribute, or monetize copyrighted material without authorization. Always support and respect creators.
+- **No DRM Circumvention:** Pinak CLI does not bypass or defeat Digital Rights Management (DRM) or access restrictions.
+- **Limitation of Liability:** The authors provide this software "as is" under the [MIT License](LICENSE) and accept no liability for misuse.

pinak_cli-1.0.0/pinak/__init__.py

@@ -0,0 +1,2 @@
+# Pinak CLI Package
+__version__ = "1.0.0"

pinak_cli-1.0.0/pinak/__main__.py

@@ -0,0 +1,9 @@
+"""
+Allows running the package directly with:
+    python -m pinak
+"""
+
+from pinak.cli import run_cli
+
+if __name__ == "__main__":
+    run_cli()  # pragma: no cover - exercised via test_entry subprocess smoke