gmail-streamer 0.2.2__tar.gz

gmail_streamer-0.2.2/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

gmail_streamer-0.2.2/.github/workflows/ci.yml

@@ -0,0 +1,11 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    uses: tsilva/.github/.github/workflows/test.yml@main

gmail_streamer-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,73 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - pyproject.toml
+      - src/gmail_streamer/__init__.py
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - run: uv sync
+      - run: |
+          exit_code=0
+          uv run --with pytest pytest || exit_code=$?
+          if [ $exit_code -eq 5 ]; then
+            echo "No tests collected — skipping"
+            exit 0
+          fi
+          exit $exit_code
+
+  pii-scan:
+    uses: tsilva/.github/.github/workflows/pii-scan.yml@main
+
+  publish-pypi:
+    needs: [test, pii-scan]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check version
+        id: check
+        uses: tsilva/.github/.github/actions/check-version@main
+
+      - name: Setup uv
+        if: steps.check.outputs.tag_exists == 'false'
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build package
+        if: steps.check.outputs.tag_exists == 'false'
+        run: uv build
+
+      - name: Create release
+        if: steps.check.outputs.tag_exists == 'false'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create ${{ steps.check.outputs.tag }} dist/* --generate-notes
+
+      - name: Publish to PyPI
+        if: steps.check.outputs.tag_exists == 'false'
+        uses: pypa/gh-action-pypi-publish@release/v1

gmail_streamer-0.2.2/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+src/gmail_streamer/_build_info.py
+*.pyc
+.venv/
+profiles/*/
+!profiles/example/
+profiles/example/token.json
+profiles/example/state.json
+profiles/example/credentials.json
+
+logs/
+
+# Managed by tsilva/.github
+# Do not remove - synced automatically
+.claude/
+.env
+.env.*
+.DS_Store
+node_modules/

gmail_streamer-0.2.2/.vscode/settings.json

@@ -0,0 +1,22 @@
+{
+    "workbench.colorCustomizations": {
+        "activityBar.activeBackground": "#f8b688",
+        "activityBar.background": "#f8b688",
+        "activityBar.foreground": "#15202b",
+        "activityBar.inactiveForeground": "#15202b99",
+        "activityBarBadge.background": "#099743",
+        "activityBarBadge.foreground": "#e7e7e7",
+        "commandCenter.border": "#15202b99",
+        "sash.hoverBorder": "#f8b688",
+        "statusBar.background": "#f59858",
+        "statusBar.foreground": "#15202b",
+        "statusBarItem.hoverBackground": "#f27a28",
+        "statusBarItem.remoteBackground": "#f59858",
+        "statusBarItem.remoteForeground": "#15202b",
+        "titleBar.activeBackground": "#f59858",
+        "titleBar.activeForeground": "#15202b",
+        "titleBar.inactiveBackground": "#f5985899",
+        "titleBar.inactiveForeground": "#15202b99"
+    },
+    "peacock.color": "#f59858"
+}

gmail_streamer-0.2.2/CLAUDE.md

@@ -0,0 +1,48 @@
+# CLAUDE.md
+
+## Project Overview
+
+gmail-streamer is a Python CLI tool that downloads Gmail messages matching configurable filters via OAuth2, organized by profiles.
+
+## Build & Run
+
+```bash
+uv sync                                          # Install dependencies
+gmail-streamer run <profile>                     # Download messages
+gmail-streamer --profile-dir /path run <profile> # Custom profile dir
+gmail-streamer profiles list                     # List available profiles
+gmail-streamer profiles init <name>              # Scaffold new profile
+gmail-streamer profiles show <name>              # Show profile config
+```
+
+## Architecture
+
+- `src/gmail_streamer/cli.py` — Click CLI entry point (group with `run` and `profiles` subcommands)
+- `src/gmail_streamer/paths.py` — Profile directory resolution and discovery
+- `src/gmail_streamer/config.py` — Loads and validates `config.yaml` into a `ProfileConfig` dataclass
+- `src/gmail_streamer/auth.py` — OAuth2 flow using google-auth-oauthlib, token caching
+- `src/gmail_streamer/gmail_client.py` — Gmail API wrapper: search, fetch raw messages, fetch attachments
+- `src/gmail_streamer/storage.py` — Saves `.eml` files and attachment files to disk
+
+## Profile Resolution
+
+Profiles directory is resolved in this order:
+1. `--profile-dir` flag or `GMAIL_STREAMER_PROFILE_DIR` env var
+2. `./profiles/` in current working directory (if it exists)
+3. `~/.gmail-streamer/profiles/` (fallback)
+
+The `profile` argument to `run` can be a name (looked up in the profiles dir) or a path to an existing directory.
+
+## Profile Structure
+
+Each profile lives in its own directory with:
+- `config.yaml` — filter query, target directory, mode (full/attachments_only)
+- `credentials.json` — user-provided OAuth client credentials
+- `token.json` — auto-generated after first OAuth flow
+
+## Key Conventions
+
+- Python 3.12+, uses hatchling build backend with uv
+- No tests yet
+- Sensitive files (token.json, credentials.json) are gitignored
+- README.md must be kept up to date with any significant project changes

gmail_streamer-0.2.2/LICENSE

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

gmail_streamer-0.2.2/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: gmail-streamer
+Version: 0.2.2
+Summary: CLI tool to download Gmail messages matching configurable filters via OAuth2
+Project-URL: Homepage, https://github.com/tsilva/gmail-streamer
+Project-URL: Repository, https://github.com/tsilva/gmail-streamer
+Project-URL: Issues, https://github.com/tsilva/gmail-streamer/issues
+Author: Tiago Silva
+License: MIT
+License-File: LICENSE
+Keywords: attachments,backup,cli,download,email,gmail,google,oauth2
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.12
+Requires-Dist: click
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth-httplib2
+Requires-Dist: google-auth-oauthlib
+Requires-Dist: pyyaml
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="logo.png" alt="gmail-streamer" width="512"/>
+
+  [![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://python.org)
+  [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+  **📧 Download Gmail messages matching your filters to local files 📥**
+
+</div>
+
+## ✨ Features
+
+- **🗂️ Profile-based configuration** — run multiple independent download profiles, each with its own filters, credentials, and output directory
+- **🔐 OAuth2 authentication** — secure Google sign-in with automatic token caching
+- **📧 Full message download** — save complete `.eml` files for archival
+- **📎 Attachments-only mode** — grab just the attachments, skip the rest
+- **🧠 Incremental downloads** — remembers what's already been downloaded, no duplicates across runs
+- **🔍 Gmail search filters** — use any Gmail search query (`from:`, `has:attachment`, `after:`, label filters, etc.)
+- **🏠 Works from anywhere** — install globally with `uv` and run from any directory
+
+## 🚀 Quick Start
+
+### 1. Install
+
+```bash
+git clone https://github.com/tsilva/gmail-streamer.git
+cd gmail-streamer
+uv tool install . --force --no-cache
+```
+
+### 2. Create a profile
+
+```bash
+gmail-streamer profiles init my-profile
+```
+
+This creates `~/.gmail-streamer/profiles/my-profile/` with a template `config.yaml`.
+
+### 3. Add your Gmail OAuth credentials
+
+Place your `credentials.json` (from [Google Cloud Console](https://console.cloud.google.com/apis/credentials)) into the profile directory.
+
+### 4. Configure the profile
+
+Edit `~/.gmail-streamer/profiles/my-profile/config.yaml`:
+
+```yaml
+filter: "from:example@gmail.com has:attachment"
+target_directory: "./downloads"
+mode: "full"  # or "attachments_only"
+```
+
+### 5. Run
+
+```bash
+gmail-streamer run my-profile
+```
+
+On first run, a browser window opens for OAuth authorization. Subsequent runs reuse the cached token.
+
+## 📁 Profile Resolution
+
+The profiles directory is resolved in this order:
+
+1. `--profile-dir` flag or `GMAIL_STREAMER_PROFILE_DIR` env var
+2. `./profiles/` in the current working directory (if it exists)
+3. `~/.gmail-streamer/profiles/` (default)
+
+The `profile` argument can be a **name** (looked up in the profiles directory) or a **path** to an existing directory (backward compatible).
+
+## 🛠️ CLI Reference
+
+```bash
+gmail-streamer run <profile>                     # Download messages
+gmail-streamer --profile-dir /path run <profile>  # Custom profiles directory
+gmail-streamer profiles list                      # List available profiles
+gmail-streamer profiles init <name>               # Scaffold a new profile
+gmail-streamer profiles show <name>               # Show profile config
+```
+
+## ⚙️ Profile Structure
+
+Each profile lives in its own directory with:
+
+| File | Purpose |
+|------|---------|
+| `config.yaml` | Filter query, target directory, download mode |
+| `credentials.json` | OAuth client credentials (you provide this) |
+| `token.json` | Auto-generated after first OAuth flow |
+
+## 🏗️ Architecture
+
+| Module | Responsibility |
+|--------|---------------|
+| `cli.py` | Click CLI entry point (group with `run` and `profiles` subcommands) |
+| `paths.py` | Profile directory resolution and discovery |
+| `config.py` | Loads and validates `config.yaml` into a `ProfileConfig` dataclass |
+| `auth.py` | OAuth2 flow with token caching |
+| `gmail_client.py` | Gmail API wrapper: search, fetch messages, fetch attachments |
+| `storage.py` | Saves `.eml` files and attachments to disk |
+
+## 📄 License
+
+[MIT](LICENSE)

gmail_streamer-0.2.2/README.md

@@ -0,0 +1,104 @@
+<div align="center">
+  <img src="logo.png" alt="gmail-streamer" width="512"/>
+
+  [![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://python.org)
+  [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+  **📧 Download Gmail messages matching your filters to local files 📥**
+
+</div>
+
+## ✨ Features
+
+- **🗂️ Profile-based configuration** — run multiple independent download profiles, each with its own filters, credentials, and output directory
+- **🔐 OAuth2 authentication** — secure Google sign-in with automatic token caching
+- **📧 Full message download** — save complete `.eml` files for archival
+- **📎 Attachments-only mode** — grab just the attachments, skip the rest
+- **🧠 Incremental downloads** — remembers what's already been downloaded, no duplicates across runs
+- **🔍 Gmail search filters** — use any Gmail search query (`from:`, `has:attachment`, `after:`, label filters, etc.)
+- **🏠 Works from anywhere** — install globally with `uv` and run from any directory
+
+## 🚀 Quick Start
+
+### 1. Install
+
+```bash
+git clone https://github.com/tsilva/gmail-streamer.git
+cd gmail-streamer
+uv tool install . --force --no-cache
+```
+
+### 2. Create a profile
+
+```bash
+gmail-streamer profiles init my-profile
+```
+
+This creates `~/.gmail-streamer/profiles/my-profile/` with a template `config.yaml`.
+
+### 3. Add your Gmail OAuth credentials
+
+Place your `credentials.json` (from [Google Cloud Console](https://console.cloud.google.com/apis/credentials)) into the profile directory.
+
+### 4. Configure the profile
+
+Edit `~/.gmail-streamer/profiles/my-profile/config.yaml`:
+
+```yaml
+filter: "from:example@gmail.com has:attachment"
+target_directory: "./downloads"
+mode: "full"  # or "attachments_only"
+```
+
+### 5. Run
+
+```bash
+gmail-streamer run my-profile
+```
+
+On first run, a browser window opens for OAuth authorization. Subsequent runs reuse the cached token.
+
+## 📁 Profile Resolution
+
+The profiles directory is resolved in this order:
+
+1. `--profile-dir` flag or `GMAIL_STREAMER_PROFILE_DIR` env var
+2. `./profiles/` in the current working directory (if it exists)
+3. `~/.gmail-streamer/profiles/` (default)
+
+The `profile` argument can be a **name** (looked up in the profiles directory) or a **path** to an existing directory (backward compatible).
+
+## 🛠️ CLI Reference
+
+```bash
+gmail-streamer run <profile>                     # Download messages
+gmail-streamer --profile-dir /path run <profile>  # Custom profiles directory
+gmail-streamer profiles list                      # List available profiles
+gmail-streamer profiles init <name>               # Scaffold a new profile
+gmail-streamer profiles show <name>               # Show profile config
+```
+
+## ⚙️ Profile Structure
+
+Each profile lives in its own directory with:
+
+| File | Purpose |
+|------|---------|
+| `config.yaml` | Filter query, target directory, download mode |
+| `credentials.json` | OAuth client credentials (you provide this) |
+| `token.json` | Auto-generated after first OAuth flow |
+
+## 🏗️ Architecture
+
+| Module | Responsibility |
+|--------|---------------|
+| `cli.py` | Click CLI entry point (group with `run` and `profiles` subcommands) |
+| `paths.py` | Profile directory resolution and discovery |
+| `config.py` | Loads and validates `config.yaml` into a `ProfileConfig` dataclass |
+| `auth.py` | OAuth2 flow with token caching |
+| `gmail_client.py` | Gmail API wrapper: search, fetch messages, fetch attachments |
+| `storage.py` | Saves `.eml` files and attachments to disk |
+
+## 📄 License
+
+[MIT](LICENSE)

gmail_streamer-0.2.2/gmail_streamer/_build_info.py

@@ -0,0 +1 @@
+GIT_HASH = "4eb78ce"

gmail_streamer-0.2.2/hatch_build.py

@@ -0,0 +1,24 @@
+"""Hatch build hook to embed git hash at build time."""
+
+import subprocess
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        try:
+            git_hash = subprocess.check_output(
+                ["git", "rev-parse", "--short", "HEAD"],
+                text=True,
+                stderr=subprocess.DEVNULL,
+            ).strip()
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            git_hash = "unknown"
+
+        build_info_path = Path(self.root) / "src" / "gmail_streamer" / "_build_info.py"
+        build_info_path.write_text(f'GIT_HASH = "{git_hash}"\n')
+
+        # Force include the generated file
+        build_data["force_include"][str(build_info_path)] = "gmail_streamer/_build_info.py"

gmail_streamer-0.2.2/profiles/example/config.yaml

@@ -0,0 +1,3 @@
+filter: "from:example@gmail.com has:attachment"
+target_directory: "./downloads"
+mode: "full"

gmail_streamer-0.2.2/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "gmail-streamer"
+version = "0.2.2"
+description = "CLI tool to download Gmail messages matching configurable filters via OAuth2"
+authors = [{ name = "Tiago Silva" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.12"
+keywords = ["gmail", "email", "download", "oauth2", "cli", "google", "attachments", "backup"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Email",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "google-api-python-client",
+    "google-auth-oauthlib",
+    "google-auth-httplib2",
+    "click",
+    "pyyaml",
+]
+
+[project.scripts]
+gmail-streamer = "gmail_streamer.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/tsilva/gmail-streamer"
+Repository = "https://github.com/tsilva/gmail-streamer"
+Issues = "https://github.com/tsilva/gmail-streamer/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gmail_streamer"]
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"

gmail_streamer-0.2.2/src/gmail_streamer/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.1"

gmail_streamer-0.2.2/src/gmail_streamer/auth.py

@@ -0,0 +1,33 @@
+from pathlib import Path
+
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+
+SCOPES = ["https://www.googleapis.com/auth/gmail.readonly"]
+
+
+def get_gmail_service(profile_dir: Path):
+    creds_path = profile_dir / "credentials.json"
+    token_path = profile_dir / "token.json"
+
+    creds = None
+    if token_path.exists():
+        creds = Credentials.from_authorized_user_file(str(token_path), SCOPES)
+
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+        else:
+            if not creds_path.exists():
+                raise FileNotFoundError(
+                    f"OAuth credentials not found: {creds_path}\n"
+                    "Download from Google Cloud Console and place in profile directory."
+                )
+            flow = InstalledAppFlow.from_client_secrets_file(str(creds_path), SCOPES)
+            creds = flow.run_local_server(port=0)
+        with open(token_path, "w") as f:
+            f.write(creds.to_json())
+
+    return build("gmail", "v1", credentials=creds)