git-ew 0.1.0__py3-none-any.whl

git_ew/_internal/debug.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2026, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import sys
+from dataclasses import dataclass
+from importlib import metadata
+
+_logger = logging.getLogger(__name__)
+
+
+@dataclass
+class _Variable:
+    """Dataclass describing an environment variable."""
+
+    name: str
+    """Variable name."""
+    value: str
+    """Variable value."""
+
+
+@dataclass
+class _Package:
+    """Dataclass describing a Python package."""
+
+    name: str
+    """Package name."""
+    version: str
+    """Package version."""
+
+
+@dataclass
+class _Environment:
+    """Dataclass to store environment information."""
+
+    interpreter_name: str
+    """Python interpreter name."""
+    interpreter_version: str
+    """Python interpreter version."""
+    interpreter_path: str
+    """Path to Python executable."""
+    platform: str
+    """Operating System."""
+    packages: list[_Package]
+    """Installed packages."""
+    variables: list[_Variable]
+    """Environment variables."""
+
+
+def _interpreter_name_version() -> tuple[str, str]:
+    if hasattr(sys, "implementation"):
+        impl = sys.implementation.version
+        version = f"{impl.major}.{impl.minor}.{impl.micro}"
+        kind = impl.releaselevel
+        if kind != "final":
+            version += kind[0] + str(impl.serial)
+        return sys.implementation.name, version
+    return "", "0.0.0"
+
+
+def _get_version(dist: str = "git-ew") -> str:
+    """Get version of the given distribution.
+
+    Parameters:
+        dist: A distribution name.
+
+    Returns:
+        A version number.
+    """
+    try:
+        return metadata.version(dist)
+    except metadata.PackageNotFoundError:
+        return "0.0.0"
+
+
+def _get_debug_info() -> _Environment:
+    """Get debug/environment information.
+
+    Returns:
+        Environment information.
+    """
+    py_name, py_version = _interpreter_name_version()
+    packages = ["git-ew"]
+    variables = ["PYTHONPATH", *[var for var in os.environ if var.startswith("GIT_EW")]]
+    return _Environment(
+        interpreter_name=py_name,
+        interpreter_version=py_version,
+        interpreter_path=sys.executable,
+        platform=platform.platform(),
+        variables=[_Variable(var, val) for var in variables if (val := os.getenv(var))],
+        packages=[_Package(pkg, _get_version(pkg)) for pkg in packages],
+    )
+
+
+def _format_debug_info() -> str:
+    """Format debug and environment information as Markdown."""
+    info = _get_debug_info()
+    lines = [
+        f"- __System__: {info.platform}",
+        f"- __Python__: {info.interpreter_name} {info.interpreter_version} ({info.interpreter_path})",
+        "- __Environment variables__:",
+    ]
+    lines.extend(f"  - `{var.name}`: `{var.value}`" for var in info.variables)
+    lines.append("- __Installed packages__:")
+    lines.extend(f"  - `{pkg.name}` v{pkg.version}" for pkg in info.packages)
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    _logger.info(_format_debug_info())

git_ew/_internal/email_fetcher.py

@@ -0,0 +1,301 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2026, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+from __future__ import annotations
+
+import asyncio
+import email
+import imaplib
+import logging
+import mailbox
+from datetime import date
+from email import policy
+from email.utils import getaddresses
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from git_ew._internal.email_parser import ParsedEmail, parse_email
+from git_ew._internal.secrets import resolve_password
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+_logger = logging.getLogger(__name__)
+
+
+class EmailFetcher:
+    """Base class for email fetchers."""
+
+    def fetch_emails(self, since: str | None = None) -> AsyncIterator[ParsedEmail]:
+        """Fetch emails from the source.
+
+        Args:
+            since: Fetch emails since this date (ISO format).
+
+        Yields:
+            ParsedEmail objects.
+        """
+        raise NotImplementedError
+
+
+class MaildirFetcher(EmailFetcher):
+    """Fetch emails from a Maildir directory."""
+
+    def __init__(self, maildir_path: str):
+        """Initialize Maildir fetcher.
+
+        Args:
+            maildir_path: Path to Maildir directory.
+        """
+        self.maildir_path = Path(maildir_path)
+        """Path to the Maildir directory."""
+
+    async def fetch_emails(self, since: str | None = None) -> AsyncIterator[ParsedEmail]:  # noqa: ARG002
+        """Fetch emails from Maildir.
+
+        Args:
+            since: Fetch emails since this date (ISO format).
+
+        Yields:
+            ParsedEmail objects.
+        """
+        if not self.maildir_path.exists():
+            return
+
+        # Use mailbox.Maildir to read the maildir
+        mbox = mailbox.Maildir(str(self.maildir_path))
+        try:
+            for message in mbox:
+                try:
+                    raw = message.as_bytes()
+                    parsed = parse_email(raw)
+                    yield parsed
+                except Exception as e:  # noqa: BLE001
+                    # Skip malformed emails
+                    _logger.debug("Skipping malformed Maildir message: %s", e)
+                    continue
+
+                # Allow event loop to process
+                await asyncio.sleep(0)
+        finally:
+            mbox.close()
+
+
+class MboxFetcher(EmailFetcher):
+    """Fetch emails from an mbox file."""
+
+    def __init__(self, mbox_path: str):
+        """Initialize mbox fetcher.
+
+        Args:
+            mbox_path: Path to mbox file.
+        """
+        self.mbox_path = Path(mbox_path)
+        """Path to the mbox file."""
+
+    async def fetch_emails(self, since: str | None = None) -> AsyncIterator[ParsedEmail]:  # noqa: ARG002
+        """Fetch emails from mbox.
+
+        Args:
+            since: Fetch emails since this date (ISO format).
+
+        Yields:
+            ParsedEmail objects.
+        """
+        if not self.mbox_path.exists():
+            return
+
+        mbox = mailbox.mbox(str(self.mbox_path))
+        try:
+            for message in mbox:
+                try:
+                    raw = message.as_bytes()
+                    parsed = parse_email(raw)
+                    yield parsed
+                except Exception as e:  # noqa: BLE001
+                    # Skip malformed emails
+                    _logger.debug("Skipping malformed mbox message: %s", e)
+                    continue
+
+                # Allow event loop to process
+                await asyncio.sleep(0)
+        finally:
+            mbox.close()
+
+
+class IMAPFetcher(EmailFetcher):
+    """Fetch emails from IMAP folders, including Fastmail accounts."""
+
+    def __init__(
+        self,
+        host: str,
+        username: str,
+        password: str,
+        *,
+        port: int = 993,
+        folders: list[str] | None = None,
+        mailing_list: dict[str, list[str]] | None = None,
+    ):
+        """Initialize an IMAP fetcher."""
+        self.host = host
+        """IMAP server hostname."""
+        self.port = port
+        """IMAP server port."""
+        self.username = username
+        """IMAP account username."""
+        self.password = password
+        """IMAP account password."""
+        self.folders = folders or ["INBOX", "Sent"]
+        """Folders to fetch messages from."""
+        self.mailing_list = mailing_list or {}
+        """Mailing list headers used to filter messages."""
+
+    async def fetch_emails(self, since: str | None = None) -> AsyncIterator[ParsedEmail]:
+        """Fetch and parse messages from configured IMAP folders."""
+        raw_messages = await asyncio.to_thread(self._fetch_messages, since)
+        for raw_message in raw_messages:
+            try:
+                yield parse_email(raw_message)
+            except Exception as e:  # noqa: BLE001
+                _logger.debug("Skipping malformed IMAP message: %s", e)
+            await asyncio.sleep(0)
+
+    def _fetch_messages(self, since: str | None) -> list[bytes]:
+        """Fetch raw messages using a synchronous IMAP connection."""
+        messages: list[bytes] = []
+        with imaplib.IMAP4_SSL(self.host, self.port) as client:
+            client.login(self.username, self.password)
+            for folder in self.folders:
+                status, _ = client.select(folder, readonly=True)
+                if status != "OK":
+                    raise RuntimeError(f"Unable to select IMAP folder {folder!r}")
+
+                criteria = "ALL"
+                if since:
+                    since_date = date.fromisoformat(since).strftime("%d-%b-%Y")
+                    criteria = f"SINCE {since_date}"
+                status, data = client.search(None, criteria)
+                if status != "OK":
+                    raise RuntimeError(f"Unable to search IMAP folder {folder!r}")
+
+                for message_number in data[0].split():
+                    if self.mailing_list:
+                        status, fetched = client.fetch(message_number, "(BODY.PEEK[HEADER])")
+                        if status != "OK":
+                            _logger.warning("Unable to fetch headers for message %s from %s", message_number, folder)
+                            continue
+                        headers = b"".join(
+                            item[1] for item in fetched if isinstance(item, tuple) and isinstance(item[1], bytes)
+                        )
+                        if not self._matches_mailing_list(headers):
+                            continue
+
+                    status, fetched = client.fetch(message_number, "(BODY.PEEK[])")
+                    if status != "OK":
+                        _logger.warning("Unable to fetch message %s from %s", message_number, folder)
+                        continue
+                    messages.extend(
+                        item[1] for item in fetched if isinstance(item, tuple) and isinstance(item[1], bytes)
+                    )
+        return messages
+
+    def _matches_mailing_list(self, raw_headers: bytes) -> bool:
+        """Return whether headers identify a configured mailing-list message."""
+        message = email.message_from_bytes(raw_headers, policy=policy.default)
+        addresses = {address.lower() for address in self.mailing_list.get("addresses", [])}
+        list_ids = {list_id.lower().strip("<>") for list_id in self.mailing_list.get("list_ids", [])}
+
+        if not addresses and not list_ids:
+            return True
+
+        address_headers = (
+            "To",
+            "Cc",
+            "Delivered-To",
+            "X-Original-To",
+            "Envelope-To",
+            "List-Post",
+        )
+        header_addresses = {
+            address.lower().removeprefix("mailto:")
+            for header in address_headers
+            for _, address in getaddresses(message.get_all(header, []))
+            if address
+        }
+        if addresses.intersection(header_addresses):
+            return True
+
+        return any(list_id in (message.get("List-Id", "").lower().strip("<>")) for list_id in list_ids)
+
+
+class PublicInboxFetcher(EmailFetcher):
+    """Fetch emails from a public-inbox archive URL."""
+
+    def __init__(self, archive_url: str):
+        """Initialize public-inbox fetcher.
+
+        Args:
+            archive_url: Base URL of the public-inbox archive.
+        """
+        self.archive_url = archive_url.rstrip("/")
+        """Base URL of the public-inbox archive."""
+
+    def fetch_emails(self, since: str | None = None) -> AsyncIterator[ParsedEmail]:
+        """Fetch emails from public-inbox archive.
+
+        Args:
+            since: Fetch emails since this date (ISO format).
+
+        Yields:
+            ParsedEmail objects.
+        """
+        # This would require implementing HTTP requests to fetch mbox files
+        # from public-inbox archives. For now, this is a placeholder.
+        # Real implementation would use httpx to fetch and parse mbox files
+        raise NotImplementedError("Public-inbox fetching not yet implemented")
+
+
+def get_fetcher(source_type: str, config: dict[str, Any]) -> EmailFetcher:
+    """Get an email fetcher based on source type.
+
+    Args:
+        source_type: Type of source (maildir, mbox, imap, public-inbox).
+        config: Configuration for the fetcher.
+
+    Returns:
+        EmailFetcher instance.
+
+    Raises:
+        ValueError: If source type is unknown.
+    """
+    if source_type == "maildir":
+        return MaildirFetcher(config["path"])
+    if source_type == "mbox":
+        return MboxFetcher(config["path"])
+    if source_type == "imap":
+        return IMAPFetcher(
+            host=config.get("host", "imap.fastmail.com"),
+            port=int(config.get("port", 993)),
+            username=config["username"],
+            password=resolve_password(config),
+            folders=config.get("folders"),
+            mailing_list=config.get("mailing_list"),
+        )
+    if source_type == "public-inbox":
+        return PublicInboxFetcher(config["url"])
+    raise ValueError(f"Unknown source type: {source_type}")

git_ew/_internal/email_parser.py

@@ -0,0 +1,274 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2026, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+# Email parsing utilities for git-ew.
+
+from __future__ import annotations
+
+import email
+import re
+from datetime import UTC, datetime
+from email import policy
+from email.utils import parseaddr, parsedate_to_datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from email.message import Message
+
+
+class ParsedEmail:
+    """Represents a parsed email message."""
+
+    def __init__(  # noqa: PLR0917
+        self,
+        message_id: str,
+        from_email: str,
+        from_name: str,
+        subject: str,
+        date: datetime,
+        body: str,
+        *,
+        in_reply_to: str | None = None,
+        references: list[str] | None = None,
+        is_patch: bool = False,
+        patch_content: str | None = None,
+        raw: str | None = None,
+    ):
+        """Initialize parsed email.
+
+        Args:
+            message_id: Unique message ID.
+            from_email: Sender email address.
+            from_name: Sender name.
+            subject: Email subject.
+            date: Email date.
+            body: Email body text.
+            in_reply_to: Message ID this replies to.
+            references: List of referenced message IDs.
+            is_patch: Whether this email contains a patch.
+            patch_content: Extracted patch content.
+            raw: Raw email content.
+        """
+        self.message_id = message_id
+        """Unique message ID."""
+        self.from_email = from_email
+        """Sender email address."""
+        self.from_name = from_name
+        """Sender name."""
+        self.subject = subject
+        """Email subject."""
+        self.date = date
+        """Email date."""
+        self.body = body
+        """Email body text."""
+        self.in_reply_to = in_reply_to
+        """Message ID this replies to."""
+        self.references = references or []
+        """List of referenced message IDs."""
+        self.is_patch = is_patch
+        """Whether this email contains a patch."""
+        self.patch_content = patch_content
+        """Extracted patch content."""
+        self.raw = raw
+        """Raw email content."""
+
+    def get_thread_id(self) -> str:
+        """Get the thread ID (first message in chain).
+
+        Returns:
+            Thread ID (the first message ID in the references chain).
+        """
+        if self.references:
+            return self.references[0]
+        if self.in_reply_to:
+            return self.in_reply_to
+        return self.message_id
+
+    @property
+    def clean_subject(self) -> str:
+        """Get subject with RE: and similar prefixes removed.
+
+        Returns:
+            Clean subject.
+        """
+        subject = self.subject
+        # Remove RE:, Re:, FWD:, Fwd: etc.
+        subject = re.sub(r"^(RE|Re|FW|Fw|FWD|Fwd):\s*", "", subject, flags=re.IGNORECASE)
+        subject = re.sub(r"^\[.*?\]\s*", "", subject)  # Remove [tag] prefixes
+        return subject.strip()
+
+
+def parse_email(raw_email: str | bytes) -> ParsedEmail:
+    """Parse a raw email message.
+
+    Args:
+        raw_email: Raw email content as string or bytes.
+
+    Returns:
+        ParsedEmail object.
+    """
+    raw_email_bytes = raw_email.encode("utf-8") if isinstance(raw_email, str) else raw_email
+
+    msg = email.message_from_bytes(raw_email_bytes, policy=policy.default)
+
+    # Extract basic headers
+    message_id = msg.get("Message-ID", "").strip("<>")
+    subject = msg.get("Subject", "No Subject")
+
+    # Parse from address
+    from_header = msg.get("From", "")
+    from_name, from_email = parseaddr(from_header)
+    if not from_name:
+        from_name = from_email
+
+    # Parse date
+    date_header = msg.get("Date")
+    try:
+        date = parsedate_to_datetime(date_header) if date_header else datetime.now(UTC)
+    except Exception:  # noqa: BLE001
+        date = datetime.now(UTC)
+
+    # Get reply information
+    in_reply_to = msg.get("In-Reply-To", "").strip("<>") or None
+    references_header = msg.get("References", "")
+    references = [ref.strip("<>") for ref in references_header.split() if ref.strip("<>")]
+
+    body, patch_content = extract_body_and_patch(msg)
+    is_patch = bool(patch_content)
+
+    # Detect and extract patches
+    # Look for git diff format or unified diff format
+    patch_patterns = [
+        r"diff --git",
+        r"^---.*\n\+\+\+",
+        r"^Index:",
+    ]
+
+    for pattern in patch_patterns:
+        if re.search(pattern, body, re.MULTILINE):
+            is_patch = True
+            # Extract everything from the first diff marker
+            match = re.search(r"(diff --git.*|^---.*\n\+\+\+.*|^Index:.*)", body, re.MULTILINE | re.DOTALL)
+            if match:
+                patch_content = body[match.start() :]
+            break
+
+    # Also check for [PATCH] in subject
+    if "[PATCH]" in subject.upper() or "PATCH" in subject.upper():
+        is_patch = True
+
+    return ParsedEmail(
+        message_id=message_id,
+        from_email=from_email,
+        from_name=from_name,
+        subject=subject,
+        date=date,
+        body=body,
+        in_reply_to=in_reply_to,
+        references=references,
+        is_patch=is_patch,
+        patch_content=patch_content,
+        raw=raw_email_bytes.decode("utf-8", errors="replace"),
+    )
+
+
+def _decode_part_payload(part: Message) -> str:
+    """Decode a MIME part payload to text."""
+    payload = part.get_payload(decode=True)
+    if isinstance(payload, bytes):
+        charset = part.get_content_charset() or "utf-8"
+        try:
+            return payload.decode(charset, errors="replace")
+        except (LookupError, TypeError):
+            return payload.decode("utf-8", errors="replace")
+    if isinstance(payload, str):
+        return payload
+    return ""
+
+
+def extract_body_and_patch(message: Message) -> tuple[str, str | None]:
+    """Extract the plain-text body and any MIME patch attachment."""
+    body = ""
+    patch_content = None
+
+    for part in message.walk():
+        if part.is_multipart():
+            continue
+
+        content_type = part.get_content_type().lower()
+        filename = (part.get_filename() or "").lower()
+        content = _decode_part_payload(part)
+
+        if content_type in {
+            "text/x-patch",
+            "text/x-diff",
+            "application/x-patch",
+            "application/x-diff",
+        } or filename.endswith(
+            (".patch", ".diff"),
+        ):
+            if patch_content is None:
+                patch_content = content
+        elif content_type == "text/plain" and not body:
+            body = content
+
+    return body, patch_content
+
+
+def extract_quoted_text(body: str) -> tuple[str, str]:
+    """Separate new content from quoted text.
+
+    Args:
+        body: Email body.
+
+    Returns:
+        Tuple of (new_content, quoted_content).
+    """
+    lines = body.split("\n")
+    new_lines = []
+    quoted_lines = []
+    in_quote = False
+
+    for line in lines:
+        stripped = line.strip()
+        # Common quote indicators
+        if stripped.startswith((">", "|")):
+            in_quote = True
+            quoted_lines.append(line)
+        elif stripped.startswith("On ") and " wrote:" in line:
+            # "On [date] [person] wrote:" pattern
+            in_quote = True
+            quoted_lines.append(line)
+        elif in_quote:
+            quoted_lines.append(line)
+        else:
+            new_lines.append(line)
+
+    return "\n".join(new_lines).strip(), "\n".join(quoted_lines).strip()
+
+
+def normalize_message_id(message_id: str) -> str:
+    """Normalize a message ID by removing angle brackets.
+
+    Args:
+        message_id: Message ID.
+
+    Returns:
+        Normalized message ID.
+    """
+    return message_id.strip("<>")