valscanner 0.1.0__tar.gz

valscanner-0.1.0/LICENSE

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

valscanner-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.1
+Name: valscanner
+Version: 0.1.0
+Summary: Recursive file scanner with metadata, tagging, and duplicate detection
+Author-email: Abdalrahman Valabji <valabji@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Abdalrahman Valabji
+        
+        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.
+        
+Keywords: scanner,files,metadata,duplicates,sqlite,gui
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Utilities
+Classifier: Topic :: System :: Filesystems
+Classifier: Environment :: X11 Applications :: Qt
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PySide6
+Provides-Extra: rich
+Requires-Dist: Pillow; extra == "rich"
+Requires-Dist: mutagen; extra == "rich"
+Requires-Dist: PyPDF2; extra == "rich"
+
+# ValScanner
+
+A recursive file scanner with rich metadata extraction, full-text search, tagging, thumbnail generation, and duplicate/similar-folder detection — available as both a CLI tool and a PySide6 GUI.
+
+---
+
+## Features
+
+- **Recursive scan** — indexes every file under a root directory into SQLite
+- **Rich metadata** — image EXIF, audio tags, PDF page count (optional deps)
+- **Thumbnails** — JPEG blobs stored in the database; displayed in the GUI grid view
+- **Tagging** — rule-based tags derived from path, filename, size, and extension
+- **Full-text search** — FTS5 virtual table over filenames and paths
+- **Similar-folder detection** — pairwise comparison using filename Jaccard + extension cosine + size ratio + SHA-256 Jaccard
+- **Export** — CSV and JSON export from the CLI
+- **Multiple scan sessions** — each scan stored with a label; list or delete past scans
+
+---
+
+## Requirements
+
+| Requirement | Version |
+|---|---|
+| Python | 3.8+ |
+| PySide6 | any recent release |
+| Pillow *(optional)* | image EXIF + thumbnails |
+| mutagen *(optional)* | audio metadata |
+| PyPDF2 *(optional)* | PDF page count |
+
+---
+
+## Installation
+
+### macOS / Linux
+
+```bash
+# Clone the repo
+git clone <repo-url> myscanner
+cd myscanner
+
+# Run the installer (creates .venv, installs all deps, links launchers)
+bash install.sh
+
+# Or skip optional rich-metadata deps
+bash install.sh --no-rich
+
+# Or install into your active Python environment (no venv)
+bash install.sh --no-venv
+
+# Or specify where launcher scripts go
+bash install.sh --prefix ~/.local
+```
+
+The installer places `valscanner` and `valscanner-gui` symlinks in `~/.local/bin` (Linux) or `/usr/local/bin` (macOS, if writable).
+
+### Windows (PowerShell)
+
+```powershell
+# Clone the repo
+git clone <repo-url> myscanner
+cd myscanner
+
+# Run the installer (creates .venv, installs all deps, writes .cmd launchers)
+.\install.ps1
+
+# Skip optional rich-metadata deps
+.\install.ps1 -NoRich
+
+# Install into your active Python environment (no venv)
+.\install.ps1 -NoVenv
+
+# Specify launcher directory
+.\install.ps1 -Prefix "C:\Tools\ValScanner"
+```
+
+Launchers are written as `.cmd` files to `%LOCALAPPDATA%\Programs\ValScanner\bin` by default. The script offers to add that directory to your user `PATH`.
+
+### Manual (pip)
+
+```bash
+# Minimal — GUI only, no image/audio/PDF metadata
+pip install -e .
+
+# Full — all optional metadata extractors
+pip install -e ".[rich]"
+```
+
+---
+
+## Usage
+
+### GUI
+
+```bash
+valscanner-gui
+# or
+python -m valscanner.gui.window
+```
+
+### CLI
+
+```bash
+# Scan a directory
+valscanner /path/to/scan
+
+# With options
+valscanner /path/to/scan --db my.db --no-hash --export-csv --export-json --verbose
+
+# List past scans
+valscanner --list-scans --db my.db
+
+# Delete a scan by ID
+valscanner --delete-scan 3 --db my.db
+```
+
+Full flag reference:
+
+| Flag | Default | Description |
+|---|---|---|
+| `--db PATH` | `scanner.db` | SQLite database file |
+| `--no-hash` | off | Skip SHA-256 (faster) |
+| `--export-csv` | off | Write `<label>.csv` after scan |
+| `--export-json` | off | Write `<label>.json` after scan |
+| `--verbose` / `-v` | off | Per-file progress |
+| `--list-scans` | — | Print all stored scans and exit |
+| `--delete-scan ID` | — | Delete scan by ID and exit |
+
+---
+
+## Project layout
+
+```
+myscanner/
+├── pyproject.toml          ← packaging & entry points
+├── install.sh              ← macOS/Linux installer
+├── install.ps1             ← Windows PowerShell installer
+├── file_scanner.py         ← backward-compat shim
+├── file_scanner_gui.py     ← backward-compat shim
+│
+└── valscanner/
+    ├── cli.py              ← CLI entry point
+    ├── core/               ← zero Qt dependencies
+    │   ├── schema.py
+    │   ├── categories.py
+    │   ├── metadata.py
+    │   ├── tagging.py
+    │   ├── scanner.py
+    │   ├── similarity.py
+    │   ├── export.py
+    │   └── db.py
+    └── gui/                ← PySide6 front-end
+        ├── constants.py
+        ├── workers.py
+        ├── models.py
+        ├── delegates.py
+        ├── dialogs.py
+        ├── window.py
+        └── panels/
+            ├── detail.py
+            ├── folders.py
+            ├── similar.py
+            ├── scans.py
+            └── console.py
+```
+
+---
+
+## Database schema
+
+Every `.db` file contains five tables:
+
+| Table | Contents |
+|---|---|
+| `scans` | One row per scan session (label, root, file count, total size) |
+| `files` | One row per file; `extra_meta` is a JSON blob of rich metadata |
+| `folders` | Cumulative byte/file counts for every ancestor directory |
+| `thumbnails` | JPEG blobs keyed by `file_id` |
+| `media_samples` | Low-quality audio/video clips keyed by `file_id` |
+| `files_fts` | FTS5 virtual table over `files`; populated by triggers |
+
+---
+
+## Development
+
+```bash
+# Editable install with all extras
+pip install -e ".[rich]"
+
+# Run directly without installing
+python -m valscanner.gui.window   # GUI
+python -m valscanner.cli          # CLI (add args after --)
+```
+
+Output files (`*.db`, `*.csv`, `*.json`) are gitignored.
+
+---
+
+## License
+
+MIT

valscanner-0.1.0/README.md

@@ -0,0 +1,200 @@
+# ValScanner
+
+A recursive file scanner with rich metadata extraction, full-text search, tagging, thumbnail generation, and duplicate/similar-folder detection — available as both a CLI tool and a PySide6 GUI.
+
+---
+
+## Features
+
+- **Recursive scan** — indexes every file under a root directory into SQLite
+- **Rich metadata** — image EXIF, audio tags, PDF page count (optional deps)
+- **Thumbnails** — JPEG blobs stored in the database; displayed in the GUI grid view
+- **Tagging** — rule-based tags derived from path, filename, size, and extension
+- **Full-text search** — FTS5 virtual table over filenames and paths
+- **Similar-folder detection** — pairwise comparison using filename Jaccard + extension cosine + size ratio + SHA-256 Jaccard
+- **Export** — CSV and JSON export from the CLI
+- **Multiple scan sessions** — each scan stored with a label; list or delete past scans
+
+---
+
+## Requirements
+
+| Requirement | Version |
+|---|---|
+| Python | 3.8+ |
+| PySide6 | any recent release |
+| Pillow *(optional)* | image EXIF + thumbnails |
+| mutagen *(optional)* | audio metadata |
+| PyPDF2 *(optional)* | PDF page count |
+
+---
+
+## Installation
+
+### macOS / Linux
+
+```bash
+# Clone the repo
+git clone <repo-url> myscanner
+cd myscanner
+
+# Run the installer (creates .venv, installs all deps, links launchers)
+bash install.sh
+
+# Or skip optional rich-metadata deps
+bash install.sh --no-rich
+
+# Or install into your active Python environment (no venv)
+bash install.sh --no-venv
+
+# Or specify where launcher scripts go
+bash install.sh --prefix ~/.local
+```
+
+The installer places `valscanner` and `valscanner-gui` symlinks in `~/.local/bin` (Linux) or `/usr/local/bin` (macOS, if writable).
+
+### Windows (PowerShell)
+
+```powershell
+# Clone the repo
+git clone <repo-url> myscanner
+cd myscanner
+
+# Run the installer (creates .venv, installs all deps, writes .cmd launchers)
+.\install.ps1
+
+# Skip optional rich-metadata deps
+.\install.ps1 -NoRich
+
+# Install into your active Python environment (no venv)
+.\install.ps1 -NoVenv
+
+# Specify launcher directory
+.\install.ps1 -Prefix "C:\Tools\ValScanner"
+```
+
+Launchers are written as `.cmd` files to `%LOCALAPPDATA%\Programs\ValScanner\bin` by default. The script offers to add that directory to your user `PATH`.
+
+### Manual (pip)
+
+```bash
+# Minimal — GUI only, no image/audio/PDF metadata
+pip install -e .
+
+# Full — all optional metadata extractors
+pip install -e ".[rich]"
+```
+
+---
+
+## Usage
+
+### GUI
+
+```bash
+valscanner-gui
+# or
+python -m valscanner.gui.window
+```
+
+### CLI
+
+```bash
+# Scan a directory
+valscanner /path/to/scan
+
+# With options
+valscanner /path/to/scan --db my.db --no-hash --export-csv --export-json --verbose
+
+# List past scans
+valscanner --list-scans --db my.db
+
+# Delete a scan by ID
+valscanner --delete-scan 3 --db my.db
+```
+
+Full flag reference:
+
+| Flag | Default | Description |
+|---|---|---|
+| `--db PATH` | `scanner.db` | SQLite database file |
+| `--no-hash` | off | Skip SHA-256 (faster) |
+| `--export-csv` | off | Write `<label>.csv` after scan |
+| `--export-json` | off | Write `<label>.json` after scan |
+| `--verbose` / `-v` | off | Per-file progress |
+| `--list-scans` | — | Print all stored scans and exit |
+| `--delete-scan ID` | — | Delete scan by ID and exit |
+
+---
+
+## Project layout
+
+```
+myscanner/
+├── pyproject.toml          ← packaging & entry points
+├── install.sh              ← macOS/Linux installer
+├── install.ps1             ← Windows PowerShell installer
+├── file_scanner.py         ← backward-compat shim
+├── file_scanner_gui.py     ← backward-compat shim
+│
+└── valscanner/
+    ├── cli.py              ← CLI entry point
+    ├── core/               ← zero Qt dependencies
+    │   ├── schema.py
+    │   ├── categories.py
+    │   ├── metadata.py
+    │   ├── tagging.py
+    │   ├── scanner.py
+    │   ├── similarity.py
+    │   ├── export.py
+    │   └── db.py
+    └── gui/                ← PySide6 front-end
+        ├── constants.py
+        ├── workers.py
+        ├── models.py
+        ├── delegates.py
+        ├── dialogs.py
+        ├── window.py
+        └── panels/
+            ├── detail.py
+            ├── folders.py
+            ├── similar.py
+            ├── scans.py
+            └── console.py
+```
+
+---
+
+## Database schema
+
+Every `.db` file contains five tables:
+
+| Table | Contents |
+|---|---|
+| `scans` | One row per scan session (label, root, file count, total size) |
+| `files` | One row per file; `extra_meta` is a JSON blob of rich metadata |
+| `folders` | Cumulative byte/file counts for every ancestor directory |
+| `thumbnails` | JPEG blobs keyed by `file_id` |
+| `media_samples` | Low-quality audio/video clips keyed by `file_id` |
+| `files_fts` | FTS5 virtual table over `files`; populated by triggers |
+
+---
+
+## Development
+
+```bash
+# Editable install with all extras
+pip install -e ".[rich]"
+
+# Run directly without installing
+python -m valscanner.gui.window   # GUI
+python -m valscanner.cli          # CLI (add args after --)
+```
+
+Output files (`*.db`, `*.csv`, `*.json`) are gitignored.
+
+---
+
+## License
+
+MIT

valscanner-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "valscanner"
+version = "0.1.0"
+description = "Recursive file scanner with metadata, tagging, and duplicate detection"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Abdalrahman Valabji", email = "valabji@gmail.com" }]
+requires-python = ">=3.8"
+keywords = ["scanner", "files", "metadata", "duplicates", "sqlite", "gui"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
+    "Topic :: System :: Filesystems",
+    "Environment :: X11 Applications :: Qt",
+]
+dependencies = [
+    "PySide6",
+]
+
+[project.optional-dependencies]
+rich = [
+    "Pillow",
+    "mutagen",
+    "PyPDF2",
+]
+
+[project.scripts]
+valscanner     = "valscanner.cli:main"
+valscanner-gui = "valscanner.gui.window:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["valscanner*"]

valscanner-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

valscanner-0.1.0/valscanner/__init__.py

@@ -0,0 +1,3 @@
+"""ValScanner — recursive file scanner with metadata, tagging, and duplicate detection."""
+
+__version__ = "0.1.0"

valscanner-0.1.0/valscanner/cli.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+"""
+ValScanner CLI — scan a directory and build a searchable file database.
+
+Usage:
+    valscanner /path/to/scan [options]
+    valscanner --list-scans --db my.db
+    valscanner --delete-scan 3 --db my.db
+"""
+
+import sys
+import time
+import argparse
+from pathlib import Path
+
+from .core.metadata import PIL_AVAILABLE, MUTAGEN_AVAILABLE, PYPDF_AVAILABLE
+from .core.scanner import scan
+from .core.export import export_csv, export_json
+from .core.db import query_db, print_summary, list_scans, delete_scan
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Scan a directory and build a searchable file database.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("path",           nargs="?", help="Root directory to scan")
+    parser.add_argument("--db",           default="file_index.db",
+                        help="SQLite database path (default: file_index.db)")
+    parser.add_argument("--label",        metavar="NAME", default="",
+                        help="Human-readable label for this scan")
+    parser.add_argument("--export-csv",   action="store_true", help="Export results to CSV")
+    parser.add_argument("--export-json",  action="store_true", help="Export results to JSON")
+    parser.add_argument("--no-hash",      action="store_true", help="Skip SHA-256 hashing")
+    parser.add_argument("--verbose",      action="store_true", help="Print each file as indexed")
+    parser.add_argument("--query",        metavar="TERM", help="Query the database after scanning")
+    parser.add_argument("--list-scans",   action="store_true", help="List all scans in the database")
+    parser.add_argument("--delete-scan",  type=int, metavar="ID", help="Delete a scan by ID")
+    args = parser.parse_args()
+
+    if args.list_scans:
+        scans = list_scans(args.db)
+        if not scans:
+            print("No scans in database.")
+        for s in scans:
+            print(f"  [{s['id']:3d}]  {s['label'] or s['root']:40s}  "
+                  f"{s['file_count']:>8,} files  {s['total_human']:>10s}  {s['scanned_at']}")
+        sys.exit(0)
+
+    if args.delete_scan is not None:
+        delete_scan(args.db, args.delete_scan)
+        print(f"✓ Scan {args.delete_scan} deleted.")
+        sys.exit(0)
+
+    if not args.path:
+        parser.error("path is required unless using --list-scans or --delete-scan")
+
+    root = Path(args.path).expanduser().resolve()
+    if not root.exists():
+        print(f"Error: path does not exist: {root}")
+        sys.exit(1)
+
+    print(f"\n🔎 Scanning: {root}")
+    print(f"   Database: {args.db}")
+    if args.label:
+        print(f"   Label:    {args.label}")
+    if not PIL_AVAILABLE:
+        print("   ⚠  Pillow not installed — image EXIF metadata skipped")
+    if not MUTAGEN_AVAILABLE:
+        print("   ⚠  mutagen not installed — audio metadata skipped")
+    if not PYPDF_AVAILABLE:
+        print("   ⚠  PyPDF2 not installed — PDF metadata skipped")
+    print()
+
+    t0      = time.time()
+    stats   = scan(root, args.db, compute_hash=not args.no_hash,
+                   verbose=args.verbose, label=args.label)
+    elapsed = time.time() - t0
+
+    print(f"\n✅ Done in {elapsed:.1f}s — "
+          f"scan #{stats['scan_id']}, "
+          f"{stats['scanned']:,} indexed, "
+          f"{stats['errors']:,} errors, "
+          f"{stats['skipped']:,} skipped")
+
+    print_summary(args.db)
+
+    if args.export_csv:
+        export_csv(args.db, args.db.replace(".db", ".csv"), scan_id=stats["scan_id"])
+    if args.export_json:
+        export_json(args.db, args.db.replace(".db", ".json"), scan_id=stats["scan_id"])
+    if args.query:
+        query_db(args.db, args.query)
+
+    print(f"  💡 Run with --query photos, --list-scans, or open the GUI:\n"
+          f"     valscanner-gui\n")
+
+
+if __name__ == "__main__":
+    main()

valscanner-0.1.0/valscanner/core/categories.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+MIME_CATEGORY: dict[str, str] = {
+    "image":       "photo",
+    "video":       "video",
+    "audio":       "audio",
+    "text":        "document",
+    "application": "application",
+}
+
+EXT_CATEGORY: dict[str, str] = {
+    # Documents
+    ".pdf": "document", ".doc": "document", ".docx": "document",
+    ".odt": "document", ".rtf": "document", ".txt": "document",
+    ".md":  "document", ".rst": "document", ".tex": "document",
+    # Spreadsheets
+    ".xls": "spreadsheet", ".xlsx": "spreadsheet", ".ods": "spreadsheet",
+    ".csv": "spreadsheet",
+    # Presentations
+    ".ppt": "presentation", ".pptx": "presentation", ".odp": "presentation",
+    # Photos / images
+    ".jpg": "photo", ".jpeg": "photo", ".png": "photo", ".gif": "photo",
+    ".bmp": "photo", ".tiff": "photo", ".tif": "photo", ".webp": "photo",
+    ".heic": "photo", ".heif": "photo", ".raw": "photo", ".cr2": "photo",
+    ".nef": "photo", ".svg": "image",
+    # Video
+    ".mp4": "video", ".mov": "video", ".avi": "video", ".mkv": "video",
+    ".wmv": "video", ".flv": "video", ".webm": "video", ".m4v": "video",
+    # Audio
+    ".mp3": "audio", ".flac": "audio", ".wav": "audio", ".aac": "audio",
+    ".ogg": "audio", ".m4a": "audio", ".wma": "audio",
+    # Code
+    ".py": "code",  ".js": "code",  ".ts": "code",  ".java": "code",
+    ".c":  "code",  ".cpp": "code", ".h":  "code",  ".cs": "code",
+    ".go": "code",  ".rs": "code",  ".rb": "code",  ".php": "code",
+    ".sh": "code",  ".bat": "code", ".ps1": "code",
+    # Data
+    ".json": "data", ".xml": "data", ".yaml": "data", ".yml": "data",
+    ".toml": "data", ".ini": "data", ".sql": "data",
+    # Archives
+    ".zip": "archive", ".tar": "archive", ".gz": "archive", ".bz2": "archive",
+    ".7z": "archive",  ".rar": "archive", ".xz": "archive",
+    # Executables / installers
+    ".exe": "executable", ".msi": "executable", ".dmg": "executable",
+    ".deb": "executable", ".rpm": "executable", ".appimage": "executable",
+    # Fonts
+    ".ttf": "font", ".otf": "font", ".woff": "font", ".woff2": "font",
+    # Ebooks
+    ".epub": "ebook", ".mobi": "ebook", ".azw": "ebook",
+}