mailrows 0.1.0__py3-none-any.whl

mailrows/smtpcheck.py

@@ -0,0 +1,138 @@
+"""Find which port and security setting a mail server accepts, without sending anything."""
+
+from __future__ import annotations
+
+import smtplib
+import socket
+import ssl
+from dataclasses import dataclass
+
+COMBOS = [
+    (465, "ssl"),
+    (587, "starttls"),
+    (25, "starttls"),
+    (2525, "starttls"),
+    (25, "none"),
+    (2525, "none"),
+]
+
+
+@dataclass
+class Result:
+    port: int
+    security: str
+    connected: bool = False
+    logged_in: bool | None = None  # None: login not tried
+    message: str = ""
+
+    @property
+    def usable(self) -> bool:
+        return self.connected and self.logged_in is not False
+
+
+def explain(exc: BaseException, port: int, security: str) -> str:
+    if isinstance(exc, (socket.timeout, TimeoutError)):
+        return ("timed out. Something between you and the server is blocking this port: usually a firewall, "
+                "antivirus 'mail shield', or a network (office, hotel, ISP) that blocks outgoing mail ports")
+    if isinstance(exc, ConnectionRefusedError):
+        return "connection refused: the server isn't accepting mail on this port"
+    if isinstance(exc, socket.gaierror):
+        return "the host name could not be found. Check [smtp] host for typos"
+    if isinstance(exc, ssl.SSLCertVerificationError):
+        return f"the server's certificate is not valid for this host name ({exc.verify_message})"
+    if isinstance(exc, ssl.SSLError):
+        if security == "ssl":
+            return "SSL handshake failed: this port probably expects STARTTLS or plain SMTP, not SSL"
+        return f"encryption failed to start ({exc.reason or exc})"
+    if isinstance(exc, smtplib.SMTPNotSupportedError):
+        return "the server doesn't offer STARTTLS on this port"
+    if isinstance(exc, smtplib.SMTPAuthenticationError):
+        return "connected, but the username or password was refused. Some providers need an 'app password'"
+    if isinstance(exc, smtplib.SMTPServerDisconnected):
+        if security != "ssl" and port == 465:
+            return "the server hung up: port 465 normally needs security = ssl"
+        return "the server closed the connection straight away"
+    if isinstance(exc, ConnectionResetError):
+        return "the connection was reset, often by antivirus or a firewall inspecting mail traffic"
+    return f"{type(exc).__name__}: {exc}"
+
+
+def try_one(host: str, port: int, security: str, username: str, password: str, timeout: float) -> Result:
+    res = Result(port, security)
+    conn = None
+    try:
+        context = ssl.create_default_context()
+        if security == "ssl":
+            conn = smtplib.SMTP_SSL(host, port, timeout=timeout, context=context)
+        else:
+            conn = smtplib.SMTP(host, port, timeout=timeout)
+        conn.ehlo()
+        if security == "starttls":
+            conn.starttls(context=context)
+            conn.ehlo()
+        res.connected = True
+        if not username:
+            res.message = "connected (no username set, so login was not tested)"
+        elif security == "none":
+            res.message = "connected, but login was not tried: it would send your password unencrypted"
+        elif not conn.has_extn("auth"):
+            res.logged_in = False
+            res.message = "connected, but the server doesn't offer login here"
+        else:
+            conn.login(username, password)
+            res.logged_in = True
+            res.message = "connected and logged in"
+    except Exception as exc:  # every failure becomes a readable line
+        if isinstance(exc, smtplib.SMTPAuthenticationError):
+            res.logged_in = False
+        res.message = explain(exc, port, security)
+    finally:
+        if conn is not None:
+            try:
+                conn.quit()
+            except Exception:
+                try:
+                    conn.close()
+                except Exception:
+                    pass
+    return res
+
+
+def check(host: str, username: str, password: str, timeout: float = 10, combos=None, out=print) -> Result | None:
+    out(f"Checking {host}. Nothing will be sent.\n")
+    try:
+        socket.getaddrinfo(host, None)
+    except socket.gaierror:
+        out(f"  {host}: the host name could not be found. Check [smtp] host for typos.")
+        return None
+    results = []
+    for port, security in combos or COMBOS:
+        out(f"  port {port:<5} {security:<9} ... ", end="")
+        res = try_one(host, port, security, username, password, timeout)
+        results.append(res)
+        mark = "OK  " if res.logged_in else ("ok  " if res.usable else "no  ")
+        out(f"{mark}{res.message}")
+
+    best = next((r for r in results if r.logged_in), None)
+    if best is None:
+        best = next((r for r in results if r.usable and r.security != "none"), None)
+    if best is None and not username:
+        # no password to protect: an unencrypted port is acceptable if it's all there is
+        best = next((r for r in results if r.usable), None)
+    out("")
+    if best:
+        out("Use these settings in the [smtp] section:")
+        out(f"  port = {best.port}")
+        out(f"  security = {best.security}")
+        if not best.logged_in:
+            out("(Login was not confirmed. Set username and password and run smtp-check again.)")
+    elif any(r.logged_in is False for r in results):
+        out("The server answered, but the login was refused. Check the username and password.")
+    else:
+        if all("timed out" in r.message for r in results):
+            out("Every port timed out. That almost always means a firewall or antivirus on this computer, "
+                "or the network you're on, is blocking outgoing mail. Try another network (a phone hotspot "
+                "is a quick test) or allow Python through the firewall/antivirus.")
+        else:
+            out("No working setting found. Check the host name with your email provider.")
+    return best

mailrows/table.py

@@ -0,0 +1,226 @@
+"""Reading rows from .xlsx or .csv, and writing the status column back.
+
+Every write re-opens the file, finds the row by its ID (so sorting or inserting rows in
+between is fine), and saves through a temporary file that then replaces the original, so
+an interrupted save can't leave a half-written file.
+"""
+
+from __future__ import annotations
+
+import csv
+import datetime as dt
+import io
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+class TableError(Exception):
+    pass
+
+
+class FileLocked(TableError):
+    """The file can't be written, usually because it is open in Excel."""
+
+
+@dataclass
+class Row:
+    line: int  # the row number a person sees in Excel (header is 1)
+    values: dict[str, str] = field(default_factory=dict)
+
+
+def as_text(value) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "TRUE" if value else "FALSE"
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    if isinstance(value, (dt.datetime, dt.date)):
+        if isinstance(value, dt.datetime) and value.time() != dt.time():
+            return value.isoformat(sep=" ")
+        return value.strftime("%Y-%m-%d")
+    return str(value).strip()
+
+
+def _replace_atomically(path: Path, write) -> None:
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        write(tmp)
+        os.replace(tmp, path)
+    except PermissionError as exc:
+        raise FileLocked(f"{path.name} can't be saved. Is it open in Excel or another program?") from exc
+    finally:
+        if tmp.exists():
+            try:
+                tmp.unlink()
+            except OSError:
+                pass
+
+
+class Table:
+    """One spreadsheet. Subclasses handle the file format."""
+
+    def __init__(self, path: Path):
+        self.path = path
+
+    @staticmethod
+    def open(path: Path, sheet: str = "", delimiter: str = "") -> "Table":
+        if not path.exists():
+            raise TableError(f"Spreadsheet {path} not found.")
+        suffix = path.suffix.lower()
+        if suffix == ".csv":
+            return CsvTable(path, delimiter)
+        if suffix == ".xlsx":
+            return XlsxTable(path, sheet)
+        raise TableError(f"{path.name}: use an .xlsx or .csv file.")
+
+    def read(self) -> tuple[list[str], list[Row]]:
+        raise NotImplementedError
+
+    def set_values(self, id_column: str, column: str, updates: dict[str, str]) -> int:
+        """Write column=value on the row whose id_column is each key. Returns rows written."""
+        raise NotImplementedError
+
+    def check_writable(self) -> None:
+        try:
+            with open(self.path, "r+b"):
+                pass
+        except PermissionError:
+            raise FileLocked(f"{self.path.name} is open in another program (often Excel). Close it and try again.")
+
+
+def _headers(raw: list) -> list[str]:
+    names = [as_text(v) for v in raw]
+    while names and not names[-1]:
+        names.pop()
+    seen = set()
+    for n in names:
+        if n and n in seen:
+            raise TableError(f"Two columns are both called '{n}'. Rename one.")
+        seen.add(n)
+    return names
+
+
+class CsvTable(Table):
+    def __init__(self, path: Path, delimiter: str = ""):
+        super().__init__(path)
+        self.delimiter = delimiter
+
+    def _load(self):
+        raw = self.path.read_bytes()
+        bom = raw.startswith(b"\xef\xbb\xbf")
+        try:
+            text = raw.decode("utf-8-sig")
+        except UnicodeDecodeError:
+            raise TableError(f"{self.path.name} is not UTF-8. Save it as 'CSV UTF-8' and try again.") from None
+        delim = self.delimiter
+        if not delim:
+            first = text.split("\n", 1)[0]
+            delim = max([",", ";", "\t"], key=first.count)
+        rows = list(csv.reader(io.StringIO(text, newline=""), delimiter=delim))
+        self.line_end = "\r\n" if b"\r\n" in raw else "\n"
+        return rows, delim, bom
+
+    def read(self):
+        rows, _, _ = self._load()
+        if not rows:
+            raise TableError(f"{self.path.name} is empty.")
+        headers = _headers(rows[0])
+        out = []
+        for i, raw in enumerate(rows[1:], start=2):
+            if not any(cell.strip() for cell in raw):
+                continue
+            values = {h: (raw[j].strip() if j < len(raw) else "") for j, h in enumerate(headers) if h}
+            out.append(Row(line=i, values=values))
+        return headers, out
+
+    def set_values(self, id_column, column, updates):
+        rows, delim, bom = self._load()
+        headers = _headers(rows[0])
+        if column not in headers:
+            raise TableError(f"{self.path.name} has no '{column}' column to write to.")
+        id_at, col_at = headers.index(id_column), headers.index(column)
+        written = 0
+        for raw in rows[1:]:
+            key = raw[id_at].strip() if id_at < len(raw) else ""
+            if key in updates:
+                while len(raw) <= col_at:
+                    raw.append("")
+                raw[col_at] = updates[key]
+                written += 1
+
+        def write(tmp: Path):
+            with open(tmp, "w", encoding="utf-8-sig" if bom else "utf-8", newline="") as f:
+                csv.writer(f, delimiter=delim, lineterminator=self.line_end).writerows(rows)
+
+        _replace_atomically(self.path, write)
+        return written
+
+
+class XlsxTable(Table):
+    def __init__(self, path: Path, sheet: str = ""):
+        super().__init__(path)
+        self.sheet = sheet
+
+    def _book(self, data_only: bool):
+        import openpyxl
+
+        try:
+            return openpyxl.load_workbook(self.path, data_only=data_only)
+        except PermissionError:
+            raise FileLocked(f"{self.path.name} can't be opened. Is it open in another program?") from None
+        except Exception as exc:  # openpyxl raises several kinds for a damaged file
+            raise TableError(f"{self.path.name} can't be read as an Excel file ({exc}).") from None
+
+    def _ws(self, wb):
+        if self.sheet:
+            if self.sheet not in wb.sheetnames:
+                raise TableError(f"{self.path.name} has no tab called '{self.sheet}'. Tabs: {', '.join(wb.sheetnames)}")
+            return wb[self.sheet]
+        return wb.worksheets[0]
+
+    def read(self):
+        # data_only gives the last calculated value of formula cells, which is what a person sees
+        wb = self._book(data_only=True)
+        try:
+            ws = self._ws(wb)
+            it = ws.iter_rows(values_only=True)
+            first = next(it, None)
+            if first is None:
+                raise TableError(f"{self.path.name} is empty.")
+            headers = _headers(list(first))
+            out = []
+            for i, raw in enumerate(it, start=2):
+                cells = [as_text(v) for v in raw]
+                if not any(cells):
+                    continue
+                values = {h: (cells[j] if j < len(cells) else "") for j, h in enumerate(headers) if h}
+                out.append(Row(line=i, values=values))
+            return headers, out
+        finally:
+            wb.close()
+
+    def set_values(self, id_column, column, updates):
+        # opened without data_only, so formulas are kept when the file is saved again
+        wb = self._book(data_only=False)
+        try:
+            ws = self._ws(wb)
+            headers = _headers([c.value for c in ws[1]])
+            if column not in headers:
+                raise TableError(f"{self.path.name} has no '{column}' column to write to.")
+            id_at, col = headers.index(id_column), headers.index(column) + 1
+            written = 0
+            for cells in ws.iter_rows(min_row=2):
+                if id_at >= len(cells):
+                    continue
+                key = as_text(cells[id_at].value)
+                if key in updates:
+                    cell = ws.cell(row=cells[id_at].row, column=col)
+                    cell.value = updates[key]
+                    cell.data_type = "s"  # always plain text, never a formula
+                    written += 1
+            _replace_atomically(self.path, wb.save)
+            return written
+        finally:
+            wb.close()

mailrows/template.py

@@ -0,0 +1,126 @@
+"""Email templates.
+
+A template file starts with a line "Subject: ..." and the rest is the body. Placeholders
+are {column name}, matched exactly against the spreadsheet headings. Write {{ or }} for a
+literal brace. An optional HTML file has the same placeholders (and no subject line); its
+values are HTML-escaped.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import html
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+SUBJECT_LINE = re.compile(r"\s*subject\s*:(.*)$", re.IGNORECASE)
+TOKEN = re.compile(r"\{\{|\}\}|\{([^{}\n]*)\}|[{}]")
+
+
+class TemplateError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Rendered:
+    to: str
+    subject: str
+    text: str
+    html: str | None
+
+    def fingerprint(self) -> str:
+        """Hash of exactly what the recipient gets. Same inputs, same hash."""
+        h = hashlib.sha256()
+        for part in (self.to.strip().lower(), self.subject, self.text, self.html or ""):
+            h.update(part.encode("utf-8"))
+            h.update(b"\x00")
+        return h.hexdigest()
+
+
+def placeholders(text: str, where: str) -> list[str]:
+    """Names used in a template, in order. Raises TemplateError on a stray brace."""
+    names = []
+    for m in TOKEN.finditer(text):
+        tok = m.group(0)
+        if tok in ("{{", "}}"):
+            continue
+        if tok in ("{", "}"):
+            line = text.count("\n", 0, m.start()) + 1
+            raise TemplateError(f"{where}, line {line}: a lone '{tok}'. Write '{tok}{tok}' for a literal brace.")
+        name = m.group(1).strip()
+        if not name:
+            line = text.count("\n", 0, m.start()) + 1
+            raise TemplateError(f"{where}, line {line}: empty placeholder {{}}.")
+        names.append(name)
+    return names
+
+
+def fill(text: str, values: dict[str, str], escape: bool = False) -> str:
+    def swap(m: re.Match) -> str:
+        tok = m.group(0)
+        if tok == "{{":
+            return "{"
+        if tok == "}}":
+            return "}"
+        value = values[m.group(1).strip()]
+        return html.escape(value) if escape else value
+
+    return TOKEN.sub(swap, text)
+
+
+@dataclass
+class Template:
+    subject: str
+    body: str
+    html_body: str | None = None
+    source: str = "template"
+
+    @classmethod
+    def load(cls, text_path: Path, html_path: Path | None = None) -> "Template":
+        if not text_path.exists():
+            raise TemplateError(f"Template file {text_path} not found.")
+        raw = text_path.read_text(encoding="utf-8-sig").replace("\r\n", "\n")
+        first, _, rest = raw.partition("\n")
+        head = SUBJECT_LINE.match(first)
+        if head is None:
+            raise TemplateError(f"{text_path.name}: the first line must start with 'Subject:'.")
+        subject = head.group(1).strip()
+        if not subject:
+            raise TemplateError(f"{text_path.name}: the subject line is empty.")
+        html_body = None
+        if html_path is not None:
+            if not html_path.exists():
+                raise TemplateError(f"HTML template {html_path} not found.")
+            html_body = html_path.read_text(encoding="utf-8-sig")
+        return cls(subject=subject, body=rest.lstrip("\n"), html_body=html_body, source=text_path.name)
+
+    def parts(self) -> list[tuple[str, str]]:
+        out = [("subject line", self.subject), (self.source, self.body)]
+        if self.html_body is not None:
+            out.append(("HTML template", self.html_body))
+        return out
+
+    def names(self) -> set[str]:
+        found: set[str] = set()
+        for where, text in self.parts():
+            found.update(placeholders(text, where))
+        return found
+
+    def check_columns(self, columns: list[str]) -> None:
+        """Stop before anything is sent if the template uses a column the sheet doesn't have."""
+        known = set(columns)
+        unknown = sorted(self.names() - known)
+        if unknown:
+            listed = ", ".join("{" + n + "}" for n in unknown)
+            raise TemplateError(
+                f"The template uses {listed}, which {'is' if len(unknown) == 1 else 'are'} not a column "
+                f"in the spreadsheet. Columns are: {', '.join(columns)}. "
+                "Placeholders must match a heading exactly, including capitals and spaces."
+            )
+
+    def render(self, to: str, values: dict[str, str]) -> Rendered:
+        subject = " ".join(fill(self.subject, values).split())  # no line breaks in a header
+        text = fill(self.body, values)
+        html_out = fill(self.html_body, values, escape=True) if self.html_body is not None else None
+        return Rendered(to=to, subject=subject, text=text, html=html_out)