klygo 0.1.0__tar.gz

klygo-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: klygo
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: build>=1.5.1
+Requires-Dist: numpy>=2.5.1
+Requires-Dist: opencv-python>=5.0.0.93
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: python-box>=7.4.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: ruamel-yaml>=0.19.1
+Requires-Dist: tomlkit>=0.15.0
+Requires-Dist: torch>=2.13.0
+Requires-Dist: tqdm>=4.68.4
+Requires-Dist: transformers>=5.13.0
+Requires-Dist: twine>=6.2.0
+
+# klygo
+
+Thư viện Python hỗ trợ nén/giải nén file, xử lý bộ dữ liệu YOLO, đọc/ghi file cấu hình và nhận diện vật thể zero-shot.
+
+---
+
+## Tính năng chính
+
+- klygo.archive: Các thao tác với file nén ZIP (nén, giải nén, tìm kiếm, gộp, chia, thêm, xóa file) hỗ trợ hiển thị thanh tiến trình.
+- klygo.datasets: Các công cụ quản lý và xử lý bộ dữ liệu YOLO (phân chia train/val/test, chia lại tỷ lệ tại chỗ, gộp nhiều dataset có ánh xạ lại class ID, và tách dataset theo class/tỷ lệ con).
+- klygo.io: Đọc và ghi các file cấu hình YAML, JSON, TOML, tự động tạo thư mục, tự động phân giải đường dẫn tương đối và truy cập dạng thuộc tính qua Box.
+- klygo.models: Lớp hỗ trợ nhận diện vật thể zero-shot (dựa trên Grounding DINO) trên ảnh và video, tự động xuất dữ liệu theo định dạng YOLO.
+
+---
+
+## Cấu trúc thư mục
+
+```
+klygo/
+├── archive/        # Các tiện ích nén và giải nén
+├── datasets/       # Công cụ quản lý và phân chia bộ dữ liệu YOLO
+├── io/             # Bộ đọc/ghi cấu hình YAML, JSON, TOML
+├── models/         # Lớp nhận diện vật thể (Kernel)
+└── validators/     # Bộ xác thực dữ liệu đầu vào
+```
+
+---
+
+## Hướng dẫn sử dụng nhanh
+
+### 1. Nén và giải nén (klygo.archive as ar)
+
+```python
+import klygo.archive as ar
+
+# Nén thư mục và giải nén
+ar.compress("src_directory/", "archive.zip")
+ar.extract("archive.zip", output="destination_dir/", overwrite=True)
+
+# Tìm kiếm file trong archive
+files = ar.search("archive.zip", "images/*.jpg")
+```
+
+Xem tài liệu đầy đủ tại docs/archive/README.md.
+
+---
+
+### 2. Quản lý bộ dữ liệu YOLO (klygo.datasets)
+
+```python
+from klygo.datasets import partition, repartition, merge, split, remap_classes, get_dataset_info
+
+# 1. Phân chia tập dữ liệu thô thành train/val/test
+partition(source="raw_data.zip", output="dataset/", ratios=(0.8,), overwrite=True)
+
+# 2. Hợp nhất hai bộ dữ liệu khác class tự động đổi class ID
+merge(sources=["data1/", "data2.zip"], output="merged.zip", overwrite=True)
+
+# 3. Tách nhỏ bộ dữ liệu theo từng class đối tượng riêng biệt
+split(source="merged.zip", output_dir="split_classes/", by_class=True, overwrite=True)
+
+# 4. Ánh xạ và đổi tên lớp dữ liệu
+remap_classes(source="merged.zip", output="remapped.zip", class_map={0: 1, "apple": "red_apple"}, overwrite=True)
+
+# 5. Lấy thông tin chi tiết của bộ dữ liệu YOLO
+info = get_dataset_info("merged.zip")
+print(info)
+
+
+```
+
+Xem tài liệu đầy đủ tại docs/datasets/README.md.
+
+---
+
+### 3. File cấu hình (klygo.io as io)
+
+```python
+import klygo.io as io
+
+# Ghi file cấu hình
+config_data = {"learning_rate": 0.01, "epochs": 50}
+io.write_file("configs/train_params.toml", config_data, overwrite=True)
+
+# Đọc file cấu hình và truy cập bằng thuộc tính
+cfg = io.Config("configs/train_params.toml").imread()
+print(cfg.learning_rate)  # 0.01
+```
+
+Xem tài liệu đầy đủ tại docs/io/README.md.
+
+---
+
+### 4. Mô hình nhận diện (klygo.models.Kernel)
+
+```python
+from klygo.models import Kernel
+
+# Khởi tạo mô hình Grounding DINO
+kernel = Kernel()
+
+# Chạy nhận diện trên video và xuất ra bộ dữ liệu YOLO
+kernel.detect(
+    input_path="input_video.mp4",
+    prompt="car. traffic light.",
+    save_yolo_dir="dataset/"
+)
+```
+
+Xem tài liệu đầy đủ tại docs/models/README.md.
+
+---
+
+## Cài đặt
+
+```bash
+git clone https://github.com/your-username/klygo.git
+cd klygo
+uv sync
+```
+
+---
+
+## Tài liệu chi tiết
+
+Tất cả hướng dẫn đầy đủ đều được lưu tại thư mục docs:
+* Hướng dẫn nén & giải nén: docs/archive/README.md
+* Hướng dẫn xử lý bộ dữ liệu YOLO: docs/datasets/README.md
+* Hướng dẫn cấu hình & IO: docs/io/README.md
+* Hướng dẫn nhận diện vật thể: docs/models/README.md
+#   k l y g o

klygo-0.1.0/README.md

@@ -0,0 +1,131 @@
+# klygo
+
+Thư viện Python hỗ trợ nén/giải nén file, xử lý bộ dữ liệu YOLO, đọc/ghi file cấu hình và nhận diện vật thể zero-shot.
+
+---
+
+## Tính năng chính
+
+- klygo.archive: Các thao tác với file nén ZIP (nén, giải nén, tìm kiếm, gộp, chia, thêm, xóa file) hỗ trợ hiển thị thanh tiến trình.
+- klygo.datasets: Các công cụ quản lý và xử lý bộ dữ liệu YOLO (phân chia train/val/test, chia lại tỷ lệ tại chỗ, gộp nhiều dataset có ánh xạ lại class ID, và tách dataset theo class/tỷ lệ con).
+- klygo.io: Đọc và ghi các file cấu hình YAML, JSON, TOML, tự động tạo thư mục, tự động phân giải đường dẫn tương đối và truy cập dạng thuộc tính qua Box.
+- klygo.models: Lớp hỗ trợ nhận diện vật thể zero-shot (dựa trên Grounding DINO) trên ảnh và video, tự động xuất dữ liệu theo định dạng YOLO.
+
+---
+
+## Cấu trúc thư mục
+
+```
+klygo/
+├── archive/        # Các tiện ích nén và giải nén
+├── datasets/       # Công cụ quản lý và phân chia bộ dữ liệu YOLO
+├── io/             # Bộ đọc/ghi cấu hình YAML, JSON, TOML
+├── models/         # Lớp nhận diện vật thể (Kernel)
+└── validators/     # Bộ xác thực dữ liệu đầu vào
+```
+
+---
+
+## Hướng dẫn sử dụng nhanh
+
+### 1. Nén và giải nén (klygo.archive as ar)
+
+```python
+import klygo.archive as ar
+
+# Nén thư mục và giải nén
+ar.compress("src_directory/", "archive.zip")
+ar.extract("archive.zip", output="destination_dir/", overwrite=True)
+
+# Tìm kiếm file trong archive
+files = ar.search("archive.zip", "images/*.jpg")
+```
+
+Xem tài liệu đầy đủ tại docs/archive/README.md.
+
+---
+
+### 2. Quản lý bộ dữ liệu YOLO (klygo.datasets)
+
+```python
+from klygo.datasets import partition, repartition, merge, split, remap_classes, get_dataset_info
+
+# 1. Phân chia tập dữ liệu thô thành train/val/test
+partition(source="raw_data.zip", output="dataset/", ratios=(0.8,), overwrite=True)
+
+# 2. Hợp nhất hai bộ dữ liệu khác class tự động đổi class ID
+merge(sources=["data1/", "data2.zip"], output="merged.zip", overwrite=True)
+
+# 3. Tách nhỏ bộ dữ liệu theo từng class đối tượng riêng biệt
+split(source="merged.zip", output_dir="split_classes/", by_class=True, overwrite=True)
+
+# 4. Ánh xạ và đổi tên lớp dữ liệu
+remap_classes(source="merged.zip", output="remapped.zip", class_map={0: 1, "apple": "red_apple"}, overwrite=True)
+
+# 5. Lấy thông tin chi tiết của bộ dữ liệu YOLO
+info = get_dataset_info("merged.zip")
+print(info)
+
+
+```
+
+Xem tài liệu đầy đủ tại docs/datasets/README.md.
+
+---
+
+### 3. File cấu hình (klygo.io as io)
+
+```python
+import klygo.io as io
+
+# Ghi file cấu hình
+config_data = {"learning_rate": 0.01, "epochs": 50}
+io.write_file("configs/train_params.toml", config_data, overwrite=True)
+
+# Đọc file cấu hình và truy cập bằng thuộc tính
+cfg = io.Config("configs/train_params.toml").imread()
+print(cfg.learning_rate)  # 0.01
+```
+
+Xem tài liệu đầy đủ tại docs/io/README.md.
+
+---
+
+### 4. Mô hình nhận diện (klygo.models.Kernel)
+
+```python
+from klygo.models import Kernel
+
+# Khởi tạo mô hình Grounding DINO
+kernel = Kernel()
+
+# Chạy nhận diện trên video và xuất ra bộ dữ liệu YOLO
+kernel.detect(
+    input_path="input_video.mp4",
+    prompt="car. traffic light.",
+    save_yolo_dir="dataset/"
+)
+```
+
+Xem tài liệu đầy đủ tại docs/models/README.md.
+
+---
+
+## Cài đặt
+
+```bash
+git clone https://github.com/your-username/klygo.git
+cd klygo
+uv sync
+```
+
+---
+
+## Tài liệu chi tiết
+
+Tất cả hướng dẫn đầy đủ đều được lưu tại thư mục docs:
+* Hướng dẫn nén & giải nén: docs/archive/README.md
+* Hướng dẫn xử lý bộ dữ liệu YOLO: docs/datasets/README.md
+* Hướng dẫn cấu hình & IO: docs/io/README.md
+* Hướng dẫn nhận diện vật thể: docs/models/README.md
+#   k l y g o

klygo-0.1.0/klygo/__init__.py

@@ -0,0 +1,18 @@
+from . import archive
+from . import datasets
+from . import io
+from . import models
+from . import utils
+from . import validators
+
+__version__ = "1.0.1"
+__author__ = "IchigoMazone"
+
+__all__ = [
+    "archive",
+    "datasets",
+    "io",
+    "models",
+    "utils",
+    "validators",
+]

klygo-0.1.0/klygo/archive/__init__.py

@@ -0,0 +1,20 @@
+from .compress import compress
+from .extract import extract, extract_file
+from .list import list_files, search
+from .info import get_info, test
+from .modify import add, remove
+from .transform import merge, split
+
+__all__ = [
+    "compress",
+    "extract",
+    "extract_file",
+    "list_files",
+    "search",
+    "get_info",
+    "test",
+    "add",
+    "remove",
+    "merge",
+    "split",
+]

klygo-0.1.0/klygo/archive/_utils.py

@@ -0,0 +1,7 @@
+def _human_size(num_bytes: int) -> str:
+    """Return a human-readable file size string."""
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if num_bytes < 1024:
+            return f"{num_bytes:.1f} {unit}"
+        num_bytes //= 1024
+    return f"{num_bytes:.1f} PB"

klygo-0.1.0/klygo/archive/compress.py

@@ -0,0 +1,119 @@
+from zipfile import ZipFile, ZIP_DEFLATED
+from pathlib import Path
+
+from tqdm import tqdm
+
+from klygo.validators.archive import Compress
+from klygo.archive._utils import _human_size
+
+
+def compress(
+    source: str | Path,
+    output: str | Path,
+    format: str = "zip",
+    overwrite: bool = False,
+    verbose: bool = True,
+) -> None:
+    """Compress a file or directory into a ZIP archive.
+
+    When ``source`` is a directory, all files are added recursively
+    while preserving the internal directory structure. Parent-level
+    directory name is kept as the root inside the archive.
+
+    Parameters
+    ----------
+    source : str or Path
+        Path to the file or directory to compress.
+    output : str or Path
+        Destination path for the archive (e.g. ``"data.zip"``).
+        Parent directories are created automatically if they do not exist.
+    format : str, optional
+        Archive format. Currently only ``"zip"`` is supported.
+        Default is ``"zip"``.
+    overwrite : bool, optional
+        If *True*, silently overwrite ``output`` when it already exists.
+        If *False* (default) and ``output`` exists, raises ``FileExistsError``.
+    verbose : bool, optional
+        If *True* (default), display a coloured progress bar and print
+        the final archive size on completion.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    TypeError
+        If any argument has the wrong type.
+    FileNotFoundError
+        If ``source`` does not exist.
+    FileExistsError
+        If ``output`` already exists and ``overwrite`` is *False*.
+    ValueError
+        If ``format`` is not supported, or ``output`` has the wrong extension.
+
+    Examples
+    --------
+    Compress a single file:
+
+    >>> compress("report.csv", "report.zip")
+
+    Compress an entire directory, overwriting any existing archive:
+
+    >>> compress("my_dataset/", "dataset.zip", overwrite=True)
+
+    Compress silently (no progress bar):
+
+    >>> compress("images/", "images.zip", verbose=False)
+    """
+
+    params = Compress(
+        source=source,
+        output=output,
+        format=format,
+        overwrite=overwrite,
+        verbose=verbose,
+    )
+
+    source_path: Path = params.source
+    output_path: Path = params.output
+
+    # Collect all files to compress
+    if source_path.is_dir():
+        all_files: list[Path] = sorted(
+            f for f in source_path.rglob("*") if f.is_file()
+        )
+    else:
+        all_files = [source_path]
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with ZipFile(output_path, mode="w", compression=ZIP_DEFLATED) as zf:
+        bar = (
+            tqdm(
+                total=len(all_files) or 1,
+                desc="Compressing",
+                unit="file",
+                colour="green",
+                bar_format="{l_bar}{bar:30}{r_bar}",
+            )
+            if verbose
+            else None
+        )
+        for file in all_files:
+            arcname = (
+                file.relative_to(source_path.parent)
+                if source_path.is_dir()
+                else file.name
+            )
+            zf.write(file, arcname=arcname)
+            if bar is not None:
+                bar.update(1)
+        if bar is not None:
+            if not all_files:
+                bar.update(1)
+            bar.close()
+
+    if verbose:
+        total_size = output_path.stat().st_size
+        print(f"Done. Archive size: {_human_size(total_size)}")

klygo-0.1.0/klygo/archive/extract.py

@@ -0,0 +1,183 @@
+from zipfile import ZipFile
+from pathlib import Path
+
+from tqdm import tqdm
+
+from klygo.validators.archive import Extract, ExtractFile
+
+
+def extract(
+    source: str | Path,
+    output: str | Path = ".",
+    overwrite: bool = False,
+    verbose: bool = True,
+) -> None:
+    """Extract all contents of an archive to a directory.
+
+    The full directory structure stored inside the archive is
+    recreated under ``output``. The output directory is created
+    automatically if it does not exist.
+
+    Parameters
+    ----------
+    source : str or Path
+        Path to the archive file to extract (e.g. ``"data.zip"``).
+    output : str or Path, optional
+        Directory where the archive contents will be extracted.
+        Defaults to the current working directory (``"."``).
+    overwrite : bool, optional
+        If *True*, overwrite files that already exist in ``output``.
+        If *False* (default) and conflicting files exist, raises
+        ``FileExistsError`` listing the first offending names.
+    verbose : bool, optional
+        If *True* (default), display a coloured progress bar and print
+        the total number of extracted files on completion.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    TypeError
+        If any argument has the wrong type.
+    FileNotFoundError
+        If ``source`` does not exist.
+    ValueError
+        If ``source`` is not a supported archive format.
+    FileExistsError
+        If files in the archive already exist at the destination
+        and ``overwrite`` is *False*.
+
+    Examples
+    --------
+    Extract to a specific folder:
+
+    >>> extract("data.zip", output="data/")
+
+    Extract and overwrite any existing files:
+
+    >>> extract("data.zip", output="data/", overwrite=True)
+
+    Extract silently:
+
+    >>> extract("data.zip", output="data/", verbose=False)
+    """
+
+    params = Extract(
+        source=source,
+        output=output,
+        overwrite=overwrite,
+        verbose=verbose,
+    )
+
+    source_path: Path = params.source
+    output_path: Path = params.output
+
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    with ZipFile(source_path, mode="r") as zf:
+        members = zf.infolist()
+
+        if not overwrite:
+            existing = [
+                m for m in members
+                if (output_path / m.filename).exists()
+            ]
+            if existing:
+                names = ", ".join(m.filename for m in existing[:5])
+                suffix = f"… (+{len(existing) - 5} more)" if len(existing) > 5 else ""
+                raise FileExistsError(
+                    f"Files already exist in output directory: {names}{suffix}. "
+                    "Use overwrite=True to replace them."
+                )
+
+        iterator = (
+            tqdm(
+                members,
+                desc="Extracting",
+                unit="file",
+                colour="cyan",
+                bar_format="{l_bar}{bar:30}{r_bar}",
+            )
+            if verbose
+            else iter(members)
+        )
+
+        for member in iterator:
+            zf.extract(member, path=output_path)
+
+    if verbose:
+        print(f"Done. Extracted {len(members)} file(s) to '{output_path}'")
+
+
+def extract_file(
+    source: str | Path,
+    filename: str,
+    output: str | Path = ".",
+    overwrite: bool = False,
+) -> None:
+    """Extract a single file from an archive without unpacking everything.
+
+    Use :func:`list_files` to discover the exact ``filename`` string
+    as it is stored inside the archive, then pass that value here.
+
+    Parameters
+    ----------
+    source : str or Path
+        Path to the archive file.
+    filename : str
+        Path of the target file *inside* the archive, exactly as returned
+        by :func:`list_files` (e.g. ``"images/frame_001.jpg"``).
+    output : str or Path, optional
+        Directory where the file will be written.
+        Defaults to the current working directory (``"."``).
+    overwrite : bool, optional
+        If *True*, overwrite the file if it already exists at the destination.
+        Default is *False*.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    TypeError
+        If any argument has the wrong type.
+    FileNotFoundError
+        If ``source`` does not exist.
+    KeyError
+        If ``filename`` is not found inside the archive.
+    FileExistsError
+        If the destination file already exists and ``overwrite`` is *False*.
+
+    Examples
+    --------
+    >>> extract_file("data.zip", "images/frame_001.jpg", output="out/")
+    """
+
+    params = ExtractFile(
+        source=source,
+        filename=filename,
+        output=output,
+        overwrite=overwrite,
+    )
+
+    output_path: Path = params.output
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    with ZipFile(params.source, mode="r") as zf:
+        names = zf.namelist()
+        if params.filename not in names:
+            raise KeyError(
+                f"'{params.filename}' not found in archive. "
+                f"Use list_files() to see available files."
+            )
+
+        target = output_path / Path(params.filename).name
+        if target.exists() and not params.overwrite:
+            raise FileExistsError(
+                f"file already exists: {target}. Use overwrite=True."
+            )
+
+        zf.extract(params.filename, path=output_path)