klygo 0.1.0__py3-none-any.whl

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/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/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/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/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)

klygo/archive/info.py

@@ -0,0 +1,125 @@
+from zipfile import ZipFile
+from pathlib import Path
+
+from klygo.validators.archive import GetInfo, Test
+
+
+def get_info(
+    source: str | Path,
+) -> dict:
+    """Return a metadata summary of an archive.
+
+    Reads all member headers in the ZIP central directory — no
+    decompression is performed, so this is fast even for very large archives.
+
+    Parameters
+    ----------
+    source : str or Path
+        Path to the archive file.
+
+    Returns
+    -------
+    dict
+        A dictionary with the following keys:
+
+        * ``"path"`` (*str*) — absolute path to the archive.
+        * ``"format"`` (*str*) — archive format, e.g. ``"zip"``.
+        * ``"file_count"`` (*int*) — number of files inside the archive.
+        * ``"uncompressed_size"`` (*int*) — total size of all files before
+          compression, in bytes.
+        * ``"compressed_size"`` (*int*) — total size of all files after
+          compression, in bytes.
+        * ``"compress_ratio"`` (*float*) — space saved by compression,
+          expressed as a percentage (0–100). A value of ``0.0`` means
+          no compression was applied.
+        * ``"archive_size"`` (*int*) — actual size of the ``.zip`` file
+          on disk (includes ZIP metadata overhead).
+
+    Raises
+    ------
+    TypeError
+        If ``source`` is not a ``str`` or ``Path``.
+    FileNotFoundError
+        If ``source`` does not exist.
+    ValueError
+        If ``source`` is not a supported archive format.
+
+    Examples
+    --------
+    >>> info = get_info("data.zip")
+    >>> print(info["file_count"], info["compress_ratio"])
+    723 0.64
+    """
+
+    params = GetInfo(source=source)
+
+    with ZipFile(params.source, mode="r") as zf:
+        members = zf.infolist()
+        total_uncompressed = sum(m.file_size for m in members)
+        total_compressed = sum(m.compress_size for m in members)
+
+    ratio = (
+        round((1 - total_compressed / total_uncompressed) * 100, 2)
+        if total_uncompressed > 0
+        else 0.0
+    )
+
+    return {
+        "path": str(params.source),
+        "format": params.source.suffix.lstrip("."),
+        "file_count": len(members),
+        "uncompressed_size": total_uncompressed,
+        "compressed_size": total_compressed,
+        "compress_ratio": ratio,
+        "archive_size": params.source.stat().st_size,
+    }
+
+
+def test(
+    source: str | Path,
+) -> bool:
+    """Verify the integrity of an archive using CRC checksum validation.
+
+    Each file inside the archive is read and its CRC32 checksum is compared
+    against the value stored in the ZIP header. This catches bit-rot,
+    partial downloads, and corrupted archives.
+
+    Parameters
+    ----------
+    source : str or Path
+        Path to the archive file to test.
+
+    Returns
+    -------
+    bool
+        *True* if every file in the archive passes its CRC check.
+
+    Raises
+    ------
+    TypeError
+        If ``source`` is not a ``str`` or ``Path``.
+    FileNotFoundError
+        If ``source`` does not exist.
+    ValueError
+        If ``source`` is not a supported archive format, or if the
+        archive is corrupted. The error message includes the name of
+        the first file that failed the checksum.
+
+    Examples
+    --------
+    >>> ok = test("data.zip")
+    >>> print(ok)
+    True
+    """
+
+    params = Test(source=source)
+
+    with ZipFile(params.source, mode="r") as zf:
+        bad_file = zf.testzip()
+
+    if bad_file is not None:
+        raise ValueError(
+            f"archive is corrupted. First bad file: '{bad_file}'"
+        )
+
+    return True

klygo/archive/list.py

@@ -0,0 +1,108 @@
+from zipfile import ZipFile
+from pathlib import Path
+import fnmatch
+
+from klygo.validators.archive import ListFiles, Search
+
+
+def list_files(
+    source: str | Path,
+) -> list[str]:
+    """Return a list of all file paths stored inside an archive.
+
+    The returned strings are the *arcnames* — the paths as they are
+    stored inside the ZIP (e.g. ``"images/frame_001.jpg"``). These
+    values can be passed directly to :func:`extract_file`, :func:`remove`,
+    and :func:`search`.
+
+    Parameters
+    ----------
+    source : str or Path
+        Path to the archive file (e.g. ``"data.zip"``).
+
+    Returns
+    -------
+    list[str]
+        Ordered list of file paths as stored inside the archive.
+
+    Raises
+    ------
+    TypeError
+        If ``source`` is not a ``str`` or ``Path``.
+    FileNotFoundError
+        If ``source`` does not exist.
+    ValueError
+        If ``source`` is not a supported archive format.
+
+    Examples
+    --------
+    >>> files = list_files("data.zip")
+    >>> print(files[:3])
+    ['images/frame_0.jpg', 'images/frame_1.jpg', 'data.yaml']
+    """
+
+    params = ListFiles(source=source)
+
+    with ZipFile(params.source, mode="r") as zf:
+        names = zf.namelist()
+
+    return names
+
+
+def search(
+    source: str | Path,
+    pattern: str,
+) -> list[str]:
+    """Find files inside an archive whose paths match a glob pattern.
+
+    Matching is performed with :func:`fnmatch.fnmatch` against each
+    arcname stored in the archive. The search is case-sensitive on
+    case-sensitive filesystems.
+
+    Parameters
+    ----------
+    source : str or Path
+        Path to the archive file.
+    pattern : str
+        Glob pattern to match against file paths inside the archive.
+        Supports the standard wildcards:
+
+        * ``*``  — matches any sequence of characters (not ``/``).
+        * ``?``  — matches any single character.
+        * ``[seq]`` — matches any character in *seq*.
+
+        Example: ``"images/*.jpg"`` matches all JPEG files under the
+        ``images/`` folder.
+
+    Returns
+    -------
+    list[str]
+        Arcnames of the files that matched ``pattern``, in the order
+        they appear inside the archive. Returns an empty list if
+        nothing matches.
+
+    Raises
+    ------
+    TypeError
+        If ``source`` or ``pattern`` has the wrong type.
+    FileNotFoundError
+        If ``source`` does not exist.
+    ValueError
+        If ``source`` is not a supported archive format.
+
+    Examples
+    --------
+    >>> results = search("data.zip", "images/frame_1*.jpg")
+    >>> print(len(results))
+    111
+
+    >>> search("data.zip", "*.yaml")
+    ['data.yaml']
+    """
+
+    params = Search(source=source, pattern=pattern)
+
+    with ZipFile(params.source, mode="r") as zf:
+        names = zf.namelist()
+
+    return [name for name in names if fnmatch.fnmatch(name, params.pattern)]