folderops 0.1.0__py3-none-any.whl

folderops/__init__.py

@@ -0,0 +1,11 @@
+from .splitter import split_dataset
+from .merger import merge_folders
+from .organizer import organize_by_labels
+from .structure import create_structure
+
+__all__ = [
+    'split_dataset',
+    'merge_folders',
+    'organize_by_labels',
+    'create_structure',
+]

folderops/merger.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Sequence
+
+from .utils import ensure_directory, list_image_files, normalize_extensions, transfer_file, unique_destination_path, validate_operation
+
+
+def merge_folders(
+    folders: Sequence[str | Path],
+    output: str | Path,
+    mode: str = 'copy',
+    extensions: Sequence[str] | None = None,
+) -> list[Path]:
+    """Merge image files from multiple folders into a single output folder.
+
+    Args:
+        folders: Input directories containing images.
+        output: Destination directory.
+        mode: File transfer mode, either 'copy' or 'move'.
+        extensions: Iterable of allowed image extensions.
+
+    Returns:
+        A list of output file paths created in the merged directory.
+
+    Raises:
+        ValueError: If no folders are provided.
+        FileNotFoundError: If an input folder does not exist.
+    """
+    if not folders:
+        raise ValueError('folders must contain at least one directory.')
+
+    mode = validate_operation(mode)
+    normalize_extensions(extensions)
+    output_dir = ensure_directory(output)
+    merged_paths: list[Path] = []
+
+    for folder in folders:
+        for image_path in list_image_files(folder, extensions):
+            destination = unique_destination_path(output_dir, image_path.name)
+            merged_paths.append(transfer_file(image_path, destination, operation=mode))
+
+    return merged_paths

folderops/organizer.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+from typing import Sequence
+
+from .utils import ensure_directory, normalize_extensions, transfer_file, validate_directory, validate_file, validate_operation
+
+
+def organize_by_labels(
+    image_dir: str | Path,
+    label_file: str | Path,
+    output: str | Path,
+    mode: str = 'copy',
+    extensions: Sequence[str] | None = None,
+    delimiter: str = ',',
+) -> dict[str, list[Path]]:
+    """Organize images into class folders based on a CSV mapping file.
+
+    Args:
+        image_dir: Directory containing images.
+        label_file: CSV file with rows formatted as filename,label.
+        output: Directory where class folders will be created.
+        mode: File transfer mode, either 'copy' or 'move'.
+        extensions: Iterable of allowed image extensions.
+        delimiter: CSV delimiter used in the label file.
+
+    Returns:
+        A dictionary mapping class labels to transferred file paths.
+
+    Raises:
+        FileNotFoundError: If the image directory or label file does not exist.
+        ValueError: If rows are malformed or files are missing.
+    """
+    mode = validate_operation(mode)
+    allowed = set(normalize_extensions(extensions))
+    image_root = validate_directory(image_dir, 'Image directory')
+    labels_path = validate_file(label_file, 'Label file')
+    output_dir = ensure_directory(output)
+
+    organized: dict[str, list[Path]] = {}
+
+    with labels_path.open('r', encoding='utf-8', newline='') as handle:
+        reader = csv.reader(handle, delimiter=delimiter)
+        for row_number, row in enumerate(reader, start=1):
+            if not row:
+                continue
+            if len(row) < 2:
+                raise ValueError(f'Malformed row {row_number} in label file: expected filename and label.')
+            filename = row[0].strip()
+            label = row[1].strip()
+            if not filename or not label:
+                raise ValueError(f'Row {row_number} contains an empty filename or label.')
+
+            image_path = image_root / filename
+            if not image_path.exists() or not image_path.is_file():
+                raise FileNotFoundError(f'Image listed in label file not found: {image_path}')
+            if image_path.suffix.lower() not in allowed:
+                raise ValueError(f'Unsupported file extension for image: {image_path.name}')
+
+            class_dir = ensure_directory(output_dir / label)
+            destination = class_dir / image_path.name
+            organized.setdefault(label, []).append(transfer_file(image_path, destination, operation=mode))
+
+    return organized

folderops/splitter.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import random
+from pathlib import Path
+from typing import Sequence
+
+from .utils import ensure_directory, normalize_extensions, transfer_file, validate_operation
+
+
+def split_dataset(
+    source: str | Path,
+    output: str | Path,
+    train_ratio: float = 0.7,
+    val_ratio: float = 0.15,
+    test_ratio: float = 0.15,
+    seed: int | None = 42,
+    mode: str = "copy",
+    extensions: Sequence[str] | None = None,
+) -> dict[str, dict[str, list[Path]]]:
+    mode = validate_operation(mode)
+    extensions = normalize_extensions(extensions)
+
+    total_ratio = train_ratio + val_ratio + test_ratio
+    if any(r < 0 for r in (train_ratio, val_ratio, test_ratio)):
+        raise ValueError("Split ratios must be non-negative.")
+    if abs(total_ratio - 1.0) > 1e-9:
+        raise ValueError("train_ratio, val_ratio, and test_ratio must sum to 1.0.")
+
+    source_path = Path(source)
+    if not source_path.exists():
+        raise FileNotFoundError(f"Source directory not found: {source}")
+
+    class_dirs = [d for d in source_path.iterdir() if d.is_dir()]
+    if not class_dirs:
+        raise ValueError("No class folders found inside source directory.")
+
+    rng = random.Random(seed)
+
+    output_path = ensure_directory(output)
+
+    result: dict[str, dict[str, list[Path]]] = {
+        "train": {},
+        "val": {},
+        "test": {},
+    }
+
+    for class_dir in class_dirs:
+        class_name = class_dir.name
+
+        images = [
+            p for p in class_dir.iterdir()
+            if p.is_file() and (extensions is None or p.suffix.lower() in extensions)
+        ]
+
+        if not images:
+            continue
+
+        rng.shuffle(images)
+
+        total = len(images)
+        train_end = int(total * train_ratio)
+        val_end = train_end + int(total * val_ratio)
+
+        split_map = {
+            "train": images[:train_end],
+            "val": images[train_end:val_end],
+            "test": images[val_end:],
+        }
+
+        for split_name, files in split_map.items():
+            split_class_dir = ensure_directory(output_path / split_name / class_name)
+
+            result[split_name][class_name] = []
+
+            for file_path in files:
+                destination = split_class_dir / file_path.name
+                transferred = transfer_file(file_path, destination, operation=mode)
+                result[split_name][class_name].append(transferred)
+
+    return result

folderops/structure.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .utils import ensure_directory, iter_structure_paths
+
+
+def create_structure(structure: dict, root: str | Path | None = None) -> list[Path]:
+    """Create nested directories from a dictionary template.
+
+    Args:
+        structure: Nested dictionary describing folder names.
+        root: Optional base directory under which the structure is created.
+
+    Returns:
+        A list of created or ensured directory paths.
+
+    Raises:
+        TypeError: If the structure is not a valid nested dictionary.
+        ValueError: If any folder name is invalid.
+    """
+    base = Path(root) if root is not None else Path()
+    created_paths: list[Path] = []
+    for relative_path in iter_structure_paths(structure):
+        directory = ensure_directory(base / relative_path)
+        created_paths.append(directory)
+    return created_paths

folderops/utils.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from pathlib import Path
+from shutil import copy2, move
+from typing import Iterable, Sequence, Tuple
+
+DEFAULT_IMAGE_EXTENSIONS: Tuple[str, ...] = ('.jpg', '.jpeg', '.png', '.bmp', '.gif', '.tif', '.tiff', '.webp')
+
+
+def normalize_extensions(extensions: Sequence[str] | None) -> Tuple[str, ...]:
+    if extensions is None:
+        return DEFAULT_IMAGE_EXTENSIONS
+    normalized = []
+    for ext in extensions:
+        if not ext:
+            continue
+        ext = ext.lower().strip()
+        if not ext.startswith('.'):
+            ext = f'.{ext}'
+        normalized.append(ext)
+    if not normalized:
+        raise ValueError('At least one valid file extension must be provided.')
+    return tuple(dict.fromkeys(normalized))
+
+
+def ensure_directory(path: str | Path) -> Path:
+    directory = Path(path)
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def validate_directory(path: str | Path, name: str) -> Path:
+    directory = Path(path)
+    if not directory.exists():
+        raise FileNotFoundError(f'{name} does not exist: {directory}')
+    if not directory.is_dir():
+        raise NotADirectoryError(f'{name} is not a directory: {directory}')
+    return directory
+
+
+def validate_file(path: str | Path, name: str) -> Path:
+    file_path = Path(path)
+    if not file_path.exists():
+        raise FileNotFoundError(f'{name} does not exist: {file_path}')
+    if not file_path.is_file():
+        raise FileNotFoundError(f'{name} is not a file: {file_path}')
+    return file_path
+
+
+def list_image_files(directory: str | Path, extensions: Sequence[str] | None = None) -> list[Path]:
+    folder = validate_directory(directory, 'Source directory')
+    allowed = set(normalize_extensions(extensions))
+    return sorted([path for path in folder.iterdir() if path.is_file() and path.suffix.lower() in allowed])
+
+
+def unique_destination_path(output_dir: str | Path, filename: str) -> Path:
+    output_path = ensure_directory(output_dir)
+    destination = output_path / filename
+    if not destination.exists():
+        return destination
+    stem = destination.stem
+    suffix = destination.suffix
+    counter = 1
+    while True:
+        candidate = output_path / f'{stem}_{counter}{suffix}'
+        if not candidate.exists():
+            return candidate
+        counter += 1
+
+
+def transfer_file(source: str | Path, destination: str | Path, operation: str = 'copy') -> Path:
+    src = Path(source)
+    dst = Path(destination)
+    ensure_directory(dst.parent)
+    if operation == 'copy':
+        copy2(src, dst)
+    elif operation == 'move':
+        move(str(src), str(dst))
+    else:
+        raise ValueError("operation must be either 'copy' or 'move'.")
+    return dst
+
+
+def validate_operation(operation: str) -> str:
+    normalized = operation.lower().strip()
+    if normalized not in {'copy', 'move'}:
+        raise ValueError("mode must be either 'copy' or 'move'.")
+    return normalized
+
+
+def iter_structure_paths(structure: dict, parent: Path | None = None) -> Iterable[Path]:
+    if not isinstance(structure, dict):
+        raise TypeError('structure must be a dictionary.')
+    parent = parent or Path()
+    for name, subtree in structure.items():
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError('Every folder name must be a non-empty string.')
+        current = parent / name
+        yield current
+        if subtree is None:
+            continue
+        if not isinstance(subtree, dict):
+            raise TypeError('Nested structure values must be dictionaries or empty dictionaries.')
+        yield from iter_structure_paths(subtree, current)

folderops-0.1.0.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: folderops
+Version: 0.1.0
+Summary: Python utilities for dataset organization and preprocessing
+Author: Ahamed
+License: MIT
+Keywords: dataset,images,ml,data-preprocessing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# folderops
+
+`folderops` is a lightweight Python package for common dataset organization tasks in machine learning workflows. It is designed for direct use inside notebooks, research code, and training scripts through clean Python imports.
+
+## Features
+
+- Split image datasets into train, validation, and test folders
+- Merge multiple image folders into a single directory
+- Organize images into class folders using a CSV label file
+- Create nested folder structures from Python dictionaries
+- Support common image formats such as `.jpg`, `.jpeg`, `.png`, `.bmp`, `.gif`, `.tif`, `.tiff`, and `.webp`
+
+## Installation
+
+```bash
+pip install folderops
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from folderops import split_dataset, merge_folders, organize_by_labels, create_structure
+
+split_dataset(
+    source="images",
+    output="dataset",
+    train_ratio=0.7,
+    val_ratio=0.15,
+    test_ratio=0.15,
+    seed=42,
+)
+
+merge_folders(
+    folders=["dataset1/images", "dataset2/images", "dataset3/images"],
+    output="merged_images",
+)
+
+organize_by_labels(
+    image_dir="images",
+    label_file="labels.csv",
+    output="organized_dataset",
+)
+
+structure = {
+    "dataset": {
+        "train": {},
+        "val": {},
+        "test": {}
+    }
+}
+create_structure(structure)
+```
+
+## Public API
+
+### `split_dataset`
+
+Split images from one folder into `train`, `val`, and `test` subdirectories.
+
+```python
+split_dataset(
+    source="images",
+    output="dataset",
+    train_ratio=0.7,
+    val_ratio=0.15,
+    test_ratio=0.15,
+    seed=42,
+    mode="copy",
+    extensions=(".jpg", ".png"),
+)
+```
+
+Key behavior:
+
+- Shuffles files before splitting
+- Supports deterministic splits with a random seed
+- Supports `copy` and `move` modes
+- Validates that split ratios sum to `1.0`
+
+### `merge_folders`
+
+Merge images from multiple folders into one output directory.
+
+```python
+merge_folders(
+    folders=["dataset1/images", "dataset2/images"],
+    output="merged_images",
+    mode="copy",
+)
+```
+
+Key behavior:
+
+- Avoids overwriting duplicate filenames
+- Automatically renames duplicates like `image_1.jpg`, `image_2.jpg`
+- Supports `copy` and `move` modes
+
+### `organize_by_labels`
+
+Organize images into class folders using a CSV file with `filename,label` rows.
+
+Example `labels.csv`:
+
+```csv
+img1.jpg,cat
+img2.jpg,dog
+img3.jpg,cat
+```
+
+Usage:
+
+```python
+organize_by_labels(
+    image_dir="images",
+    label_file="labels.csv",
+    output="organized_dataset",
+    mode="copy",
+)
+```
+
+Key behavior:
+
+- Creates class folders automatically
+- Validates image existence before transfer
+- Supports configurable CSV delimiter
+
+### `create_structure`
+
+Create nested directories recursively from a dictionary.
+
+```python
+structure = {
+    "dataset": {
+        "train": {},
+        "val": {},
+        "test": {}
+    }
+}
+
+create_structure(structure)
+create_structure(structure, root="project_data")
+```
+
+## Project Layout
+
+```text
+folderops/
+├── folderops/
+│   ├── __init__.py
+│   ├── merger.py
+│   ├── organizer.py
+│   ├── splitter.py
+│   ├── structure.py
+│   └── utils.py
+├── LICENSE
+├── pyproject.toml
+└── README.md
+```
+
+## Build and Publish
+
+Build the package:
+
+```bash
+python -m build
+```
+
+Upload to PyPI:
+
+```bash
+twine upload dist/*
+```
+
+## Development Notes
+
+- Python 3.8+
+- No CLI dependency
+- Intended for import-based use only
+- Uses standard library modules only
+
+## License
+
+MIT License

folderops-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+folderops/__init__.py,sha256=sSC4uuEB5goTK1-MtugUA6om9cQlueQsQwy6GeeTlSo,259
+folderops/merger.py,sha256=zCtVb4o9Q9nKLnVYnRqFyNgHsjXhpr60it6Vw6w-3Uk,1430
+folderops/organizer.py,sha256=9LjiRjLzx_XTkejaxUcSYEXJA879j-9tqfZ0sgbBg9U,2624
+folderops/splitter.py,sha256=GBEnRakb2_6oodNOEFrphfP6sn757drket2IBx3uAZ8,2422
+folderops/structure.py,sha256=iYNmAJlg3qRXKyGAVFrnTtvhvEG6mXKbHY_-YVoGHn8,898
+folderops/utils.py,sha256=oClFh9mCAUXERuQ5glLa5SQk0r3t05kefQ53ssQOuSA,3648
+folderops-0.1.0.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+folderops-0.1.0.dist-info/METADATA,sha256=N3zXoGHSr6kPtR5OashQJqKG4tIp7rPlNQMosc2zU1k,3994
+folderops-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+folderops-0.1.0.dist-info/top_level.txt,sha256=ar3RNZQUoTwOQJeILal6d35805Iy5Gn2wGvpZxqhY7g,10
+folderops-0.1.0.dist-info/RECORD,,

folderops-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

folderops-0.1.0.dist-info/licenses/LICENSE

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

folderops-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+folderops