Metadata-Version: 2.4
Name: pyoeclassic
Version: 0.2.3
Summary: Python library for OE Classic email client data operations
Author: MBX Project
License: MIT
Keywords: email,oeclassic,mbx,mailbox,outlook-express,email-parser
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: beautifulsoup4>=4.9.0
Requires-Dist: tabulate>=0.8.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: search
Provides-Extra: mcp
Requires-Dist: fastmcp>=3.0.0; extra == "mcp"
Provides-Extra: service
Requires-Dist: pywin32>=306; platform_system == "Windows" and extra == "service"
Provides-Extra: all
Requires-Dist: fastmcp>=3.0.0; extra == "all"
Requires-Dist: pywin32>=306; platform_system == "Windows" and extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# PyOEClassic

A Python library for working with OE Classic email client data (MBX files and SQLite databases).

## Installation

```bash
pip install -e .
```

## Quick Start

```python
from pyoeclassic import Client

# Connect to an identity
client = Client(identity="Testing")

# List folders
for folder in client.folders.list():
    print(f"{folder.name}: {folder.total_count} emails")

# Access emails
inbox = client.emails("Inbox")
print(f"Total: {inbox.count()}, Unread: {inbox.unread_count()}")

# Search emails
results = inbox.search(subject="*report*", limit=10)

# Get full email content
email = inbox.get(1)
print(email.body_text)

# Export emails
inbox.export("backup.jsonl", format="jsonl")
```

## OEC Browser

A simple command-line tool for browsing OE Classic email data:

```bash
# Interactive mode (menu-driven)
python oec_browser.py

# List folders and email counts
python oec_browser.py --list

# Show all files in identity folder
python oec_browser.py --all-files

# List detached folders (files not in database)
python oec_browser.py --detached

# Browse a specific folder
python oec_browser.py --folder Inbox

# Browse a detached folder directly
python oec_browser.py --detached-folder "Archive"

# Search by subject or sender
python oec_browser.py --search-subject "report" --search-folder Inbox
python oec_browser.py --search-sender "john@example.com"

# Analytics
python oec_browser.py --stats              # Folder statistics
python oec_browser.py --top-senders Inbox  # Top senders in folder
python oec_browser.py --top-senders-all    # Top senders across all folders
```

### Interactive Menu Features

- **Browse**: Folder tree, detached folders, all files
- **Search**: By subject, sender, or content (single folder or all)
- **Analytics**: Folder stats, top senders, top domains

## CLI

```bash
# List identities
pyoeclassic identities

# Show identity info
pyoeclassic info -i Testing

# List folders
pyoeclassic folders list --tree

# Folder operations
pyoeclassic folders attach "MyFolder"
pyoeclassic folders detach 5
pyoeclassic folders status

# Email operations
pyoeclassic emails list -f Inbox
pyoeclassic emails search "*report*" -f Inbox
pyoeclassic emails export backup.jsonl -f Inbox
```

## MCP Service (Internal Install)

The OE Classic search/write MCP server is packaged as optional PyOEClassic
features for the local Windows automation setup:

```bash
pip install -e ".[all]"
pyoeclassic-mcp --host 127.0.0.1 --port 8093
pyoeclassic-build-index --update
```

The Windows service wrapper can be installed/refreshed through a local
deployment script that runs the packaged service module under a Python
environment with pywin32. The service is intentionally local-only
(`127.0.0.1:8093`) and bound to `Main Identity`.

External Gmail/Hotmail sending is handled by queueing messages into OE Classic
so OE can use its existing account authentication. The packaged MCP does not
ship the abandoned direct Gmail API send path.

## OE Classic Corruption Recovery

Operational recovery notes are included for agents and operators:

- Human runbook: `docs/runbooks/oeclassic-corrupt-mbx-recovery.md`
- Packaged LLM card: `pyoeclassic/llm/oeclassic-corruption-recovery.md`

The short version: stop OE Classic and `PythonOEClassicEmailMCP`, back up
the `.mbx/.db` pair, repair copied files first, and deploy only after structural
verification passes.

## Folder Attach/Detach

Archive old folders by detaching them:

```python
from pathlib import Path
from pyoeclassic import Client

client = Client(identity="Testing")

# Detach folder and move files to archive
client.folders.detach_to_archive(
    folder_id=5,
    archive_path=Path("/backups/email_archive")
)

# Re-attach later
client.folders.attach_from_archive(
    name="OldEmails",
    archive_path=Path("/backups/email_archive")
)
```

## Safety

The library protects "Main Identity" from write operations. Test identities (Testing, Testing2, Testing3) are safe for development.

## Project Structure

```
pyoeclassic/           # Main library
  client.py            # Client class
  core/                # Config, database, MBX parser
  operations/          # Folder and email managers
  models/              # Folder and Email models
  cli/                 # Command-line interface

oec_browser.py         # Simple browser tool
examples/              # Example scripts
tests/                 # Test suite
_legacy/               # Old scripts (archived)
```

## MBX File Format

OE Classic MBX files use a specific format:
- `[hdr]` - Message header marker
- `mlen=<hex>` - Message length in hexadecimal
- `[msg]` - Message content follows

## Running Tests

```bash
pytest
```
