devbits 0.1.0__py3-none-any.whl

devbits/__init__.py

@@ -0,0 +1,3 @@
+"""devbits: A lightweight CLI toolkit for daily development utilities."""
+
+__version__ = "0.1.0"

devbits/cache.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+CACHE_DIR_NAMES = {"__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache"}
+PYC_PATTERNS = ["*.pyc", "*.pyo"]
+
+
+def clear_cache(root: Path, include_extra: bool = False, dry_run: bool = False) -> list[Path]:
+    targets: list[Path] = []
+    dir_names = set(CACHE_DIR_NAMES if include_extra else {"__pycache__"})
+
+    for path in root.rglob("*"):
+        if path.is_dir() and path.name in dir_names:
+            targets.append(path)
+
+    for pattern in PYC_PATTERNS:
+        targets.extend(root.rglob(pattern))
+
+    unique_targets = sorted(set(targets), key=lambda p: len(p.parts), reverse=True)
+    if dry_run:
+        return unique_targets
+
+    for target in unique_targets:
+        if not target.exists():
+            continue
+        if target.is_dir():
+            shutil.rmtree(target)
+        else:
+            target.unlink()
+    return unique_targets

devbits/cli.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .cache import clear_cache
+from .image import batch_images, check_images, contact_sheet, image_to_ico, resize_image
+from .media import clip_video, images_to_gif, images_to_video, resize_video, video_to_gif, video_to_images
+from .project import print_tree, rename_files, sample_files, top_sizes
+from .utils import ensure_exists
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="devbits", description="Daily development utility CLI toolkit.")
+    parser.add_argument("--version", action="version", version="devbits 0.1.0")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("clearcache", help="Clear Python cache files under a folder.")
+    p.add_argument("folder", type=Path)
+    p.add_argument("--all", action="store_true", help="Also remove pytest, mypy, and ruff caches.")
+    p.add_argument("--dry-run", action="store_true")
+    p.set_defaults(func=cmd_clearcache)
+
+    p = sub.add_parser("images2video", help="Convert image sequence to MP4 video.")
+    p.add_argument("folder", type=Path)
+    p.add_argument("-o", "--output", type=Path, default=Path("output.mp4"))
+    p.add_argument("--fps", type=float, default=30.0)
+    p.add_argument("--pattern", default="*")
+    p.set_defaults(func=cmd_images2video)
+
+    p = sub.add_parser("video2images", help="Extract frames from a video.")
+    p.add_argument("video", type=Path)
+    p.add_argument("-o", "--output", type=Path, default=Path("frames"))
+    p.add_argument("--every", type=int, default=1)
+    p.add_argument("--prefix", default="frame")
+    p.add_argument("--digits", type=int, default=6)
+    p.add_argument("--format", default="jpg")
+    p.set_defaults(func=cmd_video2images)
+
+    p = sub.add_parser("images2gif", help="Convert image sequence to GIF.")
+    p.add_argument("folder", type=Path)
+    p.add_argument("-o", "--output", type=Path, default=Path("output.gif"))
+    p.add_argument("--fps", type=float, default=10.0)
+    p.add_argument("--pattern", default="*")
+    p.set_defaults(func=cmd_images2gif)
+
+    p = sub.add_parser("video2gif", help="Convert video to GIF.")
+    p.add_argument("video", type=Path)
+    p.add_argument("-o", "--output", type=Path, default=Path("output.gif"))
+    p.add_argument("--fps", type=float, default=10.0)
+    p.add_argument("--start", type=float)
+    p.add_argument("--end", type=float)
+    p.add_argument("--size", help="Output size, e.g. 640,360")
+    p.set_defaults(func=cmd_video2gif)
+
+    p = sub.add_parser("clipvideo", help="Clip video by seconds or frame indices.")
+    p.add_argument("video", type=Path)
+    p.add_argument("-o", "--output", type=Path, default=Path("clip.mp4"))
+    p.add_argument("--start", type=float)
+    p.add_argument("--end", type=float)
+    p.add_argument("--start-frame", type=int)
+    p.add_argument("--end-frame", type=int)
+    p.add_argument("--gui", action="store_true", help="Reserved for future GUI clip selection.")
+    p.set_defaults(func=cmd_clipvideo)
+
+    p = sub.add_parser("resizevideo", help="Resize a video.")
+    p.add_argument("video", type=Path)
+    p.add_argument("-o", "--output", type=Path, default=Path("resized.mp4"))
+    p.add_argument("--size", required=True, help="Output size, e.g. 1280,720")
+    p.set_defaults(func=cmd_resizevideo)
+
+    p = sub.add_parser("image2ico", help="Convert an image to ICO.")
+    p.add_argument("image", type=Path)
+    p.add_argument("-o", "--output", type=Path, default=Path("image.ico"))
+    p.add_argument("--sizes", default="16,32,48,64,128,256")
+    p.set_defaults(func=cmd_image2ico)
+
+    p = sub.add_parser("resizeimage", help="Resize an image.")
+    p.add_argument("image", type=Path)
+    p.add_argument("-o", "--output", type=Path, default=Path("resized.jpg"))
+    p.add_argument("--size", required=True)
+    p.add_argument("--no-keep-ratio", action="store_true")
+    p.set_defaults(func=cmd_resizeimage)
+
+    p = sub.add_parser("batchimages", help="Batch resize or convert images.")
+    p.add_argument("folder", type=Path)
+    p.add_argument("-o", "--output", type=Path, required=True)
+    p.add_argument("--size")
+    p.add_argument("--format")
+    p.set_defaults(func=cmd_batchimages)
+
+    p = sub.add_parser("checkimages", help="Check broken image files.")
+    p.add_argument("folder", type=Path)
+    p.add_argument("--recursive", action="store_true")
+    p.add_argument("--remove-broken", action="store_true")
+    p.set_defaults(func=cmd_checkimages)
+
+    p = sub.add_parser("contactsheet", help="Create a contact sheet from images.")
+    p.add_argument("folder", type=Path)
+    p.add_argument("-o", "--output", type=Path, default=Path("sheet.jpg"))
+    p.add_argument("--cols", type=int, default=5)
+    p.add_argument("--thumb-size", default="256,256")
+    p.add_argument("--labels", action="store_true")
+    p.set_defaults(func=cmd_contactsheet)
+
+    p = sub.add_parser("tree", help="Print project tree.")
+    p.add_argument("folder", type=Path, nargs="?", default=Path("."))
+    p.add_argument("--depth", type=int, default=3)
+    p.set_defaults(func=cmd_tree)
+
+    p = sub.add_parser("size", help="Show top-level folder sizes.")
+    p.add_argument("folder", type=Path, nargs="?", default=Path("."))
+    p.add_argument("--top", type=int, default=20)
+    p.set_defaults(func=cmd_size)
+
+    p = sub.add_parser("renamefiles", help="Batch rename files in a folder.")
+    p.add_argument("folder", type=Path)
+    p.add_argument("--prefix", default="file")
+    p.add_argument("--digits", type=int, default=6)
+    p.add_argument("--start", type=int, default=1)
+    p.add_argument("--dry-run", action="store_true")
+    p.set_defaults(func=cmd_renamefiles)
+
+    p = sub.add_parser("samplefiles", help="Copy first N files into another folder.")
+    p.add_argument("folder", type=Path)
+    p.add_argument("-o", "--output", type=Path, required=True)
+    p.add_argument("--num", type=int, required=True)
+    p.add_argument("--move", action="store_true")
+    p.set_defaults(func=cmd_samplefiles)
+    return parser
+
+
+def cmd_clearcache(args: argparse.Namespace) -> None:
+    targets = clear_cache(ensure_exists(args.folder), include_extra=args.all, dry_run=args.dry_run)
+    for target in targets:
+        print(target)
+    print(f"{'Found' if args.dry_run else 'Removed'} {len(targets)} cache item(s).")
+
+
+def cmd_images2video(args: argparse.Namespace) -> None:
+    print(images_to_video(ensure_exists(args.folder), args.output, args.fps, args.pattern))
+
+
+def cmd_video2images(args: argparse.Namespace) -> None:
+    outputs = video_to_images(ensure_exists(args.video), args.output, args.every, args.prefix, args.digits, args.format)
+    print(f"Saved {len(outputs)} frame(s) to {args.output}")
+
+
+def cmd_images2gif(args: argparse.Namespace) -> None:
+    print(images_to_gif(ensure_exists(args.folder), args.output, args.fps, args.pattern))
+
+
+def cmd_video2gif(args: argparse.Namespace) -> None:
+    print(video_to_gif(ensure_exists(args.video), args.output, args.fps, args.start, args.end, args.size))
+
+
+def cmd_clipvideo(args: argparse.Namespace) -> None:
+    if args.gui:
+        print("Warning: --gui is reserved for a future interactive clip selector; using CLI options now.")
+    print(clip_video(ensure_exists(args.video), args.output, args.start, args.end, args.start_frame, args.end_frame))
+
+
+def cmd_resizevideo(args: argparse.Namespace) -> None:
+    print(resize_video(ensure_exists(args.video), args.output, args.size))
+
+
+def cmd_image2ico(args: argparse.Namespace) -> None:
+    print(image_to_ico(ensure_exists(args.image), args.output, args.sizes))
+
+
+def cmd_resizeimage(args: argparse.Namespace) -> None:
+    print(resize_image(ensure_exists(args.image), args.output, args.size, not args.no_keep_ratio))
+
+
+def cmd_batchimages(args: argparse.Namespace) -> None:
+    outputs = batch_images(ensure_exists(args.folder), args.output, args.size, args.format)
+    print(f"Saved {len(outputs)} image(s) to {args.output}")
+
+
+def cmd_checkimages(args: argparse.Namespace) -> None:
+    broken = check_images(ensure_exists(args.folder), args.recursive, args.remove_broken)
+    if broken:
+        print("Broken images:")
+        for path in broken:
+            print(path)
+    print(f"Found {len(broken)} broken image(s).")
+
+
+def cmd_contactsheet(args: argparse.Namespace) -> None:
+    print(contact_sheet(ensure_exists(args.folder), args.output, args.cols, args.thumb_size, labels=args.labels))
+
+
+def cmd_tree(args: argparse.Namespace) -> None:
+    for line in print_tree(ensure_exists(args.folder), args.depth):
+        print(line)
+
+
+def cmd_size(args: argparse.Namespace) -> None:
+    for path, _, size_text in top_sizes(ensure_exists(args.folder), args.top):
+        print(f"{size_text:>10}  {path}")
+
+
+def cmd_renamefiles(args: argparse.Namespace) -> None:
+    mappings = rename_files(ensure_exists(args.folder), args.prefix, args.digits, args.start, args.dry_run)
+    for old, new in mappings:
+        print(f"{old.name} -> {new.name}")
+    print(f"{'Planned' if args.dry_run else 'Renamed'} {len(mappings)} file(s).")
+
+
+def cmd_samplefiles(args: argparse.Namespace) -> None:
+    outputs = sample_files(ensure_exists(args.folder), args.output, args.num, copy=not args.move)
+    print(f"Saved {len(outputs)} file(s) to {args.output}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        args.func(args)
+    except Exception as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devbits/image.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageOps, UnidentifiedImageError
+
+from .utils import ensure_dir, list_images, parse_size
+
+
+def image_to_ico(input_path: Path, output_path: Path, sizes: str = "16,32,48,64,128,256") -> Path:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    size_values = [int(item.strip()) for item in sizes.split(",") if item.strip()]
+    ico_sizes = [(size, size) for size in size_values]
+    with Image.open(input_path) as image:
+        image = image.convert("RGBA")
+        image.save(output_path, format="ICO", sizes=ico_sizes)
+    return output_path
+
+
+def contact_sheet(
+    folder: Path,
+    output_path: Path,
+    cols: int = 5,
+    thumb_size: str = "256,256",
+    pattern: str = "*",
+    labels: bool = False,
+) -> Path:
+    images = list_images(folder, pattern=pattern)
+    if not images:
+        raise ValueError(f"No images found in {folder}")
+
+    thumb_w, thumb_h = parse_size(thumb_size)
+    label_h = 24 if labels else 0
+    rows = (len(images) + cols - 1) // cols
+    sheet = Image.new("RGB", (cols * thumb_w, rows * (thumb_h + label_h)), "white")
+    draw = ImageDraw.Draw(sheet)
+
+    for index, image_path in enumerate(images):
+        row, col = divmod(index, cols)
+        x = col * thumb_w
+        y = row * (thumb_h + label_h)
+        try:
+            with Image.open(image_path) as image:
+                thumb = ImageOps.contain(image.convert("RGB"), (thumb_w, thumb_h))
+        except UnidentifiedImageError:
+            continue
+        paste_x = x + (thumb_w - thumb.width) // 2
+        paste_y = y + (thumb_h - thumb.height) // 2
+        sheet.paste(thumb, (paste_x, paste_y))
+        if labels:
+            draw.text((x + 4, y + thumb_h + 4), image_path.name[:40], fill="black")
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    sheet.save(output_path)
+    return output_path
+
+
+def check_images(folder: Path, recursive: bool = False, remove_broken: bool = False) -> list[Path]:
+    broken: list[Path] = []
+    for image_path in list_images(folder, recursive=recursive):
+        try:
+            with Image.open(image_path) as image:
+                image.verify()
+        except Exception:
+            broken.append(image_path)
+            if remove_broken:
+                image_path.unlink(missing_ok=True)
+    return broken
+
+
+def resize_image(input_path: Path, output_path: Path, size: str, keep_ratio: bool = True) -> Path:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    target_size = parse_size(size)
+    with Image.open(input_path) as image:
+        image = image.convert("RGB")
+        if keep_ratio:
+            image = ImageOps.contain(image, target_size)
+        else:
+            image = image.resize(target_size)
+        image.save(output_path)
+    return output_path
+
+
+def batch_images(folder: Path, output_folder: Path, size: str | None = None, fmt: str | None = None) -> list[Path]:
+    ensure_dir(output_folder)
+    outputs: list[Path] = []
+    for image_path in list_images(folder):
+        with Image.open(image_path) as image:
+            image = image.convert("RGB")
+            if size:
+                image = ImageOps.contain(image, parse_size(size))
+            suffix = f".{fmt.lower()}" if fmt else image_path.suffix
+            out = output_folder / f"{image_path.stem}{suffix}"
+            image.save(out)
+            outputs.append(out)
+    return outputs

devbits/media.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import cv2
+from PIL import Image
+
+from .utils import ensure_dir, list_images, parse_size
+
+
+def images_to_video(folder: Path, output_path: Path, fps: float = 30.0, pattern: str = "*") -> Path:
+    images = list_images(folder, pattern=pattern)
+    if not images:
+        raise ValueError(f"No images found in {folder}")
+
+    first = cv2.imread(str(images[0]))
+    if first is None:
+        raise ValueError(f"Cannot read image: {images[0]}")
+    height, width = first.shape[:2]
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    writer = cv2.VideoWriter(str(output_path), cv2.VideoWriter_fourcc(*"mp4v"), fps, (width, height))
+    if not writer.isOpened():
+        raise RuntimeError(f"Cannot create video writer: {output_path}")
+
+    try:
+        for image_path in images:
+            frame = cv2.imread(str(image_path))
+            if frame is None:
+                continue
+            if frame.shape[:2] != (height, width):
+                frame = cv2.resize(frame, (width, height))
+            writer.write(frame)
+    finally:
+        writer.release()
+    return output_path
+
+
+def video_to_images(
+    video_path: Path,
+    output_folder: Path,
+    every: int = 1,
+    prefix: str = "frame",
+    digits: int = 6,
+    fmt: str = "jpg",
+) -> list[Path]:
+    ensure_dir(output_folder)
+    cap = cv2.VideoCapture(str(video_path))
+    if not cap.isOpened():
+        raise RuntimeError(f"Cannot open video: {video_path}")
+
+    outputs: list[Path] = []
+    frame_index = 0
+    saved_index = 1
+    try:
+        while True:
+            ok, frame = cap.read()
+            if not ok:
+                break
+            if frame_index % every == 0:
+                output = output_folder / f"{prefix}_{saved_index:0{digits}d}.{fmt}"
+                cv2.imwrite(str(output), frame)
+                outputs.append(output)
+                saved_index += 1
+            frame_index += 1
+    finally:
+        cap.release()
+    return outputs
+
+
+def images_to_gif(folder: Path, output_path: Path, fps: float = 10.0, pattern: str = "*") -> Path:
+    images = list_images(folder, pattern=pattern)
+    if not images:
+        raise ValueError(f"No images found in {folder}")
+    frames = [Image.open(path).convert("RGB") for path in images]
+    duration = int(1000 / fps)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    frames[0].save(output_path, save_all=True, append_images=frames[1:], duration=duration, loop=0)
+    for frame in frames:
+        frame.close()
+    return output_path
+
+
+def video_to_gif(
+    video_path: Path,
+    output_path: Path,
+    fps: float = 10.0,
+    start: float | None = None,
+    end: float | None = None,
+    size: str | None = None,
+) -> Path:
+    cap = cv2.VideoCapture(str(video_path))
+    if not cap.isOpened():
+        raise RuntimeError(f"Cannot open video: {video_path}")
+
+    source_fps = cap.get(cv2.CAP_PROP_FPS) or 30.0
+    start_frame = int(start * source_fps) if start is not None else 0
+    end_frame = int(end * source_fps) if end is not None else None
+    sample_every = max(1, int(round(source_fps / fps)))
+    target_size = parse_size(size) if size else None
+    frames: list[Image.Image] = []
+
+    cap.set(cv2.CAP_PROP_POS_FRAMES, start_frame)
+    frame_index = start_frame
+    try:
+        while True:
+            if end_frame is not None and frame_index > end_frame:
+                break
+            ok, frame = cap.read()
+            if not ok:
+                break
+            if (frame_index - start_frame) % sample_every == 0:
+                frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+                if target_size:
+                    frame = cv2.resize(frame, target_size)
+                frames.append(Image.fromarray(frame))
+            frame_index += 1
+    finally:
+        cap.release()
+
+    if not frames:
+        raise ValueError("No frames were extracted for GIF")
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    frames[0].save(output_path, save_all=True, append_images=frames[1:], duration=int(1000 / fps), loop=0)
+    for frame in frames:
+        frame.close()
+    return output_path
+
+
+def clip_video(
+    video_path: Path,
+    output_path: Path,
+    start: float | None = None,
+    end: float | None = None,
+    start_frame: int | None = None,
+    end_frame: int | None = None,
+) -> Path:
+    cap = cv2.VideoCapture(str(video_path))
+    if not cap.isOpened():
+        raise RuntimeError(f"Cannot open video: {video_path}")
+
+    fps = cap.get(cv2.CAP_PROP_FPS) or 30.0
+    width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+    height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+    s_frame = start_frame if start_frame is not None else int((start or 0) * fps)
+    e_frame = end_frame if end_frame is not None else (int(end * fps) if end is not None else None)
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    writer = cv2.VideoWriter(str(output_path), cv2.VideoWriter_fourcc(*"mp4v"), fps, (width, height))
+    if not writer.isOpened():
+        raise RuntimeError(f"Cannot create video writer: {output_path}")
+
+    cap.set(cv2.CAP_PROP_POS_FRAMES, s_frame)
+    frame_index = s_frame
+    try:
+        while True:
+            if e_frame is not None and frame_index > e_frame:
+                break
+            ok, frame = cap.read()
+            if not ok:
+                break
+            writer.write(frame)
+            frame_index += 1
+    finally:
+        cap.release()
+        writer.release()
+    return output_path
+
+
+def resize_video(video_path: Path, output_path: Path, size: str) -> Path:
+    target_size = parse_size(size)
+    cap = cv2.VideoCapture(str(video_path))
+    if not cap.isOpened():
+        raise RuntimeError(f"Cannot open video: {video_path}")
+    fps = cap.get(cv2.CAP_PROP_FPS) or 30.0
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    writer = cv2.VideoWriter(str(output_path), cv2.VideoWriter_fourcc(*"mp4v"), fps, target_size)
+    try:
+        while True:
+            ok, frame = cap.read()
+            if not ok:
+                break
+            writer.write(cv2.resize(frame, target_size))
+    finally:
+        cap.release()
+        writer.release()
+    return output_path

devbits/project.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from .utils import ensure_dir, iter_project_tree, list_files, readable_size
+
+DEFAULT_IGNORES = [".git", "__pycache__", ".venv", "venv", "node_modules", "build", "dist"]
+
+
+def print_tree(root: Path, depth: int = 3, ignore: list[str] | None = None) -> list[str]:
+    return iter_project_tree(root, ignore or DEFAULT_IGNORES, depth)
+
+
+def folder_size(path: Path) -> int:
+    if path.is_file():
+        return path.stat().st_size
+    total = 0
+    for item in path.rglob("*"):
+        if item.is_file():
+            total += item.stat().st_size
+    return total
+
+
+def top_sizes(root: Path, top: int = 20) -> list[tuple[Path, int, str]]:
+    items = [(p, folder_size(p)) for p in root.iterdir()]
+    items.sort(key=lambda item: item[1], reverse=True)
+    return [(path, size, readable_size(size)) for path, size in items[:top]]
+
+
+def rename_files(folder: Path, prefix: str = "file", digits: int = 6, start: int = 1, dry_run: bool = False) -> list[tuple[Path, Path]]:
+    files = list_files(folder)
+    mappings: list[tuple[Path, Path]] = []
+    for index, old_path in enumerate(files, start=start):
+        new_path = folder / f"{prefix}_{index:0{digits}d}{old_path.suffix.lower()}"
+        mappings.append((old_path, new_path))
+    if dry_run:
+        return mappings
+    temp_mappings: list[tuple[Path, Path]] = []
+    for index, (old_path, _) in enumerate(mappings):
+        temp_path = folder / f".__devbits_tmp_{index}{old_path.suffix}"
+        old_path.rename(temp_path)
+        temp_mappings.append((temp_path, mappings[index][1]))
+    for temp_path, new_path in temp_mappings:
+        temp_path.rename(new_path)
+    return mappings
+
+
+def sample_files(folder: Path, output_folder: Path, num: int, copy: bool = True) -> list[Path]:
+    files = list_files(folder)
+    ensure_dir(output_folder)
+    selected = files[:num]
+    outputs: list[Path] = []
+    for source in selected:
+        dest = output_folder / source.name
+        if copy:
+            shutil.copy2(source, dest)
+        else:
+            shutil.move(str(source), str(dest))
+        outputs.append(dest)
+    return outputs

devbits/scripts.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+
+from .cli import main as devbits_main
+
+
+def _run(command: str, argv: Sequence[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    return devbits_main([command, *args])
+
+
+def clearcache() -> int:
+    return _run("clearcache")
+
+
+def images2video() -> int:
+    return _run("images2video")
+
+
+def video2images() -> int:
+    return _run("video2images")
+
+
+def images2gif() -> int:
+    return _run("images2gif")
+
+
+def video2gif() -> int:
+    return _run("video2gif")
+
+
+def clipvideo() -> int:
+    return _run("clipvideo")
+
+
+def resizevideo() -> int:
+    return _run("resizevideo")
+
+
+def image2ico() -> int:
+    return _run("image2ico")
+
+
+def resizeimage() -> int:
+    return _run("resizeimage")
+
+
+def batchimages() -> int:
+    return _run("batchimages")
+
+
+def checkimages() -> int:
+    return _run("checkimages")
+
+
+def contactsheet() -> int:
+    return _run("contactsheet")
+
+
+def tree() -> int:
+    return _run("tree")
+
+
+def size() -> int:
+    return _run("size")
+
+
+def renamefiles() -> int:
+    return _run("renamefiles")
+
+
+def samplefiles() -> int:
+    return _run("samplefiles")

devbits/utils.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Iterable
+
+IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".bmp", ".tif", ".tiff", ".webp"}
+VIDEO_EXTS = {".mp4", ".avi", ".mov", ".mkv", ".webm"}
+
+
+def ensure_exists(path: Path) -> Path:
+    if not path.exists():
+        raise FileNotFoundError(f"Path does not exist: {path}")
+    return path
+
+
+def ensure_dir(path: Path) -> Path:
+    if not path.exists():
+        path.mkdir(parents=True, exist_ok=True)
+    if not path.is_dir():
+        raise NotADirectoryError(f"Not a directory: {path}")
+    return path
+
+
+def natural_key(value: str) -> list[object]:
+    return [int(text) if text.isdigit() else text.lower() for text in re.split(r"(\d+)", value)]
+
+
+def list_files(folder: Path, pattern: str = "*", recursive: bool = False) -> list[Path]:
+    iterator = folder.rglob(pattern) if recursive else folder.glob(pattern)
+    return sorted([p for p in iterator if p.is_file()], key=lambda p: natural_key(p.name))
+
+
+def list_images(folder: Path, pattern: str = "*", recursive: bool = False) -> list[Path]:
+    return [p for p in list_files(folder, pattern, recursive) if p.suffix.lower() in IMAGE_EXTS]
+
+
+def parse_size(size: str) -> tuple[int, int]:
+    try:
+        width, height = size.replace("x", ",").split(",")
+        width_i, height_i = int(width), int(height)
+    except Exception as exc:
+        raise ValueError("Size must be WIDTH,HEIGHT or WIDTHxHEIGHT, e.g. 640,480") from exc
+    if width_i <= 0 or height_i <= 0:
+        raise ValueError("Width and height must be positive integers")
+    return width_i, height_i
+
+
+def parse_int_tuple(value: str, expected: int, name: str) -> tuple[int, ...]:
+    try:
+        items = tuple(int(x.strip()) for x in value.split(","))
+    except Exception as exc:
+        raise ValueError(f"{name} must be comma-separated integers") from exc
+    if len(items) != expected:
+        raise ValueError(f"{name} must contain {expected} comma-separated integers")
+    return items
+
+
+def readable_size(num_bytes: int) -> str:
+    value = float(num_bytes)
+    for unit in ["B", "KB", "MB", "GB", "TB"]:
+        if value < 1024 or unit == "TB":
+            return f"{value:.1f} {unit}"
+        value /= 1024
+    return f"{num_bytes} B"
+
+
+def iter_project_tree(root: Path, ignore: Iterable[str], max_depth: int) -> list[str]:
+    ignore_set = set(ignore)
+    lines: list[str] = []
+
+    def walk(path: Path, prefix: str = "", depth: int = 0) -> None:
+        if depth > max_depth:
+            return
+        children = [p for p in sorted(path.iterdir(), key=lambda p: (p.is_file(), natural_key(p.name))) if p.name not in ignore_set]
+        for index, child in enumerate(children):
+            connector = "└── " if index == len(children) - 1 else "├── "
+            lines.append(f"{prefix}{connector}{child.name}{'/' if child.is_dir() else ''}")
+            if child.is_dir():
+                extension = "    " if index == len(children) - 1 else "│   "
+                walk(child, prefix + extension, depth + 1)
+
+    lines.append(f"{root.name}/")
+    walk(root, max_depth=max_depth)
+    return lines

devbits-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: devbits
+Version: 0.1.0
+Summary: A lightweight CLI toolkit for daily development utilities.
+Author: Bruce Chuang
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/<your-github-username>/devbits
+Project-URL: Repository, https://github.com/<your-github-username>/devbits
+Project-URL: Issues, https://github.com/<your-github-username>/devbits/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python>=4.8.0
+Requires-Dist: pillow>=10.0.0
+Dynamic: license-file
+
+# devbits
+
+## CLI style
+
+`devbits` provides both a main command and standalone commands installed into your Python environment's PATH.
+
+Main command style:
+
+```bash
+devbits clearcache .
+devbits images2video frames/ -o output.mp4 --fps 30
+```
+
+Standalone command style:
+
+```bash
+clearcache .
+images2video frames/ -o output.mp4 --fps 30
+video2gif input.mp4 -o output.gif
+clipvideo input.mp4 --start 3 --end 10 -o clip.mp4
+```
+
+After editable install, reopen the terminal or run `hash -r` if your shell does not immediately find the new commands.
+
+
+`devbits` is a lightweight CLI toolkit for daily development utilities, including cache cleanup, media conversion, image helpers, dataset-like file operations, and project maintenance tools.
+
+The project supports two CLI styles:
+
+```bash
+devbits <command> [options]
+<command> [options]
+```
+
+## Features
+
+### Project cleanup
+
+```bash
+devbits clearcache .
+devbits clearcache . --all
+devbits clearcache . --dry-run
+```
+
+Removes:
+
+- `__pycache__/`
+- `*.pyc`
+- `*.pyo`
+- optionally `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`
+
+### Image and video conversion
+
+```bash
+devbits images2video ./frames -o output.mp4 --fps 30
+devbits video2images input.mp4 -o ./frames --every 1
+devbits images2gif ./frames -o output.gif --fps 10
+devbits video2gif input.mp4 -o output.gif --fps 10 --start 2 --end 8
+devbits clipvideo input.mp4 -o clip.mp4 --start 3 --end 10
+devbits clipvideo input.mp4 -o clip.mp4 --start-frame 100 --end-frame 500
+devbits resizevideo input.mp4 -o resized.mp4 --size 1280,720
+```
+
+### Image utilities
+
+```bash
+devbits image2ico logo.png -o logo.ico
+devbits resizeimage input.jpg -o output.jpg --size 640,480
+devbits batchimages ./images -o ./resized --size 640,480 --format jpg
+devbits checkimages ./images --recursive
+devbits contactsheet ./images -o sheet.jpg --cols 5 --labels
+```
+
+### Project utilities
+
+```bash
+devbits tree . --depth 3
+devbits size . --top 20
+devbits renamefiles ./images --prefix frame --digits 6
+devbits renamefiles ./images --prefix frame --digits 6 --dry-run
+devbits samplefiles ./images -o ./sample --num 100
+```
+
+## Installation for local development
+
+```bash
+git clone https://github.com/yourname/devbits.git
+cd devbits
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Check the CLI:
+
+```bash
+devbits --help
+devbits images2video --help
+clearcache --help
+images2video --help
+```
+
+## Build package
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+## Upload to TestPyPI
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+## Upload to PyPI
+
+```bash
+python -m twine upload dist/*
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `clearcache` | Clear Python cache files. |
+| `images2video` | Convert image sequence to MP4 video. |
+| `video2images` | Extract frames from a video. |
+| `images2gif` | Convert image sequence to GIF. |
+| `video2gif` | Convert video to GIF. |
+| `clipvideo` | Clip video by seconds or frame indices. |
+| `resizevideo` | Resize a video. |
+| `image2ico` | Convert image to `.ico`. |
+| `resizeimage` | Resize an image. |
+| `batchimages` | Batch resize or convert images. |
+| `checkimages` | Check broken image files. |
+| `contactsheet` | Create a contact sheet. |
+| `tree` | Print a compact project tree. |
+| `size` | Show top-level folder/file sizes. |
+| `renamefiles` | Batch rename files. |
+| `samplefiles` | Copy or move first N files. |
+
+## Roadmap
+
+- Interactive `clipvideo --gui`
+- `mergevideos`
+- `comparevideos`
+- `concatframes`
+- `annotatevideo`
+- `watermark`
+- `splitdataset`
+- `countdataset`
+- `dedupimages`
+- Optional ROS helpers under `devbits[ros]`
+
+## License
+
+MIT

devbits-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+devbits/__init__.py,sha256=zqY4XfgveM5MNPiCnaR8ibIN5LNKsJgNgAcXotHkU3w,97
+devbits/cache.py,sha256=B_KL0XjgwpBGX1ZTZ3Mm1ZSKKyN9d1vMuTzc2crp3CM,939
+devbits/cli.py,sha256=vyfjjyktgDJ2uqN4L0qiJ0KnifJTYvn3LfHI7dInU6g,9612
+devbits/image.py,sha256=5U8hejhx7zONa7Hdgh8vzzA_mgnNm8o5EKP_Up9f29g,3436
+devbits/media.py,sha256=jssw4hsoDjRZXDS-jrkLG54GxbU4DFIoFc6vQ-3rnQg,6177
+devbits/project.py,sha256=uZqOrRTlMVhANq2vDQXwZUObuOLIHQ2J3GCGcUPCbjE,2163
+devbits/scripts.py,sha256=EccTlPhLRau5OwX4KyQiiSnRTDsagPDPauki3MNr7BI,1195
+devbits/utils.py,sha256=4MFbn8biH6WW7x2w_GXnHf3lFbcdTxAEGs9WYkGjFpk,3131
+devbits-0.1.0.dist-info/licenses/LICENSE,sha256=c0Rf85t-tlEpHaWcw2PEO-9h-tBhDLKeU_cBpdYJISA,1069
+devbits-0.1.0.dist-info/METADATA,sha256=NsrCuP9tgmg8k_c4F4Mtwqx17UEwOWxKAk6WS0ey16o,4252
+devbits-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+devbits-0.1.0.dist-info/entry_points.txt,sha256=LA9XpAutCCLCS4fFl8m4j8WNOQoxnHgiyjCEeCHypXY,679
+devbits-0.1.0.dist-info/top_level.txt,sha256=4cDyBdxRwcICa4LrpFjN5159MDxI23MeAtM9RYZ5fS0,8
+devbits-0.1.0.dist-info/RECORD,,

devbits-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
+

devbits-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,18 @@
+[console_scripts]
+batchimages = devbits.scripts:batchimages
+checkimages = devbits.scripts:checkimages
+clearcache = devbits.scripts:clearcache
+clipvideo = devbits.scripts:clipvideo
+contactsheet = devbits.scripts:contactsheet
+devbits = devbits.cli:main
+image2ico = devbits.scripts:image2ico
+images2gif = devbits.scripts:images2gif
+images2video = devbits.scripts:images2video
+renamefiles = devbits.scripts:renamefiles
+resizeimage = devbits.scripts:resizeimage
+resizevideo = devbits.scripts:resizevideo
+samplefiles = devbits.scripts:samplefiles
+size = devbits.scripts:size
+tree = devbits.scripts:tree
+video2gif = devbits.scripts:video2gif
+video2images = devbits.scripts:video2images

devbits-0.1.0.dist-info/licenses/LICENSE

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

devbits-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+devbits