dirplot 0.1.2__tar.gz → 0.2.0__tar.gz

{dirplot-0.1.2 → dirplot-0.2.0}/.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v6
@@ -36,3 +36,21 @@ jobs:
 
       - name: Test
         run: uv run pytest --cov=src --cov-report=xml
+
+  test-windows:
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python 3.10
+        run: uv python install 3.10
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Test
+        run: uv run pytest --cov=src --cov-report=xml

dirplot-0.2.0/.ipynb_checkpoints/Untitled-checkpoint.ipynb

@@ -0,0 +1,6 @@
+{
+ "cells": [],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

{dirplot-0.1.2 → dirplot-0.2.0}/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-09
+
+### Added
+
+- Support for Windows, incl. full test suite
+
+### Fixed
+
+- Improved README, Makefile
+
 ## [0.1.2] - 2026-03-06
 
 ### Fixed

dirplot-0.2.0/Makefile

@@ -0,0 +1,41 @@
+.PHONY: install lint format test coverage clean install-tool check-all publish-test publish help
+
+help:  ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf "  %-14s %s\n", $$1, $$2}'
+
+install:  ## Install all dependencies (including extras)
+	uv sync --all-extras
+
+format:  ## Auto-format and fix lint issues
+	uv run ruff format src tests
+	uv run ruff check --fix src tests
+
+lint:  ## Run ruff and mypy
+	uv run ruff check src tests
+	uv run --all-extras mypy src
+
+test:  ## Run the test suite
+	uv run --all-extras pytest
+
+coverage:  ## Run tests with HTML + terminal coverage report
+	uv run --all-extras pytest --cov=src --cov-report=html --cov-report=term
+
+check-all: install format lint test clean  ## Run format, lint, test, and clean
+	@echo "All checks passed!"
+
+install-tool:  ## Install dirplot as a uv tool (reinstall)
+	uv tool install --reinstall .
+
+clean:  ## Remove build artifacts and caches
+	rm -rf dist build *.egg-info
+	rm -rf .pytest_cache .mypy_cache .ruff_cache
+	rm -rf htmlcov .coverage coverage.xml
+	find . -type d -name __pycache__ -exec rm -rf {} +
+
+publish-test:  ## Build and publish to TestPyPI
+	uv build
+	uv publish --index testpypi --token $(TEST_PYPI_TOKEN)
+
+publish:  ## Build and publish to PyPI
+	uv build
+	uv publish --token $(PYPI_TOKEN)

{dirplot-0.1.2 → dirplot-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirplot
-Version: 0.1.2
+Version: 0.2.0
 Summary: Static treemap bitmaps for directory trees, displayed as inline terminal images
 Project-URL: Repository, https://github.com/deeplook/dirplot
 License: MIT
@@ -17,6 +17,7 @@ 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 :: Filesystems
 Classifier: Topic :: Terminals
@@ -46,12 +47,35 @@ Description-Content-Type: text/markdown
 
 **dirplot** creates static nested treemap images for directory trees. It can display them in the system image viewer (default, works everywhere) or inline inside the terminal using the [iTerm2 inline image protocol](https://iterm2.com/documentation-images.html) or the [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/) — detected automatically at runtime.
 
-Each rectangle represents a file; its **area** is proportional to the file size and its **colour** is determined by the file extension. Directories are shown as labelled, nested containers, mirroring the actual hierarchy.
-
 ![dirplot output](https://raw.githubusercontent.com/deeplook/dirplot/main/docs/dirplot.png)
 
+## Features
+
+- Directories are shown as labelled, nested containers, mirroring the actual hierarchy.
+- Squarified treemap layout — rectangles are as square as possible for easy reading.
+- File area proportional to file size; colour determined by file extension.
+- ~500 known extensions mapped to colours from the [GitHub Linguist](https://github.com/github/linguist) table; unknown extensions get an MD5-stable colour from any Matplotlib colormap.
+- Label colour (black/white) chosen automatically based on background luminance.
+- Output resolution matches the current terminal window pixel size (via `TIOCGWINSZ`), or a custom `WIDTHxHEIGHT`.
+- Van Wijk cushion shading gives tiles a raised 3-D appearance (optional).
+- Display via system image viewer or inline in the terminal (iTerm2 and Kitty protocols, auto-detected).
+- Save output to a PNG file with `--output`.
+- Exclude paths with `--exclude` (repeatable).
+- Works on macOS, Linux, and Windows; WSL2 fully supported.
+
+## How It Works
+
+1. Scans the directory tree, collecting each file's path, extension, and size in bytes.
+2. Computes a squarified dirplot layout recursively — directories allocate space for their children.
+3. Renders to a PNG via Pillow (PIL) at the exact pixel dimensions of the current terminal window (detected via `TIOCGWINSZ`), or at a custom size when `--size` is given.
+4. Displays via the system image viewer (`open` / `xdg-open`) or inline via an auto-detected terminal graphics protocol (iTerm2 or Kitty).
+
+Extension colours come from the [GitHub Linguist](https://github.com/github/linguist) language colour table (~500 known extensions). Unknown extensions fall back to an MD5-stable colour derived from the chosen `--colormap`. File label text is automatically black or white depending on the background luminance.
+
 ## Installation
 
+> **Note:** The recommended install methods below use [uv](https://docs.astral.sh/uv/). See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it yet. Alternatively, use `pip install dirplot` to install without uv.
+
 ```bash
 # As a standalone tool (recommended)
 uv tool install dirplot
@@ -70,6 +94,10 @@ uv tool install git+https://github.com/deeplook/dirplot
 pip install git+https://github.com/deeplook/dirplot
 ```
 
+## Platform Support
+
+This tool has been developed and tested on macOS and is CI-tested on Linux and Windows (Python 3.10+). The default `--show` mode works on all platforms. The `--inline` mode requires a terminal emulator that supports the iTerm2 or Kitty graphics protocol; on Windows, only [WezTerm](https://wezfurlong.org/wezterm/) currently qualifies. WSL2 is treated as Linux and has full support. Feedback and bug reports are welcome — please open an issue on GitHub.
+
 ## Usage
 
 ```bash
@@ -112,6 +140,7 @@ dirplot . --no-cushion
 | `--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 |
 
 ## Inline Display
 
@@ -120,24 +149,50 @@ The `--inline` flag renders the image directly in the terminal. The protocol is
 | Terminal | Platform | Protocol |
 |---|---|---|
 | [iTerm2](https://iterm2.com/) | macOS | iTerm2 |
-| [WezTerm](https://wezfurlong.org/wezterm/) | macOS, Linux, Windows | iTerm2 |
+| [WezTerm](https://wezfurlong.org/wezterm/) | macOS, Linux, Windows | Kitty & iTerm2 |
 | [Warp](https://www.warp.dev/) | macOS, Linux | iTerm2 |
 | [Hyper](https://hyper.is/) | macOS, Linux, Windows | iTerm2 |
 | [Kitty](https://sw.kovidgoyal.net/kitty/) | macOS, Linux | Kitty |
 | [Ghostty](https://ghostty.org/) | macOS, Linux | Kitty |
 
-The default mode (`--show`, no `--inline`) opens the PNG in the system viewer (`open` on macOS, `xdg-open` on Linux) and works in any terminal.
+The default mode (`--show`, no `--inline`) opens the PNG in the system viewer (`open` on macOS, `xdg-open` on Linux, system default on Windows) and works in any terminal.
 
-> **Note:** `--inline` does not work in AI coding assistants such as Claude Code, Cursor, or GitHub Copilot Chat. These tools intercept terminal output as plain text and do not implement any graphics protocol, so the escape sequences are either stripped or displayed as garbage. Use the default `--show` mode (system viewer) or `--output` to save the PNG to a file instead.
+> **Windows note:** Common Windows shells (PowerShell, cmd, Git Bash) and terminal emulators (Windows Terminal, ConEmu) do not support any inline image protocol. `--inline` will silently produce no output in these environments. [WezTerm](https://wezfurlong.org/wezterm/) is currently the only mainstream Windows terminal emulator that supports inline image rendering (via the Kitty graphics protocol). WSL2 is treated as Linux and has full support.
 
-## How It Works
+> **Note:** `--inline` does not work in AI coding assistants such as Claude Code, Cursor, or GitHub Copilot Chat. These tools intercept terminal output as plain text and do not implement any graphics protocol, so the escape sequences are either stripped or displayed as garbage. Use the default `--show` mode (system viewer) or `--output` to save the PNG to a file instead. Or use [Pi](https://pi.dev) where it is easily added as an extension.
 
-1. Scans the directory tree, collecting each file's path, extension, and size in bytes.
-2. Computes a squarified dirplot layout recursively — directories allocate space for their children.
-3. Renders to a PNG via Pillow (PIL) at the exact pixel dimensions of the current terminal window (detected via `TIOCGWINSZ`), or at a custom size when `--size` is given.
-4. Displays via the system image viewer (`open` / `xdg-open`) or inline via an auto-detected terminal graphics protocol (iTerm2 or Kitty).
+## Python API
 
-Extension colours come from the [GitHub Linguist](https://github.com/github/linguist) language colour table (~500 known extensions). Unknown extensions fall back to an MD5-stable colour derived from the chosen `--colormap`. File label text is automatically black or white depending on the background luminance.
+The public API is small — `build_tree`, `create_treemap`, and the display helpers:
+
+```python
+from pathlib import Path
+from dirplot.scanner import build_tree
+from dirplot.render import create_treemap
+
+# Build the tree and render to a PNG in memory
+root = build_tree(Path("/path/to/project"))
+buf = create_treemap(root, width_px=1920, height_px=1080, colormap="tab20", cushion=True)
+
+# Save to disk
+Path("treemap.png").write_bytes(buf.read())
+
+# In a Jupyter notebook: display inline as a cell output (no save needed)
+from PIL import Image
+Image.open(buf)  # Jupyter renders PIL images automatically via _repr_png_()
+```
+
+To open the result in the system image viewer or display it inline:
+
+```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)
+```
 
 ## Development
 
@@ -149,10 +204,6 @@ make test
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
 
-## Platform Support
-
-This tool has been developed and tested on macOS. Linux should work, and Windows support is untested. Feedback and bug reports from Linux and Windows users are very welcome — please open an issue on GitHub.
-
 ## License
 
 [MIT](LICENSE)

{dirplot-0.1.2 → dirplot-0.2.0}/README.md

@@ -9,12 +9,35 @@
 
 **dirplot** creates static nested treemap images for directory trees. It can display them in the system image viewer (default, works everywhere) or inline inside the terminal using the [iTerm2 inline image protocol](https://iterm2.com/documentation-images.html) or the [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/) — detected automatically at runtime.
 
-Each rectangle represents a file; its **area** is proportional to the file size and its **colour** is determined by the file extension. Directories are shown as labelled, nested containers, mirroring the actual hierarchy.
-
 ![dirplot output](https://raw.githubusercontent.com/deeplook/dirplot/main/docs/dirplot.png)
 
+## Features
+
+- Directories are shown as labelled, nested containers, mirroring the actual hierarchy.
+- Squarified treemap layout — rectangles are as square as possible for easy reading.
+- File area proportional to file size; colour determined by file extension.
+- ~500 known extensions mapped to colours from the [GitHub Linguist](https://github.com/github/linguist) table; unknown extensions get an MD5-stable colour from any Matplotlib colormap.
+- Label colour (black/white) chosen automatically based on background luminance.
+- Output resolution matches the current terminal window pixel size (via `TIOCGWINSZ`), or a custom `WIDTHxHEIGHT`.
+- Van Wijk cushion shading gives tiles a raised 3-D appearance (optional).
+- Display via system image viewer or inline in the terminal (iTerm2 and Kitty protocols, auto-detected).
+- Save output to a PNG file with `--output`.
+- Exclude paths with `--exclude` (repeatable).
+- Works on macOS, Linux, and Windows; WSL2 fully supported.
+
+## How It Works
+
+1. Scans the directory tree, collecting each file's path, extension, and size in bytes.
+2. Computes a squarified dirplot layout recursively — directories allocate space for their children.
+3. Renders to a PNG via Pillow (PIL) at the exact pixel dimensions of the current terminal window (detected via `TIOCGWINSZ`), or at a custom size when `--size` is given.
+4. Displays via the system image viewer (`open` / `xdg-open`) or inline via an auto-detected terminal graphics protocol (iTerm2 or Kitty).
+
+Extension colours come from the [GitHub Linguist](https://github.com/github/linguist) language colour table (~500 known extensions). Unknown extensions fall back to an MD5-stable colour derived from the chosen `--colormap`. File label text is automatically black or white depending on the background luminance.
+
 ## Installation
 
+> **Note:** The recommended install methods below use [uv](https://docs.astral.sh/uv/). See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it yet. Alternatively, use `pip install dirplot` to install without uv.
+
 ```bash
 # As a standalone tool (recommended)
 uv tool install dirplot
@@ -33,6 +56,10 @@ uv tool install git+https://github.com/deeplook/dirplot
 pip install git+https://github.com/deeplook/dirplot
 ```
 
+## Platform Support
+
+This tool has been developed and tested on macOS and is CI-tested on Linux and Windows (Python 3.10+). The default `--show` mode works on all platforms. The `--inline` mode requires a terminal emulator that supports the iTerm2 or Kitty graphics protocol; on Windows, only [WezTerm](https://wezfurlong.org/wezterm/) currently qualifies. WSL2 is treated as Linux and has full support. Feedback and bug reports are welcome — please open an issue on GitHub.
+
 ## Usage
 
 ```bash
@@ -75,6 +102,7 @@ dirplot . --no-cushion
 | `--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 |
 
 ## Inline Display
 
@@ -83,24 +111,50 @@ The `--inline` flag renders the image directly in the terminal. The protocol is
 | Terminal | Platform | Protocol |
 |---|---|---|
 | [iTerm2](https://iterm2.com/) | macOS | iTerm2 |
-| [WezTerm](https://wezfurlong.org/wezterm/) | macOS, Linux, Windows | iTerm2 |
+| [WezTerm](https://wezfurlong.org/wezterm/) | macOS, Linux, Windows | Kitty & iTerm2 |
 | [Warp](https://www.warp.dev/) | macOS, Linux | iTerm2 |
 | [Hyper](https://hyper.is/) | macOS, Linux, Windows | iTerm2 |
 | [Kitty](https://sw.kovidgoyal.net/kitty/) | macOS, Linux | Kitty |
 | [Ghostty](https://ghostty.org/) | macOS, Linux | Kitty |
 
-The default mode (`--show`, no `--inline`) opens the PNG in the system viewer (`open` on macOS, `xdg-open` on Linux) and works in any terminal.
+The default mode (`--show`, no `--inline`) opens the PNG in the system viewer (`open` on macOS, `xdg-open` on Linux, system default on Windows) and works in any terminal.
 
-> **Note:** `--inline` does not work in AI coding assistants such as Claude Code, Cursor, or GitHub Copilot Chat. These tools intercept terminal output as plain text and do not implement any graphics protocol, so the escape sequences are either stripped or displayed as garbage. Use the default `--show` mode (system viewer) or `--output` to save the PNG to a file instead.
+> **Windows note:** Common Windows shells (PowerShell, cmd, Git Bash) and terminal emulators (Windows Terminal, ConEmu) do not support any inline image protocol. `--inline` will silently produce no output in these environments. [WezTerm](https://wezfurlong.org/wezterm/) is currently the only mainstream Windows terminal emulator that supports inline image rendering (via the Kitty graphics protocol). WSL2 is treated as Linux and has full support.
 
-## How It Works
+> **Note:** `--inline` does not work in AI coding assistants such as Claude Code, Cursor, or GitHub Copilot Chat. These tools intercept terminal output as plain text and do not implement any graphics protocol, so the escape sequences are either stripped or displayed as garbage. Use the default `--show` mode (system viewer) or `--output` to save the PNG to a file instead. Or use [Pi](https://pi.dev) where it is easily added as an extension.
 
-1. Scans the directory tree, collecting each file's path, extension, and size in bytes.
-2. Computes a squarified dirplot layout recursively — directories allocate space for their children.
-3. Renders to a PNG via Pillow (PIL) at the exact pixel dimensions of the current terminal window (detected via `TIOCGWINSZ`), or at a custom size when `--size` is given.
-4. Displays via the system image viewer (`open` / `xdg-open`) or inline via an auto-detected terminal graphics protocol (iTerm2 or Kitty).
+## Python API
 
-Extension colours come from the [GitHub Linguist](https://github.com/github/linguist) language colour table (~500 known extensions). Unknown extensions fall back to an MD5-stable colour derived from the chosen `--colormap`. File label text is automatically black or white depending on the background luminance.
+The public API is small — `build_tree`, `create_treemap`, and the display helpers:
+
+```python
+from pathlib import Path
+from dirplot.scanner import build_tree
+from dirplot.render import create_treemap
+
+# Build the tree and render to a PNG in memory
+root = build_tree(Path("/path/to/project"))
+buf = create_treemap(root, width_px=1920, height_px=1080, colormap="tab20", cushion=True)
+
+# Save to disk
+Path("treemap.png").write_bytes(buf.read())
+
+# In a Jupyter notebook: display inline as a cell output (no save needed)
+from PIL import Image
+Image.open(buf)  # Jupyter renders PIL images automatically via _repr_png_()
+```
+
+To open the result in the system image viewer or display it inline:
+
+```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)
+```
 
 ## Development
 
@@ -112,10 +166,6 @@ make test
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
 
-## Platform Support
-
-This tool has been developed and tested on macOS. Linux should work, and Windows support is untested. Feedback and bug reports from Linux and Windows users are very welcome — please open an issue on GitHub.
-
 ## License
 
 [MIT](LICENSE)

dirplot-0.2.0/TASKS.md~

@@ -0,0 +1,25 @@
+## Tasks
+
+- [x] Write some function to scan a directory tree and find for each file the path, extension and size in bytes.
+- [x] Write a function that creates a bitmap with a treemap for that information. Make the color by file extension and the size of a rectangle representing a file according to the file size. Use Matplotlib.
+- [x] Write some typer CLI that accepts a root path for which to create the treemap.
+- [x] Save the treemap first in a PNG file.
+- [x] The PNG should have the same aspect ratio as the current terminal window in pixels. Needs some conversion from rows/cells to pixels.
+
+- [x] Make small example image and analyse the right margin where one or two pixel columns seem to be missing cause the effect that the outmost rectangle lacks its right line.
+- [x] Add a --size width,height option with a default based on the current terminal size.
+- [x] Chose filename label color like this: black if the file color converted to grayscale is between white and medium gray, else white
+- [x] Use GitHub Linguist color mappings for known file extensions instead of random colormap colors.
+- [x] Add Examples section to --help output.
+- [x] Add a `--header` (default) / `--no-header` option to print text lines before showing the plot inline or saving it.
+- [ ] Brainstorm about creating the same plots but for other types of input data where we have groups of elements, each with some category and size. Which examples would make the most sense? Write result into a file named OTHER_USECASES.md.
+- [ ] Brainstorm about creating the same plots but where the area of a file rectangle represents the age of the last modification, the bigger, the newer so to say. Write result into a file named FILE_AGE.md.
+- [ ] Try accessing remote directories via SSH as input.
+- [ ] Add a feature to take not only local directories as input but also remote repositories like github or gitlab.
+- [ ] Access remote directory trees via SSH using paramiko (incl. size and other attributes).
+- [ ] Support archive files (often compressed) as input, Z, zoo, zip, tar, tgz, tar.gz, tar.xz, txz using zipfile, tarfile, zlib, zoo, py7zr.
+- [ ] Add some option to cap file size and ignore larger files.
+- [ ] Think about creating the images in other formats, especially SVG/PDF.
+- [ ] Add a Features list before the Installation section to the README.md file.
+
+