dirplot 0.3.1__tar.gz → 0.3.3__tar.gz

{dirplot-0.3.1 → dirplot-0.3.3}/CHANGELOG.md

@@ -7,6 +7,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-03-14
+
+### Added
+
+- **Breadcrumbs mode** (`--breadcrumbs/--no-breadcrumbs`, `-b/-B`, on by default): directories
+  that form a single-child chain (one subdirectory, no files) are collapsed into a single tile
+  whose header shows the full path separated by ` / ` (e.g. `src / dirplot / fonts`). When the
+  label is too wide, middle segments are replaced with `…` (`src / … / fonts`). The root tile
+  is never collapsed. Disable with `-B` or `--no-breadcrumbs`.
+- **Tree depth in root label**: the root tile header now includes `depth: N` alongside the
+  file, directory, and size summary (e.g. `myproject — 124 files, 18 dirs, 4.0 MB (…), depth: 6`).
+  The depth reflects the original tree structure and is invariant to whether breadcrumbs mode
+  is active.
+
+## [0.3.2] - 2026-03-13
+
+### Added
+
+- **`dirplot watch`** subcommand — watches a directory and regenerates the treemap
+  on every file-system change using watchdog (FSEvents on macOS, inotify on Linux,
+  kqueue on BSD). Requires `watchdog`, now a core dependency.
+  ```bash
+  dirplot watch . --output treemap.png
+  dirplot watch . --output treemap.png --animate   # APNG, one frame per change
+  ```
+- **Vertical file labels**: file tiles that are at least twice as tall as wide now
+  display their label rotated 90° CCW, letting the text span the full tile height
+  instead of being squeezed into the narrow width.
+- **Scan and render timing** shown in header output:
+  `Found 1,414 files … [2.3s]` and `Saved dirplot to out.png  [0.4s]`.
+- **Multiple local roots**: `dirplot map src tests` accepts two or more local
+  directory paths, finds their common parent, and shows only those subtrees.
+- **`--subtree` / `-s`** option (repeatable) — allowlist complement to `--exclude`:
+  keep only the named direct children of the root after scanning. Supports nested
+  paths such as `--subtree src/dirplot/fonts`.
+
+### Fixed
+
+- `--exclude` on pod and Docker backends now prunes entire subtrees — previously only
+  the exact path was matched, so all children leaked through.
+- Clearer error for distroless pods: exit code 126 from `kubectl exec` now surfaces as
+  an actionable message explaining that the container has no shell or `find` utility.
+- Adaptive file-label font size is now computed with a single `textbbox` measurement
+  (one call per tile) instead of stepping down one pixel at a time — eliminates an
+  O(font_size × n_tiles) bottleneck that caused near-blocking on large trees such as
+  `.venv` directories.
+
+### Changed
+
+- `-s` short alias reassigned from `--font-size` to `--subtree`. `--font-size` still
+  works as before; it just no longer has a single-letter alias.
+
+## [0.3.1] - 2026-03-11
+
 ### Added
 
 - `github://` URI now accepts an optional subpath after the repository name, letting

{dirplot-0.3.1 → dirplot-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirplot
-Version: 0.3.1
+Version: 0.3.3
 Summary: Static treemap bitmaps for directory trees and archives, displayed as inline terminal images
 Project-URL: Repository, https://github.com/deeplook/dirplot
 License: MIT
@@ -33,6 +33,7 @@ Requires-Dist: py7zr>=0.20
 Requires-Dist: rarfile>=4.0
 Requires-Dist: squarify>=0.4
 Requires-Dist: typer>=0.9
+Requires-Dist: watchdog>=6.0.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pre-commit>=3.0; extra == 'dev'
@@ -72,10 +73,13 @@ Description-Content-Type: text/markdown
 - **SVG output** (`--format svg` or `--output file.svg`) produces a fully self-contained interactive file: CSS hover highlight, a JavaScript floating tooltip panel, and cushion shading via a gradient — no external dependencies.
 - Display via system image viewer or inline in the terminal (iTerm2 and Kitty protocols, auto-detected).
 - Save output to a PNG or SVG file with `--output`.
-- Exclude paths with `--exclude` (repeatable).
+- Exclude paths with `--exclude` (repeatable), or focus on specific subtrees with `--subtree` / `-s` (allowlist complement, supports nested paths like `src/dirplot/fonts`).
+- Pass multiple local paths (`dirplot map src tests`) to scan each independently and display them under their common parent, ignoring all other siblings.
 - Works on macOS, Linux, and Windows; WSL2 fully supported.
 - Scan remote hosts over SSH (`pip install "dirplot[ssh]"`), AWS S3 buckets (`pip install "dirplot[s3]"`), any public/private GitHub repository (including specific branch, tag, commit SHA, or subdirectory), **running Docker containers**, or **Kubernetes pods** — all without extra dependencies beyond the respective CLI/SDK. See [EXAMPLES.md](docs/EXAMPLES.md).
 - Optional **file-count legend** (`--legend`) — a corner overlay listing the top extensions by number of files, with coloured swatches and counts, automatically sized to fit the image.
+- **Breadcrumbs mode** (on by default) — single-child directory chains are collapsed into one tile with a `foo / bar / baz` header label. Middle segments are replaced with `…` when the tile is too narrow. Disable with `-B` / `--no-breadcrumbs`.
+- **Tree depth** shown in the root tile header alongside the file count and total size (e.g. `myproject — 124 files, 18 dirs, 4.0 MB (…), depth: 6`).
 - **Wide archive support** — reads zip, tar (gz/bz2/xz/zst), 7z, rar, and via libarchive: iso, cpio, rpm, cab, lha/lzh, xar/pkg, a/ar, and all ZIP-based formats (jar, whl, apk, nupkg, vsix, ipa, …) as virtual directory trees without unpacking. Encrypted archives are handled gracefully: metadata-only reads work without a password for most formats; a password can be supplied with `--password` or entered interactively when needed.
 
 ## How It Works
@@ -134,6 +138,13 @@ dirplot map . --inline
 # Exclude directories
 dirplot map . --exclude .venv --exclude .git
 
+# Map two specific subtrees under their common parent
+dirplot map src tests
+
+# Focus on named subtrees of a root (allowlist; supports nested paths)
+dirplot map . --subtree src --subtree tests
+dirplot map . --subtree src/dirplot/fonts
+
 # Use a different colormap and larger directory labels
 dirplot map . --colormap Set2 --font-size 18
 
@@ -149,6 +160,9 @@ dirplot map . --legend
 # Show a file-count legend limited to 10 entries
 dirplot map . --legend 10
 
+# Disable breadcrumbs (show full nested hierarchy instead of collapsed chains)
+dirplot map . -B
+
 # Save as an interactive SVG (hover highlight + floating tooltip)
 dirplot map . --output treemap.svg --no-show
 
@@ -165,13 +179,15 @@ dirplot map . --format svg --output treemap.svg --no-show
 | `--show/--no-show` | | `--show` | Display the image after rendering |
 | `--inline` | | off | Display in terminal (protocol auto-detected; PNG only) |
 | `--legend [N]` | | off | Show file-count legend; `N` sets max entries (default: 20) |
-| `--font-size` | `-s` | `12` | Directory label font size in pixels |
+| `--font-size` | | `12` | Directory label font size in pixels |
 | `--colormap` | `-c` | `tab20` | Matplotlib colormap for unknown extensions |
 | `--exclude` | `-e` | — | Path to exclude (repeatable) |
+| `--subtree` | `-s` | — | Show only this subtree of the root (repeatable); supports nested paths like `src/dirplot/fonts` |
 | `--size` | | terminal size | Output dimensions as `WIDTHxHEIGHT` (e.g. `1920x1080`) |
 | `--header/--no-header` | | `--header` | Print info lines before rendering |
 | `--cushion/--no-cushion` | | `--cushion` | Apply van Wijk cushion shading for a raised 3-D look |
 | `--log/--no-log` | | `--no-log` | Use log of file sizes for layout, making small files more visible |
+| `--breadcrumbs/--no-breadcrumbs` | `-b`/`-B` | `--breadcrumbs` | Collapse single-child directory chains into `foo / bar / baz` labels |
 | `--password` | | — | Password for encrypted archives; prompted interactively if not supplied and needed |
 | `--github-token` | | `$GITHUB_TOKEN` | GitHub personal access token for private repos or higher rate limits |
 

{dirplot-0.3.1 → dirplot-0.3.3}/README.md

@@ -23,10 +23,13 @@
 - **SVG output** (`--format svg` or `--output file.svg`) produces a fully self-contained interactive file: CSS hover highlight, a JavaScript floating tooltip panel, and cushion shading via a gradient — no external dependencies.
 - Display via system image viewer or inline in the terminal (iTerm2 and Kitty protocols, auto-detected).
 - Save output to a PNG or SVG file with `--output`.
-- Exclude paths with `--exclude` (repeatable).
+- Exclude paths with `--exclude` (repeatable), or focus on specific subtrees with `--subtree` / `-s` (allowlist complement, supports nested paths like `src/dirplot/fonts`).
+- Pass multiple local paths (`dirplot map src tests`) to scan each independently and display them under their common parent, ignoring all other siblings.
 - Works on macOS, Linux, and Windows; WSL2 fully supported.
 - Scan remote hosts over SSH (`pip install "dirplot[ssh]"`), AWS S3 buckets (`pip install "dirplot[s3]"`), any public/private GitHub repository (including specific branch, tag, commit SHA, or subdirectory), **running Docker containers**, or **Kubernetes pods** — all without extra dependencies beyond the respective CLI/SDK. See [EXAMPLES.md](docs/EXAMPLES.md).
 - Optional **file-count legend** (`--legend`) — a corner overlay listing the top extensions by number of files, with coloured swatches and counts, automatically sized to fit the image.
+- **Breadcrumbs mode** (on by default) — single-child directory chains are collapsed into one tile with a `foo / bar / baz` header label. Middle segments are replaced with `…` when the tile is too narrow. Disable with `-B` / `--no-breadcrumbs`.
+- **Tree depth** shown in the root tile header alongside the file count and total size (e.g. `myproject — 124 files, 18 dirs, 4.0 MB (…), depth: 6`).
 - **Wide archive support** — reads zip, tar (gz/bz2/xz/zst), 7z, rar, and via libarchive: iso, cpio, rpm, cab, lha/lzh, xar/pkg, a/ar, and all ZIP-based formats (jar, whl, apk, nupkg, vsix, ipa, …) as virtual directory trees without unpacking. Encrypted archives are handled gracefully: metadata-only reads work without a password for most formats; a password can be supplied with `--password` or entered interactively when needed.
 
 ## How It Works
@@ -85,6 +88,13 @@ dirplot map . --inline
 # Exclude directories
 dirplot map . --exclude .venv --exclude .git
 
+# Map two specific subtrees under their common parent
+dirplot map src tests
+
+# Focus on named subtrees of a root (allowlist; supports nested paths)
+dirplot map . --subtree src --subtree tests
+dirplot map . --subtree src/dirplot/fonts
+
 # Use a different colormap and larger directory labels
 dirplot map . --colormap Set2 --font-size 18
 
@@ -100,6 +110,9 @@ dirplot map . --legend
 # Show a file-count legend limited to 10 entries
 dirplot map . --legend 10
 
+# Disable breadcrumbs (show full nested hierarchy instead of collapsed chains)
+dirplot map . -B
+
 # Save as an interactive SVG (hover highlight + floating tooltip)
 dirplot map . --output treemap.svg --no-show
 
@@ -116,13 +129,15 @@ dirplot map . --format svg --output treemap.svg --no-show
 | `--show/--no-show` | | `--show` | Display the image after rendering |
 | `--inline` | | off | Display in terminal (protocol auto-detected; PNG only) |
 | `--legend [N]` | | off | Show file-count legend; `N` sets max entries (default: 20) |
-| `--font-size` | `-s` | `12` | Directory label font size in pixels |
+| `--font-size` | | `12` | Directory label font size in pixels |
 | `--colormap` | `-c` | `tab20` | Matplotlib colormap for unknown extensions |
 | `--exclude` | `-e` | — | Path to exclude (repeatable) |
+| `--subtree` | `-s` | — | Show only this subtree of the root (repeatable); supports nested paths like `src/dirplot/fonts` |
 | `--size` | | terminal size | Output dimensions as `WIDTHxHEIGHT` (e.g. `1920x1080`) |
 | `--header/--no-header` | | `--header` | Print info lines before rendering |
 | `--cushion/--no-cushion` | | `--cushion` | Apply van Wijk cushion shading for a raised 3-D look |
 | `--log/--no-log` | | `--no-log` | Use log of file sizes for layout, making small files more visible |
+| `--breadcrumbs/--no-breadcrumbs` | `-b`/`-B` | `--breadcrumbs` | Collapse single-child directory chains into `foo / bar / baz` labels |
 | `--password` | | — | Password for encrypted archives; prompted interactively if not supplied and needed |
 | `--github-token` | | `$GITHUB_TOKEN` | GitHub personal access token for private repos or higher rate limits |