dirplot 0.1.0__tar.gz

dirplot-0.1.0/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv add:*)",
+      "Bash(uv run:*)",
+      "Bash(uv pip:*)",
+      "Bash(git mv:*)",
+      "Bash(LC_ALL=C sed:*)",
+      "Bash(find:*)"
+    ]
+  }
+}

dirplot-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug Report
+about: Report a bug
+labels: bug
+---
+
+## Description
+
+A clear description of the bug.
+
+## Steps to Reproduce
+
+1. ...
+2. ...
+
+## Expected Behavior
+
+What should happen.
+
+## Actual Behavior
+
+What actually happens.
+
+## Environment
+
+- Python version:
+- dirplot version:
+- OS:

dirplot-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature Request
+about: Suggest a feature
+labels: enhancement
+---
+
+## Description
+
+A clear description of the feature.
+
+## Use Case
+
+Why is this feature needed?
+
+## Proposed Solution
+
+How might this be implemented?

dirplot-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## Description
+
+<!-- Brief description of changes. -->
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Checklist
+
+- [ ] Tests pass (`make test`)
+- [ ] Linting passes (`make lint`)
+- [ ] Documentation updated (if needed)

dirplot-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

dirplot-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Format check
+        run: uv run ruff format --check src tests
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Type check
+        run: uv run mypy src
+
+      - name: Test
+        run: uv run pytest --cov=src --cov-report=xml

dirplot-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: uv publish

dirplot-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Tools
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project-specific
+NOTES.md
+TASKS.md
+tests/example_dirplot.png

dirplot-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

dirplot-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

dirplot-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+
+## [0.1.0] - 2026-03-06
+
+### Added
+
+- Nested squarified treemap rendered as a PNG at the exact pixel dimensions of the terminal window.
+- Inline terminal display via iTerm2 and Kitty graphics protocols, auto-detected at runtime; supports iTerm2, WezTerm, Warp, Hyper, Kitty, and Ghostty.
+- System-viewer fallback (`open` / `xdg-open`) as the default display mode.
+- File-extension colours from the GitHub Linguist palette (~500 known extensions); unknown extensions fall back to a stable MD5-derived colour from the chosen colormap.
+- Van Wijk quadratic cushion shading giving each tile a raised 3-D look (`--cushion`, on by default).
+- Bundled JetBrains Mono fonts for crisp directory labels at any size.
+- CLI options: `--output`, `--show/--no-show`, `--inline`, `--legend`, `--font-size`, `--colormap`, `--exclude`, `--size`, `--header/--no-header`, `--cushion/--no-cushion`, `--log`.
+- Full test suite (65 tests), strict mypy, ruff linting, pre-commit hooks, and CI on Python 3.10–3.13.

dirplot-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+## Development Setup
+
+```bash
+git clone https://github.com/deeplook/dirplot
+cd dirplot
+uv sync --all-extras
+uv run pre-commit install
+```
+
+## Code Style
+
+This project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting, and [mypy](https://mypy.readthedocs.io/) for type checking.
+
+```bash
+make format   # auto-format and fix lint issues
+make lint     # check only (no changes)
+```
+
+## Testing
+
+```bash
+make test       # run the test suite
+make coverage   # run with coverage report
+```
+
+Target: 90 % line coverage.
+
+## Submitting Changes
+
+1. Fork the repository and create a feature branch (`feature/my-thing`).
+2. Make your changes, add tests if needed.
+3. Run `make lint` and `make test` — both must pass.
+4. Open a pull request against `main`.

dirplot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dinu Gherman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dirplot-0.1.0/Makefile

@@ -0,0 +1,38 @@
+.PHONY: install lint format test coverage clean install-tool check-all publish-test publish
+
+install:
+	uv sync --all-extras
+
+lint:
+	uv run ruff check src tests
+	uv run mypy src
+
+format:
+	uv run ruff format src tests
+	uv run ruff check --fix src tests
+
+test:
+	uv run --all-extras pytest
+
+coverage:
+	uv run --all-extras pytest --cov=src --cov-report=html --cov-report=term
+
+clean:
+	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 {} +
+
+install-tool:
+	uv tool install --reinstall .
+
+publish-test:
+	uv build
+	uv publish --index testpypi --token $(TEST_PYPI_TOKEN)
+
+publish:
+	uv build
+	uv publish --token $(PYPI_TOKEN)
+
+check-all: install format lint test clean
+	@echo "All checks passed!"

dirplot-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: dirplot
+Version: 0.1.0
+Summary: Static treemap bitmaps for directory trees, displayed as inline terminal images
+Project-URL: Repository, https://github.com/deeplook/dirplot
+License: MIT
+License-File: LICENSE
+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: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: pillow>=9.0
+Requires-Dist: squarify>=0.4
+Requires-Dist: typer>=0.9
+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'
+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 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)
+
+## Installation
+
+```bash
+# As a standalone tool (recommended)
+uv tool install dirplot
+
+# Into the current environment
+pip install dirplot
+```
+
+### From GitHub
+
+```bash
+# As a standalone tool
+uv tool install git+https://github.com/deeplook/dirplot
+
+# Into the current environment
+pip install git+https://github.com/deeplook/dirplot
+```
+
+## Usage
+
+```bash
+# Show dirplot for the current directory (opens image in system viewer)
+dirplot .
+
+# Save to a file without displaying
+dirplot . --output dirplot.png --no-show
+
+# Display inline (protocol auto-detected: iTerm2, Kitty, Ghostty)
+dirplot . --inline
+
+# Exclude directories
+dirplot . --exclude .venv --exclude .git
+
+# Use a different colormap and larger directory labels
+dirplot . --colormap Set2 --font-size 18
+
+# Render at a fixed resolution instead of terminal size
+dirplot . --size 1920x1080 --output dirplot.png --no-show
+
+# Don't apply cushion shading — makes tiles look flat
+dirplot . --no-cushion
+```
+
+### Options
+
+| Flag | Short | Default | Description |
+|---|---|---|---|
+| `--output` | `-o` | — | Save PNG to this path |
+| `--show/--no-show` | | `--show` | Display the image after rendering |
+| `--inline` | | off | Display in terminal (protocol auto-detected) |
+| `--legend/--no-legend` | | `--no-legend` | Show file-extension colour legend |
+| `--font-size` | `-s` | `12` | Directory label font size in pixels |
+| `--colormap` | `-c` | `tab20` | Matplotlib colormap for unknown extensions |
+| `--exclude` | `-e` | — | Path to exclude (repeatable) |
+| `--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 |
+
+## Inline Display
+
+The `--inline` flag renders the image directly in the terminal. The protocol is auto-detected at runtime: terminals that support the [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/) use APC chunks (`ESC_G…`); all others fall back to the [iTerm2 inline image protocol](https://iterm2.com/documentation-images.html) (`ESC]1337;File=…`).
+
+| Terminal | Platform | Protocol |
+|---|---|---|
+| [iTerm2](https://iterm2.com/) | macOS | iTerm2 |
+| [WezTerm](https://wezfurlong.org/wezterm/) | macOS, Linux, Windows | 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.
+
+> **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.
+
+## 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.
+
+## Development
+
+```bash
+git clone https://github.com/deeplook/dirplot
+cd dirplot
+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.0/README.md

@@ -0,0 +1,118 @@
+# 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 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)
+
+## Installation
+
+```bash
+# As a standalone tool (recommended)
+uv tool install dirplot
+
+# Into the current environment
+pip install dirplot
+```
+
+### From GitHub
+
+```bash
+# As a standalone tool
+uv tool install git+https://github.com/deeplook/dirplot
+
+# Into the current environment
+pip install git+https://github.com/deeplook/dirplot
+```
+
+## Usage
+
+```bash
+# Show dirplot for the current directory (opens image in system viewer)
+dirplot .
+
+# Save to a file without displaying
+dirplot . --output dirplot.png --no-show
+
+# Display inline (protocol auto-detected: iTerm2, Kitty, Ghostty)
+dirplot . --inline
+
+# Exclude directories
+dirplot . --exclude .venv --exclude .git
+
+# Use a different colormap and larger directory labels
+dirplot . --colormap Set2 --font-size 18
+
+# Render at a fixed resolution instead of terminal size
+dirplot . --size 1920x1080 --output dirplot.png --no-show
+
+# Don't apply cushion shading — makes tiles look flat
+dirplot . --no-cushion
+```
+
+### Options
+
+| Flag | Short | Default | Description |
+|---|---|---|---|
+| `--output` | `-o` | — | Save PNG to this path |
+| `--show/--no-show` | | `--show` | Display the image after rendering |
+| `--inline` | | off | Display in terminal (protocol auto-detected) |
+| `--legend/--no-legend` | | `--no-legend` | Show file-extension colour legend |
+| `--font-size` | `-s` | `12` | Directory label font size in pixels |
+| `--colormap` | `-c` | `tab20` | Matplotlib colormap for unknown extensions |
+| `--exclude` | `-e` | — | Path to exclude (repeatable) |
+| `--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 |
+
+## Inline Display
+
+The `--inline` flag renders the image directly in the terminal. The protocol is auto-detected at runtime: terminals that support the [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/) use APC chunks (`ESC_G…`); all others fall back to the [iTerm2 inline image protocol](https://iterm2.com/documentation-images.html) (`ESC]1337;File=…`).
+
+| Terminal | Platform | Protocol |
+|---|---|---|
+| [iTerm2](https://iterm2.com/) | macOS | iTerm2 |
+| [WezTerm](https://wezfurlong.org/wezterm/) | macOS, Linux, Windows | 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.
+
+> **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.
+
+## 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.
+
+## Development
+
+```bash
+git clone https://github.com/deeplook/dirplot
+cd dirplot
+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.0/SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+|---------|--------------------|
+| 0.1.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+Please do **not** create a public GitHub issue for security vulnerabilities.
+
+Instead, open a [GitHub Security Advisory](https://github.com/deeplook/dirplot/security/advisories/new)
+or email the maintainer directly.