Metadata-Version: 2.4
Name: pc-cleaner
Version: 1.6.0
Summary: Safe disk analytics, duplicate discovery, and offline reports
Author: Rituraj
License-Expression: MIT
Project-URL: Homepage, https://github.com/rituraj/pc-cleaner
Project-URL: Issues, https://github.com/rituraj/pc-cleaner/issues
Keywords: disk,storage,analytics,duplicate-files,cleanup,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# PC Cleaner

**PC Cleaner** is a safe, cross-platform disk analytics tool. It scans a drive or
folder and produces an offline HTML dashboard, JSON data, and a complete CSV
file inventory. It finds duplicate files and cleanup candidates, but it never
deletes or changes user files.

## Install

```bash
pip install pc-cleaner
```

PC Cleaner works on Windows, macOS, Linux desktops, WSL, and Linux VPS hosts.
On Windows it lists drive letters; on POSIX systems it lists useful mounted
filesystems while avoiding virtual kernel mounts such as `/proc`, `/sys`, and
`tmpfs`.

## Use

Launch the terminal dashboard:

```bash
pc-cleaner
```

The dashboard lists accessible drives with free-space information and includes
a folder browser. Select a drive, click a folder to make it the scan target,
or type a path manually. While scanning it shows the subprocess output, offers
a visible cancel button, and keeps the scan controls disabled until completion.

During scans, the dashboard shows the active phase, elapsed time, indexed file
and folder totals, data indexed, and files-per-second rate. Filesystem discovery
does not pretend to know an exact completion time; it displays an honest unknown
ETA until traversal is complete. Duplicate hashing has a known candidate count,
so it shows a real remaining-time estimate. When an HTML report completes, use
**Open HTML report** to open it directly in the default browser.

Check for an update from PyPI:

```bash
pc-cleaner update
```

This asks before installing. After a successful upgrade, restart PC Cleaner to
use the new release. For non-interactive automation only, use:

```bash
pc-cleaner update --yes
```

Run from scripts or CI:

```bash
pc-cleaner scan --drive D --open
pc-cleaner scan --path "D:\\Projects" --no-dups
pc-cleaner scan --path ~/Downloads --out ./reports
pc-cleaner scan --path /var --out ~/pc-cleaner-reports --no-dups --verbose
```

Compare two saved reports to see what grew or shrank:

```bash
pc-cleaner compare drive_report_D_old.json drive_report_D_new.json
pc-cleaner compare old.json new.json --json
```

Guard CI against a full volume (exit code 3 when the limit is crossed):

```bash
pc-cleaner scan --path D:\ --no-dups --quiet --fail-usage 90
```

Get ranked, read-only cleanup recommendations (and a script you review yourself):

```bash
pc-cleaner advise drive_report_D.json
pc-cleaner advise drive_report_D.json --script cleanup.ps1 --keep shortest
pc-cleaner advise drive_report_D.json --method hardlink --os posix --json
```

Monitor a volume and alert when it crosses a threshold:

```bash
pc-cleaner watch --path D:\ --interval 300 --max-usage 90
pc-cleaner watch --path /var --once --webhook https://example.test/hook
```

Use PC Cleaner as a library:

```python
from pc_cleaner import api
summary = api.scan(r"D:\\Projects", duplicates=True)
print(summary["totals"]["size"], summary["reclaimable_total"])
```

### Plugins

Drop a `*.py` file in `~/.pc-cleaner/plugins` to add a custom report section:

```python
def analyze(summary):
    return {"title": "My section",
            "html": "<p>Files: %s</p>" % summary["totals"]["files"]}
```

Use a named scan profile instead of repeating flags:

```bash
pc-cleaner scan --path D:\ --profile quick    # skip duplicate hashing + CSV
pc-cleaner scan --path D:\ --profile deep     # hash everything, top 100 rows
pc-cleaner scan --path D:\ --profile dev      # fast pass for developer machines
pc-cleaner scan --path D:\ --profile photos   # size-filtered photo dedupe
```

Explicit flags always override profile values.

### Configuration file

Optional defaults live in `~/.pc-cleaner/config.toml` (override with the
`PC_CLEANER_CONFIG` environment variable):

```toml
# PC Cleaner configuration
top = 100
threads = 8
min_dup_size = "2MB"
exclude = ["node_modules", ".git", "Windows"]
no_dups = false

[keybindings]
# Rebind dashboard keys (see tui.DEFAULT_BINDINGS for action names)
results = "r"
search = "/"
```

### Exit codes

| Code | Meaning |
| ---- | ------- |
| 0    | success |
| 1    | runtime error (scan or update failure) |
| 2    | invalid arguments / unsupported environment |
| 130  | interrupted by the user |

### Structured progress events

In `--verbose` mode the scanner additionally emits single-line JSON events on
stderr, prefixed with `#EVT `. Automation can consume these instead of scraping
human-readable text:

```text
#EVT {"v":1,"kind":"discovery","files":12500,"folders":1200,"bytes":471859200}
#EVT {"v":1,"kind":"dups","done":45,"total":100}
```


For an Ubuntu/Linux VPS over SSH, use command mode explicitly. If the terminal
is not interactive, `pc-cleaner` will show the equivalent CLI command instead
of trying to open a full-screen terminal interface.

The scan produces timestamped HTML, JSON, and CSV reports. The default report
location in the TUI is `%USERPROFILE%\Documents\PC Cleaner Reports` (Windows) or
`~/pc-cleaner-reports` (Linux/VPS); use `--out REPORTS_DIR` to choose another.

## Features

- Fast, recursive, read-only scans using `os.scandir`
- Self-contained offline HTML dashboard with sortable tables
- Inline SVG storage treemap and growth-over-time chart (no CDN, no JS libs)
- Dark-mode toggle, global table search, and per-card CSV export (all offline)
- Full CSV file inventory plus JSON, Markdown, and HTML reports
- `pc-cleaner compare` to diff any two reports (text or `--json`)
- Cold-data (unused 1y+), old-and-large, and disk-fill forecast insights
- Largest files, folders, extensions, categories, ages, and size buckets
- Duplicate finder using nothing but stdlib hashing (two-stage: cheap head/tail
  digest first, full BLAKE2b only on real candidates) across a thread pool
- Persistent hash cache so repeat scans skip re-hashing unchanged files
- Multi-target scans (`--also`) that combine several roots into one report
- `.pc-cleanerignore` files plus `--ignore-file` for repeatable exclusions
- Hardlink-aware duplicate detection and sparse/allocated-size accounting
- `--estimate` for an honest, time-boxed pre-scan scope estimate
- Junk/cache/zero-byte/empty-folder signals
- Ranked cleanup advisor with reclaim estimates and confidence levels
- Dry-run manifest plus review scripts (PowerShell/shell) you inspect and run;
  `--method hardlink` suggests reclaiming duplicates without deleting them
- Access-error handling and Windows long-path support
- SQLite-backed processing for very large drives
- Drive chooser and browsable folder tree in the terminal dashboard
- Live results view (largest files seen), with filter and sort
- Scan queue that runs targets back-to-back; favorite targets and saved sessions
- In-log search, activity-log export, and completion notifications + bell
- Profile selector (quick/deep/dev/photos) in the dashboard
- Confirmed PyPI update checker; no automatic restart or silent upgrade
- Cross-platform mount discovery and VPS-safe virtual filesystem exclusions
- Optional `--system-scan` measuring known Windows/macOS/Linux caches, browser
  caches, Docker/WSL disks, package caches, and game libraries (read-only)
- Sensitive-file flagging (paths only; contents never read) for `.env`, keys, etc.
- Custom report sections via drop-in plugins in `~/.pc-cleaner/plugins`
- Public in-process Python API (`pc_cleaner.api.scan`) and optional `--webhook`
- `pc-cleaner watch` volume monitor with threshold alerts
- Perceptually similar image finder (`--similar-images`) with a PNG/BMP
  average-hash, plus image dimension and EXIF capture-date reading
- Configurable dashboard keybindings (`[keybindings]`) and mouse support
  (wheel scrolls the log; click selects list rows) on POSIX terminals

## Safety

PC Cleaner is an **analysis and recommendation** tool. It does not delete,
move, modify, or upload your data. Review report findings yourself before
performing any cleanup.

## License

MIT
