penguin-email 0.1.0__tar.gz

penguin_email-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Penguin Tech Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

penguin_email-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: penguin-email
+Version: 0.1.0
+Summary: Pluggable email sending library for Penguin Tech applications
+Author-email: Penguin Tech Inc <dev@penguintech.io>
+License: MIT
+Project-URL: Homepage, https://www.penguintech.io
+Project-URL: Repository, https://github.com/penguintechinc/penguin-libs
+Keywords: penguintech,email,gmail,smtp,jinja2
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2>=3.1
+Provides-Extra: gmail
+Requires-Dist: google-auth>=2.0; extra == "gmail"
+Requires-Dist: google-auth-oauthlib>=1.0; extra == "gmail"
+Requires-Dist: google-api-python-client>=2.0; extra == "gmail"
+Provides-Extra: sendgrid
+Requires-Dist: requests>=2.31; extra == "sendgrid"
+Provides-Extra: dkim
+Requires-Dist: dkimpy>=1.1.5; extra == "dkim"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: bandit>=1.7; extra == "dev"
+Requires-Dist: google-auth>=2.0; extra == "dev"
+Requires-Dist: google-auth-oauthlib>=1.0; extra == "dev"
+Requires-Dist: google-api-python-client>=2.0; extra == "dev"
+Requires-Dist: requests>=2.31; extra == "dev"
+Requires-Dist: dkimpy>=1.1.5; extra == "dev"
+Dynamic: license-file
+
+# penguin-email
+
+Pluggable email sending library for Penguin Tech applications.
+
+## Features
+
+- **Gmail REST API** transport (OAuth2, primary)
+- **SMTP** transport (SSL / STARTTLS / PLAIN with `InsecureConnectionWarning`)
+- Fluent `EmailMessage` builder with Jinja2 templating
+- Built-in templates: welcome, notification, transactional, alert, password_reset, form
+- Form builder and table builder helpers
+- Full attachment support (files, bytes, inline images)
+- Formal `EmailTransport` Protocol — add new transports with zero core changes
+
+## Installation
+
+```bash
+pip install penguin-email            # SMTP + templates only
+pip install "penguin-email[gmail]"   # adds Gmail REST API support
+```
+
+## Quick Start
+
+```python
+from penguin_email import EmailClient, EmailMessage, SmtpTransport, SmtpMode
+
+transport = SmtpTransport(host="smtp.example.com", mode=SmtpMode.STARTTLS,
+                          username="user", password="pass")
+client = EmailClient(transport)
+
+result = client.send(
+    EmailMessage()
+    .from_addr("sender@example.com")
+    .to("recipient@example.com")
+    .subject("Hello!")
+    .template("welcome", name="Alice", app_name="MyApp", login_url="https://app.example.com/login")
+)
+print(result.success, result.message_id)
+```
+
+## Gmail Transport
+
+```python
+from penguin_email import EmailClient, EmailMessage, GmailTransport
+
+transport = GmailTransport.from_env()   # reads GMAIL_* env vars
+client = EmailClient(transport)
+```
+
+## License
+
+AGPL-3.0 — see LICENSE.md

penguin_email-0.1.0/README.md

@@ -0,0 +1,52 @@
+# penguin-email
+
+Pluggable email sending library for Penguin Tech applications.
+
+## Features
+
+- **Gmail REST API** transport (OAuth2, primary)
+- **SMTP** transport (SSL / STARTTLS / PLAIN with `InsecureConnectionWarning`)
+- Fluent `EmailMessage` builder with Jinja2 templating
+- Built-in templates: welcome, notification, transactional, alert, password_reset, form
+- Form builder and table builder helpers
+- Full attachment support (files, bytes, inline images)
+- Formal `EmailTransport` Protocol — add new transports with zero core changes
+
+## Installation
+
+```bash
+pip install penguin-email            # SMTP + templates only
+pip install "penguin-email[gmail]"   # adds Gmail REST API support
+```
+
+## Quick Start
+
+```python
+from penguin_email import EmailClient, EmailMessage, SmtpTransport, SmtpMode
+
+transport = SmtpTransport(host="smtp.example.com", mode=SmtpMode.STARTTLS,
+                          username="user", password="pass")
+client = EmailClient(transport)
+
+result = client.send(
+    EmailMessage()
+    .from_addr("sender@example.com")
+    .to("recipient@example.com")
+    .subject("Hello!")
+    .template("welcome", name="Alice", app_name="MyApp", login_url="https://app.example.com/login")
+)
+print(result.success, result.message_id)
+```
+
+## Gmail Transport
+
+```python
+from penguin_email import EmailClient, EmailMessage, GmailTransport
+
+transport = GmailTransport.from_env()   # reads GMAIL_* env vars
+client = EmailClient(transport)
+```
+
+## License
+
+AGPL-3.0 — see LICENSE.md

penguin_email-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "penguin-email"
+version = "0.1.0"
+description = "Pluggable email sending library for Penguin Tech applications"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.13"
+authors = [{name = "Penguin Tech Inc", email = "dev@penguintech.io"}]
+keywords = ["penguintech", "email", "gmail", "smtp", "jinja2"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Email",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "jinja2>=3.1",
+]
+
+[project.optional-dependencies]
+gmail = [
+    "google-auth>=2.0",
+    "google-auth-oauthlib>=1.0",
+    "google-api-python-client>=2.0",
+]
+sendgrid = [
+    "requests>=2.31",
+]
+dkim = [
+    "dkimpy>=1.1.5",
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0",
+    "bandit>=1.7",
+    "google-auth>=2.0",
+    "google-auth-oauthlib>=1.0",
+    "google-api-python-client>=2.0",
+    "requests>=2.31",
+    "dkimpy>=1.1.5",
+]
+
+[project.scripts]
+penguin-email = "penguin_email.cli:main"
+
+[project.urls]
+Homepage = "https://www.penguintech.io"
+Repository = "https://github.com/penguintechinc/penguin-libs"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+penguin_email = ["templates/builtin/*.j2"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["N802"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.bandit]
+skips = ["B101"]

penguin_email-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

penguin_email-0.1.0/src/penguin_email/__init__.py

@@ -0,0 +1,30 @@
+"""penguin-email — pluggable email sending library for Penguin Tech applications."""
+
+__version__ = "0.1.0"
+
+from .client import EmailClient
+from .message import EmailMessage
+from .signature import Signature
+from .transports import EmailTransport, SendResult
+from .transports.smtp import InsecureConnectionWarning, SmtpMode, SmtpTransport
+
+__all__ = [
+    "__version__",
+    "EmailClient",
+    "EmailMessage",
+    "EmailTransport",
+    "SendResult",
+    "Signature",
+    "SmtpTransport",
+    "SmtpMode",
+    "InsecureConnectionWarning",
+]
+
+# GmailTransport is only importable when google-auth extras are installed.
+# Import it lazily so SMTP-only users don't get an ImportError.
+try:
+    from .transports.gmail import GmailTransport  # noqa: F401
+
+    __all__ = [*__all__, "GmailTransport"]
+except ImportError:
+    pass

penguin_email-0.1.0/src/penguin_email/auth/__init__.py

@@ -0,0 +1,5 @@
+"""Gmail OAuth2 authentication helpers."""
+
+from .gmail_oauth import refresh_credentials, run_oauth_flow
+
+__all__ = ["run_oauth_flow", "refresh_credentials"]

penguin_email-0.1.0/src/penguin_email/auth/gmail_oauth.py

@@ -0,0 +1,73 @@
+"""Gmail OAuth2 flow and token refresh helpers."""
+
+from __future__ import annotations
+
+_SCOPES = ["https://www.googleapis.com/auth/gmail.send"]
+
+# Module-level imports so that unittest.mock.patch can target them.
+# Both are None when the [gmail] extra is not installed.
+try:
+    from google.auth.transport.requests import Request
+    from google_auth_oauthlib.flow import InstalledAppFlow
+except ImportError:
+    InstalledAppFlow = None  # type: ignore[assignment, misc]
+    Request = None  # type: ignore[assignment, misc]
+
+
+def run_oauth_flow(
+    credentials_path: str,
+    token_path: str,
+    scopes: list[str] | None = None,
+) -> None:
+    """Run the Google OAuth2 installed-app flow and save the token.
+
+    Opens a browser window for the user to grant permission.  The resulting
+    token is written to *token_path* for later use by
+    :class:`~penguin_email.transports.gmail.GmailTransport`.
+
+    Parameters
+    ----------
+    credentials_path:
+        Path to the ``credentials.json`` file downloaded from the Google
+        Cloud Console (OAuth 2.0 Client IDs).
+    token_path:
+        Path where the resulting ``token.json`` will be written (or
+        overwritten on refresh).
+    scopes:
+        OAuth2 scopes to request.  Defaults to
+        ``["https://www.googleapis.com/auth/gmail.send"]``.
+    """
+    if InstalledAppFlow is None:
+        raise ImportError(
+            "Gmail support requires 'google-auth-oauthlib'. "
+            "Install with: pip install 'penguin-email[gmail]'"
+        )
+
+    requested_scopes = scopes or _SCOPES
+    flow = InstalledAppFlow.from_client_secrets_file(credentials_path, requested_scopes)
+    creds = flow.run_local_server(port=0)
+
+    with open(token_path, "w") as f:
+        f.write(creds.to_json())
+
+    print(f"Token saved to {token_path}")
+
+
+def refresh_credentials(creds: object) -> object:
+    """Refresh an expired Google OAuth2 credential object.
+
+    Calls ``creds.refresh(Request())`` using the stored refresh token.
+    Returns the same credential object (mutated in place) for convenience.
+
+    Parameters
+    ----------
+    creds:
+        A :class:`google.oauth2.credentials.Credentials` instance.
+    """
+    if Request is None:
+        raise ImportError(
+            "Gmail support requires 'google-auth'. Install with: pip install 'penguin-email[gmail]'"
+        )
+
+    creds.refresh(Request())  # type: ignore[union-attr]
+    return creds

penguin_email-0.1.0/src/penguin_email/cli.py

@@ -0,0 +1,134 @@
+"""CLI entry point for penguin-email.
+
+Usage::
+
+    python -m penguin_email auth --credentials credentials.json --token token.json
+    python -m penguin_email check
+
+Or via the console script::
+
+    penguin-email auth --credentials credentials.json --token token.json
+    penguin-email check
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+
+def _cmd_auth(args: argparse.Namespace) -> int:
+    """Run the Gmail OAuth2 flow and save the token."""
+    try:
+        from .auth.gmail_oauth import run_oauth_flow
+    except ImportError:
+        print(
+            "ERROR: Gmail support not installed. Run: pip install 'penguin-email[gmail]'",
+            file=sys.stderr,
+        )
+        return 1
+
+    run_oauth_flow(
+        credentials_path=args.credentials,
+        token_path=args.token,
+        scopes=args.scopes or None,
+    )
+    return 0
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    """Run a health check on the configured transport."""
+    mode = os.environ.get("EMAIL_TRANSPORT", "smtp").lower()
+
+    if mode == "gmail":
+        try:
+            from .transports.gmail import GmailTransport
+
+            transport = GmailTransport.from_env()
+        except ImportError:
+            print(
+                "ERROR: Gmail support not installed. Run: pip install 'penguin-email[gmail]'",
+                file=sys.stderr,
+            )
+            return 1
+        except KeyError as exc:
+            print(f"ERROR: Missing environment variable: {exc}", file=sys.stderr)
+            return 1
+    else:
+        from .transports.smtp import SmtpMode, SmtpTransport
+
+        host = os.environ.get("SMTP_HOST", "localhost")
+        port_str = os.environ.get("SMTP_PORT", "")
+        mode_str = os.environ.get("SMTP_MODE", "starttls").upper()
+        username = os.environ.get("SMTP_USERNAME", "")
+        password = os.environ.get("SMTP_PASSWORD", "")
+
+        try:
+            smtp_mode = SmtpMode[mode_str]
+        except KeyError:
+            print(f"ERROR: Unknown SMTP_MODE '{mode_str}'", file=sys.stderr)
+            return 1
+
+        transport = SmtpTransport(
+            host=host,
+            port=int(port_str) if port_str else None,
+            mode=smtp_mode,
+            username=username,
+            password=password,
+        )
+
+    ok = transport.health_check()
+    if ok:
+        print(f"✓ Transport '{transport.transport_name}' is healthy.")
+        return 0
+    else:
+        print(f"✗ Transport '{transport.transport_name}' health check FAILED.", file=sys.stderr)
+        return 1
+
+
+def main() -> None:
+    """Entry point for ``penguin-email`` console script."""
+    parser = argparse.ArgumentParser(
+        prog="penguin-email",
+        description="penguin-email CLI — manage Gmail OAuth2 and check transport health",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # auth subcommand
+    auth_parser = subparsers.add_parser("auth", help="Run Gmail OAuth2 flow")
+    auth_parser.add_argument(
+        "--credentials",
+        default="credentials.json",
+        help="Path to Google credentials.json (default: credentials.json)",
+    )
+    auth_parser.add_argument(
+        "--token",
+        default="token.json",
+        help="Output path for token.json (default: token.json)",
+    )
+    auth_parser.add_argument(
+        "--scopes",
+        nargs="*",
+        help="OAuth2 scopes (default: gmail.send)",
+    )
+
+    # check subcommand
+    subparsers.add_parser(
+        "check",
+        help="Health-check the configured transport (reads EMAIL_TRANSPORT env var)",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "auth":
+        sys.exit(_cmd_auth(args))
+    elif args.command == "check":
+        sys.exit(_cmd_check(args))
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

penguin_email-0.1.0/src/penguin_email/client.py

@@ -0,0 +1,173 @@
+"""EmailClient — orchestrates message building, rendering, and sending."""
+
+from __future__ import annotations
+
+import logging
+
+from .message import EmailMessage
+from .signature import Signature
+from .templates.engine import TemplateRenderer
+from .transports import EmailTransport, SendResult
+
+logger = logging.getLogger(__name__)
+
+
+class EmailClient:
+    """High-level email client that validates, renders, and dispatches messages.
+
+    Parameters
+    ----------
+    transport:
+        Primary :class:`~penguin_email.transports.EmailTransport`.
+    fallback:
+        Optional secondary transport used when *fallback_on_error* is ``True``
+        and the primary transport raises an exception.
+    fallback_on_error:
+        When ``True``, a send error on the primary transport is logged and the
+        fallback transport is tried.  Defaults to ``False`` (re-raise).
+    default_signature:
+        Optional :class:`~penguin_email.signature.Signature` appended to
+        every message sent through this client. A signature attached
+        directly to a message via
+        :meth:`~penguin_email.message.EmailMessage.signature` overrides
+        this default for that message only.
+
+    Raises
+    ------
+    TypeError
+        If *transport* (or *fallback*) does not implement the
+        :class:`~penguin_email.transports.EmailTransport` protocol.
+    """
+
+    def __init__(
+        self,
+        transport: EmailTransport,
+        fallback: EmailTransport | None = None,
+        fallback_on_error: bool = False,
+        default_signature: Signature | None = None,
+    ) -> None:
+        if not isinstance(transport, EmailTransport):
+            raise TypeError(f"{transport!r} does not implement the EmailTransport protocol")
+        if fallback is not None and not isinstance(fallback, EmailTransport):
+            raise TypeError(f"{fallback!r} does not implement the EmailTransport protocol")
+        self._transport = transport
+        self._fallback = fallback
+        self._fallback_on_error = fallback_on_error
+        self._default_signature = default_signature
+        self._renderer = TemplateRenderer()
+
+    def send(self, message: EmailMessage) -> SendResult:
+        """Validate, render, and send *message*.
+
+        1. Calls :meth:`~penguin_email.message.EmailMessage.build` to validate.
+        2. Renders the template (if any) into HTML.
+        3. Appends the effective signature (message override or client
+           default) to both the HTML and plain-text bodies.
+        4. Tries the primary transport.
+        5. Falls back to the secondary transport when configured.
+
+        Returns a :class:`~penguin_email.transports.SendResult` with
+        ``transport_used`` set to the name of the transport that succeeded (or
+        attempted last).
+        """
+        if not message.is_built:
+            message.build()
+
+        self._render_message(message)
+        self._apply_signature(message)
+
+        try:
+            return self._transport.send(message)
+        except Exception as exc:
+            if self._fallback_on_error and self._fallback is not None:
+                logger.warning(
+                    "Primary transport '%s' failed (%s), trying fallback '%s'",
+                    self._transport.transport_name,
+                    exc,
+                    self._fallback.transport_name,
+                )
+                try:
+                    return self._fallback.send(message)
+                except Exception as fallback_exc:
+                    logger.error(
+                        "Fallback transport '%s' also failed: %s",
+                        self._fallback.transport_name,
+                        fallback_exc,
+                    )
+                    return SendResult(
+                        success=False,
+                        transport_used=self._fallback.transport_name,
+                        error=str(fallback_exc),
+                    )
+            raise
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _render_message(self, message: EmailMessage) -> None:
+        """Render the template (if any) and inject the result into the message.
+
+        After rendering, ``message._html_body`` is set so the transport only
+        needs to handle plain HTML.  This mutates the message in place.
+        """
+        if message.html_body:
+            # Already has raw HTML — nothing to render.
+            return
+
+        if message.template_name:
+            html = self._renderer.render_builtin(message.template_name, **message.template_kwargs)
+            message._html_body = html  # noqa: SLF001
+        elif message.template_path:
+            html = self._renderer.render_file(message.template_path, **message.template_kwargs)
+            message._html_body = html  # noqa: SLF001
+        elif message.form_data is not None:
+            html = self._renderer.render_builtin(
+                "form",
+                title=message.template_kwargs.get("title", "Form Submission"),
+                data=message.form_data,
+            )
+            message._html_body = html  # noqa: SLF001
+
+    def _apply_signature(self, message: EmailMessage) -> None:
+        """Render the effective signature and append it to both bodies.
+
+        A per-message signature (``EmailMessage.signature()``) overrides the
+        client-wide ``default_signature``; if neither is set, the message is
+        left completely untouched. This runs once, here, in the client —
+        never in a transport — so every transport (SMTP, Gmail, SendGrid)
+        receives an already-signed ``html_body``/``text_body`` and cannot
+        forget to apply it.
+
+        Every transport independently falls back to
+        ``strip_tags(html_body)`` for the plain-text body when
+        ``text_body`` is empty. To keep the signature's own text form (when
+        supplied) out of that fallback — i.e. to avoid ending up with
+        ``strip_tags(body_html + signature_html)`` instead of
+        ``strip_tags(body_html) + signature.text`` — the body's
+        auto-generated plain text is captured *before* the signature's HTML
+        is appended, and the final ``text_body`` is written back here so
+        transports see it already populated and skip their own fallback.
+        """
+        sig = message.signature_block or self._default_signature
+        if sig is None:
+            return
+
+        # Capture the body's own auto-generated plain text before the
+        # signature's HTML is merged in.
+        base_text = message.text_body or (
+            self._renderer.strip_tags(message.html_body) if message.html_body else ""
+        )
+
+        sig_html = self._renderer.render_string(sig.html, **sig.variables) if sig.html else ""
+        if sig.text:
+            sig_text = self._renderer.render_string(sig.text, autoescape=False, **sig.variables)
+        elif sig_html:
+            sig_text = self._renderer.strip_tags(sig_html)
+        else:
+            sig_text = ""
+
+        if sig_html:
+            message._html_body = message.html_body + sig_html  # noqa: SLF001
+
+        message._text_body = f"{base_text}\n\n{sig_text}" if sig_text else base_text  # noqa: SLF001