unhog 0.5.0__tar.gz

unhog-0.5.0/DEVELOPMENT.md

@@ -0,0 +1,275 @@
+# Developing Unhog
+
+User documentation is in [README.md](README.md) and [USAGE.md](USAGE.md). This page covers running from
+source, testing, building the standalone exe and publishing releases.
+
+## Requirements
+
+- Windows, Python 3.9+
+- `pip install -r requirements.txt` (only dependency: [Dear PyGui](https://github.com/hoffstadt/DearPyGui))
+
+Alternatively `pip install -e .` installs the checkout as an editable package,
+which also puts an `unhog` command on the path (the same GUI entry point the
+PyPI package provides).
+
+## Run from source
+
+```
+python -m unhog            # scans %OneDrive% (the home folder on Linux and macOS)
+python -m unhog D:\Other   # scans another folder
+```
+
+or double-click `Unhog.pyw`.
+
+## Demo mode
+
+```
+python -m unhog --demo
+```
+
+shows a made-up but plausible OneDrive folder tree instead of scanning the
+disk (the built exe accepts `--demo` too). Use it to try the UI without a
+cloud-synced folder or to reproduce a layout issue with data that can be
+shared. The tree comes from `unhog/demo.py`: a fixed random seed generates the
+same names and sizes every time, and modification times are relative to the
+current time, so the **Modified** filter behaves the same whenever it is run.
+Nothing is read from or written to disk; *Open in Explorer* on a demo item
+therefore opens nothing useful.
+
+The demo "scan" is not instant: `demo_scan` replays the generated tree file by
+file through the same `TreeBuilder` the real scanner uses, spread over about
+8 seconds (`DEMO_SCAN_SECONDS`), so the live-updating treemap can be watched
+filling in. Callers that need the tree at once pass `duration=0`, as the tests
+and the screenshot tool do. `demo_disk_usage` supplies made-up drive figures
+for the free-space tile.
+
+## Layout
+
+- `unhog/scanner.py` walks the folder tree and builds the size model. Its
+  `TreeBuilder` adds each folder's files to the totals of all folders above
+  as soon as the folder is listed and reports the growing tree to a progress
+  callback, so the app can draw the treemap while the scan is still running.
+- `unhog/treemap.py` lays out the squarified treemap and does hit testing.
+- `unhog/app.py` is the Dear PyGui user interface.
+- `unhog/win_dialogs.py` wraps the native Windows folder picker via ctypes.
+- `unhog/demo.py` generates the made-up folder tree for demo mode and screenshots.
+- `tools/make_screenshots.py` renders the README screenshots from that tree.
+- `tests/` holds unit tests for the scanner, the treemap layout and the demo tree.
+
+## How "local storage" is detected
+
+A OneDrive placeholder that is online-only carries the Win32 attribute
+`FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS`. Files without it are hydrated and use
+local disk. The scanner reads attributes from the directory listing
+(`os.scandir`) and never opens files, so scanning does not trigger downloads.
+
+This attribute only exists on Windows. On other platforms every file currently
+counts as local, so the app degrades to a plain disk-usage treemap.
+
+The scan loop in `_scan_dir` runs once per entry of the scanned tree, so it
+is kept lean: on Windows the entry's kind (folder, file, symlink or junction)
+is read from the attributes the directory listing already supplied, with no
+per-entry method calls or extra system calls, and a folder's files are added
+to the tree in one batch (`TreeBuilder.add_files`), so the folders above are
+updated once per folder rather than once per file. Roughly two thirds of a
+warm-cache scan's time is now the directory listing itself.
+
+## Drawing while scanning
+
+The scan runs in a worker thread and grows the tree in place; the UI thread
+lays out and draws that same tree while the scan runs, at most every
+`LIVE_REDRAW_S` seconds and, after a slow redraw (very large trees), no sooner
+than `LIVE_REDRAW_BUDGET` times the redraw's own duration. No lock is taken:
+attribute updates are atomic under the GIL, and `TreeBuilder` adds a folder's
+files to the totals of the folders above before appending them to the
+folder's children, so a folder never shows less than its visible contents. A
+redraw may see a folder whose children do not yet add up to its total; the
+next redraw corrects it.
+
+The two threads do not run in parallel: both are Python code, so the GIL
+serializes them, and every millisecond the UI thread spends laying out or
+drawing is a millisecond the scan stands still (more threads would not help;
+only a separate process would, at the cost of shipping the tree across). The
+redraw limits above therefore double as a cap on how much the live view slows
+the scan: with a redraw taking `t`, redraws take at most
+`t / max(LIVE_REDRAW_S, LIVE_REDRAW_BUDGET * t)` of the time, under a tenth
+either way. The layout weighs every child of every visible folder on each
+redraw, so `redraw` uses a C-level attribute getter as the weight when no
+filter is active, and `make_aggregate` sums the folded-away small items in a
+single pass; for a 650,000-file tree a redraw takes about 60 ms. The drive figures behind the optional
+free-space tile and the whole-drive progress bar come from `shutil.disk_usage`,
+fetched by the same worker before the scan starts.
+
+*Rescan* in the right-click menu scans one folder again in place:
+`scanner.detach` takes the old subtree's numbers out of the folders above and
+unlinks it, an empty node is attached where it was, and `scanner.scan_into`
+fills that node, propagating totals upwards as usual, so the treemap shows the
+folder filling in. `scanner.refresh_upwards` then restores child order, newest
+file and pinned state up the chain. The demo uses `demo_rescan`, which replays
+the matching part of the demo tree.
+
+Dear PyGui normally runs widget callbacks on its own thread. The app switches
+that off (`manual_callback_management`) and runs the queued callbacks itself
+at the start of every frame, so button, combo and mouse handlers execute on
+the UI thread and can never rebuild the drawlist while a live redraw is in
+progress. Mouse moves only set a flag; the hover tooltip is redrawn once per
+frame.
+
+## Display scaling
+
+`win_dialogs.ui_scale` declares the process DPI-aware (otherwise Windows
+renders it at 96 DPI and stretches the bitmap, which blurs all text) and
+returns the display scale. `app.py` calls it at import time, before the
+viewport exists, and puts every pixel size through `px()`, so fonts, widget
+widths and treemap paddings keep their physical size at 100%, 150% or 200%
+scaling. Setting `UNHOG_SCALE` (for example `1.25`) overrides the detected
+scale; the screenshot tool sets it to `1` so the images do not depend on the
+machine that renders them.
+
+## Progress estimate
+
+`TreeBuilder.progress` judges how far a scan has got from folders alone, since
+nothing is known about a folder's size before it is scanned. `enter_dir`
+records how many subfolders a folder has and `finish_dir` counts them off; the
+estimate is the share of the root's subfolders finished, plus the current
+one's share times the same estimate one level down, and so on. It never goes
+backwards and reaches 1 when the root is finished. When a whole drive is
+scanned the app ignores it and shows bytes found against the drive's used
+bytes instead, which is exact.
+
+## Tests
+
+```
+python -m unittest discover -s tests
+```
+
+## Building the release files
+
+The exe needs no Python on the target machine. Use a regular python.org
+install (not the Microsoft Store one) to build it:
+
+```
+python -m venv .venv-build
+.venv-build\Scripts\pip install -r requirements.txt pyinstaller
+.venv-build\Scripts\python build_exe.py
+```
+
+This produces two files in `dist\`:
+
+- `Unhog.zip` (about 11 MB): PyInstaller's one-folder build, a folder
+  `Unhog` with a small `Unhog.exe` and its runtime in `_internal`. This is
+  the download the README points to. It runs in place, which keeps Windows
+  Defender's heuristics much quieter than the single-file build.
+- `Unhog.exe` (about 12 MB): the single-file build. It unpacks itself to a
+  temp folder on every start, which Defender's machine-learning detection
+  has flagged as a false positive in the past.
+
+Both are windowed (no console) and take an optional folder argument like
+`python -m unhog` does. The zip's name has no version in it so that the
+README's link to the latest release keeps working; the version is in the
+window title and on the release page.
+
+## Version number
+
+There is no version number in the source. The version shown in the window
+title comes from git:
+
+- Running from a source checkout, `unhog/__init__.py` asks git directly, so a
+  tagged commit reports `0.1.0` and later commits something like
+  `0.1.0-3-g1a2b3c4`, with `-dirty` appended for uncommitted changes. Git is
+  consulted first so that a leftover `unhog/_version.py` from an earlier
+  build cannot show a stale version.
+- `build_exe.py` runs `git describe --tags` (or uses the `UNHOG_VERSION`
+  environment variable if set) and writes the result to `unhog/_version.py`,
+  which is packaged into the exe and ignored by git.
+- The PyPI package gets its version from
+  [setuptools-scm](https://setuptools-scm.readthedocs.io/), configured in
+  `pyproject.toml`, which reads the same tag (`v0.4.1` gives `0.4.1`; an
+  untagged commit gives a PEP 440 version like `0.4.2.dev3+g1a2b3c4`) and
+  writes the same `unhog/_version.py` into the wheel. When running from an
+  installed package that file supplies the version; failing that, the
+  package metadata does.
+- Without any of these the version is `dev`.
+
+The release workflow passes the tag name as `UNHOG_VERSION`, so a release
+built from tag `v0.2.0` shows "Unhog 0.2.0".
+
+## Updating the screenshots
+
+The images in `docs/images` are rendered from the demo tree, so they never
+show anyone's real files, and they can be regenerated after any change to the
+look of the app:
+
+```
+python tools/make_screenshots.py
+```
+
+This opens the app window briefly, drives it through the scenes listed in
+`tools/make_screenshots.py` (home view, a folder zoomed in, the "Older than
+1 year" filter, "Local files only" unchecked, and "Show free space" checked) and writes one PNG per
+scene using Dear PyGui's frame-buffer capture. It must run on Windows with
+Segoe UI installed so the text matches what users see. The window is set to
+a fixed size, so the images have the same dimensions every time. Re-render
+after changing anything visible (colors, fonts, layout rules, toolbar) and
+commit the PNGs together with the change. The dates in tooltips shift with the
+time of rendering, which is expected.
+
+To add a scene, add a block to `ScreenshotApp.shoot()`: navigate with
+`set_view`, `set_modified`, `set_local_only` or `set_show_free`, call `hover` on the node to
+show a tooltip for, then `save` with the file name. Reference the new image
+from `USAGE.md` (or `README.md` for the overview image). To change what the demo tree contains, edit `unhog/demo.py`
+and run the tests, which check that the tree is internally consistent.
+
+## Making a release
+
+Pushing a tag that starts with `v` runs the GitHub Actions workflow in
+`.github/workflows/release.yml`, which builds the exe on a Windows runner, runs
+the tests, and attaches `Unhog.zip` and `Unhog.exe` to a GitHub release
+for that tag:
+
+```
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+If a release for the tag already exists (e.g. one created by hand on GitHub),
+the exe is added to it. The tag name is the version, so nothing in the source
+needs to be changed before tagging.
+
+The download link in the README points at the latest release's `Unhog.zip`
+asset, so it updates automatically whenever a new release is published.
+
+### PyPI
+
+The same workflow has a second job, `pypi`, which runs after the exe build
+and tests succeed on a tag. It builds the sdist and wheel with
+`python -m build`, checks them with `twine check`, and uploads them to
+[PyPI](https://pypi.org/project/unhog/) with
+[trusted publishing](https://docs.pypi.org/trusted-publishers/), so no API
+token is stored in the repository. This needs a one-time setup:
+
+1. On PyPI, log in and open *Your account*, *Publishing*. Under *Add a new
+   pending publisher* choose GitHub and enter: PyPI project name `unhog`,
+   owner `lassoan`, repository name `unhog`, workflow name `release.yml`,
+   environment name `pypi`. (Once the project exists, the same form is under
+   the project's *Manage*, *Publishing* page.)
+2. On GitHub, in the repository's *Settings*, *Environments*, create an
+   environment named `pypi`. Optionally restrict it to tags matching `v*` or
+   require a reviewer; that is where a manual approval step for PyPI uploads
+   would go.
+
+After that, every `v*` tag publishes to PyPI. A version can only be uploaded
+once; to fix a broken release, tag a new patch version rather than re-tagging.
+
+To build and check the package locally (the files land in `dist/`):
+
+```
+pip install build twine
+python -m build
+python -m twine check dist/*
+```
+
+To try the upload path without touching the real index, `python -m twine
+upload --repository testpypi dist/*` publishes to
+[TestPyPI](https://test.pypi.org/), which needs a separate account and API
+token there.

unhog-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andras Lasso
+
+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.

unhog-0.5.0/MANIFEST.in

@@ -0,0 +1,5 @@
+# setuptools-scm puts every git-tracked file into the sdist; leave out what a
+# source install does not need (the screenshots alone are over a megabyte).
+prune docs
+prune .github
+exclude .gitignore

unhog-0.5.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: unhog
+Version: 0.5.0
+Summary: Treemap of the files that use local disk space in OneDrive, Dropbox and SharePoint folders
+Author: Andras Lasso
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lassoan/unhog
+Project-URL: Documentation, https://github.com/lassoan/unhog/blob/main/USAGE.md
+Project-URL: Changelog, https://github.com/lassoan/unhog/releases
+Project-URL: Issues, https://github.com/lassoan/unhog/issues
+Keywords: onedrive,dropbox,sharepoint,files-on-demand,treemap,disk-usage,disk-space
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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 :: Desktop Environment :: File Managers
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dearpygui>=2.0
+Dynamic: license-file
+
+# Unhog
+
+Reclaim space on your disk hogged by OneDrive, Dropbox, SharePoint offline files.
+
+Unhog draws a SpaceMonger-style treemap of the files in a cloud-synced folder
+that actually occupy local disk space. "Files On-Demand" keeps most files
+online-only; Unhog shows only the hydrated ones, so you can see where the
+local space goes and free it up.
+
+![Unhog showing where the local space in a OneDrive folder goes](https://raw.githubusercontent.com/lassoan/unhog/main/docs/images/home.png)
+
+The treemap fills in while the folder is being scanned, so large folders can
+be explored right away, with a progress bar showing how far the scan has got.
+Optionally the free space on the drive is drawn next to the folder, on the
+same scale, to show how much the local copies matter.
+
+## Download
+
+**[Download Unhog.zip (latest release)](https://github.com/lassoan/unhog/releases/latest/download/Unhog.zip)**
+
+Requires Windows 10 or 11. No installation needed. All releases, with release
+notes, are listed on the [releases page](https://github.com/lassoan/unhog/releases).
+Each release also offers `Unhog.exe`, the same program packed into a single
+file; it is handy for copying around, but Windows Defender is more likely to
+mistrust it, so the zip is the recommended download.
+
+The files are not code-signed. When you run Unhog the first time, Windows
+SmartScreen may show "Windows protected your PC". Click **More info**, then
+**Run anyway**. If Defender removes the file as a suspected threat instead
+(a false positive that new unsigned programs sometimes trigger), open Windows
+Security, *Protection history*, find the entry and choose *Restore* or
+*Allow*.
+
+## Run
+
+Unzip `Unhog.zip` anywhere, for example into your Documents or
+Downloads folder. This creates a folder named `Unhog`. Open it and double-click
+`Unhog.exe`. It scans your OneDrive folder and shows the treemap.
+
+Keep `Unhog.exe` together with the `_internal` folder next to it; the program
+does not run if the exe is copied out on its own. To put it on the desktop or
+Start menu, right-click `Unhog.exe` and create a shortcut.
+
+To scan a different folder, use the **Browse...** button, or start it from a
+command prompt with the folder as argument:
+
+```
+Unhog.exe D:\Other
+```
+
+## Install with pip
+
+If Python 3.9 or later is installed, Unhog can also be installed from
+[PyPI](https://pypi.org/project/unhog/) instead of downloading the zip:
+
+```
+pip install unhog
+unhog
+```
+
+or, to keep it in its own environment, `pipx install unhog`. The `unhog`
+command takes the same optional folder argument as the exe. Windows Defender
+and SmartScreen have nothing to say about this route, since no unsigned exe is
+involved.
+
+## Freeing up space
+
+Unhog only shows where the space goes; it does not delete or change anything.
+To free the space a file or folder uses, right-click it in Unhog and choose
+*Open folder in Explorer* (the item is selected there), then in Explorer
+right-click it and choose **Free up space**. The file stays in
+the cloud and is downloaded again when you open it. Back in Unhog, right-click
+the folder and choose *Rescan* to see the result without scanning everything
+again.
+
+## How to use
+
+Hover a rectangle for details, double-click a folder to zoom in, right-click for
+options. The toolbar filters by modification time, size and local storage.
+All controls and settings are explained in
+[USAGE.md](https://github.com/lassoan/unhog/blob/main/USAGE.md).
+
+## How it works
+
+Unhog asks Windows which files in the folder are online-only placeholders and
+which are actually present on disk. It reads only the directory listing and
+never opens files, so scanning does not download anything.
+
+It is tested with OneDrive, OneDrive for Business (SharePoint), and Dropbox
+but it should be compatible with other cloud storage providers as well.
+
+## Privacy
+
+Unhog runs entirely on your PC, does not connect to the internet, and does not
+send any information anywhere.
+
+## For developers
+
+Running from source, tests, building the exe and making releases are described
+in [DEVELOPMENT.md](https://github.com/lassoan/unhog/blob/main/DEVELOPMENT.md).
+
+## License
+
+[MIT](https://github.com/lassoan/unhog/blob/main/LICENSE)

unhog-0.5.0/README.md

@@ -0,0 +1,104 @@
+# Unhog
+
+Reclaim space on your disk hogged by OneDrive, Dropbox, SharePoint offline files.
+
+Unhog draws a SpaceMonger-style treemap of the files in a cloud-synced folder
+that actually occupy local disk space. "Files On-Demand" keeps most files
+online-only; Unhog shows only the hydrated ones, so you can see where the
+local space goes and free it up.
+
+![Unhog showing where the local space in a OneDrive folder goes](https://raw.githubusercontent.com/lassoan/unhog/main/docs/images/home.png)
+
+The treemap fills in while the folder is being scanned, so large folders can
+be explored right away, with a progress bar showing how far the scan has got.
+Optionally the free space on the drive is drawn next to the folder, on the
+same scale, to show how much the local copies matter.
+
+## Download
+
+**[Download Unhog.zip (latest release)](https://github.com/lassoan/unhog/releases/latest/download/Unhog.zip)**
+
+Requires Windows 10 or 11. No installation needed. All releases, with release
+notes, are listed on the [releases page](https://github.com/lassoan/unhog/releases).
+Each release also offers `Unhog.exe`, the same program packed into a single
+file; it is handy for copying around, but Windows Defender is more likely to
+mistrust it, so the zip is the recommended download.
+
+The files are not code-signed. When you run Unhog the first time, Windows
+SmartScreen may show "Windows protected your PC". Click **More info**, then
+**Run anyway**. If Defender removes the file as a suspected threat instead
+(a false positive that new unsigned programs sometimes trigger), open Windows
+Security, *Protection history*, find the entry and choose *Restore* or
+*Allow*.
+
+## Run
+
+Unzip `Unhog.zip` anywhere, for example into your Documents or
+Downloads folder. This creates a folder named `Unhog`. Open it and double-click
+`Unhog.exe`. It scans your OneDrive folder and shows the treemap.
+
+Keep `Unhog.exe` together with the `_internal` folder next to it; the program
+does not run if the exe is copied out on its own. To put it on the desktop or
+Start menu, right-click `Unhog.exe` and create a shortcut.
+
+To scan a different folder, use the **Browse...** button, or start it from a
+command prompt with the folder as argument:
+
+```
+Unhog.exe D:\Other
+```
+
+## Install with pip
+
+If Python 3.9 or later is installed, Unhog can also be installed from
+[PyPI](https://pypi.org/project/unhog/) instead of downloading the zip:
+
+```
+pip install unhog
+unhog
+```
+
+or, to keep it in its own environment, `pipx install unhog`. The `unhog`
+command takes the same optional folder argument as the exe. Windows Defender
+and SmartScreen have nothing to say about this route, since no unsigned exe is
+involved.
+
+## Freeing up space
+
+Unhog only shows where the space goes; it does not delete or change anything.
+To free the space a file or folder uses, right-click it in Unhog and choose
+*Open folder in Explorer* (the item is selected there), then in Explorer
+right-click it and choose **Free up space**. The file stays in
+the cloud and is downloaded again when you open it. Back in Unhog, right-click
+the folder and choose *Rescan* to see the result without scanning everything
+again.
+
+## How to use
+
+Hover a rectangle for details, double-click a folder to zoom in, right-click for
+options. The toolbar filters by modification time, size and local storage.
+All controls and settings are explained in
+[USAGE.md](https://github.com/lassoan/unhog/blob/main/USAGE.md).
+
+## How it works
+
+Unhog asks Windows which files in the folder are online-only placeholders and
+which are actually present on disk. It reads only the directory listing and
+never opens files, so scanning does not download anything.
+
+It is tested with OneDrive, OneDrive for Business (SharePoint), and Dropbox
+but it should be compatible with other cloud storage providers as well.
+
+## Privacy
+
+Unhog runs entirely on your PC, does not connect to the internet, and does not
+send any information anywhere.
+
+## For developers
+
+Running from source, tests, building the exe and making releases are described
+in [DEVELOPMENT.md](https://github.com/lassoan/unhog/blob/main/DEVELOPMENT.md).
+
+## License
+
+[MIT](https://github.com/lassoan/unhog/blob/main/LICENSE)

unhog-0.5.0/USAGE.md

@@ -0,0 +1,113 @@
+# How to use Unhog
+
+Download and run Unhog as described in [README.md](README.md). This page explains
+the controls and settings.
+
+The treemap appears as soon as the scan starts and fills in while it runs; a
+progress bar and the status line show how far it has got, and the folder title
+says "scanning". You can hover, zoom and use every control before the scan is
+finished. Sizes grow until the status line reports the final totals. For a
+whole drive (such as `C:\`) the progress bar compares the bytes found with the
+drive's used space; for a folder nothing says in advance how big it is, so the
+bar is an estimate from the folders found but not yet finished.
+
+- **Hover** a rectangle for its full path, local size and file counts.
+- **Double-click a folder** to zoom in: show only that folder's contents.
+  Double-click the background (or the current folder's title bar) to zoom out
+  one level. The breadcrumb row and the **Zoom out** / **Zoom full** buttons
+  navigate too; **Zoom full** returns to the whole scanned folder. **Back**
+  (button, or in the right-click menu) returns to the previously shown view,
+  step by step.
+- **Right-click** an item for a menu: **Back** (when there is a view to
+  return to) and *Zoom in* (the same as double-clicking a folder); then *Open
+  in Explorer* (folders), *Open folder in Explorer* (a file's folder, or a
+  folder's parent with the folder selected), *Copy path* and *Open Properties*
+  (the Windows Properties dialog); and *Rescan*, which reads just that folder
+  (for a file, its folder) again and updates the treemap in place, handy after
+  freeing space in Explorer; and *Hide*, which takes that folder out of the
+  treemap (see below). Entries that do not apply are left out. **Escape**
+  closes the menu (and the Settings window).
+- **Hide** (right-click menu, folders only) removes a folder from the display,
+  as if it were not there: the folders above it shrink accordingly, so the
+  rest of the treemap gets the space and the remaining items can be compared
+  without it. Use it to set aside folders that are known and wanted (a photo
+  archive, say) and see what else takes up space. Any number of folders can be
+  hidden; the status line counts them. While folders are hidden, an
+  **Unhide N folders (size)** button appears next to **Zoom full**, showing
+  how many folders are hidden and how much space they take together; click it
+  to show all of them again. Hiding is only a view setting: nothing is changed
+  on disk, and a new scan (**Browse...**, the folder box or the **Rescan**
+  button) starts with nothing hidden. Rescanning a folder from the right-click
+  menu keeps the hidden folders hidden.
+- **Browse...** / the folder box + **Rescan** scan a different folder.
+- **Modified** filters by last-modified time: "Older than …" (1 month to
+  5 years) or "Newer than …" (1 week to 1 year). Only matching files count
+  toward folder sizes and are drawn; folders act as containers for whatever
+  inside them matches. A folder's own time is the newest file anywhere inside
+  it (shown in the tooltip), so a folder whose newest file is older than the
+  cutoff shows in full under "Older than", while a folder with recent changes
+  shows just its old parts and is drawn gray to mark it as a container only.
+  The tooltip also shows each file's modification date and the unfiltered
+  sizes. Switching does not rescan.
+- **Local files only** (checked by default) sizes the treemap by bytes on local
+  disk and hides online-only placeholders. Uncheck it to see every file sized by
+  its full logical size; online-only files are drawn dimmed. Switching does not
+  rescan.
+- **Min size** (default 1 MB) hides files and folders smaller than the limit as
+  separate rectangles. Within each folder they are folded into one grey
+  "N smaller items" tile that carries their combined size, so the parent's area
+  stays accurate. Double-click that tile (or right-click it and choose *Zoom
+  in*) to view the folded items on their own; the limit shrinks with the
+  view, so they appear individually. Right-click the tile to open its folder
+  in Explorer. "Off" shows everything. The limit applies to the scanned root: when you drill into
+  a folder it shrinks in proportion to that folder's share of the total, so you
+  see the same level of detail at every depth. The effective limit for the
+  current folder is shown next to the dropdown.
+
+**Settings...** opens a dialog with the appearance settings, followed by an
+*About* section with the version, author and website (click the address to
+open it in your browser):
+
+- **Scale fonts and padding by folder size** (on by default) grows folder
+  titles (and file labels) with the item's share of the folder currently
+  shown, from 10 px up to 34 px, so the biggest space hogs jump out. Title
+  strips grow to match, and folder frames scale the same way: the folder shown
+  gets the full padding, smaller folders get proportionally thinner frames.
+- **Padding** (1 px to 32 px, default 12 px) sets how wide the frame is that
+  each folder draws around its children.
+- **Padding scaling** (Off to Extreme) sets how much thinner the frames of
+  smaller folders get: the percentage is what the smallest folders keep of the
+  chosen padding, from 100% (uniform) down to 5%. Default is Firm (20%).
+  Only applies while scaling by size is on.
+- **Show free space on the drive** (off by default) adds a hatched dark tile
+  for the free space on the drive the scanned folder is on, sized on the same
+  scale as the folder, so you can see at a glance how the space the files take
+  compares with what is left on the disk.
+  The tile appears only in the top-level view. Hover it for the exact numbers;
+  the status line shows them too.
+
+Files are colored by type (video, image, audio, document, archive, code, disk
+image, other) and shaded darker the deeper they sit.
+
+Text and controls follow the Windows display scaling. To make everything
+larger or smaller than that, start Unhog with the environment variable
+`UNHOG_SCALE` set, for example `set UNHOG_SCALE=1.25` before running it.
+
+Zoomed into a folder, with the tooltip for one of its subfolders:
+
+![Unhog zoomed into the Camera Roll folder](docs/images/folder.png)
+
+**Modified** set to "Older than 1 year". Gray folder titles mark folders that
+have newer files too and are shown only as containers:
+
+![Unhog showing only files older than a year](docs/images/older-than.png)
+
+**Local files only** unchecked: every file is sized by its full size and
+online-only files are dimmed:
+
+![Unhog showing all files, online-only ones dimmed](docs/images/all-files.png)
+
+**Show free space on the drive** checked: the free space on drive C: appears
+as a hatched tile next to the OneDrive folder, on the same scale:
+
+![Unhog showing the drive's free space next to the folder](docs/images/free-space.png)

unhog-0.5.0/Unhog.pyw

@@ -0,0 +1,10 @@
+"""Double-click launcher (no console window). Scans %OneDrive% by default (the home folder on Linux and macOS)."""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from unhog.app import main  # noqa: E402
+
+sys.exit(main())