Skip to content

QUICK_START.md

Latest commit

 

History

History
153 lines (116 loc) · 3.66 KB

QUICK_START.md

File metadata and controls

153 lines (116 loc) · 3.66 KB

Quick Start Guide - Refactored Outlook Email Deleter

For End Users

How to Run

The application now uses a virtual environment for dependencies. Use the convenience script:

./run.sh

Or activate the virtual environment manually:

source venv/bin/activate
python email_deleter.py

See RUNNING.md for detailed instructions and troubleshooting.

For Developers

New Project Structure

outlook-email-deleter/
├── src/                    # All application code
│   ├── auth/              # OAuth2 authentication
│   ├── imap/              # IMAP email operations
│   ├── ui/                # User interface
│   ├── utils/             # Utilities (logging, parsing)
│   ├── config.py          # Configuration management
│   └── exceptions.py      # Custom exceptions
├── tests/                 # Unit tests
├── email_deleter.py       # Main entry point
└── requirements.txt       # Dependencies

Running Tests

# Setup (first time)
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_config.py -v

# Run with coverage
pytest tests/ --cov=src

Importing Modules

# Authentication
from src.auth import OAuth2Authenticator, TokenCache

# IMAP operations
from src.imap import EmailDeleter

# UI components
from src.ui.display import display_preview, display_welcome_banner

# Utilities
from src.utils.date_parser import parse_date_range
from src.utils.logger import setup_logger

# Configuration
from src.config import AppConfig, IMAP_CONFIG, OAUTH_CONFIG

# Exceptions
from src.exceptions import (
    AuthenticationError,
    IMAPConnectionError,
    EmailSearchError
)

Adding New Features

Example: Add a new search filter

  1. Update src/imap/client.py::search_emails() method
  2. Add tests in tests/test_imap_client.py
  3. Update UI in src/ui/display.py if needed

Example: Add a new configuration option

  1. Add to appropriate config class in src/config.py
  2. Add validation if needed
  3. Add tests in tests/test_config.py
  4. Use in relevant modules

Logging

Application logs to email_deleter.log by default:

from src.utils.logger import setup_logger

logger = setup_logger(__name__)
logger.info("Operation started")
logger.error("Operation failed", exc_info=True)

Error Handling

Use specific exceptions for better error handling:

from src.exceptions import AuthenticationError

try:
    # Your code
    pass
except AuthenticationError as e:
    print(f"Auth failed: {e}")
    print(e.get_recovery_guidance())  # User-friendly recovery steps

Configuration

Configuration is validated on startup:

from src.config import AppConfig

try:
    config = AppConfig()  # Loads from .env
    print(f"Email: {config.email}")
    print(f"IMAP Server: {config.imap.SERVER}")
except ConfigurationError as e:
    print(f"Config error: {e}")

Key Improvements

  1. Better Error Messages: Specific exceptions with recovery guidance
  2. Logging: All operations logged to file for debugging
  3. Testing: 59 comprehensive unit tests
  4. Type Safety: Full type hints for IDE support
  5. Modular: Easy to extend and maintain

Documentation

  • Main README: Usage and setup instructions
  • REFACTORING_SUMMARY.md: Detailed refactoring changes
  • Docstrings: Every function and class documented

Getting Help

  • Check email_deleter.log for debugging
  • Run tests: pytest tests/ -v
  • Read docstrings: All modules have comprehensive documentation
  • Check REFACTORING_SUMMARY.md for architecture details