dirplot 0.3.0__tar.gz → 0.3.1__tar.gz

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

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### 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 +78,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 +99,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 +111,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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirplot
-Version: 0.3.0
+Version: 0.3.1
 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,6 +26,7 @@ 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
@@ -38,6 +39,8 @@ 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
@@ -71,7 +74,9 @@ Description-Content-Type: text/markdown
 - Save output to a PNG or SVG file with `--output`.
 - Exclude paths with `--exclude` (repeatable).
 - 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
 
@@ -138,6 +143,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,7 +164,7 @@ 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 |
+| `--legend [N]` | | off | Show file-count legend; `N` sets max entries (default: 20) |
 | `--font-size` | `-s` | `12` | Directory label font size in pixels |
 | `--colormap` | `-c` | `tab20` | Matplotlib colormap for unknown extensions |
 | `--exclude` | `-e` | — | Path to exclude (repeatable) |
@@ -161,6 +172,7 @@ dirplot map . --format svg --output treemap.svg --no-show
 | `--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 +198,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 +222,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 +247,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.1}/README.md

@@ -25,7 +25,9 @@
 - Save output to a PNG or SVG file with `--output`.
 - Exclude paths with `--exclude` (repeatable).
 - 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
 
@@ -92,6 +94,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,7 +115,7 @@ 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 |
+| `--legend [N]` | | off | Show file-count legend; `N` sets max entries (default: 20) |
 | `--font-size` | `-s` | `12` | Directory label font size in pixels |
 | `--colormap` | `-c` | `tab20` | Matplotlib colormap for unknown extensions |
 | `--exclude` | `-e` | — | Path to exclude (repeatable) |
@@ -115,6 +123,7 @@ dirplot map . --format svg --output treemap.svg --no-show
 | `--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 +149,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 +173,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 +198,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.1}/SECURITY.md

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

{dirplot-0.3.0 → dirplot-0.3.1}/docs/ARCHIVES.md

@@ -21,14 +21,34 @@ dirplot map backup.7z --exclude node_modules
 | `.apk` | ZIP (Android package) | `zipfile` (stdlib) |
 | `.epub` | ZIP (eBook) | `zipfile` (stdlib) |
 | `.xpi` | ZIP (browser extension) | `zipfile` (stdlib) |
+| `.nupkg` | ZIP (NuGet package) | `zipfile` (stdlib) |
+| `.vsix` | ZIP (VS Code extension) | `zipfile` (stdlib) |
+| `.ipa` | ZIP (iOS app package) | `zipfile` (stdlib) |
+| `.aab` | ZIP (Android App Bundle) | `zipfile` (stdlib) |
 | `.tar`, `.tar.gz`, `.tgz` | TAR | `tarfile` (stdlib) |
 | `.tar.bz2`, `.tbz2` | TAR | `tarfile` (stdlib) |
 | `.tar.xz`, `.txz` | TAR | `tarfile` (stdlib) |
 | `.7z` | 7-Zip | `py7zr` (bundled) |
 | `.rar` | RAR | `rarfile` (bundled) |
-
-ZIP and all its synonyms (`.jar`, `.whl`, etc.) are read with the same stdlib
-`zipfile` module — the format is identical, only the extension differs.
+| `.tar.zst`, `.tzst` | TAR + Zstandard | `libarchive-c` (bundled) |
+| `.iso` | ISO 9660 disc image | `libarchive-c` (bundled) |
+| `.cpio` | CPIO archive | `libarchive-c` (bundled) |
+| `.xar` | XAR / macOS package | `libarchive-c` (bundled) |
+| `.pkg` | macOS installer package (XAR) | `libarchive-c` (bundled) |
+| `.dmg` | macOS disk image | `libarchive-c` (bundled) |
+| `.img` | Raw/FAT disk image | `libarchive-c` (bundled) |
+| `.rpm` | RPM package (Red Hat / Fedora / SUSE) | `libarchive-c` (bundled) |
+| `.cab` | Microsoft Cabinet (Windows installers/drivers) | `libarchive-c` (bundled) |
+| `.lha`, `.lzh` | LHA/LZH (legacy, common in Japanese software) | `libarchive-c` (bundled) |
+| `.a`, `.ar` | Unix static library / generic `ar` archive | `libarchive-c` (bundled) |
+
+ZIP and all its synonyms (`.jar`, `.whl`, `.nupkg`, etc.) are read with the
+same stdlib `zipfile` module — the format is identical, only the extension
+differs.
+
+`.tar.zst` and `.tzst` are routed through libarchive rather than stdlib
+`tarfile`, which only gained zstd support in Python 3.12. This ensures
+consistent behaviour across all supported Python versions (3.10+).
 
 Symlinks inside TAR archives are silently skipped. Dotfiles (members whose
 filename starts with `.`) are skipped in all formats, consistent with the
@@ -36,13 +56,33 @@ behaviour of local and remote directory scans.
 
 ## Python dependencies
 
-`py7zr` and `rarfile` are regular dependencies — no extra install flag is
-needed:
+`py7zr`, `rarfile`, and `libarchive-c` are regular dependencies — no extra
+install flag is needed:
+
+```bash
+pip install dirplot        # py7zr, rarfile, and libarchive-c included
+```
+
+`libarchive-c` is a thin Python binding to the system **libarchive** C
+library.  The library itself must be installed separately:
 
 ```bash
-pip install dirplot        # py7zr and rarfile included
+# macOS
+brew install libarchive
+
+# Debian / Ubuntu
+sudo apt install libarchive-dev
+
+# Fedora / RHEL
+sudo dnf install libarchive-devel
 ```
 
+On macOS the Homebrew-installed libarchive includes support for reading Apple
+disk images (`.dmg`), ISO 9660 (`.iso`), XAR/PKG (`.xar`, `.pkg`), CPIO
+(`.cpio`), and raw disk images (`.img`).  Support for individual formats may
+vary across Linux distributions depending on how their libarchive package was
+compiled.
+
 ## RAR: system tool requirement
 
 `rarfile` reads RAR metadata in pure Python, but the `rar` CLI must be
@@ -96,6 +136,25 @@ The pytest `sample_archives` session fixture in `tests/conftest.py` regenerates
 the same files into a temporary directory at test-session start, so running the
 script is not required for CI or for running the test suite locally.
 
+## Intentionally unsupported formats
+
+**`.deb` (Debian/Ubuntu packages)** — a `.deb` file is an `ar` archive whose
+members are `debian-binary`, `control.tar.*`, and `data.tar.*`.  libarchive
+sees only those three `ar` members, not the actual file tree inside
+`data.tar.*`.  Showing three opaque tarball blobs is not useful, so `.deb` is
+not registered as a supported input.  To inspect the contents, extract the
+`data.tar.*` member first:
+
+```bash
+ar x package.deb data.tar.gz
+dirplot map data.tar.gz
+```
+
+**macOS UDIF disk images (`.dmg`)** — most modern macOS disk images use the
+proprietary UDIF format, which is not supported by the open-source libarchive.
+dirplot will report a clear error if the format is unrecognised.  Plain
+HFS+/FAT images without UDIF wrapping may still be readable.
+
 ## Behaviour notes
 
 - **Root name**: the archive filename without its suffix is used as the root

{dirplot-0.3.0 → dirplot-0.3.1}/docs/EXAMPLES.md

@@ -64,6 +64,8 @@ dirplot map ssh://prod/var/www   # resolves using the config block above
 
 ### 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.
+
 ```python
 from dirplot.ssh import connect, build_tree_ssh
 from dirplot.render import create_treemap
@@ -126,6 +128,8 @@ boto3's standard credential chain is used automatically — no extra configurati
 
 ### 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.
+
 ```python
 from dirplot.s3 import make_s3_client, build_tree_s3
 from dirplot.render import create_treemap
@@ -225,6 +229,8 @@ Tokens are resolved in this order:
 
 ### 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.
+
 ```python
 from dirplot.github import build_tree_github
 from dirplot.render import create_treemap
@@ -294,6 +300,8 @@ docker rm -f pg-demo
 
 ### 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.
+
 ```python
 from dirplot.docker import build_tree_docker
 from dirplot.render import create_treemap
@@ -370,6 +378,8 @@ kubectl delete pod pg-demo --grace-period=0
 
 ### 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.
+
 ```python
 from dirplot.k8s import build_tree_pod
 from dirplot.render import create_treemap

{dirplot-0.3.0 → dirplot-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dirplot"
-version = "0.3.0"
+version = "0.3.1"
 description = "Static treemap bitmaps for directory trees and archives, displayed as inline terminal images"
 readme = "README.md"
 license = {text = "MIT"}
@@ -32,6 +32,7 @@ classifiers = [
 ]
 dependencies = [
     "drawsvg>=2.4.1",
+    "libarchive-c>=5.0",
     "matplotlib>=3.7",
     "pillow>=9.0",
     "py7zr>=0.20",
@@ -53,6 +54,9 @@ dev = [
     "ruff>=0.4",
     "pre-commit>=3.0",
 ]
+libarchive = [
+    "libarchive-c>=5.3",
+]
 
 [project.urls]
 Repository = "https://github.com/deeplook/dirplot"
@@ -90,7 +94,7 @@ python_version = "3.10"
 strict = true
 
 [[tool.mypy.overrides]]
-module = ["matplotlib.*", "squarify", "PIL.*", "paramiko.*", "boto3.*", "botocore.*", "py7zr.*", "rarfile", "drawsvg.*"]
+module = ["matplotlib.*", "squarify", "PIL.*", "paramiko.*", "boto3.*", "botocore.*", "py7zr.*", "rarfile", "drawsvg.*", "libarchive.*"]
 ignore_missing_imports = true
 
 # ---------------------------------------------------------------------------