mbox-extractor 0.1.4__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+main.py,sha256=TDk4cMcNkW7IZvz2kr-fQLUK4gJH-PIUmBnJI9oRmOM,2742
+mbox_extractor-0.1.4.dist-info/METADATA,sha256=D_rLzJn1mf6Lw9fD6sie5BGHnjOkTPbaDYNaJ0WvLDU,2581
+mbox_extractor-0.1.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mbox_extractor-0.1.4.dist-info/entry_points.txt,sha256=OYHWL_RW3Ng13Fwb9dfggI36Iwl52SJP4qUkUgEhJys,45
+mbox_extractor-0.1.4.dist-info/licenses/LICENSE,sha256=gTrdDdqFDu7VtWezebCYIHmebmc-XTVxqWTZGKvDux0,1068
+mbox_extractor-0.1.4.dist-info/RECORD,,

mbox_extractor-0.1.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mbox_extractor-0.1.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mbox-extractor = main:main

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