upwork-learning 0.1.0__py3-none-any.whl

src/__init__.py

@@ -0,0 +1,3 @@
+"""Upwork Learning - Automation and Integration Tools."""
+
+__version__ = "0.1.0"

src/cli.py

@@ -0,0 +1,349 @@
+"""CLI entry point using Typer."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from src import __version__
+from src.integrations.email_handler import Email, EmailClient, EmailConfig
+from src.integrations.google_sheets import GoogleSheetsClient, GoogleSheetsConfig
+from src.integrations.pdf_processor import PDFProcessor
+from src.utils.logger import bind_request_id, get_logger
+
+app = typer.Typer(
+    name="upwork-learn",
+    help="Automation and Integration Tools for Upwork Projects",
+    add_completion=False,
+)
+console = Console()
+logger = get_logger(__name__)
+
+
+@app.command()
+def version() -> None:
+    """Show version information."""
+    console.print(f"[bold blue]upwork-learn[/bold blue] v{__version__}")
+
+
+@app.command()
+def sheets_read(
+    spreadsheet_id: Annotated[str, typer.Option("--spreadsheet-id", "-s", help="Spreadsheet ID")],
+    range_name: Annotated[str, typer.Option("--range", "-r", help="Range in A1 notation")],
+    credentials_path: Annotated[str | None, typer.Option("--credentials", "-c")] = None,
+) -> None:
+    """Read data from Google Sheets."""
+    try:
+        config = GoogleSheetsConfig(spreadsheet_id=spreadsheet_id)
+        if credentials_path:
+            config.credentials_path = Path(credentials_path)
+        client = GoogleSheetsClient(config=config)
+
+        with client:
+            data = client.read_range(range_name)
+
+        table = Table(title=f"Data from {range_name}")
+        table.add_column("Row", style="cyan")
+
+        for i, row in enumerate(data):
+            table.add_row(str(i + 1), " | ".join(str(cell) for cell in row))
+
+        console.print(table)
+
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def sheets_write(
+    spreadsheet_id: Annotated[str, typer.Option("--spreadsheet-id", "-s", help="Spreadsheet ID")],
+    range_name: Annotated[str, typer.Option("--range", "-r", help="Range in A1 notation")],
+    values: Annotated[str, typer.Option("--values", "-v", help="JSON array of values")],
+    credentials_path: Annotated[str | None, typer.Option("--credentials", "-c")] = None,
+) -> None:
+    """Write data to Google Sheets."""
+    import json
+
+    try:
+        config = GoogleSheetsConfig(spreadsheet_id=spreadsheet_id)
+        if credentials_path:
+            config.credentials_path = Path(credentials_path)
+        client = GoogleSheetsClient(config=config)
+
+        data = json.loads(values)
+
+        with client:
+            client.write_range(range_name, data)
+
+        console.print(f"[green]Successfully wrote {len(data)} rows[/green]")
+
+    except json.JSONDecodeError as e:
+        console.print("[bold red]Error:[/bold red] Invalid JSON format for values")
+        raise typer.Exit(1) from e
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def sheets_list(
+    spreadsheet_id: Annotated[str, typer.Option("--spreadsheet-id", "-s", help="Spreadsheet ID")],
+    credentials_path: Annotated[str | None, typer.Option("--credentials", "-c")] = None,
+) -> None:
+    """List worksheets in a spreadsheet."""
+    try:
+        config = GoogleSheetsConfig(spreadsheet_id=spreadsheet_id)
+        if credentials_path:
+            config.credentials_path = Path(credentials_path)
+        client = GoogleSheetsClient(config=config)
+
+        with client:
+            worksheets = client.get_worksheets()
+
+        table = Table(title="Worksheets")
+        table.add_column("Name", style="cyan")
+
+        for ws in worksheets:
+            table.add_row(ws)
+
+        console.print(table)
+
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def pdf_extract_text(
+    path: Annotated[str, typer.Argument(help="Path to PDF file")],
+    pages: Annotated[
+        str | None, typer.Option("--pages", "-p", help="Page numbers (comma-separated)")
+    ] = None,
+    output: Annotated[str | None, typer.Option("--output", "-o", help="Output file")] = None,
+) -> None:
+    """Extract text from PDF."""
+    try:
+        processor = PDFProcessor()
+
+        page_numbers = None
+        if pages:
+            page_numbers = [int(p.strip()) for p in pages.split(",")]
+
+        with processor:
+            if page_numbers:
+                data = processor.extract_text(path=path, page_numbers=page_numbers)
+            else:
+                data = processor.extract_text(path=path)
+
+        text = "\n\n".join(f"--- Page {i + 1} ---\n{text}" for i, text in data.items())
+
+        if output:
+            with open(output, "w", encoding="utf-8") as f:
+                f.write(text)
+            console.print(f"[green]Text extracted to {output}[/green]")
+        else:
+            console.print(text)
+
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def pdf_extract_tables(
+    path: Annotated[str, typer.Argument(help="Path to PDF file")],
+    output: Annotated[str | None, typer.Option("--output", "-o", help="Output file")] = None,
+) -> None:
+    """Extract tables from PDF."""
+    import json
+
+    try:
+        processor = PDFProcessor()
+
+        with processor:
+            tables = processor.extract_tables(path=path)
+            dicts = []
+            for table in tables:
+                dicts.extend(table.as_dicts)
+
+        if output:
+            with open(output, "w", encoding="utf-8") as f:
+                json.dump(dicts, f, indent=2, ensure_ascii=False)
+            console.print(f"[green]Tables extracted to {output}[/green]")
+        else:
+            console.print_json(data=dicts)
+
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def pdf_extract_invoice(
+    path: Annotated[str, typer.Argument(help="Path to PDF file")],
+) -> None:
+    """Extract invoice data from PDF."""
+    try:
+        processor = PDFProcessor()
+
+        with processor:
+            data = processor.extract_invoice_data(path)
+
+        table = Table(title="Extracted Invoice Data")
+        table.add_column("Field", style="cyan")
+        table.add_column("Value", style="green")
+
+        for key, value in data.items():
+            if key != "line_items":
+                table.add_row(key, str(value))
+
+        console.print(table)
+
+        if data.get("line_items"):
+            console.print("\n[bold]Line Items:[/bold]")
+            console.print_json(data=data["line_items"])
+
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def email_send(
+    to: Annotated[str, typer.Option("--to", "-t", help="Recipient email(s), comma-separated")],
+    subject: Annotated[str, typer.Option("--subject", "-s", help="Email subject")],
+    body: Annotated[str, typer.Option("--body", "-b", help="Email body")],
+    cc: Annotated[str | None, typer.Option("--cc", help="CC recipients, comma-separated")] = None,
+) -> None:
+    """Send an email."""
+    try:
+        config = EmailConfig()
+        client = EmailClient(config=config)
+
+        recipients = [r.strip() for r in to.split(",")]
+        cc_list = [r.strip() for r in cc.split(",")] if cc else []
+
+        email_msg = Email(
+            to=recipients,
+            subject=subject,
+            body=body,
+            cc=cc_list,
+        )
+
+        with client:
+            client.send_email(email_msg)
+
+        console.print("[green]Email sent successfully![/green]")
+
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def email_fetch(
+    folder: Annotated[str, typer.Option("--folder", "-f", help="IMAP folder")] = "INBOX",
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Max emails to fetch")] = 10,
+    unread_only: Annotated[
+        bool, typer.Option("--unread-only/--all", help="Only fetch unread")
+    ] = False,
+) -> None:
+    """Fetch emails from IMAP server."""
+    try:
+        config = EmailConfig()
+        client = EmailClient(config=config)
+
+        with client:
+            emails = client.fetch_emails(
+                folder=folder,
+                limit=limit,
+                unread_only=unread_only,
+            )
+
+        table = Table(title=f"Emails from {folder}")
+        table.add_column("UID", style="cyan", width=6)
+        table.add_column("From", style="yellow", width=20)
+        table.add_column("Subject", style="white")
+        table.add_column("Date", style="green", width=12)
+
+        for email in emails:
+            table.add_row(
+                str(email.uid),
+                email.from_address[:18] + "..."
+                if len(email.from_address) > 18
+                else email.from_address,
+                email.subject[:40] + "..." if len(email.subject) > 40 else email.subject,
+                email.date.strftime("%Y-%m-%d"),
+            )
+
+        console.print(table)
+
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def health() -> None:
+    """Check connectivity to configured external services."""
+    import socket
+
+    from src.utils.config import load_config
+
+    cfg = load_config()
+    all_ok = True
+
+    # SMTP check
+    smtp_host = cfg.email.smtp_host
+    smtp_port = cfg.email.smtp_port
+    try:
+        with socket.create_connection((smtp_host, smtp_port), timeout=5):
+            console.print(f"[green]SMTP {smtp_host}:{smtp_port} — OK[/green]")
+    except OSError as e:
+        console.print(f"[red]SMTP {smtp_host}:{smtp_port} — FAIL ({e})[/red]")
+        all_ok = False
+
+    # IMAP check
+    imap_host = cfg.email.imap_host
+    imap_port = cfg.email.imap_port
+    try:
+        with socket.create_connection((imap_host, imap_port), timeout=5):
+            console.print(f"[green]IMAP {imap_host}:{imap_port} — OK[/green]")
+    except OSError as e:
+        console.print(f"[red]IMAP {imap_host}:{imap_port} — FAIL ({e})[/red]")
+        all_ok = False
+
+    # Credentials file check
+    creds = cfg.google_sheets.credentials_path
+    import os as _os
+
+    creds_json = _os.environ.get("GOOGLE_SHEETS_CREDENTIALS_JSON")
+    if creds_json:
+        console.print("[green]Google credentials — OK (env var)[/green]")
+    elif creds.exists():
+        console.print(f"[green]Google credentials — OK ({creds})[/green]")
+    else:
+        console.print(f"[yellow]Google credentials — NOT FOUND ({creds})[/yellow]")
+
+    if not all_ok:
+        raise typer.Exit(1)
+
+
+def main() -> None:
+    """Main entry point."""
+    import logging as _logging
+
+    from src.utils.config import load_config
+    from src.utils.logger import configure_logging
+
+    cfg = load_config()
+    configure_logging(getattr(_logging, cfg.app.log_level, _logging.INFO))
+    bind_request_id()
+    app()
+
+
+if __name__ == "__main__":
+    main()

src/integrations/__init__.py

@@ -0,0 +1,9 @@
+"""Integration modules for external services."""
+
+from src.integrations.base import BaseIntegration, IntegrationError, RateLimitError
+
+__all__ = [
+    "BaseIntegration",
+    "IntegrationError",
+    "RateLimitError",
+]

src/integrations/base.py

@@ -0,0 +1,237 @@
+"""Base integration classes and common patterns."""
+
+import threading
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+import tenacity
+from tenacity import (
+    RetryCallState,
+    stop_after_attempt,
+)
+
+from src.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+T = TypeVar("T")
+
+
+class IntegrationError(Exception):
+    """Base exception for integration errors."""
+
+
+class RateLimitError(IntegrationError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(self, message: str, retry_after: int | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class AuthenticationError(IntegrationError):
+    """Raised when authentication fails."""
+
+
+class IntegrationConnectionError(IntegrationError):
+    """Raised when connection fails."""
+
+
+class _TokenBucket:
+    """Thread-safe token-bucket rate limiter.
+
+    Tokens refill at *rate* per second up to *capacity*.  Call ``acquire()``
+    before each outbound request; it blocks until a token is available.
+
+    Args:
+        rate: Tokens added per second (= maximum sustained requests/s).
+        capacity: Burst capacity (defaults to *rate*, i.e. no burst).
+    """
+
+    def __init__(self, rate: float, capacity: float | None = None) -> None:
+        if rate <= 0:
+            raise ValueError("rate must be positive")
+        self._rate = rate
+        self._capacity = capacity if capacity is not None else rate
+        self._tokens = self._capacity
+        self._last_refill = time.monotonic()
+        self._lock = threading.Lock()
+
+    def acquire(self) -> None:
+        """Block until a token is available, then consume it."""
+        while True:
+            with self._lock:
+                now = time.monotonic()
+                elapsed = now - self._last_refill
+                self._tokens = min(
+                    self._capacity, self._tokens + elapsed * self._rate
+                )
+                self._last_refill = now
+                if self._tokens >= 1.0:
+                    self._tokens -= 1.0
+                    return
+                wait = (1.0 - self._tokens) / self._rate
+            # Sleep outside the lock so other threads can proceed.
+            time.sleep(wait)
+
+
+@dataclass
+class IntegrationConfig:
+    """Base configuration for integrations."""
+
+    max_retries: int = 3
+    timeout: float = 30.0
+    rate_limit_delay: float = 1.0
+    #: Maximum outbound requests per second (0 = unlimited / no throttle).
+    requests_per_second: float = 0.0
+
+
+class BaseIntegration(ABC):
+    """Abstract base class for integrations.
+
+    Provides common patterns:
+    - Exponential backoff retry logic
+    - Rate limiting awareness
+    - Connection management
+    - Standardized logging
+    """
+
+    def __init__(self, config: IntegrationConfig | None = None) -> None:
+        self._config = config or IntegrationConfig()
+        self._connected = False
+        self._logger = get_logger(f"{__name__}.{self.__class__.__name__}")
+        self._bucket: _TokenBucket | None = (
+            _TokenBucket(self._config.requests_per_second)
+            if self._config.requests_per_second > 0
+            else None
+        )
+
+    @property
+    @abstractmethod
+    def service_name(self) -> str:
+        """Return the name of the service."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def connect(self) -> None:
+        """Establish connection to the service."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def disconnect(self) -> None:
+        """Close connection to the service."""
+        raise NotImplementedError
+
+    def __enter__(self) -> "BaseIntegration":
+        """Context manager entry."""
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        self.disconnect()
+
+    def _throttle(self) -> None:
+        """Pace outgoing requests to the configured rate.
+
+        Call once before each outbound API request.  When
+        ``IntegrationConfig.requests_per_second`` is 0 (the default) this is a
+        no-op.  When a positive rate is set this blocks until the token bucket
+        has a token available, ensuring the sustained request rate never exceeds
+        the configured limit.
+
+        Example::
+
+            def fetch_data(self) -> dict:
+                self._throttle()          # pace before hitting the API
+                return self._client.get("/data")
+        """
+        if self._bucket is not None:
+            self._bucket.acquire()
+
+    def retry_with_backoff(
+        self,
+        max_attempts: int | None = None,
+        initial_wait: float = 1.0,
+        max_wait: float = 60.0,
+    ) -> Callable[[Callable[..., T]], Callable[..., T]]:
+        """Decorator for retry with exponential backoff.
+
+        Args:
+            max_attempts: Maximum number of retry attempts
+            initial_wait: Initial wait time in seconds
+            max_wait: Maximum wait time in seconds
+
+        Returns:
+            Decorated function with retry logic
+        """
+        if max_attempts is None:
+            max_attempts = self._config.max_retries
+
+        stop_strategy = stop_after_attempt(max_attempts)
+        wait_strategy = tenacity.wait_exponential(
+            multiplier=initial_wait,
+            max=max_wait,
+        )
+
+        def before_callback(retry_state: RetryCallState) -> None:
+            """Log retry attempts."""
+            attempt = retry_state.attempt_number
+            exception = retry_state.outcome.exception() if retry_state.outcome else None
+            self._logger.warning(
+                f"Retry attempt {attempt}/{max_attempts} for {self.service_name}",
+                extra={"exception": str(exception) if exception else None},
+            )
+
+        return tenacity.retry(
+            stop=stop_strategy,
+            wait=wait_strategy,
+            before_sleep=before_callback,
+            reraise=True,
+        )
+
+    def _handle_rate_limit(self, response: Any) -> None:
+        """Handle rate limit response with automatic backoff.
+
+        If the response carries a 429 status, waits for the ``Retry-After``
+        interval (default: ``rate_limit_delay``) before raising
+        ``RateLimitError`` so the caller's retry logic gets a real chance to
+        succeed.
+
+        Args:
+            response: API response object
+
+        Raises:
+            RateLimitError: When rate limit is exceeded
+        """
+        if hasattr(response, "status_code") and response.status_code == 429:
+            retry_after_raw = response.headers.get("Retry-After")
+            retry_after = int(retry_after_raw) if retry_after_raw else None
+            wait = retry_after if retry_after is not None else self._config.rate_limit_delay
+            self._logger.warning(
+                "rate_limit_hit",
+                wait_seconds=wait,
+                retry_after=retry_after,
+            )
+            time.sleep(wait)
+            raise RateLimitError(
+                "Rate limit exceeded",
+                retry_after=retry_after,
+            )
+
+    def _validate_config(self) -> None:
+        """Validate integration configuration."""
+        if self._config.max_retries < 1:
+            raise ValueError("max_retries must be at least 1")
+        if self._config.timeout <= 0:
+            raise ValueError("timeout must be positive")
+        if self._config.rate_limit_delay < 0:
+            raise ValueError("rate_limit_delay cannot be negative")
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if integration is connected."""
+        return self._connected