toolify 0.2.0__tar.gz → 1.0.1__tar.gz

{toolify-0.2.0 → toolify-1.0.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Amr Abdelsamea
+Copyright (c) 2025 Amr Abdelsamea
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ 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.
+SOFTWARE.

toolify-1.0.1/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: toolify
+Version: 1.0.1
+Summary: Utilities for terminal output, Arabic text, audio, plotting, Hugging Face, and YouTube.
+Author-email: Amr Abdelsamea <amr.abdelsamee33@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Amr-abdelsamee/toolify
+Project-URL: Source, https://github.com/Amr-abdelsamee/toolify
+Project-URL: Documentation, https://amr-abdelsamee.github.io/toolify/
+Project-URL: Issues, https://github.com/Amr-abdelsamee/toolify/issues
+Project-URL: Changelog, https://github.com/Amr-abdelsamee/toolify/blob/main/CHANGELOG.md
+Keywords: tools,arabic,audio,plotting,youtube,huggingface
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-bidi>=0.6.6
+Requires-Dist: arabic-reshaper>=3.0.0
+Requires-Dist: youtube-transcript-api>=1.1.0
+Requires-Dist: yt-dlp>=2025.10.22
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: matplotlib>=3.11.0
+Requires-Dist: librosa>=0.11.0
+Requires-Dist: numpy>=1.25
+Requires-Dist: soundfile>=0.14.0
+Requires-Dist: huggingface-hub>=1.21.0
+Requires-Dist: hf-transfer>=0.1.9
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Dynamic: license-file
+
+<h1>
+  <img
+    src="docs/assets/images/toolify-logo.png"
+    alt="Toolify logo"
+    width="84"
+    align="absmiddle"
+  >
+  Toolify
+</h1>
+
+[![PyPI](https://img.shields.io/pypi/v/toolify)](https://pypi.org/project/toolify/)
+[![Python](https://img.shields.io/pypi/pyversions/toolify)](https://pypi.org/project/toolify/)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://amr-abdelsamee.github.io/toolify/)
+[![License](https://img.shields.io/pypi/l/toolify)](https://github.com/Amr-abdelsamee/toolify/blob/main/LICENSE)
+
+Toolify is a Python utility library for terminal output, Arabic text handling,
+logging, plotting, audio inspection, Hugging Face downloads, and YouTube media
+downloads.
+
+## Features
+
+| Module | Purpose |
+| --- | --- |
+| `toolify.tools` | Colored output, Arabic text, tables, logging, and confirmation |
+| `toolify.plots` | Line-plot generation |
+| `toolify.audio` | Silence detection, spectrograms, and duration helpers |
+| `toolify.ai` | Hugging Face repository inspection and downloads |
+| `toolify.youtube` | YouTube video, transcript, and playlist utilities |
+
+## Installation
+
+Install the latest release from PyPI:
+
+```bash
+pip install toolify
+```
+
+Python 3.11 or newer is required. FFmpeg is also required when YouTube video
+and audio streams need to be merged.
+
+### Install FFmpeg
+
+FFmpeg is a system application, not a Python package.
+
+#### Windows
+
+Install it from PowerShell with Windows Package Manager:
+
+```powershell
+winget install --exact --id Gyan.FFmpeg
+```
+
+Close and reopen the terminal after installation. If `winget` is unavailable,
+download a Windows build from the
+[official FFmpeg download page](https://ffmpeg.org/download.html), extract it,
+and add its `bin` directory to the Windows `PATH`.
+
+#### Linux
+
+Ubuntu, Debian, and Linux Mint:
+
+```bash
+sudo apt update
+sudo apt install ffmpeg
+```
+
+
+Verify the installation on either operating system:
+
+```bash
+ffmpeg -version
+```
+
+
+## Documentation
+
+The complete guides and API reference are available in the
+[Toolify documentation](https://amr-abdelsamee.github.io/toolify/).
+
+- [Installation](https://amr-abdelsamee.github.io/toolify/getting-started/installation/)
+- [Quick start](https://amr-abdelsamee.github.io/toolify/getting-started/quickstart/)
+- [User guides](https://amr-abdelsamee.github.io/toolify/guides/tools/)
+- [API reference](https://amr-abdelsamee.github.io/toolify/reference/tools/)
+- [Changelog](https://github.com/Amr-abdelsamee/toolify/blob/main/CHANGELOG.md)
+
+## Development
+
+```bash
+git clone https://github.com/Amr-abdelsamee/toolify.git
+cd toolify
+pip install -e ".[dev,docs]"
+python -m pytest -m "not integration"
+mkdocs serve
+```
+
+See the [contributing guide](https://amr-abdelsamee.github.io/toolify/development/contributing/)
+and [release guide](https://amr-abdelsamee.github.io/toolify/development/releasing/).
+
+## License
+
+Toolify is licensed under the
+[MIT License](https://github.com/Amr-abdelsamee/toolify/blob/main/LICENSE).

toolify-1.0.1/README.md

@@ -0,0 +1,102 @@
+<h1>
+  <img
+    src="docs/assets/images/toolify-logo.png"
+    alt="Toolify logo"
+    width="84"
+    align="absmiddle"
+  >
+  Toolify
+</h1>
+
+[![PyPI](https://img.shields.io/pypi/v/toolify)](https://pypi.org/project/toolify/)
+[![Python](https://img.shields.io/pypi/pyversions/toolify)](https://pypi.org/project/toolify/)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://amr-abdelsamee.github.io/toolify/)
+[![License](https://img.shields.io/pypi/l/toolify)](https://github.com/Amr-abdelsamee/toolify/blob/main/LICENSE)
+
+Toolify is a Python utility library for terminal output, Arabic text handling,
+logging, plotting, audio inspection, Hugging Face downloads, and YouTube media
+downloads.
+
+## Features
+
+| Module | Purpose |
+| --- | --- |
+| `toolify.tools` | Colored output, Arabic text, tables, logging, and confirmation |
+| `toolify.plots` | Line-plot generation |
+| `toolify.audio` | Silence detection, spectrograms, and duration helpers |
+| `toolify.ai` | Hugging Face repository inspection and downloads |
+| `toolify.youtube` | YouTube video, transcript, and playlist utilities |
+
+## Installation
+
+Install the latest release from PyPI:
+
+```bash
+pip install toolify
+```
+
+Python 3.11 or newer is required. FFmpeg is also required when YouTube video
+and audio streams need to be merged.
+
+### Install FFmpeg
+
+FFmpeg is a system application, not a Python package.
+
+#### Windows
+
+Install it from PowerShell with Windows Package Manager:
+
+```powershell
+winget install --exact --id Gyan.FFmpeg
+```
+
+Close and reopen the terminal after installation. If `winget` is unavailable,
+download a Windows build from the
+[official FFmpeg download page](https://ffmpeg.org/download.html), extract it,
+and add its `bin` directory to the Windows `PATH`.
+
+#### Linux
+
+Ubuntu, Debian, and Linux Mint:
+
+```bash
+sudo apt update
+sudo apt install ffmpeg
+```
+
+
+Verify the installation on either operating system:
+
+```bash
+ffmpeg -version
+```
+
+
+## Documentation
+
+The complete guides and API reference are available in the
+[Toolify documentation](https://amr-abdelsamee.github.io/toolify/).
+
+- [Installation](https://amr-abdelsamee.github.io/toolify/getting-started/installation/)
+- [Quick start](https://amr-abdelsamee.github.io/toolify/getting-started/quickstart/)
+- [User guides](https://amr-abdelsamee.github.io/toolify/guides/tools/)
+- [API reference](https://amr-abdelsamee.github.io/toolify/reference/tools/)
+- [Changelog](https://github.com/Amr-abdelsamee/toolify/blob/main/CHANGELOG.md)
+
+## Development
+
+```bash
+git clone https://github.com/Amr-abdelsamee/toolify.git
+cd toolify
+pip install -e ".[dev,docs]"
+python -m pytest -m "not integration"
+mkdocs serve
+```
+
+See the [contributing guide](https://amr-abdelsamee.github.io/toolify/development/contributing/)
+and [release guide](https://amr-abdelsamee.github.io/toolify/development/releasing/).
+
+## License
+
+Toolify is licensed under the
+[MIT License](https://github.com/Amr-abdelsamee/toolify/blob/main/LICENSE).

toolify-1.0.1/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "toolify"
+version = "1.0.1"
+description = "Utilities for terminal output, Arabic text, audio, plotting, Hugging Face, and YouTube."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+
+authors = [
+    { name = "Amr Abdelsamea", email = "amr.abdelsamee33@gmail.com" }
+]
+
+keywords = [
+    "tools",
+    "arabic",
+    "audio",
+    "plotting",
+    "youtube",
+    "huggingface",
+]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+]
+
+dependencies = [
+    "python-bidi>=0.6.6",
+    "arabic-reshaper>=3.0.0",
+    "youtube-transcript-api>=1.1.0",
+    "yt-dlp>=2025.10.22",
+    "tqdm>=4.67.1",
+    "matplotlib>=3.11.0",
+    "librosa>=0.11.0",
+    "numpy>=1.25",
+    "soundfile>=0.14.0",
+    "huggingface-hub>=1.21.0",
+    "hf-transfer>=0.1.9",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "build",
+    "twine",
+]
+
+docs = [
+    "mkdocs-material",
+    "mkdocstrings[python]",
+]
+
+[project.urls]
+Homepage = "https://github.com/Amr-abdelsamee/toolify"
+Source = "https://github.com/Amr-abdelsamee/toolify"
+Documentation = "https://amr-abdelsamee.github.io/toolify/"
+Issues = "https://github.com/Amr-abdelsamee/toolify/issues"
+Changelog = "https://github.com/Amr-abdelsamee/toolify/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+include = ["toolify*"]
+exclude = ["tests*", "docs*"]

toolify-1.0.1/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

toolify-1.0.1/tests/test_ai.py

@@ -0,0 +1,223 @@
+import os
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+import toolify.ai.huggingface as hf
+from toolify.ai import (
+    get_hf_model_size,
+    get_hf_dataset_size,
+    download_hf_model,
+    download_hf_dataset,
+)
+
+
+GB = 1024**3
+
+
+def test_ai_public_imports():
+    assert callable(get_hf_model_size)
+    assert callable(get_hf_dataset_size)
+    assert callable(download_hf_model)
+    assert callable(download_hf_dataset)
+
+
+def test_get_hf_model_size_falls_back_when_safetensors_size_is_none(monkeypatch):
+    """This test catches the real bug:
+    safetensors metadata exists but total size cannot be extracted.
+    The fallback must reset total_bytes to 0, not keep it as None.
+    """
+
+    class FakeHfApi:
+        def __init__(self, token=None):
+            self.token = token
+
+        def get_safetensors_metadata(self, repo_id, revision=None):
+            # No total_size, no metadata["total_size"], no files_metadata sizes.
+            return SimpleNamespace()
+
+        def model_info(self, repo_id, revision=None, files_metadata=True):
+            return SimpleNamespace(
+                siblings=[
+                    SimpleNamespace(size=1 * GB),
+                    SimpleNamespace(size=2 * GB),
+                    SimpleNamespace(size=None),
+                ]
+            )
+
+    monkeypatch.setattr(
+        hf,
+        "_require_huggingface_hub",
+        lambda: (FakeHfApi, None),
+    )
+
+    size = hf.get_hf_model_size("org/test-model", verbose=False)
+
+    assert size == 3.0
+
+
+def test_get_hf_model_size_uses_safetensors_when_valid(monkeypatch):
+    class FakeHfApi:
+        def __init__(self, token=None):
+            self.token = token
+
+        def get_safetensors_metadata(self, repo_id, revision=None):
+            return SimpleNamespace(total_size=4 * GB)
+
+        def model_info(self, *args, **kwargs):
+            raise AssertionError("model_info should not be called")
+
+    monkeypatch.setattr(
+        hf,
+        "_require_huggingface_hub",
+        lambda: (FakeHfApi, None),
+    )
+
+    size = hf.get_hf_model_size("org/test-model", verbose=False)
+
+    assert size == 4.0
+
+
+def test_get_hf_dataset_size(monkeypatch):
+    class FakeHfApi:
+        def __init__(self, token=None):
+            self.token = token
+
+        def dataset_info(self, repo_id, revision=None, expand=None):
+            assert expand == ["usedStorage"]
+            return SimpleNamespace(usedStorage=5 * GB)
+
+    monkeypatch.setattr(
+        hf,
+        "_require_huggingface_hub",
+        lambda: (FakeHfApi, None),
+    )
+
+    size = hf.get_hf_dataset_size("org/test-dataset", verbose=False)
+
+    assert size == 5.0
+
+
+def test_download_hf_model_uses_local_dir(monkeypatch, tmp_path):
+    calls = {}
+
+    class FakeHfApi:
+        pass
+
+    def fake_snapshot_download(**kwargs):
+        calls.update(kwargs)
+
+        local_dir = Path(kwargs["local_dir"])
+        local_dir.mkdir(parents=True, exist_ok=True)
+        (local_dir / "README.md").write_text("fake model", encoding="utf-8")
+
+        return str(local_dir)
+
+    monkeypatch.setattr(
+        hf,
+        "_require_huggingface_hub",
+        lambda: (FakeHfApi, fake_snapshot_download),
+    )
+
+    target_dir = tmp_path / "custom_model"
+
+    path = hf.download_hf_model(
+        "org/test-model",
+        local_dir=target_dir,
+        show_size=False,
+        verbose=False,
+    )
+
+    assert path == target_dir
+    assert path.exists()
+    assert (path / "README.md").exists()
+    assert calls["repo_id"] == "org/test-model"
+    assert calls["repo_type"] == "model"
+    assert Path(calls["local_dir"]) == target_dir
+
+
+def test_download_hf_dataset_uses_base_dir(monkeypatch, tmp_path):
+    calls = {}
+
+    class FakeHfApi:
+        pass
+
+    def fake_snapshot_download(**kwargs):
+        calls.update(kwargs)
+
+        local_dir = Path(kwargs["local_dir"])
+        local_dir.mkdir(parents=True, exist_ok=True)
+        (local_dir / "README.md").write_text("fake dataset", encoding="utf-8")
+
+        return str(local_dir)
+
+    monkeypatch.setattr(
+        hf,
+        "_require_huggingface_hub",
+        lambda: (FakeHfApi, fake_snapshot_download),
+    )
+
+    path = hf.download_hf_dataset(
+        "org/test-dataset",
+        base_dir=tmp_path / "datasets",
+        show_size=False,
+        verbose=False,
+    )
+
+    expected = tmp_path / "datasets" / "org_test-dataset"
+
+    assert path == expected
+    assert path.exists()
+    assert (path / "README.md").exists()
+    assert calls["repo_id"] == "org/test-dataset"
+    assert calls["repo_type"] == "dataset"
+    assert Path(calls["local_dir"]) == expected
+
+
+def test_download_hf_repo_rejects_invalid_repo_type(tmp_path):
+    with pytest.raises(ValueError):
+        hf.download_hf_repo(
+            "org/test-repo",
+            repo_type="invalid",  # type: ignore[arg-type]
+            base_dir=tmp_path,
+            verbose=False,
+        )
+
+
+@pytest.mark.integration
+def test_integration_get_real_hf_model_size():
+    """Real Hugging Face test.
+
+    Run only when:
+        RUN_HF_INTEGRATION=1 python -m pytest tests/test_ai.py -m integration -v
+    """
+    if os.getenv("RUN_HF_INTEGRATION") != "1":
+        pytest.skip("Set RUN_HF_INTEGRATION=1 to run Hugging Face integration tests.")
+
+    size = hf.get_hf_model_size(
+        "Qwen/Qwen3-Reranker-0.6B",
+        verbose=True,
+        raise_on_error=True,
+    )
+
+    assert size is not None
+    assert size > 0
+
+
+@pytest.mark.integration
+def test_integration_download_model_readme_only(tmp_path):
+    """Downloads only tiny files from a real model repo."""
+    if os.getenv("RUN_HF_INTEGRATION") != "1":
+        pytest.skip("Set RUN_HF_INTEGRATION=1 to run Hugging Face integration tests.")
+
+    path = hf.download_hf_model(
+        "Qwen/Qwen3-Reranker-0.6B",
+        local_dir=tmp_path / "qwen_reranker_test",
+        allow_patterns=["README.md", "config.json"],
+        show_size=False,
+        verbose=True,
+    )
+
+    assert path.exists()
+    assert any(path.iterdir())

toolify-1.0.1/tests/test_tools.py

@@ -0,0 +1,103 @@
+import os
+import logging
+import pytest
+from datetime import datetime
+
+from toolify.tools import (
+    pct,
+    print_table,
+    setup_logger,
+    strip_tashkeel,
+    confirm,
+)
+
+
+def test_strip_tashkeel_removes_arabic_diacritics():
+    text = "مُحَمَّدٌ"
+    result = strip_tashkeel(text)
+
+    assert result == "محمد"
+
+
+def test_strip_tashkeel_removes_special_symbols_by_default():
+    text = "ا^ل>س<لام؞"
+    result = strip_tashkeel(text)
+
+    assert result == "السلام"
+
+
+def test_strip_tashkeel_can_keep_special_symbols():
+    text = "ا^ل>س<لام؞"
+    result = strip_tashkeel(text, remove_special_symbols=False)
+
+    assert result == "ا^ل>س<لام؞"
+
+
+def test_pct_prints_plain_text_when_ec_false(capsys):
+    pct("Hello Toolify", ec=False)
+
+    captured = capsys.readouterr()
+
+    assert captured.out == "Hello Toolify\n"
+
+
+def test_pct_prints_with_emoji_when_ec_false(capsys):
+    pct("Done", ec=False, emoji="success", end_emoji="fire")
+
+    captured = capsys.readouterr()
+
+    assert captured.out == "✅ Done 🔥\n"
+
+
+def test_pct_custom_end(capsys):
+    pct("Hello", ec=False, end="")
+
+    captured = capsys.readouterr()
+
+    assert captured.out == "Hello"
+
+
+def test_print_table_outputs_headers_and_rows(capsys):
+    headers = ["Name", "Score"]
+    rows = [
+        ["Ali", 95],
+        ["Sara", 88],
+    ]
+
+    print_table(headers, rows)
+
+    captured = capsys.readouterr()
+
+    assert "Name" in captured.out
+    assert "Score" in captured.out
+    assert "Ali" in captured.out
+    assert "Sara" in captured.out
+
+
+def test_setup_logger_creates_log_file(tmp_path):
+    date_str = datetime.now().strftime("%Y_%m_%d")
+    log_file = tmp_path /f"test.log"
+    logger = setup_logger(__name__, str(log_file))
+    log_file = tmp_path /f"test__{date_str}.log"
+    logger.info("Hello logger")
+
+    assert isinstance(logger, logging.Logger)
+    assert log_file.exists()
+
+    content = log_file.read_text(encoding="utf-8")
+    assert "Hello logger" in content
+
+
+def test_confirm_returns_none_when_user_confirms(monkeypatch):
+    monkeypatch.setattr("builtins.input", lambda _: "yes")
+
+    result = confirm(message="Continue? ")
+
+    assert result is None
+
+
+def test_confirm_exits_when_user_declines(monkeypatch):
+    monkeypatch.setattr("builtins.input", lambda _: "no")
+
+    with pytest.raises(SystemExit):
+        confirm(message="Continue? ")