dirplot 0.3.0__tar.gz → 0.3.2__tar.gz

{dirplot-0.3.0 → dirplot-0.3.2}/CHANGELOG.md

@@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+  you scan a subdirectory directly:
+  - `github://owner/repo/sub/path` — subpath on the default branch
+  - `github://owner/repo@ref/sub/path` — subpath on a specific branch, tag, or commit SHA
+  - `https://github.com/owner/repo/tree/branch/sub/path` — full GitHub URL form
+  - Tags and commit SHAs are supported wherever a branch ref was previously accepted
+    (e.g. `github://torvalds/linux@v6.12`), as the GitHub trees API accepts any git ref.
+- `--legend N` replaces the old boolean `--legend/--no-legend` flag. It now shows a
+  **file-count legend** — a sorted list of the top N extensions by number of files,
+  with a coloured swatch and the file count for each entry:
+  - Pass `--legend` alone to use the default of 20 entries.
+  - Pass `--legend 10` for a custom limit.
+  - Omit the flag entirely to show no legend.
+  - The number of rows is also capped automatically so the box never overflows the
+    image, based on available vertical space and the current `--font-size`.
+  - Extensions with the same count are sorted alphabetically as a tiebreaker.
+  - When the total number of extensions exceeds the limit, a `(+N more)` line is
+    appended at the bottom of the box.
+
+- The root tile header now includes a summary of the scanned tree after an em-dash
+  separator: `myproject — 124 files, 18 dirs, 4.0 MB (4,231,680 bytes)`.
+  Applies to both PNG and SVG output. The label is truncated with `…` when the tile
+  is too narrow to fit the full string.
+
+- Greatly expanded archive format support via the new `libarchive-c` core dependency
+  (wraps the system libarchive C library):
+  - **New formats**: `.iso`, `.cpio`, `.xar`, `.pkg`, `.dmg`, `.img`, `.rpm`, `.cab`,
+    `.lha`, `.lzh`, `.a`, `.ar`, `.tar.zst`, `.tzst`
+  - **New ZIP aliases**: `.nupkg` (NuGet), `.vsix` (VS Code extension), `.ipa` (iOS app),
+    `.aab` (Android App Bundle)
+  - `.tar.zst` / `.tzst` routed through libarchive for consistent behaviour across all
+    supported Python versions (stdlib `tarfile` only gained zstd support in 3.12).
+  - `libarchive-c>=5.0` added as a core dependency alongside `py7zr` and `rarfile`.
+    Requires the system libarchive library:
+    `brew install libarchive` / `apt install libarchive-dev`.
+  - See [ARCHIVES.md](docs/ARCHIVES.md) for the full format table, platform notes, and
+    intentionally unsupported formats (`.deb`, UDIF `.dmg`).
+- Encrypted archive handling:
+  - `--password` CLI option passes a passphrase upfront.
+  - If an archive turns out to be encrypted and no password was given, dirplot prompts
+    interactively (`Password:` hidden-input prompt) and retries — no need to re-run with a flag.
+  - A wrong password exits cleanly with `Error: incorrect password.`
+  - `PasswordRequired` exception exported from `dirplot.archives` for programmatic use.
+  - **Encryption behaviour by format** (since dirplot reads metadata only, never extracts):
+    - ZIP and 7z: central directory / file list is unencrypted by default → readable without
+      a password even for encrypted archives.
+    - RAR with header encryption (`-hp`): listing is hidden without password;
+      wrong password raises `PasswordRequired`.
+
+### Fixed
+
+- `--version` moved back to the top-level `dirplot` command (was accidentally scoped
+  to `dirplot map` after the CLI was restructured into subcommands).
+
 ## [0.3.0] - 2026-03-10
 
 ### Added
@@ -22,33 +118,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     the scanned path are traversed — the common case in k8s where images declare
     `VOLUME` entries that are always mounted on a separate filesystem.
   - Automatically falls back to a portable `sh` + `stat` loop on BusyBox/Alpine pods.
-- `github://owner/repo[@branch]` URI scheme for GitHub repository scanning. The old
-  `github:owner/repo` shorthand has been removed.
-- File tiles now have a 1-px dark outline (60/255 below fill colour per channel) so
-  adjacent same-coloured tiles — e.g. a directory full of extension-less files — are
-  always visually distinct rather than blending into a single flat block.
-
-### Changed
-
-- `docs/REMOTE-ACCESS.md` renamed to `docs/EXAMPLES.md`; Docker and Kubernetes pod
-  sections added; images with captions added for all remote backends.
-
-### Fixed
-
-- SVG tooltips now show the original byte count when `--log` is active, not the
-  log-transformed layout value. `Node.original_size` is populated by `apply_log_sizes`
-  for both file and directory nodes and is used by the SVG renderer for `data-size`.
-- GitHub error messages are now clear and actionable:
-  - 401 explicitly says the token is invalid or expired.
-  - 403 distinguishes rate-limit exceeded (with the 60 vs 5,000 req/h figures and a
-    token hint) from a permissions failure on a private repository.
-  - 404 now also hints that a token is required for private repositories (GitHub returns
-    404, not 403, for private repos accessed without authentication).
-  - Errors are caught in the CLI and printed as a single `Error: …` line to stderr
-    instead of showing a Python traceback.
-
-### Added
-
 - Docker container scanning via `docker://container:/path` syntax — uses `docker exec`
   and `find` to build the tree without copying files out of the container. Works on any
   running container that has a POSIX shell and `find` (GNU or BusyBox). No extra
@@ -70,7 +139,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     overlay (`gradientUnits="objectBoundingBox"`), defined once and shared across all tiles.
     Matches the ×1.20 highlight / ×0.80 shadow range of the PNG renderer.
     Disabled with `--no-cushion`.
-- `--format png|svg` CLI option; format is also auto-detected from the `--output` file extension.
+- `--format png|svg` CLI option; format is also auto-detected from the `--output` file
+   extension.
 - `create_treemap_svg()` added to the public Python API (`from dirplot import create_treemap_svg`).
 - `drawsvg>=2.4` added as a core dependency.
 - Rename the treemap command to `map` (dirplot map <root>).
@@ -81,6 +151,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for local archive files, .zip, tgz, .tar.xz, .rar, .7z, etc.
 - Include example archives for 17 different extentions for testing.
 - Comprehensive documentation.
+- `github://owner/repo[@branch]` URI scheme for GitHub repository scanning. The old
+  `github:owner/repo` shorthand has been removed.
+- File tiles now have a 1-px dark outline (60/255 below fill colour per channel) so
+  adjacent same-coloured tiles — e.g. a directory full of extension-less files — are
+  always visually distinct rather than blending into a single flat block.
+
+### Changed
+
+- `docs/REMOTE-ACCESS.md` renamed to `docs/EXAMPLES.md`; Docker and Kubernetes pod
+  sections added; images with captions added for all remote backends.
+
+### Fixed
+
+- SVG tooltips now show the original byte count when `--log` is active, not the
+  log-transformed layout value. `Node.original_size` is populated by `apply_log_sizes`
+  for both file and directory nodes and is used by the SVG renderer for `data-size`.
+- GitHub error messages are now clear and actionable.
 
 ## [0.2.0] - 2026-03-09
 

{dirplot-0.3.0 → dirplot-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirplot
-Version: 0.3.0
+Version: 0.3.2
 Summary: Static treemap bitmaps for directory trees and archives, displayed as inline terminal images
 Project-URL: Repository, https://github.com/deeplook/dirplot
 License: MIT
@@ -26,18 +26,22 @@ Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: drawsvg>=2.4.1
+Requires-Dist: libarchive-c>=5.0
 Requires-Dist: matplotlib>=3.7
 Requires-Dist: pillow>=9.0
 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'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: libarchive
+Requires-Dist: libarchive-c>=5.3; extra == 'libarchive'
 Provides-Extra: s3
 Requires-Dist: boto3>=1.26; extra == 's3'
 Provides-Extra: ssh
@@ -69,9 +73,12 @@ 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, **running Docker containers**, or **Kubernetes pods** — all without extra dependencies beyond the respective CLI/SDK. See [EXAMPLES.md](docs/EXAMPLES.md).
+- 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.
+- **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
 
@@ -129,6 +136,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
 
@@ -138,6 +152,12 @@ dirplot map . --size 1920x1080 --output dirplot.png --no-show
 # Don't apply cushion shading — makes tiles look flat
 dirplot map . --no-cushion
 
+# Show a file-count legend (top 20 extensions by default)
+dirplot map . --legend
+
+# Show a file-count legend limited to 10 entries
+dirplot map . --legend 10
+
 # Save as an interactive SVG (hover highlight + floating tooltip)
 dirplot map . --output treemap.svg --no-show
 
@@ -153,14 +173,16 @@ dirplot map . --format svg --output treemap.svg --no-show
 | `--format` | `-f` | auto | Output format: `png` or `svg`. Auto-detected from `--output` extension |
 | `--show/--no-show` | | `--show` | Display the image after rendering |
 | `--inline` | | off | Display in terminal (protocol auto-detected; PNG only) |
-| `--legend/--no-legend` | | `--no-legend` | Show file-extension colour legend |
-| `--font-size` | `-s` | `12` | Directory label font size in pixels |
+| `--legend [N]` | | off | Show file-count legend; `N` sets max entries (default: 20) |
+| `--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 |
+| `--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 |
 
 ## Inline Display
@@ -186,7 +208,7 @@ The default mode (`--show`, no `--inline`) opens the PNG in the system viewer (`
 
 ## Archives
 
-dirplot can read local archive files (zip, tar, 7z, rar, and ZIP-based formats like jar, whl, apk) as treemap inputs without unpacking them. See [ARCHIVES.md](docs/ARCHIVES.md) for supported formats, dependencies, and RAR setup on macOS.
+dirplot can read local archive files without unpacking them — zip, tar (gz/bz2/xz/zst), 7z, rar, and many more via libarchive (iso, cpio, rpm, cab, lha, xar, and all ZIP-based formats like jar, whl, apk, nupkg, vsix, ipa). See [ARCHIVES.md](docs/ARCHIVES.md) for the full list, dependencies, and platform notes.
 
 ```bash
 dirplot map project.zip
@@ -210,6 +232,7 @@ pip install "dirplot[s3]"    # AWS S3 via boto3
 dirplot map ssh://alice@prod.example.com/var/www
 dirplot map s3://noaa-ghcn-pds --no-sign
 dirplot map github://pallets/flask
+dirplot map github://torvalds/linux@v6.12/Documentation
 dirplot map docker://my-container:/app
 dirplot map pod://my-pod:/app
 dirplot map pod://my-pod@staging:/app
@@ -234,6 +257,8 @@ To create a token: GitHub → Settings → Developer settings → Personal acces
 
 ## Python API
 
+> **Note:** The programmatic Python API is still evolving and may change between releases without notice. Pin a specific version if you depend on it. The CLI interface is stable.
+
 The public API is small — `build_tree`, `create_treemap`, `create_treemap_svg`, and the display helpers:
 
 ```python

{dirplot-0.3.0 → dirplot-0.3.2}/README.md

@@ -23,9 +23,12 @@
 - **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, **running Docker containers**, or **Kubernetes pods** — all without extra dependencies beyond the respective CLI/SDK. See [EXAMPLES.md](docs/EXAMPLES.md).
+- 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.
+- **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
 
@@ -83,6 +86,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
 
@@ -92,6 +102,12 @@ dirplot map . --size 1920x1080 --output dirplot.png --no-show
 # Don't apply cushion shading — makes tiles look flat
 dirplot map . --no-cushion
 
+# Show a file-count legend (top 20 extensions by default)
+dirplot map . --legend
+
+# Show a file-count legend limited to 10 entries
+dirplot map . --legend 10
+
 # Save as an interactive SVG (hover highlight + floating tooltip)
 dirplot map . --output treemap.svg --no-show
 
@@ -107,14 +123,16 @@ dirplot map . --format svg --output treemap.svg --no-show
 | `--format` | `-f` | auto | Output format: `png` or `svg`. Auto-detected from `--output` extension |
 | `--show/--no-show` | | `--show` | Display the image after rendering |
 | `--inline` | | off | Display in terminal (protocol auto-detected; PNG only) |
-| `--legend/--no-legend` | | `--no-legend` | Show file-extension colour legend |
-| `--font-size` | `-s` | `12` | Directory label font size in pixels |
+| `--legend [N]` | | off | Show file-count legend; `N` sets max entries (default: 20) |
+| `--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 |
+| `--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 |
 
 ## Inline Display
@@ -140,7 +158,7 @@ The default mode (`--show`, no `--inline`) opens the PNG in the system viewer (`
 
 ## Archives
 
-dirplot can read local archive files (zip, tar, 7z, rar, and ZIP-based formats like jar, whl, apk) as treemap inputs without unpacking them. See [ARCHIVES.md](docs/ARCHIVES.md) for supported formats, dependencies, and RAR setup on macOS.
+dirplot can read local archive files without unpacking them — zip, tar (gz/bz2/xz/zst), 7z, rar, and many more via libarchive (iso, cpio, rpm, cab, lha, xar, and all ZIP-based formats like jar, whl, apk, nupkg, vsix, ipa). See [ARCHIVES.md](docs/ARCHIVES.md) for the full list, dependencies, and platform notes.
 
 ```bash
 dirplot map project.zip
@@ -164,6 +182,7 @@ pip install "dirplot[s3]"    # AWS S3 via boto3
 dirplot map ssh://alice@prod.example.com/var/www
 dirplot map s3://noaa-ghcn-pds --no-sign
 dirplot map github://pallets/flask
+dirplot map github://torvalds/linux@v6.12/Documentation
 dirplot map docker://my-container:/app
 dirplot map pod://my-pod:/app
 dirplot map pod://my-pod@staging:/app
@@ -188,6 +207,8 @@ To create a token: GitHub → Settings → Developer settings → Personal acces
 
 ## Python API
 
+> **Note:** The programmatic Python API is still evolving and may change between releases without notice. Pin a specific version if you depend on it. The CLI interface is stable.
+
 The public API is small — `build_tree`, `create_treemap`, `create_treemap_svg`, and the display helpers:
 
 ```python

{dirplot-0.3.0 → dirplot-0.3.2}/SECURITY.md

@@ -4,7 +4,7 @@
 
 | Version | Supported          |
 |---------|--------------------|
-| 0.1.x   | :white_check_mark: |
+| 0.3.x   | :white_check_mark: |
 
 ## Reporting a Vulnerability