optforge 0.2.0__py3-none-any.whl

optforge/pycacheClean/cleaner.py

@@ -0,0 +1,43 @@
+"""Deletion of discovered cache directories, with per-target failure reporting."""
+
+from __future__ import annotations
+
+import shutil
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from optforge.pycacheclean.models import CacheTarget, CleanFailure, CleanReport
+
+Remover = Callable[..., Any]
+
+
+class CacheCleaner:
+    """Remove targets and report exactly what succeeded and what did not."""
+
+    def __init__(self, remover: Remover = shutil.rmtree) -> None:
+        self._remover = remover
+
+    def clean(self, targets: Iterable[CacheTarget], *, dry_run: bool = False) -> CleanReport:
+        removed: list[CacheTarget] = []
+        failed: list[CleanFailure] = []
+
+        for target in targets:
+            if dry_run:
+                removed.append(target)
+                continue
+            errors: list[str] = []
+
+            def on_error(_func: Any, path: str, exc: BaseException) -> None:
+                errors.append(f"{path}: {exc}")
+
+            try:
+                self._remover(target.path, onexc=on_error)
+            except OSError as exc:
+                failed.append(CleanFailure(path=target.path, error=str(exc)))
+                continue
+            if errors:
+                failed.append(CleanFailure(path=target.path, error="; ".join(errors)))
+            else:
+                removed.append(target)
+
+        return CleanReport(dry_run=dry_run, removed=removed, failed=failed)

optforge/pycacheClean/cli.py

@@ -0,0 +1,127 @@
+"""``pycache-clean``: remove ``__pycache__`` directories safely and visibly."""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated
+
+import typer
+from rich.text import Text
+
+from optforge.core.cli import ErrorBoundary, ExitCode
+from optforge.core.console import ConsoleIO
+from optforge.core.formatting import format_bytes
+from optforge.core.version import get_version
+from optforge.pycacheclean.service import CacheService
+
+app = typer.Typer(
+    name="pycache-clean",
+    help="Remove Python __pycache__ directories. Skips virtualenvs by default.",
+    no_args_is_help=False,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+console = ConsoleIO()
+
+
+def _service() -> CacheService:
+    return CacheService()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"pycache-clean (optforge {get_version()})")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    path: Annotated[str, typer.Argument(help="Directory to scan for cache directories.")] = ".",
+    recursive: Annotated[
+        bool, typer.Option("--recursive/--no-recursive", help="Search recursively beneath the path.")
+    ] = True,
+    max_depth: Annotated[
+        int | None,
+        typer.Option("--max-depth", min=1, help="Maximum directory depth to traverse."),
+    ] = None,
+    exclude: Annotated[
+        list[str] | None,
+        typer.Option("--exclude", "-e", help="Additional directory name to skip. Repeatable."),
+    ] = None,
+    skip_venvs: Annotated[
+        bool,
+        typer.Option("--skip-venv/--include-venv", help="Skip (or include) venv and .venv trees."),
+    ] = True,
+    measure: Annotated[
+        bool, typer.Option("--size/--no-size", help="Measure files and bytes per target.")
+    ] = True,
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="List what would be removed without deleting it.")
+    ] = False,
+    yes: Annotated[
+        bool, typer.Option("--yes", "-y", help="Delete without asking for confirmation.")
+    ] = False,
+    allow_root: Annotated[
+        bool, typer.Option("--allow-root", help="Permit scanning the filesystem root.")
+    ] = False,
+    as_json: Annotated[bool, typer.Option("--json", help="Print machine-readable JSON.")] = False,
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = None,
+) -> None:
+    """Remove __pycache__ directories under a path."""
+    service = _service()
+    with ErrorBoundary(console):
+        targets = service.scan(
+            path,
+            recursive=recursive,
+            max_depth=max_depth,
+            exclude=set(exclude or ()),
+            skip_venvs=skip_venvs,
+            measure=measure,
+            allow_root=allow_root,
+        )
+
+    if not targets:
+        if as_json:
+            console.json({"dry_run": dry_run, "removed": [], "failed": [], "freed_bytes": 0})
+        else:
+            console.text(f"No __pycache__ directories found under {path!r}.")
+        raise typer.Exit(ExitCode.OK)
+
+    if not dry_run and not yes:
+        if not sys.stdin.isatty():
+            console.error("Refusing to delete without --yes in a non-interactive session.")
+            raise typer.Exit(2)
+        noun = "directory" if len(targets) == 1 else "directories"
+        if not typer.confirm(f"Delete {len(targets)} __pycache__ {noun}?", default=False):
+            console.text("Aborted; nothing was deleted.")
+            raise typer.Exit(ExitCode.OK)
+
+    report = service.remove(targets, dry_run=dry_run)
+
+    if as_json:
+        console.json(report.to_dict())
+    else:
+        verb = "Would remove" if dry_run else "Removed"
+        console.text(f"{verb} {len(report.removed)} cache directories.")
+        for target in report.removed:
+            detail = f" ({target.files} files, {format_bytes(target.bytes)})" if measure else ""
+            console.print(Text(f"  - {target.path}{detail}"))
+        for failure in report.failed:
+            console.error(f"{failure.path}: {failure.error}")
+        if not dry_run:
+            console.text(f"Freed {format_bytes(report.freed_bytes)}.")
+
+    raise typer.Exit(ExitCode.OK if report.ok else ExitCode.NO)
+
+
+if __name__ == "__main__":
+    app()

optforge/pycacheClean/models.py

@@ -0,0 +1,55 @@
+"""Value objects for Python cache cleanup."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class CacheTarget:
+    """A ``__pycache__`` directory discovered by the scanner."""
+
+    path: Path
+    files: int = 0
+    bytes: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"path": str(self.path), "files": self.files, "bytes": self.bytes}
+
+
+@dataclass(frozen=True, slots=True)
+class CleanFailure:
+    """A target that could not be removed."""
+
+    path: Path
+    error: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"path": str(self.path), "error": self.error}
+
+
+@dataclass(frozen=True, slots=True)
+class CleanReport:
+    """What a cleanup run did (or would do)."""
+
+    dry_run: bool
+    removed: list[CacheTarget] = field(default_factory=list)
+    failed: list[CleanFailure] = field(default_factory=list)
+
+    @property
+    def freed_bytes(self) -> int:
+        return sum(target.bytes for target in self.removed)
+
+    @property
+    def ok(self) -> bool:
+        return not self.failed
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "dry_run": self.dry_run,
+            "removed": [target.to_dict() for target in self.removed],
+            "failed": [failure.to_dict() for failure in self.failed],
+            "freed_bytes": self.freed_bytes,
+        }

optforge/pycacheClean/scanner.py

@@ -0,0 +1,122 @@
+"""Discovery of ``__pycache__`` directories with venv and symlink safety."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from optforge.pycacheclean.models import CacheTarget
+
+_CACHE_DIR = "__pycache__"
+_VENV_DIRS = frozenset({"venv", ".venv", "env", ".env"})
+_DEFAULT_SKIP = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        ".tox",
+        ".nox",
+        ".mypy_cache",
+        ".ruff_cache",
+        ".pytest_cache",
+        "node_modules",
+        "site-packages",
+    }
+)
+
+
+class CacheScanner:
+    """Walk a tree and return every cache directory worth removing.
+
+    The scanner never follows symlinks, never descends into a cache directory,
+    and skips virtualenvs by default so a cleanup does not destroy a project's
+    installed dependencies.
+    """
+
+    def __init__(self, skip: set[str] | None = None, *, skip_venvs: bool = True) -> None:
+        self._extra_skip = {name.lower() for name in (skip or set())}
+        self._skip_venvs = skip_venvs
+
+    def scan(
+        self,
+        root: str | os.PathLike[str],
+        *,
+        recursive: bool = True,
+        max_depth: int | None = None,
+        exclude: set[str] | None = None,
+        measure: bool = True,
+        skip_venvs: bool | None = None,
+    ) -> list[CacheTarget]:
+        """Return matching cache directories under ``root``."""
+        root_path = Path(root).expanduser()
+        skip = self._build_skip(exclude, skip_venvs)
+        if not recursive:
+            candidate = root_path / _CACHE_DIR
+            return [self._target(candidate, measure)] if candidate.is_dir() else []
+
+        targets: list[CacheTarget] = []
+        stack: list[tuple[str, int]] = [(os.fspath(root_path), 0)]
+        while stack:
+            current, depth = stack.pop()
+            try:
+                entries = list(os.scandir(current))
+            except OSError:
+                continue
+            for entry in entries:
+                try:
+                    if not entry.is_dir(follow_symlinks=False):
+                        continue
+                except OSError:
+                    continue
+                name = entry.name
+                if name.lower() in skip:
+                    continue
+                child_depth = depth + 1
+                if name == _CACHE_DIR:
+                    if max_depth is None or child_depth <= max_depth:
+                        targets.append(self._target(Path(entry.path), measure))
+                    continue
+                if max_depth is not None and child_depth >= max_depth:
+                    continue
+                stack.append((entry.path, child_depth))
+
+        return sorted(targets, key=lambda target: str(target.path))
+
+    def _build_skip(self, exclude: set[str] | None, skip_venvs: bool | None) -> set[str]:
+        skip = set(self._extra_skip) | _DEFAULT_SKIP
+        include_venvs = self._skip_venvs if skip_venvs is None else skip_venvs
+        if include_venvs:
+            skip |= _VENV_DIRS
+        else:
+            skip -= _VENV_DIRS
+        skip |= {name.lower() for name in (exclude or set())}
+        return skip
+
+    @staticmethod
+    def _target(path: Path, measure: bool) -> CacheTarget:
+        if not measure:
+            return CacheTarget(path=path)
+        files, size = _measure(path)
+        return CacheTarget(path=path, files=files, bytes=size)
+
+
+def _measure(path: Path) -> tuple[int, int]:
+    files = 0
+    size = 0
+    stack = [os.fspath(path)]
+    while stack:
+        current = stack.pop()
+        try:
+            entries = list(os.scandir(current))
+        except OSError:
+            continue
+        for entry in entries:
+            try:
+                if entry.is_dir(follow_symlinks=False):
+                    stack.append(entry.path)
+                elif entry.is_file(follow_symlinks=False):
+                    files += 1
+                    size += entry.stat(follow_symlinks=False).st_size
+            except OSError:
+                continue
+    return files, size

optforge/pycacheClean/service.py

@@ -0,0 +1,79 @@
+"""Facade for scanning and cleaning Python cache directories."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from optforge.core.errors import InvalidInput, NotFound
+from optforge.pycacheclean.cleaner import CacheCleaner
+from optforge.pycacheclean.models import CacheTarget, CleanReport
+from optforge.pycacheclean.scanner import CacheScanner
+
+
+class CacheService:
+    """Resolve a root, scan it, then delete or preview the matches."""
+
+    def __init__(self, scanner: CacheScanner | None = None, cleaner: CacheCleaner | None = None) -> None:
+        self._scanner = scanner or CacheScanner()
+        self._cleaner = cleaner or CacheCleaner()
+
+    def scan(
+        self,
+        root: str | os.PathLike[str] = ".",
+        *,
+        recursive: bool = True,
+        max_depth: int | None = None,
+        exclude: set[str] | None = None,
+        skip_venvs: bool = True,
+        measure: bool = True,
+        allow_root: bool = False,
+    ) -> list[CacheTarget]:
+        path = self._validate_root(root, allow_root=allow_root)
+        return self._scanner.scan(
+            path,
+            recursive=recursive,
+            max_depth=max_depth,
+            exclude=exclude,
+            measure=measure,
+            skip_venvs=skip_venvs,
+        )
+
+    def remove(self, targets: list[CacheTarget], *, dry_run: bool = False) -> CleanReport:
+        return self._cleaner.clean(targets, dry_run=dry_run)
+
+    def clean(
+        self,
+        root: str | os.PathLike[str] = ".",
+        *,
+        recursive: bool = True,
+        max_depth: int | None = None,
+        exclude: set[str] | None = None,
+        skip_venvs: bool = True,
+        measure: bool = True,
+        dry_run: bool = False,
+        allow_root: bool = False,
+    ) -> CleanReport:
+        targets = self.scan(
+            root,
+            recursive=recursive,
+            max_depth=max_depth,
+            exclude=exclude,
+            skip_venvs=skip_venvs,
+            measure=measure,
+            allow_root=allow_root,
+        )
+        return self.remove(targets, dry_run=dry_run)
+
+    @staticmethod
+    def _validate_root(root: str | os.PathLike[str], *, allow_root: bool) -> Path:
+        path = Path(root).expanduser()
+        if not path.exists():
+            raise NotFound(f"Path does not exist: {path}")
+        if not path.is_dir():
+            raise InvalidInput(f"Not a directory: {path}")
+        if not allow_root and path.resolve() == Path(path.anchor):
+            raise InvalidInput(
+                f"Refusing to scan the filesystem root {path}. Pass --allow-root if you mean it."
+            )
+        return path

optforge/volume/__init__.py

@@ -0,0 +1,7 @@
+"""Output-volume control for the default audio device."""
+
+from __future__ import annotations
+
+from optforge.volume.core import MAX_VOLUME, MIN_VOLUME, VolumeBackend, VolumeController, create_backend
+
+__all__ = ["MAX_VOLUME", "MIN_VOLUME", "VolumeBackend", "VolumeController", "create_backend"]

optforge/volume/cli.py

@@ -0,0 +1,224 @@
+"""``vol``: get or set the default output volume.
+
+Exit codes
+    0  the volume was read or changed successfully
+    2  invalid usage (raised by Typer)
+    3  the volume could not be read or changed
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+import typer
+from rich.text import Text
+
+from optforge.core.cli import ErrorBoundary
+from optforge.core.console import ConsoleIO
+from optforge.core.version import get_version
+from optforge.volume.core import MAX_VOLUME, MIN_VOLUME, VolumeController
+
+app = typer.Typer(
+    name="vol",
+    help="Get or set the default output volume.",
+    epilog="Exit codes: 0 ok | 2 bad usage | 3 could not run",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+console = ConsoleIO()
+
+LevelArg = Annotated[
+    int,
+    typer.Argument(
+        min=MIN_VOLUME,
+        max=MAX_VOLUME,
+        metavar="PERCENT",
+        show_default=False,
+        help="Volume percentage (0-100).",
+    ),
+]
+StepArg = Annotated[
+    int,
+    typer.Argument(
+        min=1,
+        max=MAX_VOLUME,
+        metavar="STEP",
+        show_default=True,
+        help="Amount to change (1-100).",
+    ),
+]
+QuietOpt = Annotated[bool, typer.Option("--quiet", "-q", help="Print nothing; use the exit code only.")]
+JsonOpt = Annotated[bool, typer.Option("--json", help="Print machine-readable JSON.")]
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"vol (optforge {get_version()})")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = None,
+) -> None:
+    pass
+
+
+def _controller() -> VolumeController:
+    return VolumeController()
+
+
+def _report(level: int, *, json_output: bool, quiet: bool, reading: bool, muted: bool = False) -> None:
+    if quiet:
+        return
+    if json_output:
+        payload: dict[str, Any] = {"volume": level}
+        if reading:
+            payload["muted"] = muted
+        console.json(payload)
+        return
+    if reading:
+        suffix = " (muted)" if muted else ""
+        console.print(Text(f"Volume: {level}%{suffix}", style="cyan"))
+    else:
+        console.print(Text(f"Volume set to {level}%.", style="green"))
+
+
+def _report_mute(muted: bool, *, json_output: bool, quiet: bool) -> None:
+    if quiet:
+        return
+    if json_output:
+        console.json({"muted": muted})
+        return
+    console.print(Text("Muted." if muted else "Unmuted.", style="green"))
+
+
+def _show(*, json_output: bool, quiet: bool) -> None:
+    with ErrorBoundary(console):
+        controller = _controller()
+        current = controller.get()
+        muted = controller.is_muted()
+    _report(current, json_output=json_output, quiet=quiet, reading=True, muted=muted)
+
+
+@app.command("on")
+def set_on(
+    level: LevelArg,
+    json_output: JsonOpt = False,
+    quiet: QuietOpt = False,
+) -> None:
+    """Set the output volume to a percentage (0-100)."""
+    with ErrorBoundary(console):
+        applied = _controller().set(level)
+    _report(applied, json_output=json_output, quiet=quiet, reading=False)
+
+
+@app.command("full")
+def set_full(
+    json_output: JsonOpt = False,
+    quiet: QuietOpt = False,
+) -> None:
+    """Set the output volume to 100%."""
+    with ErrorBoundary(console):
+        applied = _controller().full()
+    _report(applied, json_output=json_output, quiet=quiet, reading=False)
+
+
+@app.command("none")
+def set_none(
+    json_output: JsonOpt = False,
+    quiet: QuietOpt = False,
+) -> None:
+    """Set the output volume to 0%."""
+    with ErrorBoundary(console):
+        applied = _controller().none()
+    _report(applied, json_output=json_output, quiet=quiet, reading=False)
+
+
+@app.command("up")
+def volume_up(
+    step: StepArg = 5,
+    json_output: JsonOpt = False,
+    quiet: QuietOpt = False,
+) -> None:
+    """Increase the output volume by STEP (default 5)."""
+    with ErrorBoundary(console):
+        applied = _controller().up(step)
+    _report(applied, json_output=json_output, quiet=quiet, reading=False)
+
+
+@app.command("down")
+def volume_down(
+    step: StepArg = 5,
+    json_output: JsonOpt = False,
+    quiet: QuietOpt = False,
+) -> None:
+    """Decrease the output volume by STEP (default 5)."""
+    with ErrorBoundary(console):
+        applied = _controller().down(step)
+    _report(applied, json_output=json_output, quiet=quiet, reading=False)
+
+
+@app.command("mute")
+def mute(
+    json_output: JsonOpt = False,
+    quiet: QuietOpt = False,
+) -> None:
+    """Mute the default output."""
+    with ErrorBoundary(console):
+        muted = _controller().mute()
+    _report_mute(muted, json_output=json_output, quiet=quiet)
+
+
+@app.command("unmute")
+def unmute(
+    json_output: JsonOpt = False,
+    quiet: QuietOpt = False,
+) -> None:
+    """Unmute the default output."""
+    with ErrorBoundary(console):
+        muted = _controller().unmute()
+    _report_mute(muted, json_output=json_output, quiet=quiet)
+
+
+@app.command("toggle")
+def toggle(
+    json_output: JsonOpt = False,
+    quiet: QuietOpt = False,
+) -> None:
+    """Toggle mute on the default output."""
+    with ErrorBoundary(console):
+        muted = _controller().toggle_mute()
+    _report_mute(muted, json_output=json_output, quiet=quiet)
+
+
+@app.command("get")
+def get_volume(
+    json_output: JsonOpt = False,
+    quiet: QuietOpt = False,
+) -> None:
+    """Show the current output volume."""
+    _show(json_output=json_output, quiet=quiet)
+
+
+@app.command("status")
+def status(
+    json_output: JsonOpt = False,
+    quiet: QuietOpt = False,
+) -> None:
+    """Show the current output volume (alias for get)."""
+    _show(json_output=json_output, quiet=quiet)
+
+
+if __name__ == "__main__":
+    app()