mbox-extractor 0.1.4__tar.gz

mbox_extractor-0.1.4/.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"

mbox_extractor-0.1.4/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    outputs:
+      created: ${{ steps.check.outputs.exists == 'false' }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Get version
+        id: version
+        run: |
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=v$VERSION" >> "$GITHUB_OUTPUT"
+      - name: Check if tag exists
+        id: check
+        run: |
+          if gh release view "${{ steps.version.outputs.tag }}" &>/dev/null; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Create release
+        if: steps.check.outputs.exists == 'false'
+        run: gh release create "${{ steps.version.outputs.tag }}" --title "${{ steps.version.outputs.tag }}" --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    needs: release
+    if: needs.release.outputs.created == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

mbox_extractor-0.1.4/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Sensitive data - credentials and secrets
+.env.*
+.env.local
+.env.*.local
+*.pem
+*.key
+*.p12
+*.pfx
+credentials.json
+secrets.json
+service-account*.json
+*-credentials.json
+.aws/
+.ssh/
+*.gpg
+
+# API keys and tokens often in these
+config.local.*
+*.secret
+.secrets/
+
+# Logs (may contain sensitive data)
+logs/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build artifacts and caches
+.venv/
+node_modules/
+.npm/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Claude Code
+.claude-sandbox.json
+*.code-workspace

mbox_extractor-0.1.4/CLAUDE.md

@@ -0,0 +1,66 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+mbox-extractor is a command-line tool that recursively scans directories for `.mbox` email archive files and extracts all attachments. It's a single-file Python application with minimal dependencies.
+
+## Installation & Setup
+
+Install the tool using uv:
+
+```bash
+uv tool install .
+```
+
+## Running the Tool
+
+Extract attachments from all `.mbox` files in a directory:
+
+```bash
+mbox-extractor /path/to/search
+```
+
+Test during development by running the main.py module directly:
+
+```bash
+python main.py /path/to/test/directory
+```
+
+## Architecture
+
+This is a single-file application (`main.py`) with a simple processing pipeline:
+
+1. **File Discovery** (`find_mbox_files`): Recursively walks directory tree to find `.mbox` files
+2. **Attachment Extraction** (`extract_attachments`): For each `.mbox` file:
+   - Opens it as a mailbox using Python's `mailbox.mbox`
+   - Iterates through all messages with a progress bar
+   - Extracts attachments from each message
+   - Saves attachments with sanitized, unique filenames
+3. **Filename Handling**:
+   - `sanitize_filename`: Removes illegal characters for safe filesystem names
+   - Uniqueness is ensured by appending an 8-character MD5 hash of the file content
+
+**Key Design Points:**
+- Each `.mbox` file's attachments are saved to a folder with the same name as the `.mbox` file (without extension)
+- Filenames are made unique using content-based hashing (MD5) to prevent overwriting duplicate filenames
+- Progress display uses `tqdm` for visual feedback on large mailboxes
+
+## Dependencies
+
+- **tqdm**: Progress bar display
+- Python standard library: `mailbox`, `email`, `hashlib`, `argparse`, `os`, `re`
+
+## Project Configuration
+
+- Built with `hatchling` as the build backend
+- Entry point: `mbox-extractor` command → `main:main`
+- Python 3.7+ required
+- The `main.py` file is packaged in the wheel distribution
+
+## Important Notes
+
+- README.md must be kept up to date with any significant project changes
+- The tool uses `email.policy.default` for modern email parsing
+- The `get_unique_filepath` function at main.py:16 is deprecated (MD5-based uniqueness replaced it)

mbox_extractor-0.1.4/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.

mbox_extractor-0.1.4/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: mbox-extractor
+Version: 0.1.4
+Summary: Recursively extract attachments from .mbox files
+Project-URL: Homepage, https://github.com/tsilva/mbox-extractor
+Project-URL: Repository, https://github.com/tsilva/mbox-extractor
+Author-email: Tiago Silva <eng.tiago.silva@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.12
+Requires-Dist: tqdm
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="logo.png" alt="mbox-extractor" width="512"/>
+
+  # mbox-extractor
+
+  [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+  [![Python](https://img.shields.io/badge/python-3.7+-blue.svg)](https://python.org)
+
+  **📬 Recursively extract all attachments from .mbox email archives with a single command**
+
+</div>
+
+## Features
+
+- **Recursive scanning** - Finds all `.mbox` files in any directory tree
+- **Safe filenames** - Sanitizes attachment names, removing illegal characters
+- **No duplicates** - Uses content-based hashing to prevent overwrites
+- **Progress display** - Visual progress bar for large mailboxes
+
+## Quick Start
+
+```bash
+uv tool install mbox-extractor
+```
+
+```bash
+mbox-extractor /path/to/emails
+```
+
+## Installation
+
+### Using uv (recommended)
+
+```bash
+uv tool install mbox-extractor
+```
+
+### Using pip
+
+```bash
+pip install mbox-extractor
+```
+
+### From source
+
+```bash
+git clone https://github.com/tsilva/mbox-extractor.git
+cd mbox-extractor
+uv tool install .
+```
+
+## Usage
+
+Extract all attachments from `.mbox` files under a directory:
+
+```bash
+mbox-extractor /path/to/search
+```
+
+Attachments from each `.mbox` file are saved to a folder with the same name:
+
+```
+Found mbox: /emails/archive.mbox -> extracting to /emails/archive
+Extracting archive.mbox: 100%|████████████████████| 500/500 [00:10<00:00, 48.5it/s]
+Extracted 42 attachments to '/emails/archive'.
+```
+
+### How It Works
+
+1. Recursively scans the given path for `.mbox` files
+2. Opens each mailbox and iterates through all messages
+3. Extracts attachments with sanitized, unique filenames
+4. Saves them to a folder named after the source `.mbox` file
+
+Filenames are made unique by appending an 8-character MD5 hash of the file content, preventing overwrites when multiple attachments share the same name.
+
+## Requirements
+
+- Python 3.7+
+- tqdm (installed automatically)
+
+## License
+
+[MIT](LICENSE)

mbox_extractor-0.1.4/README.md

@@ -0,0 +1,84 @@
+<div align="center">
+  <img src="logo.png" alt="mbox-extractor" width="512"/>
+
+  # mbox-extractor
+
+  [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+  [![Python](https://img.shields.io/badge/python-3.7+-blue.svg)](https://python.org)
+
+  **📬 Recursively extract all attachments from .mbox email archives with a single command**
+
+</div>
+
+## Features
+
+- **Recursive scanning** - Finds all `.mbox` files in any directory tree
+- **Safe filenames** - Sanitizes attachment names, removing illegal characters
+- **No duplicates** - Uses content-based hashing to prevent overwrites
+- **Progress display** - Visual progress bar for large mailboxes
+
+## Quick Start
+
+```bash
+uv tool install mbox-extractor
+```
+
+```bash
+mbox-extractor /path/to/emails
+```
+
+## Installation
+
+### Using uv (recommended)
+
+```bash
+uv tool install mbox-extractor
+```
+
+### Using pip
+
+```bash
+pip install mbox-extractor
+```
+
+### From source
+
+```bash
+git clone https://github.com/tsilva/mbox-extractor.git
+cd mbox-extractor
+uv tool install .
+```
+
+## Usage
+
+Extract all attachments from `.mbox` files under a directory:
+
+```bash
+mbox-extractor /path/to/search
+```
+
+Attachments from each `.mbox` file are saved to a folder with the same name:
+
+```
+Found mbox: /emails/archive.mbox -> extracting to /emails/archive
+Extracting archive.mbox: 100%|████████████████████| 500/500 [00:10<00:00, 48.5it/s]
+Extracted 42 attachments to '/emails/archive'.
+```
+
+### How It Works
+
+1. Recursively scans the given path for `.mbox` files
+2. Opens each mailbox and iterates through all messages
+3. Extracts attachments with sanitized, unique filenames
+4. Saves them to a folder named after the source `.mbox` file
+
+Filenames are made unique by appending an 8-character MD5 hash of the file content, preventing overwrites when multiple attachments share the same name.
+
+## Requirements
+
+- Python 3.7+
+- tqdm (installed automatically)
+
+## License
+
+[MIT](LICENSE)

mbox_extractor-0.1.4/main.py

@@ -0,0 +1,72 @@
+import mailbox
+import os
+import re
+import hashlib
+from email import policy
+from email.parser import BytesParser
+import argparse
+from tqdm import tqdm
+
+def sanitize_filename(filename):
+    # Remove directories and illegal characters
+    filename = re.sub(r'[\\/*?:"<>|]', "_", filename)
+    filename = filename.replace("..", "")  # extra safety
+    return os.path.basename(filename)
+
+def get_unique_filepath(output_dir, filename):
+    # This function is no longer needed with MD5-based disambiguation
+    return os.path.join(output_dir, filename)
+
+def find_mbox_files(root_path):
+    """Recursively yield paths to all .mbox files under root_path."""
+    for dirpath, _, filenames in os.walk(root_path):
+        for fname in filenames:
+            if fname.lower().endswith('.mbox'):
+                yield os.path.join(dirpath, fname)
+
+def extract_attachments(mbox_file, output_dir):
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    print(f"Starting extraction for: {mbox_file}")
+    mbox = mailbox.mbox(mbox_file, factory=lambda f: BytesParser(policy=policy.default).parse(f))
+    attachment_count = 0
+
+    # Get total number of messages for tqdm progress bar
+    total_msgs = len(mbox)
+    for idx, message in enumerate(tqdm(mbox, total=total_msgs, desc=f"Extracting {os.path.basename(mbox_file)}")):
+        for part in message.iter_attachments():
+            filename = part.get_filename()
+            if filename:
+                clean_name = sanitize_filename(filename)
+                payload = part.get_payload(decode=True)
+                # Append short MD5 digest to filename for uniqueness
+                digest = hashlib.md5(payload).hexdigest()[:8]
+                base, ext = os.path.splitext(clean_name)
+                unique_name = f"{base}_{digest}{ext}"
+                safe_path = os.path.join(output_dir, unique_name)
+
+                # Save file
+                with open(safe_path, 'wb') as f:
+                    f.write(payload)
+                attachment_count += 1
+
+    print(f"Extracted {attachment_count} attachments to '{output_dir}'.")
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Recursively extract attachments from all .mbox files under a given path."
+    )
+    parser.add_argument(
+        "path",
+        help="Root directory or file to search for .mbox files"
+    )
+    args = parser.parse_args()
+    root_path = args.path
+    for mbox_path in find_mbox_files(root_path):
+        mbox_dir = os.path.splitext(mbox_path)[0]
+        print(f"Found mbox: {mbox_path} -> extracting to {mbox_dir}")
+        extract_attachments(mbox_path, mbox_dir)
+
+if __name__ == "__main__":
+    main()

mbox_extractor-0.1.4/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mbox-extractor"
+version = "0.1.4"
+description = "Recursively extract attachments from .mbox files"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Tiago Silva", email = "eng.tiago.silva@gmail.com" }
+]
+dependencies = [
+    "tqdm"
+]
+requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Communications :: Email",
+]
+
+[project.urls]
+Homepage = "https://github.com/tsilva/mbox-extractor"
+Repository = "https://github.com/tsilva/mbox-extractor"
+
+[project.scripts]
+mbox-extractor = "main:main"
+
+[tool.hatch.build.targets.wheel]
+include = ["main.py"]

mbox_extractor-0.1.4/uv.lock

@@ -0,0 +1,35 @@
+version = 1
+revision = 3
+requires-python = ">=3.12"
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "mbox-extractor"
+version = "0.1.1"
+source = { editable = "." }
+dependencies = [
+    { name = "tqdm" },
+]
+
+[package.metadata]
+requires-dist = [{ name = "tqdm" }]
+
+[[package]]
+name = "tqdm"
+version = "4.67.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a8/4b/29b4ef32e036bb34e4ab51796dd745cdba7ed47ad142a9f4a1eb8e0c744d/tqdm-4.67.1.tar.gz", hash = "sha256:f8aef9c52c08c13a65f30ea34f4e5aac3fd1a34959879d7e59e63027286627f2", size = 169737, upload-time = "2024-11-24T20:12:22.481Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d0/30/dc54f88dd4a2b5dc8a0279bdd7270e735851848b762aeb1c1184ed1f6b14/tqdm-4.67.1-py3-none-any.whl", hash = "sha256:26445eca388f82e72884e0d580d5464cd801a3ea01e63e5601bdff9ba6a48de2", size = 78540, upload-time = "2024-11-24T20:12:19.698Z" },
+]