gmail-cleaner 0.1.0__tar.gz

gmail_cleaner-0.1.0/LICENSE

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

gmail_cleaner-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: gmail_cleaner
+Version: 0.1.0
+Summary: A powerful local CLI tool to sync, cluster, and surgically clean your Gmail.
+Author-email: Mayank Gupta <mayankgupta690@gmail.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth-httplib2
+Requires-Dist: google-auth-oauthlib
+Requires-Dist: pandas
+Requires-Dist: scikit-learn
+Requires-Dist: tqdm
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/logo.png" width="220" alt="Gmail Cleaner Logo">
+</p>
+
+<h1 align="center">Gmail Cleaner</h1>
+
+<p align="center">
+  <em>Because somewhere in those 50,000 emails is a tax document you actually need.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/gmail-cleaner/"><img src="https://img.shields.io/pypi/v/gmail-cleaner.svg?color=blue" alt="PyPI version"></a>
+  <a href="https://codecov.io/gh/immkg/gmail-cleaner"><img src="https://codecov.io/gh/immkg/gmail-cleaner/branch/main/graph/badge.svg" alt="Coverage"></a>
+  <a href="https://github.com/immkg/gmail-cleaner/releases/latest"><img src="https://img.shields.io/github/v/release/immkg/gmail-cleaner?style=flat-square&color=brightgreen&label=release" alt="Release"></a>
+  <img src="https://img.shields.io/badge/license-MIT-111111" alt="MIT license">
+</p>
+
+<p align="center">
+  <strong>Built by Mayank Gupta</strong><br>
+  <sub>Surgical precision for your inbox. ~99% less clutter &middot; ~100% more sanity &middot; 100% local.</sub>
+</p>
+
+---
+
+You have 50,000 emails. Somewhere in that mountain of newsletters, random promotions, and auto-generated alerts is a critical message from your bank that you cannot afford to lose. You can't just 'Select All -> Delete'.
+
+You need a surgical tool.
+
+With Gmail Cleaner:
+
+```bash
+# It just deletes them.
+python -m gmail_cleaner.main clean
+```
+
+Gmail Cleaner synchronizes your Gmail account into a local SQLite database, analyzes your emails using Pandas and Scikit-Learn, and interactively bulk-deletes the noise based on aggressive, local strategies.
+
+## Before / after
+
+You try to find an important bank email. Your search results are flooded with 400 "Limited Time Offer!" emails from a newsletter you never subscribed to. 
+
+After Gmail Cleaner: You actually see your bank email.
+
+## Setup
+
+The most effort Gmail Cleaner will ever ask of you:
+
+### 1. Enable the Gmail API
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
+2. Create a new project or select an existing one.
+3. Navigate to **APIs & Services > Library**.
+4. Search for "Gmail API" and click **Enable**.
+
+### 2. Set Up Desktop App Credentials
+1. Go to **APIs & Services > OAuth consent screen**. Choose **External** and add your own Gmail address under **Test users**.
+2. Go to **APIs & Services > Credentials**.
+3. Click **Create Credentials** > **OAuth client ID**.
+4. Choose **Desktop app**.
+5. Click **Download JSON** on the confirmation dialog.
+6. Rename the file to `credentials.json` and place it in the root folder.
+
+### 3. Install
+You can install directly from PyPI or download the standalone `.exe` from the latest GitHub Release.
+
+```bash
+pip install gmail-cleaner
+```
+
+## Configuration
+
+Before running the clean command, open `gmail_cleaner/config.py` and customize your patterns:
+
+- `AUTO_DELETE_EMAIL_PATTERNS`: Add email addresses or domains that you always want to delete instantly (e.g. `newsletter@spam.com`).
+- `PROTECTED_EMAIL_PATTERNS`: Add personal or banking emails that should NEVER be deleted by the tool (e.g. `@yourbank.com`).
+
+*Lazy, not negligent: The code ensures these patterns are scrubbed from version control, so you can safely keep this repo synced without leaking your personal contacts.*
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `python -m gmail_cleaner.main sync` | Syncs your emails to a local SQLite database. |
+| `python -m gmail_cleaner.main analyze` | Analyzes emails to show top domains, senders, and TF-IDF topic clusters. |
+| `python -m gmail_cleaner.main clean` | Starts the interactive CLI to bulk delete emails based on strategies (newsletters, promotions, etc.). |
+| `python -m gmail_cleaner.main clean --dry-run` | Simulates the deletion queue and prints what *would* be deleted without touching the Gmail API. |
+
+*When cleaning, you can select specific email ranges (e.g., `1,2,5-10`, `k10` to keep the latest 10) and accumulate deletions before executing them in bulk by typing `yes` to skip or `now` to process the queue.*
+
+## FAQ
+
+**Does it upload my emails to a random server?**
+No. It downloads them to a local SQLite database (`gmail.db`). The TF-IDF analysis, clustering, and deleting all happen entirely on your machine. 100% local.
+
+**Will it accidentally delete my tax returns or bank statements?**
+Not if you tell it not to. Add `@yourbank.com` or your accountant's email to `PROTECTED_EMAIL_PATTERNS` in `config.py`. Once there, it becomes structurally impossible for the tool to delete them, even if you explicitly select them.
+
+**Can I undo a deletion?**
+Yes. The tool moves emails to the Gmail Trash folder; it doesn't permanently annihilate them. You have 30 days to rescue them through the standard Gmail UI before Google purges them forever.
+
+**What if I really need that shoe store newsletter from 2019?**
+You don't. Insist anyway and you can use the `k` command (e.g., `k10`) to keep the latest 10 and delete the rest. But it will judge you silently.
+
+## License
+
+[MIT](LICENSE). The shortest license that works.

gmail_cleaner-0.1.0/README.md

@@ -0,0 +1,105 @@
+<p align="center">
+  <img src="assets/logo.png" width="220" alt="Gmail Cleaner Logo">
+</p>
+
+<h1 align="center">Gmail Cleaner</h1>
+
+<p align="center">
+  <em>Because somewhere in those 50,000 emails is a tax document you actually need.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/gmail-cleaner/"><img src="https://img.shields.io/pypi/v/gmail-cleaner.svg?color=blue" alt="PyPI version"></a>
+  <a href="https://codecov.io/gh/immkg/gmail-cleaner"><img src="https://codecov.io/gh/immkg/gmail-cleaner/branch/main/graph/badge.svg" alt="Coverage"></a>
+  <a href="https://github.com/immkg/gmail-cleaner/releases/latest"><img src="https://img.shields.io/github/v/release/immkg/gmail-cleaner?style=flat-square&color=brightgreen&label=release" alt="Release"></a>
+  <img src="https://img.shields.io/badge/license-MIT-111111" alt="MIT license">
+</p>
+
+<p align="center">
+  <strong>Built by Mayank Gupta</strong><br>
+  <sub>Surgical precision for your inbox. ~99% less clutter &middot; ~100% more sanity &middot; 100% local.</sub>
+</p>
+
+---
+
+You have 50,000 emails. Somewhere in that mountain of newsletters, random promotions, and auto-generated alerts is a critical message from your bank that you cannot afford to lose. You can't just 'Select All -> Delete'.
+
+You need a surgical tool.
+
+With Gmail Cleaner:
+
+```bash
+# It just deletes them.
+python -m gmail_cleaner.main clean
+```
+
+Gmail Cleaner synchronizes your Gmail account into a local SQLite database, analyzes your emails using Pandas and Scikit-Learn, and interactively bulk-deletes the noise based on aggressive, local strategies.
+
+## Before / after
+
+You try to find an important bank email. Your search results are flooded with 400 "Limited Time Offer!" emails from a newsletter you never subscribed to. 
+
+After Gmail Cleaner: You actually see your bank email.
+
+## Setup
+
+The most effort Gmail Cleaner will ever ask of you:
+
+### 1. Enable the Gmail API
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
+2. Create a new project or select an existing one.
+3. Navigate to **APIs & Services > Library**.
+4. Search for "Gmail API" and click **Enable**.
+
+### 2. Set Up Desktop App Credentials
+1. Go to **APIs & Services > OAuth consent screen**. Choose **External** and add your own Gmail address under **Test users**.
+2. Go to **APIs & Services > Credentials**.
+3. Click **Create Credentials** > **OAuth client ID**.
+4. Choose **Desktop app**.
+5. Click **Download JSON** on the confirmation dialog.
+6. Rename the file to `credentials.json` and place it in the root folder.
+
+### 3. Install
+You can install directly from PyPI or download the standalone `.exe` from the latest GitHub Release.
+
+```bash
+pip install gmail-cleaner
+```
+
+## Configuration
+
+Before running the clean command, open `gmail_cleaner/config.py` and customize your patterns:
+
+- `AUTO_DELETE_EMAIL_PATTERNS`: Add email addresses or domains that you always want to delete instantly (e.g. `newsletter@spam.com`).
+- `PROTECTED_EMAIL_PATTERNS`: Add personal or banking emails that should NEVER be deleted by the tool (e.g. `@yourbank.com`).
+
+*Lazy, not negligent: The code ensures these patterns are scrubbed from version control, so you can safely keep this repo synced without leaking your personal contacts.*
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `python -m gmail_cleaner.main sync` | Syncs your emails to a local SQLite database. |
+| `python -m gmail_cleaner.main analyze` | Analyzes emails to show top domains, senders, and TF-IDF topic clusters. |
+| `python -m gmail_cleaner.main clean` | Starts the interactive CLI to bulk delete emails based on strategies (newsletters, promotions, etc.). |
+| `python -m gmail_cleaner.main clean --dry-run` | Simulates the deletion queue and prints what *would* be deleted without touching the Gmail API. |
+
+*When cleaning, you can select specific email ranges (e.g., `1,2,5-10`, `k10` to keep the latest 10) and accumulate deletions before executing them in bulk by typing `yes` to skip or `now` to process the queue.*
+
+## FAQ
+
+**Does it upload my emails to a random server?**
+No. It downloads them to a local SQLite database (`gmail.db`). The TF-IDF analysis, clustering, and deleting all happen entirely on your machine. 100% local.
+
+**Will it accidentally delete my tax returns or bank statements?**
+Not if you tell it not to. Add `@yourbank.com` or your accountant's email to `PROTECTED_EMAIL_PATTERNS` in `config.py`. Once there, it becomes structurally impossible for the tool to delete them, even if you explicitly select them.
+
+**Can I undo a deletion?**
+Yes. The tool moves emails to the Gmail Trash folder; it doesn't permanently annihilate them. You have 30 days to rescue them through the standard Gmail UI before Google purges them forever.
+
+**What if I really need that shoe store newsletter from 2019?**
+You don't. Insist anyway and you can use the `k` command (e.g., `k10`) to keep the latest 10 and delete the rest. But it will judge you silently.
+
+## License
+
+[MIT](LICENSE). The shortest license that works.

gmail_cleaner-0.1.0/gmail_cleaner/analyze.py

@@ -0,0 +1,131 @@
+import sqlite3
+import re
+from collections import Counter
+from email.utils import parseaddr
+
+import pandas as pd
+from sklearn.cluster import MiniBatchKMeans
+from sklearn.feature_extraction.text import TfidfVectorizer
+from sklearn.feature_extraction import text as sklearn_text
+
+from gmail_cleaner.config import DB_FILE, AUTO_DELETE_EMAIL_PATTERNS, PROTECTED_EMAIL_PATTERNS
+
+
+def matches_pattern(email, patterns):
+    email = (email or "").lower()
+    for pattern in patterns:
+        pattern = pattern.lower()
+        if pattern.startswith("@"):
+            domain = pattern[1:]
+            if email.endswith("@" + domain) or email.endswith("." + domain):
+                return True
+        elif email == pattern:
+            return True
+    return False
+
+
+def extract_email(sender):
+    return parseaddr(sender or "")[1].lower()
+
+
+def extract_domain(sender):
+    email = extract_email(sender)
+    if "@" not in email:
+        return "(unknown)"
+    return email.split("@", 1)[1].lower()
+
+
+def canonical_email(sender):
+    email = extract_email(sender)
+    return email.lower() if email else ""
+
+
+def matches_auto_delete(email):
+    return matches_pattern(email, AUTO_DELETE_EMAIL_PATTERNS)
+
+
+def matches_protected(email):
+    return matches_pattern(email, PROTECTED_EMAIL_PATTERNS)
+
+
+def load_data():
+    conn = sqlite3.connect(DB_FILE)
+    df = pd.read_sql(
+        """
+        SELECT id, sender, subject, internal_date, snippet, body_text, deleted
+        FROM gmail_messages
+        WHERE COALESCE(deleted, 0) = 0
+        """,
+        conn,
+    )
+    conn.close()
+
+    df["email"] = df["sender"].fillna("").apply(canonical_email)
+    df = df[~df["email"].apply(matches_protected)]
+    df["domain"] = df["sender"].fillna("").apply(extract_domain)
+
+    return df
+
+
+def run_analysis():
+    df = load_data()
+
+    print("\n" + "=" * 100)
+    print(f"EMAILS: {len(df):,}")
+    print("=" * 100)
+
+    # --------------------------------------------------
+    # TOP DOMAINS
+    # --------------------------------------------------
+    print("\nTOP DOMAINS")
+    print("-" * 100)
+    for domain, count in df["domain"].value_counts().head(50).items():
+        print(f"{count:8,d}  {domain}")
+
+    # --------------------------------------------------
+    # TOP SENDERS
+    # --------------------------------------------------
+    print("\nTOP SENDERS")
+    print("-" * 100)
+    for sender, count in df["email"].value_counts().head(100).items():
+        print(f"{count:8,d}  {sender}")
+
+    # --------------------------------------------------
+    # SUBJECT WORD ANALYSIS
+    # --------------------------------------------------
+    subject_words = []
+    for subject in df["subject"].fillna(""):
+        tokens = re.findall(r"[a-zA-Z]{4,}", subject.lower())
+        subject_words.extend(tokens)
+
+    print("\nTOP SUBJECT WORDS")
+    print("-" * 100)
+    for word, count in Counter(subject_words).most_common(50):
+        print(f"{count:8,d}  {word}")
+
+    # --------------------------------------------------
+    # TF-IDF TOPICS
+    # --------------------------------------------------
+    print("\nTOPIC CLUSTERS")
+    print("-" * 100)
+    documents = df["subject"].fillna("") + " " + df["snippet"].fillna("")
+    vectorizer = TfidfVectorizer(
+        stop_words="english", max_features=5000, min_df=5)
+
+    if len(documents) > 0:
+        X = vectorizer.fit_transform(documents)
+        cluster_count = min(20, max(2, len(df) // 100))
+        model = MiniBatchKMeans(n_clusters=cluster_count,
+                                random_state=42, batch_size=2048)
+        model.fit(X)
+        terms = vectorizer.get_feature_names_out()
+
+        for cluster_id in range(cluster_count):
+            center = model.cluster_centers_[cluster_id]
+            top_indices = center.argsort()[-12:][::-1]
+            keywords = [terms[i] for i in top_indices]
+            size = (model.labels_ == cluster_id).sum()
+            print(f"\nCluster {cluster_id + 1} ({size:,} emails)")
+            print(", ".join(keywords))
+
+    print("\nDone.")

gmail_cleaner-0.1.0/gmail_cleaner/auth.py

@@ -0,0 +1,57 @@
+import time
+import random
+from pathlib import Path
+
+from google.oauth2.credentials import Credentials
+from google.auth.transport.requests import Request
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+from googleapiclient.errors import HttpError
+
+from gmail_cleaner.config import SCOPES, TOKEN_FILE, CREDS_FILE, MAX_RETRIES
+
+
+def get_gmail_service():
+    creds = None
+
+    if Path(TOKEN_FILE).exists():
+        creds = Credentials.from_authorized_user_file(TOKEN_FILE, SCOPES)
+
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+        else:
+            flow = InstalledAppFlow.from_client_secrets_file(
+                CREDS_FILE, SCOPES)
+            creds = flow.run_local_server(port=0)
+
+        with open(TOKEN_FILE, "w") as f:
+            f.write(creds.to_json())
+
+    return build("gmail", "v1", credentials=creds, cache_discovery=False)
+
+
+def gmail_call(request):
+    for attempt in range(MAX_RETRIES):
+        try:
+            result = request.execute(num_retries=3)
+            return result
+        except HttpError as e:
+            status = getattr(e.resp, "status", None)
+            if status in (429, 500, 502, 503, 504):
+                wait = min(60, 2 ** attempt) + random.random()
+                print(
+                    f"\nHTTP {status} retry {attempt+1}/{MAX_RETRIES} wait={wait:.1f}s")
+                time.sleep(wait)
+                continue
+            raise
+    raise RuntimeError("Max retries exceeded")
+
+
+def trash_email(gmail_id):
+    service = get_gmail_service()
+    try:
+        service.users().messages().trash(userId="me", id=gmail_id).execute()
+        return True
+    except Exception as e:
+        return str(e)

gmail_cleaner-0.1.0/gmail_cleaner/config.py

@@ -0,0 +1,28 @@
+# config.py
+
+DB_FILE = "gmail.db"
+CREDS_FILE = "credentials.json"
+TOKEN_FILE = "token.json"
+
+SCOPES = [
+    "https://www.googleapis.com/auth/gmail.modify"
+]
+
+MAX_WORKERS = 20
+MAX_RETRIES = 8
+COMMIT_BATCH = 100
+
+# --------------------------------------------------
+# CONFIGURABLE PATTERNS
+# --------------------------------------------------
+# Add email addresses or domains you want to automatically categorize for deletion here.
+# Example: "newsletter@example.com", "@spamdomain.com"
+AUTO_DELETE_EMAIL_PATTERNS = [
+    # Add your auto delete patterns here
+]
+
+# Add email addresses or domains you want to protect from accidental deletion.
+# Example: "personal@gmail.com", "@mybank.com"
+PROTECTED_EMAIL_PATTERNS = [
+    # Add your protected email patterns here
+]

gmail_cleaner-0.1.0/gmail_cleaner/db.py

@@ -0,0 +1,68 @@
+import sqlite3
+from gmail_cleaner.config import DB_FILE
+
+
+def init_db():
+    conn = sqlite3.connect(
+        DB_FILE,
+        check_same_thread=False
+    )
+
+    conn.execute("""
+    CREATE TABLE IF NOT EXISTS gmail_messages (
+        id TEXT PRIMARY KEY,
+        thread_id TEXT,
+        history_id INTEGER,
+        internal_date INTEGER,
+        label_ids TEXT,
+        subject TEXT,
+        sender TEXT,
+        recipients TEXT,
+        snippet TEXT,
+        body_text TEXT,
+        raw_json TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    )
+    """)
+
+    conn.execute("""
+    CREATE TABLE IF NOT EXISTS sync_state (
+        key TEXT PRIMARY KEY,
+        value TEXT
+    )
+    """)
+
+    conn.execute("""
+    CREATE INDEX IF NOT EXISTS idx_internal_date
+    ON gmail_messages(internal_date)
+    """)
+
+    # From analyze.py
+    try:
+        conn.execute("""
+        ALTER TABLE gmail_messages
+        ADD COLUMN deleted INTEGER NOT NULL DEFAULT 0
+        """)
+    except sqlite3.OperationalError:
+        pass
+
+    conn.commit()
+    return conn
+
+
+def get_state(conn, key):
+    row = conn.execute(
+        "SELECT value FROM sync_state WHERE key=?",
+        (key,)
+    ).fetchone()
+    return row[0] if row else None
+
+
+def set_state(conn, key, value):
+    conn.execute(
+        """
+        INSERT OR REPLACE INTO sync_state(key,value)
+        VALUES (?,?)
+        """,
+        (key, str(value))
+    )