dsz 0.1.0__tar.gz

dsz-0.1.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.3
+Name: dsz
+Version: 0.1.0
+Summary: Show disk usage of a directory's immediate children.
+Author: Kyle O'Malley
+Author-email: Kyle O'Malley <j.kyle.omalley@gmail.com>
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# dsz
+
+Show disk usage of a directory's immediate children, sorted by size.
+
+## Installation
+
+```
+uv tool install dsz
+```
+
+## Usage
+
+```
+dsz [PATH] [--min-percent N]
+```
+
+- `PATH` — directory to scan (default: current directory)
+- `--min-percent N` — collapse entries below N% of the total into a single `<other>` line (default: 1.0)
+
+## Example
+
+```
+$ dsz ~
+/home/user    24.2 GB
+   18.2 GB  75% Videos               ###############
+    4.1 GB  17% Documents            ###
+    1.6 GB   7% Downloads            #
+  312.4 MB   1% <other 5>
+```
+
+Hidden entries (dot files and directories) and symlinks are excluded from all counts. Drill into a subdirectory by passing it as `PATH`.

dsz-0.1.0/README.md

@@ -0,0 +1,31 @@
+# dsz
+
+Show disk usage of a directory's immediate children, sorted by size.
+
+## Installation
+
+```
+uv tool install dsz
+```
+
+## Usage
+
+```
+dsz [PATH] [--min-percent N]
+```
+
+- `PATH` — directory to scan (default: current directory)
+- `--min-percent N` — collapse entries below N% of the total into a single `<other>` line (default: 1.0)
+
+## Example
+
+```
+$ dsz ~
+/home/user    24.2 GB
+   18.2 GB  75% Videos               ###############
+    4.1 GB  17% Documents            ###
+    1.6 GB   7% Downloads            #
+  312.4 MB   1% <other 5>
+```
+
+Hidden entries (dot files and directories) and symlinks are excluded from all counts. Drill into a subdirectory by passing it as `PATH`.

dsz-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "dsz"
+version = "0.1.0"
+description = "Show disk usage of a directory's immediate children."
+readme = "README.md"
+authors = [{ name = "Kyle O'Malley", email = "j.kyle.omalley@gmail.com" }]
+requires-python = ">=3.14"
+dependencies = []
+
+[project.scripts]
+dsz = "dsz.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.16,<0.12.0"]
+build-backend = "uv_build"

dsz-0.1.0/src/dsz/__init__.py

@@ -0,0 +1 @@
+"""Show disk usage of a directory's immediate children."""

dsz-0.1.0/src/dsz/cli.py

@@ -0,0 +1,36 @@
+from dsz.core import generate_size_report
+
+from pathlib import Path
+
+import argparse
+import sys
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Show disk usage of a directory's immediate children.")
+    parser.add_argument(
+        "PATH",
+        nargs="?",
+        default=".",
+        type=Path,
+        help="directory to scan (default: current directory)",
+    )
+    parser.add_argument(
+        "--min-percent",
+        default=1.0,
+        metavar="N",
+        type=float,
+        help="collapse entries below N%% of total into one '<other>' line (default: 1.0)",
+    )
+    args = parser.parse_args()
+
+    directory: Path = args.PATH
+    min_percent: float = args.min_percent
+
+    try:
+        results = generate_size_report(directory, min_percent)
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        raise SystemExit(1)
+
+    print(results, end="")

dsz-0.1.0/src/dsz/core.py

@@ -0,0 +1,111 @@
+"""dsz scan module."""
+
+from pathlib import Path
+import os
+
+
+def _fmt_size(n: int) -> str:
+    if n < 1024:
+        return f"{n} B"
+
+    size = float(n)
+
+    for unit in ("KB", "MB", "GB"):
+        size /= 1024
+        if size < 1024 or unit == "GB":
+            break
+
+    return f"{size:.1f} {unit}"
+
+
+def _dir_size(path: str) -> int:
+    """Return total byte size of all files under path, skipping symlinks and permission-denied entries."""
+    total_size = 0
+    stack = [path]
+
+    while stack:
+        current = stack.pop()
+
+        try:
+            scandir_ctx = os.scandir(current)
+        except PermissionError:
+            continue
+
+        with scandir_ctx as dir_iter:
+            for entry in dir_iter:
+                if entry.is_symlink():
+                    continue
+                try:
+                    entry_stat = entry.stat()
+                except OSError:
+                    continue
+                if entry.is_file(follow_symlinks=False):
+                    total_size += entry_stat.st_size
+                elif entry.is_dir(follow_symlinks=False):
+                    stack.append(entry.path)
+
+    return total_size
+
+
+def generate_size_report(path: Path, min_percent: float) -> str:
+    """Scan path's immediate children and return a formatted size report string.
+
+    Raises ValueError if path does not exist or is not a directory.
+    Hidden entries (leading dot) and symlinks are excluded from all counts.
+    Entries below min_percent of the total are collapsed into a single '<other N>' line.
+    """
+    if not path.exists():
+        msg = f"path '{path}' does not exist"
+        raise ValueError(msg)
+
+    if not path.is_dir():
+        msg = f"path '{path}' is not a directory"
+        raise ValueError(msg)
+
+    total_size: int = 0
+
+    entries: dict[str, int] = {}
+
+    try:
+        with os.scandir(path) as dir_iter:
+            for entry in dir_iter:
+                if entry.name.startswith("."):
+                    continue
+                if entry.is_symlink():
+                    continue
+                entry_stat = entry.stat()
+                if entry.is_file(follow_symlinks=False):
+                    total_size += entry_stat.st_size
+                    entries[entry.name] = entry_stat.st_size
+                elif entry.is_dir(follow_symlinks=False):
+                    entry_size = _dir_size(entry.path)
+                    total_size += entry_size
+                    entries[entry.name] = entry_size
+    except PermissionError:
+        pass  # unreadable directory: return header with whatever was counted
+
+    out = f"{path.absolute()}    {_fmt_size(total_size)}\n"
+
+    if not entries or total_size == 0:
+        return out
+
+    sorted_entries = sorted(entries.items(), key=lambda x: -x[-1])
+
+    above, below = [], []
+
+    for name, size in sorted_entries:
+        percent = (size / total_size) * 100
+        (above if percent >= min_percent else below).append((name, size, percent))
+
+    for entry, size, percent in above:
+        bar = "#" * round(size / total_size * 20)
+        out += f"{_fmt_size(size):>10} {percent:>3.0f}% {entry:<20} {bar}\n"
+
+    if below:
+        other_size = sum(size for _, size, _ in below)
+        other_percent = (other_size / total_size) * 100
+        other_count = len(below)
+        bar = "#" * round(other_size / total_size * 20)
+        out += f"{_fmt_size(other_size):>10} {other_percent:>3.0f}% {f'<other {other_count}>':<20} {bar}\n"
+
+    return out