dedrive 0.1.0__tar.gz

dedrive-0.1.0/.github/dependabot.yml

@@ -0,0 +1,8 @@
+# Dependabot configuration for automated dependency updates
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

dedrive-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release
+on:
+  push:
+    branches: [main]
+    paths: [dedrive/__init__.py]
+concurrency:
+  group: release
+  cancel-in-progress: false
+jobs:
+  test:
+    uses: tsilva/.github/.github/workflows/test.yml@main
+
+  pii-scan:
+    uses: tsilva/.github/.github/workflows/pii-scan.yml@main
+
+  publish:
+    needs: [test, pii-scan]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: pypi
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Check version
+        id: check-version
+        uses: tsilva/.github/.github/actions/check-version@main
+      - name: Setup uv
+        if: steps.check-version.outputs.tag_exists == 'false'
+        uses: astral-sh/setup-uv@v4
+        with:
+          cache: true
+      - name: Build package
+        if: steps.check-version.outputs.tag_exists == 'false'
+        run: uv build
+      - name: Create GitHub release
+        if: steps.check-version.outputs.tag_exists == 'false'
+        run: gh release create "${{ steps.check-version.outputs.tag }}" --title "${{ steps.check-version.outputs.tag }}" --generate-notes dist/*
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Publish to PyPI
+        if: steps.check-version.outputs.tag_exists == 'false'
+        uses: pypa/gh-action-pypi-publish@release/v1

dedrive-0.1.0/.gitignore

@@ -0,0 +1,135 @@
+# >>> MANAGED BY GITGUARD - DO NOT EDIT THIS SECTION <<<
+.claude/*.local.json
+.claude/*.local.json.bak
+.claude-sandbox.json
+.mcp.json
+.env
+.env.*
+!.env.example
+!.env.*.example
+.env.*.local
+.env.local
+*.pem
+*.key
+*.p12
+*.pfx
+*.gpg
+*.secret
+*-credentials.json
+service-account*.json
+credentials.json
+secrets.json
+.secrets/
+.aws/
+.ssh/
+config.local.*
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+*.code-workspace
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+env/
+*.egg-info/
+node_modules/
+.npm/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+dist/
+build/
+logs/
+*.log
+# >>> END MANAGED <<<
+
+# Project-specific rules
+!.output/.gitkeep
+*$py.class
+*.cover
+*.egg
+*.manifest
+*.mo
+*.pot
+*.py.cover
+*.py[codz]
+*.sage.py
+*.so
+*.spec
+.abstra/
+.cache
+.coverage
+.coverage.*
+.cursorignore
+.cursorindexingignore
+.dmypy.json
+.eggs/
+.envrc
+.hypothesis/
+.installed.cfg
+.ipynb_checkpoints
+.mypy_cache/
+.nox/
+.output/*
+.pdm-build/
+.pdm-python
+.pixi
+.pybuilder/
+.pypirc
+.pyre/
+.pytest_cache/
+.Python
+.pytype/
+.ropeproject
+.ruff_cache/
+.scrapy
+.spyderproject
+.spyproject
+.tox/
+.venv
+.webassets-cache
+/site
+__marimo__/
+__pypackages__/
+celerybeat-schedule
+celerybeat.pid
+cover/
+coverage.xml
+cython_debug/
+db.sqlite3
+db.sqlite3-journal
+develop-eggs/
+dmypy.json
+docs/_build/
+downloads/
+eggs/
+env.bak/
+ENV/
+htmlcov/
+instance/
+ipython_config.py
+lib/
+lib64/
+local_settings.py
+MANIFEST
+marimo/_lsp/
+marimo/_static/
+nosetests.xml
+parts/
+pip-delete-this-directory.txt
+pip-log.txt
+profile_default/
+profiles/*
+sdist/
+share/python-wheels/
+target/
+token.json
+var/
+venv.bak/
+wheels/
+!profiles/.example
+!profiles/.example/**

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

@@ -0,0 +1,5 @@
+repos:
+  - repo: https://github.com/tsilva/.github
+    rev: main
+    hooks:
+      - id: gitleaks

dedrive-0.1.0/AGENTS.md

@@ -0,0 +1,177 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install dependencies
+uv sync
+
+# Install as standalone CLI tool
+uv tool install . --editable
+
+# Login (opens browser, auto-creates profile from email)
+dedrive login
+
+# Logout
+dedrive logout
+
+# List profiles with login status
+dedrive --list-profiles
+
+# Launch the Gradio web UI (auto-detects logged-in profile)
+dedrive
+
+# Launch on a custom port
+dedrive --port 8080
+
+# Enable public sharing link
+dedrive --share
+
+# Enable verbose/debug logging
+dedrive --verbose
+
+# Write logs to file
+dedrive --log-file debug.log
+
+# Validate credentials without launching UI
+dedrive --profile work --validate
+
+# Backward-compatible: run via main.py
+uv run main.py login
+uv run main.py --list-profiles
+```
+
+**Note:** PDF preview in the web UI requires poppler: `brew install poppler` (macOS)
+
+## Configuration
+
+All settings can be configured via environment variables, `config.json`, or profiles. Precedence: profile config.yaml > ENV > config.json > defaults.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GDRIVE_CREDENTIALS_PATH` | `credentials.json` | Path to OAuth credentials file |
+| `GDRIVE_TOKEN_PATH` | (next to credentials) | Path to OAuth token file |
+| `GDRIVE_OUTPUT_DIR` | `.output` | Directory for output files |
+| `GDRIVE_DUPES_FOLDER` | `/_dupes` | Folder name for duplicates in Drive |
+| `GDRIVE_BATCH_SIZE` | `100` | Batch size for API operations |
+| `GDRIVE_MAX_PREVIEW_MB` | `10` | Max file size for previews (MB) |
+| `GDRIVE_EXCLUDE_PATHS` | (none) | Comma-separated paths to exclude |
+
+### Config File
+
+Create `config.json` in the project root:
+
+```json
+{
+  "credentials_path": "~/.config/dedrive/credentials.json",
+  "output_dir": "~/.local/share/dedrive",
+  "dupes_folder": "/_dupes",
+  "batch_size": 100,
+  "max_preview_mb": 10,
+  "exclude_paths": [
+    "/Backup/Old",
+    "/tmp"
+  ]
+}
+```
+
+Paths support `~` expansion for home directory.
+
+### Exclude Paths
+
+Folders can be excluded from scans using two methods (combined):
+
+1. **Config file:** Add `exclude_paths` array to `config.json`
+2. **Environment variable:** Set `GDRIVE_EXCLUDE_PATHS` (comma-separated)
+
+Example `.env` file:
+```
+GDRIVE_EXCLUDE_PATHS=/documentor-puzzle/export,/Backup/Old
+```
+
+### Config File Fallback
+
+`config.json` is checked in cwd first, then falls back to `~/.dedrive/config.json`.
+
+### Credentials Fallback
+
+`credentials.json` is checked in cwd first, then falls back to `~/.dedrive/credentials.json`.
+
+### Profiles
+
+Profiles allow targeting multiple Google Drive accounts. Each profile is a subfolder under `~/.dedrive/` with its own credentials, token, config, and output data. Profiles are auto-created on `dedrive login` using the Google account email as the profile name.
+
+```
+~/.dedrive/
+  credentials.json     # Shared OAuth client credentials (fallback)
+  config.json          # Shared config (fallback)
+  user@gmail.com/
+    config.yaml        # Profile settings (YAML)
+    token.json         # OAuth token (auto-generated)
+    .output/           # Scan results, decisions, logs
+```
+
+Example `config.yaml`:
+
+```yaml
+dupes_folder: /_dupes
+batch_size: 100
+max_preview_mb: 10
+exclude_paths:
+  - /Backup/Old
+  - /tmp
+```
+
+When `--profile <name>` is used, `config.py` resolves credentials, token, and output paths from the profile directory. Profile `config.yaml` values slot into the precedence chain between CLI args and environment variables.
+
+## Architecture
+
+Installable CLI tool (`dedrive`) with a Gradio web UI for finding and managing duplicate files in Google Drive.
+
+**Package structure:**
+- `dedrive/cli.py` — CLI entry point with `login`, `logout` subcommands and Gradio launcher
+- `dedrive/ui.py` — Gradio web UI (all UI code, dataclasses, helpers)
+- `dedrive/drive.py` — Google Drive authentication, API fetch, path resolution
+- `dedrive/dedup.py` — Duplicate detection logic
+- `dedrive/config.py` — Configuration management with fallback chain
+- `dedrive/profiles.py` — Profile management (profiles stored in `~/.dedrive/`)
+- `main.py` — Thin wrapper for backward compatibility (`uv run main.py`)
+
+**Features:**
+- **CLI:** `login` (browser-based OAuth), `logout` (remove token), `--list-profiles`
+- **Scan Tab:** Run scans with progress feedback
+- **Review Tab:** Side-by-side file comparison with previews, make keep/skip decisions
+- **Export Tab:** Preview and execute moves, export decisions.json
+- **CLI flags:** Profile selection (`--profile`), credential validation (`--validate`), logging (`--verbose`, `--log-file`), Gradio options (`--port`, `--share`)
+
+**Key design decisions:**
+- Profiles auto-created on login using Google account email as name
+- Profiles stored in `~/.dedrive/` (works when installed as standalone CLI)
+- `login` subcommand opens browser for OAuth without importing Gradio
+- Uses `drive` scope (full access for file moves)
+- Fetches all files in one query then filters locally (faster than recursive folder traversal)
+- Path resolution uses memoization (`path_cache`) for efficiency
+- Files with same MD5 but different size marked as "uncertain"
+- Google Workspace files (Docs, Sheets) skipped (no MD5 available)
+- Decisions auto-save to `.output/decisions.json` (resume sessions)
+- File previews cached in `.output/preview_cache/`
+
+**Output:** `.output/scan_results.json` (scan results), `.output/decisions.json` (user decisions), `.output/execution_log.json` (move results)
+
+### Moving Duplicates
+
+Instead of deleting duplicates, files are moved to a `/_dupes` folder at the root of your Google Drive:
+
+1. **Scan** your drive to find duplicates
+2. **Review** and mark which files to keep
+3. **Preview (Dry Run)** to see what would be moved
+4. **Execute** to move duplicates to `/_dupes`
+
+The original folder structure is preserved under `/_dupes`:
+- `/Photos/2024/IMG.jpg` → `/_dupes/Photos/2024/IMG.jpg`
+
+**Re-authentication required:** If you previously used this tool with read-only access, delete `token.json` and re-authenticate to grant move permissions.

dedrive-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

dedrive-0.1.0/LICENSE

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

dedrive-0.1.0/Makefile

@@ -0,0 +1,5 @@
+release-%:
+	hatch version $*
+	git add dedrive/__init__.py
+	git commit -m "chore: release $$(hatch version)"
+	git push

dedrive-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: dedrive
+Version: 0.1.0
+Summary: Find duplicate files in Google Drive using MD5 checksums
+Project-URL: Homepage, https://github.com/tsilva/dedrive
+Project-URL: Repository, https://github.com/tsilva/dedrive
+Project-URL: Issues, https://github.com/tsilva/dedrive/issues
+Author-email: Tiago Silva <tiago@tsilva.com>
+License: MIT
+License-File: LICENSE
+Keywords: cleanup,deduplication,duplicates,google-drive,md5,storage
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth-httplib2
+Requires-Dist: google-auth-oauthlib
+Requires-Dist: gradio>=4.0.0
+Requires-Dist: pdf2image>=1.16.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="logo.png" alt="dedrive" width="512"/>
+
+  [![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)](https://python.org)
+  [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+  [![Google Drive API](https://img.shields.io/badge/Google%20Drive-API%20v3-4285F4?logo=googledrive&logoColor=white)](https://developers.google.com/drive)
+
+  **🔍 Find and manage duplicate files in Google Drive using MD5 checksums 🗑️**
+
+  [Features](#features) · [Quick Start](#quick-start) · [Configuration](#configuration) · [Usage](#usage)
+</div>
+
+---
+
+## Features
+
+- **Fast MD5-based detection** - Identifies duplicates by comparing file checksums, not just names
+- **Two interfaces** - CLI for quick scans, Web UI for interactive review with file previews
+- **Non-destructive** - Moves duplicates to `/_dupes` folder instead of deleting them
+- **Preserves structure** - Original folder hierarchy is maintained under the dupes folder
+- **Resumable sessions** - Decisions auto-save and persist across sessions
+- **Flexible filtering** - Scan specific paths and exclude folders from analysis
+- **Multi-account profiles** - Target different Google Drive accounts with named profiles
+
+## Quick Start
+
+```bash
+# Install with uv
+uv sync
+
+# Launch the web UI
+uv run main.py
+```
+
+**First run:** A browser window will open for Google OAuth authentication. Grant access to your Google Drive.
+
+## Installation
+
+### Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) package manager
+- Google Cloud OAuth credentials ([setup guide](#google-cloud-setup))
+
+### Google Cloud Setup
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
+2. Create a project (or select existing)
+3. Enable the **Google Drive API**
+4. Create **OAuth 2.0 Client ID** (choose "Desktop app")
+5. Download the JSON file and save as `credentials.json` in the project root
+
+## Usage
+
+### CLI Tool
+
+```bash
+# Scan entire drive
+uv run main.py
+
+# Scan specific folder
+uv run main.py --path "/Photos"
+
+# Exclude folders
+uv run main.py --exclude "/Backup/Old" --exclude "/tmp"
+
+# Custom output location
+uv run main.py --output results.csv
+
+# Validate credentials
+uv run main.py --validate
+
+# Debug logging
+uv run main.py --verbose --log-file debug.log
+
+# Profiles (multiple Google accounts)
+uv run main.py --init-profile work
+uv run main.py --list-profiles
+uv run main.py --profile work
+```
+
+### Web UI
+
+```bash
+uv run main.py
+```
+
+The web interface provides three tabs:
+
+| Tab | Purpose |
+|-----|---------|
+| **Scan** | Run scans with path filtering and progress feedback |
+| **Review** | Side-by-side comparison with file previews, make keep/skip decisions |
+| **Export** | Preview moves (dry run), execute moves, export decisions to JSON |
+
+**Note:** PDF preview requires poppler: `brew install poppler` (macOS)
+
+### Moving Duplicates
+
+Instead of deleting, duplicates are moved to `/_dupes` at Drive root:
+
+```
+/Photos/2024/IMG.jpg  →  /_dupes/Photos/2024/IMG.jpg
+```
+
+1. **Scan** - Find duplicates
+2. **Review** - Mark which files to keep
+3. **Preview** - Dry run to see what would move
+4. **Execute** - Move duplicates to `/_dupes`
+
+## Configuration
+
+Settings can be configured via environment variables, `config.json`, or CLI arguments.
+
+**Precedence:** CLI > Profile config.yaml > Environment > Config file > Defaults
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GDRIVE_CREDENTIALS_PATH` | `credentials.json` | OAuth credentials file |
+| `GDRIVE_TOKEN_PATH` | (next to credentials) | OAuth token file |
+| `GDRIVE_OUTPUT_DIR` | `.output` | Output directory |
+| `GDRIVE_DUPES_FOLDER` | `/_dupes` | Folder for duplicates |
+| `GDRIVE_BATCH_SIZE` | `100` | Batch size for API operations |
+| `GDRIVE_MAX_PREVIEW_MB` | `10` | Max file size for previews |
+| `GDRIVE_EXCLUDE_PATHS` | (none) | Comma-separated paths to exclude |
+
+### Config File
+
+Create `config.json` in the project root:
+
+```json
+{
+  "credentials_path": "~/.config/dedrive/credentials.json",
+  "output_dir": "~/.local/share/dedrive",
+  "dupes_folder": "/_dupes",
+  "batch_size": 100,
+  "exclude_paths": ["/Backup/Old", "/tmp"]
+}
+```
+
+### Profiles
+
+Use profiles to manage multiple Google Drive accounts:
+
+```bash
+# Create a profile
+uv run main.py --init-profile work
+
+# Copy credentials into the profile
+cp ~/Downloads/credentials.json profiles/work/
+
+# Use the profile
+uv run main.py --profile work
+```
+
+Each profile stores its own `credentials.json`, `token.json`, `config.yaml`, and `.output/` under `profiles/<name>/`.
+
+## Output Files
+
+| File | Description |
+|------|-------------|
+| `.output/duplicates.csv` | Scan results with duplicate pairs |
+| `.output/decisions.json` | User decisions (auto-saved) |
+| `.output/execution_log.json` | Move operation results |
+| `.output/scan_results.json` | Cached scan data for session resume |
+
+## How It Works
+
+1. **OAuth authentication** - Cached in `token.json` after first login
+2. **Single API call** - Fetches all files with MD5 metadata in one paginated request
+3. **In-memory path resolution** - Builds paths from parent IDs with memoization
+4. **MD5 grouping** - Groups files by checksum to identify duplicates
+5. **Size validation** - Files with same MD5 but different sizes flagged as "uncertain"
+
+**Note:** Google Workspace files (Docs, Sheets, Slides) are skipped as they don't have MD5 checksums.
+
+## Re-authentication
+
+If you previously used this tool with read-only access, delete `token.json` and re-authenticate to grant move permissions.
+
+## License
+
+MIT