dirplot 0.4.0__tar.gz → 0.4.1__tar.gz

{dirplot-0.4.0 → dirplot-0.4.1}/.gitignore

@@ -38,3 +38,4 @@ Thumbs.db
 NOTES.md
 TASKS.md
 tests/example_dirplot.png
+demo/

dirplot-0.4.1/ANIMATION.md

@@ -0,0 +1,27 @@
+# Animation design notes
+
+## `dirplot watch` — is non-animated mode useful?
+
+The watch command has two modes:
+
+- **Non-animated** (`dirplot watch . --output treemap.png`): regenerates and overwrites the
+  PNG on every debounced filesystem change. Useful paired with an auto-refreshing image
+  viewer (e.g. `feh --reload` on Linux) as a live dashboard.
+- **Animated** (`dirplot watch . --output treemap.mp4 --animate`): each debounced render
+  becomes one frame; the complete APNG or MP4 is written on Ctrl-C.
+
+The non-animated mode is a niche use case. The compelling reason to use `dirplot watch`
+at all — vs. running `dirplot map .` on demand — is the animation: a timelapse of how
+the filesystem changed over time.
+
+The current design is also asymmetric: `--animate` produces a file *on exit*, while
+non-animated produces a file *on every change*. They're almost opposite behaviours on
+the same command.
+
+### Options to consider
+
+1. **Keep as-is**, but lead the docs with `--animate` as the primary use case.
+2. **Make `--animate` the default** for `watch`, keeping `--no-animate` for the
+   live-refresh use case — but this is a breaking change.
+3. **Document the live-refresh pattern explicitly** so non-animated mode doesn't look
+   like a half-baked feature.

{dirplot-0.4.0 → dirplot-0.4.1}/CHANGELOG.md

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-04-03
+
+### Added
+
+- **`--last PERIOD`** for `dirplot git` — filter commits by a relative time period instead
+  of (or in addition to) `--max-commits`. Accepts a number followed by a unit:
+  `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `mo` (months = 30 days).
+  For GitHub URLs, uses `git clone --shallow-since` for an efficient date-bounded shallow
+  clone. `--last` and `--max-commits` may be combined (date filter + count cap both apply).
+  ```bash
+  dirplot git . -o history.mp4 --animate --last 30d
+  dirplot git . -o history.mp4 --animate --last 24h
+  dirplot git github://owner/repo -o history.mp4 --animate --last 2w --max-commits 10
+  ```
+
+- **`dirplot demo` command** — new subcommand that runs a curated set of example commands
+  and saves outputs to a folder. Useful for first-time walkthroughs or verifying that
+  everything works in a given environment. Accepts `--output` (default: `demo/`),
+  `--github-url` (default: `https://github.com/deeplook/dirplot`), and
+  `--interactive` / `-i` to step through and confirm each command individually. Output
+  uses rich formatting with colour, section rules, and status indicators.
+  ```bash
+  dirplot demo                             # run all examples, save to ./demo/
+  dirplot demo --output ~/dp-demo --interactive
+  ```
+
+- **`--fade-out` for animated output** — appends a fade-out sequence at the end of
+  animations produced by `dirplot git --animate`, `dirplot watch --animate`, and
+  `dirplot replay`. Four flags control the effect:
+  - `--fade-out` / `--no-fade-out` — enable/disable (default: off)
+  - `--fade-out-duration SECS` — total fade length in seconds (default: 1.0)
+  - `--fade-out-frames N` — number of blend steps; defaults to 4 per second of duration
+    so longer fades are automatically finer-grained
+  - `--fade-out-color COLOR` — target colour: `auto` (black in dark mode, white in light
+    mode), `transparent` (PNG/APNG only; fades to fully transparent), any CSS colour
+    name, or hex code (e.g. `"#1a1a2e"`)
+  ```bash
+  dirplot git . -o history.png --animate --fade-out
+  dirplot git . -o history.mp4 --animate --fade-out --fade-out-duration 2.0
+  dirplot git . -o history.png --animate --fade-out --fade-out-color transparent
+  ```
+
+- **`--dark` / `--light` mode** for all treemap commands — controls background and border
+  colours. Dark mode (default) uses a near-black canvas with white directory labels; light
+  mode uses a white canvas with black labels. Available on `map`, `git`, `watch`, and
+  `replay`.
+  ```bash
+  dirplot map . --light
+  dirplot git . -o history.mp4 --animate --light
+  ```
+
+- **Metadata in MP4/MOV output** — `dirplot git`, `dirplot watch`, and `dirplot replay`
+  now embed the same dirplot metadata (date, software version, OS, Python version,
+  executed command) into MP4/MOV files that was previously only written to PNG and SVG.
+  `dirplot read-meta` reads it back via `ffprobe`.
+
+- **Automatic `gh` CLI credential fallback** — if `--github-token` and `GITHUB_TOKEN`
+  are both absent, dirplot silently runs `gh auth token`. Users authenticated with the
+  [GitHub CLI](https://cli.github.com/) (`gh auth login`) can access private repositories
+  with no extra configuration. Token resolution order: `--github-token` →
+  `$GITHUB_TOKEN` → `gh auth token`.
+
+### Changed
+
+- `--fade-out-frames` defaults dynamically to `round(fade_out_duration × 4)` rather than
+  a fixed 4, so a 2-second fade automatically uses 8 frames and a 0.5-second fade uses 2.
+
+### Fixed
+
+- **`--total-duration` overshooting the target length** — when many commits fell within
+  a burst (closely-spaced timestamps), their proportional frame durations would each be
+  raised to the 200 ms floor, inflating the total well beyond the requested duration
+  (e.g. 34 s instead of 30 s). The floor is still applied for readability, but the
+  non-floored frames are now scaled down to compensate so the sum always matches
+  `--total-duration` exactly.
+
+### Docs
+
+- Added `## dirplot read-meta` section to `docs/CLI.md` (previously undocumented).
+- Documented external tool requirements: `git` (required by `dirplot git`), `ffmpeg`
+  (required for MP4 output), `ffprobe` (required by `read-meta` on MP4 files) — in both
+  `README.md` and `docs/CLI.md`.
+
 ## [0.4.0] - 2026-03-28
 
 ### Added

dirplot-0.4.1/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: dirplot
+Version: 0.4.1
+Summary: Nested treemap visualizations for directory trees and archives
+Project-URL: Repository, https://github.com/deeplook/dirplot
+License: MIT
+License-File: LICENSE
+License-File: LICENSE2
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: drawsvg>=2.4.1
+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.0; extra == 'libarchive'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.26; extra == 's3'
+Provides-Extra: ssh
+Requires-Dist: paramiko>=3.0; extra == 'ssh'
+Description-Content-Type: text/markdown
+
+# dirplot
+
+[![CI](https://github.com/deeplook/dirplot/actions/workflows/ci.yml/badge.svg)](https://github.com/deeplook/dirplot/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/dirplot.svg)](https://pypi.org/project/dirplot/)
+[![Python](https://img.shields.io/pypi/pyversions/dirplot.svg)](https://pypi.org/project/dirplot/)
+[![Downloads](https://img.shields.io/pypi/dm/dirplot.svg)](https://pepy.tech/project/dirplot)
+[![License](https://img.shields.io/pypi/l/dirplot.svg)](https://pypi.org/project/dirplot/)
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=flat&logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/deeplook)
+
+**dirplot** creates nested treemap images for directory trees. It can display them in the system image viewer or inline in the terminal (iTerm2 and Kitty protocols, auto-detected). It also animates git history, watches live filesystems, and scans remote sources.
+
+![dirplot output](https://raw.githubusercontent.com/deeplook/dirplot/main/docs/dirplot.png)
+
+## Features
+
+- Squarified treemap layout; file area proportional to size; ~500 extensions mapped to [GitHub Linguist](https://github.com/github/linguist) colours.
+- PNG and interactive SVG output; renders at terminal pixel size or a custom `WIDTHxHEIGHT`.
+- **Animate git history** (`dirplot git`), **watch live filesystems** (`dirplot watch`), and **replay event logs** (`dirplot replay`) — all output APNG or MP4.
+- Scan **SSH hosts**, **AWS S3**, **GitHub repos** (public and private), **Docker containers**, and **Kubernetes pods** — no extra deps beyond the respective CLI.
+- Read **archives** directly (zip, tar, 7z, rar, jar, whl, …) without unpacking.
+- Works on macOS, Linux, and Windows (WSL2 fully supported).
+
+## Installation
+
+```bash
+# Standalone tool (recommended)
+uv tool install dirplot
+
+# Into the current environment
+pip install dirplot
+```
+
+Optional extras: `pip install "dirplot[ssh]"`, `"dirplot[s3]"`, `"dirplot[libarchive]"`.
+
+`dirplot watch` uses [watchdog](https://github.com/gorakhargosh/watchdog) for filesystem monitoring — installed automatically as a dependency.
+
+`dirplot git` requires `git` on `PATH`. MP4 output (`dirplot git`, `dirplot watch`, `dirplot replay` with `--animate`) requires [ffmpeg](https://ffmpeg.org/) on `PATH`. `dirplot read-meta` on `.mp4` files also requires `ffprobe` (bundled with ffmpeg).
+
+## Quick start
+
+```bash
+dirplot map .                                                    # current directory
+dirplot map . --inline                                           # display in terminal
+dirplot map . --output treemap.png --no-show                     # save to file
+dirplot map . --log --inline                                     # log scale, inline
+dirplot map github://pallets/flask                               # GitHub repo
+dirplot map docker://my-container:/app                           # Docker container
+dirplot map project.zip                                          # archive file
+tree src/ | dirplot map                                          # pipe tree output
+
+dirplot git . -o history.mp4 --animate                           # full git history
+dirplot git . -o history.mp4 --animate --last 30d                # last 30 days
+dirplot git github://owner/repo -o h.mp4 --animate --last 7d    # GitHub, last week
+
+dirplot watch . --output treemap.png                             # live watch
+dirplot watch . --output treemap.mp4 --animate                   # record as MP4
+
+dirplot demo                                                     # run examples, save to ./demo/
+```
+
+## Documentation
+
+- [CLI reference](docs/CLI.md) — all commands, flags, and usage examples
+- [Remote access](docs/EXAMPLES.md) — SSH, S3, GitHub, Docker, Kubernetes
+- [Archives](docs/ARCHIVES.md) — supported formats and dependencies
+- [Python API](docs/API.md) — programmatic usage
+
+## Development
+
+```bash
+git clone https://github.com/deeplook/dirplot
+cd dirplot
+make test
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

dirplot-0.4.1/README.md

@@ -0,0 +1,80 @@
+# dirplot
+
+[![CI](https://github.com/deeplook/dirplot/actions/workflows/ci.yml/badge.svg)](https://github.com/deeplook/dirplot/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/dirplot.svg)](https://pypi.org/project/dirplot/)
+[![Python](https://img.shields.io/pypi/pyversions/dirplot.svg)](https://pypi.org/project/dirplot/)
+[![Downloads](https://img.shields.io/pypi/dm/dirplot.svg)](https://pepy.tech/project/dirplot)
+[![License](https://img.shields.io/pypi/l/dirplot.svg)](https://pypi.org/project/dirplot/)
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=flat&logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/deeplook)
+
+**dirplot** creates nested treemap images for directory trees. It can display them in the system image viewer or inline in the terminal (iTerm2 and Kitty protocols, auto-detected). It also animates git history, watches live filesystems, and scans remote sources.
+
+![dirplot output](https://raw.githubusercontent.com/deeplook/dirplot/main/docs/dirplot.png)
+
+## Features
+
+- Squarified treemap layout; file area proportional to size; ~500 extensions mapped to [GitHub Linguist](https://github.com/github/linguist) colours.
+- PNG and interactive SVG output; renders at terminal pixel size or a custom `WIDTHxHEIGHT`.
+- **Animate git history** (`dirplot git`), **watch live filesystems** (`dirplot watch`), and **replay event logs** (`dirplot replay`) — all output APNG or MP4.
+- Scan **SSH hosts**, **AWS S3**, **GitHub repos** (public and private), **Docker containers**, and **Kubernetes pods** — no extra deps beyond the respective CLI.
+- Read **archives** directly (zip, tar, 7z, rar, jar, whl, …) without unpacking.
+- Works on macOS, Linux, and Windows (WSL2 fully supported).
+
+## Installation
+
+```bash
+# Standalone tool (recommended)
+uv tool install dirplot
+
+# Into the current environment
+pip install dirplot
+```
+
+Optional extras: `pip install "dirplot[ssh]"`, `"dirplot[s3]"`, `"dirplot[libarchive]"`.
+
+`dirplot watch` uses [watchdog](https://github.com/gorakhargosh/watchdog) for filesystem monitoring — installed automatically as a dependency.
+
+`dirplot git` requires `git` on `PATH`. MP4 output (`dirplot git`, `dirplot watch`, `dirplot replay` with `--animate`) requires [ffmpeg](https://ffmpeg.org/) on `PATH`. `dirplot read-meta` on `.mp4` files also requires `ffprobe` (bundled with ffmpeg).
+
+## Quick start
+
+```bash
+dirplot map .                                                    # current directory
+dirplot map . --inline                                           # display in terminal
+dirplot map . --output treemap.png --no-show                     # save to file
+dirplot map . --log --inline                                     # log scale, inline
+dirplot map github://pallets/flask                               # GitHub repo
+dirplot map docker://my-container:/app                           # Docker container
+dirplot map project.zip                                          # archive file
+tree src/ | dirplot map                                          # pipe tree output
+
+dirplot git . -o history.mp4 --animate                           # full git history
+dirplot git . -o history.mp4 --animate --last 30d                # last 30 days
+dirplot git github://owner/repo -o h.mp4 --animate --last 7d    # GitHub, last week
+
+dirplot watch . --output treemap.png                             # live watch
+dirplot watch . --output treemap.mp4 --animate                   # record as MP4
+
+dirplot demo                                                     # run examples, save to ./demo/
+```
+
+## Documentation
+
+- [CLI reference](docs/CLI.md) — all commands, flags, and usage examples
+- [Remote access](docs/EXAMPLES.md) — SSH, S3, GitHub, Docker, Kubernetes
+- [Archives](docs/ARCHIVES.md) — supported formats and dependencies
+- [Python API](docs/API.md) — programmatic usage
+
+## Development
+
+```bash
+git clone https://github.com/deeplook/dirplot
+cd dirplot
+make test
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

dirplot-0.4.1/docs/API.md

@@ -0,0 +1,72 @@
+# 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 centres on `build_tree`, `create_treemap`, and `create_treemap_svg`:
+
+```python
+from pathlib import Path
+from dirplot import build_tree, create_treemap, create_treemap_svg
+
+root = build_tree(Path("/path/to/project"))
+
+# PNG — returns a BytesIO containing PNG bytes
+buf = create_treemap(root, width_px=1920, height_px=1080, colormap="tab20", cushion=True)
+Path("treemap.png").write_bytes(buf.read())
+
+# SVG — returns a BytesIO containing UTF-8 SVG bytes
+# Includes CSS hover highlight, a JS floating tooltip, and cushion gradient shading.
+buf = create_treemap_svg(root, width_px=1920, height_px=1080, cushion=True)
+Path("treemap.svg").write_bytes(buf.read())
+```
+
+To open a PNG in the system image viewer or display it inline in the terminal:
+
+```python
+from dirplot.display import display_window, display_inline
+
+buf.seek(0)
+display_window(buf)   # system viewer (works everywhere)
+
+buf.seek(0)
+display_inline(buf)   # inline in terminal (iTerm2 / Kitty / WezTerm)
+```
+
+In a Jupyter notebook, PNG output renders automatically via PIL:
+
+```python
+from PIL import Image
+buf = create_treemap(root, width_px=1280, height_px=720)
+Image.open(buf)  # Jupyter renders PIL images automatically via _repr_png_()
+```
+
+## Remote backends
+
+Each remote backend exposes a `build_tree_*` function that returns the same `Node` type accepted by `create_treemap`:
+
+```python
+# GitHub
+from dirplot.github import build_tree_github
+root, branch = build_tree_github("pallets", "flask", token="ghp_…", depth=4)
+
+# SSH
+from dirplot.ssh import connect, build_tree_ssh
+client = connect("prod.example.com", "alice", ssh_key="~/.ssh/prod_key")
+sftp = client.open_sftp()
+root = build_tree_ssh(sftp, "/var/www", depth=5)
+sftp.close(); client.close()
+
+# S3
+from dirplot.s3 import make_s3_client, build_tree_s3
+s3 = make_s3_client(profile="prod")          # authenticated
+s3 = make_s3_client(no_sign=True)            # public bucket
+root = build_tree_s3(s3, "my-bucket", "path/to/prefix/", depth=5)
+
+# Docker
+from dirplot.docker import build_tree_docker
+root = build_tree_docker("my-container", "/app", depth=5)
+
+# Kubernetes
+from dirplot.k8s import build_tree_pod
+root = build_tree_pod("my-pod", "/app", namespace="staging", container="main", depth=5)
+```