velocity-python 0.1.17__tar.gz → 0.1.20__tar.gz

{velocity_python-0.1.17/src/velocity_python.egg-info → velocity_python-0.1.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.17
+Version: 0.1.20
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -30,7 +30,7 @@ Requires-Dist: openpyxl>=3.1.0; extra == "excel"
 Provides-Extra: templates
 Requires-Dist: jinja2>=3.1.0; extra == "templates"
 Provides-Extra: pdf
-Requires-Dist: weasyprint>=62.0; extra == "pdf"
+Requires-Dist: pdfkit>=1.0.0; extra == "pdf"
 Provides-Extra: http
 Requires-Dist: requests>=2.32.0; extra == "http"
 Provides-Extra: mysql

{velocity_python-0.1.17 → velocity_python-0.1.20}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.17"
+version = "0.1.20"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]
@@ -49,7 +49,7 @@ templates = [
   "jinja2>=3.1.0",
 ]
 pdf = [
-  "weasyprint>=62.0",
+  "pdfkit>=1.0.0",
 ]
 http = [
   "requests>=2.32.0",

{velocity_python-0.1.17 → velocity_python-0.1.20}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.17"
+__version__ = version = "0.1.20"
 
 import importlib as _importlib
 

{velocity_python-0.1.17 → velocity_python-0.1.20}/src/velocity/aws/handlers/base_handler.py

@@ -239,15 +239,16 @@ class BaseHandler:
                 or "error"
             )
 
-            logger.warning(
-                "AlertError during action execution",
-                exc_info=True,
-                extra={
-                    "handler": self.__class__.__name__,
-                    "action": getattr(local_context, "action", lambda: None)(),
-                    "tx_present": tx is not None,
-                },
-            )
+            if getattr(exception, "log_to_cloudwatch", False):
+                logger.warning(
+                    "AlertError during action execution",
+                    exc_info=True,
+                    extra={
+                        "handler": self.__class__.__name__,
+                        "action": getattr(local_context, "action", lambda: None)(),
+                        "tx_present": tx is not None,
+                    },
+                )
 
             # Default behavior: raising AlertError surfaces a UI alert.
             # If `toast: true` is present in the payload, show a toast instead.

{velocity_python-0.1.17 → velocity_python-0.1.20}/src/velocity/aws/handlers/exceptions.py

@@ -14,6 +14,7 @@ class AlertError(AppError):
         title: str | None = None,
         toast: bool = False,
         variant: str | None = None,
+        log_to_cloudwatch: bool = False,
         **payload,
     ):
         # Backwards compatible:
@@ -24,13 +25,16 @@ class AlertError(AppError):
             and title is None
             and toast is False
             and variant is None
+            and log_to_cloudwatch is False
             and not payload
         ):
             super().__init__(message)
+            self.log_to_cloudwatch = log_to_cloudwatch
             return
 
-        if isinstance(message, dict) and title is None and toast is False and variant is None and not payload:
+        if isinstance(message, dict) and title is None and toast is False and variant is None and log_to_cloudwatch is False and not payload:
             super().__init__(message)
+            self.log_to_cloudwatch = log_to_cloudwatch
             return
 
         data: dict = {}
@@ -49,6 +53,7 @@ class AlertError(AppError):
             data.update(payload)
 
         super().__init__(data)
+        self.log_to_cloudwatch = log_to_cloudwatch
 
     def get_payload(self):
         data = self.args[0]

velocity_python-0.1.20/src/velocity/misc/pdf.py

@@ -0,0 +1,217 @@
+"""
+HTML-to-PDF generation using pdfkit + wkhtmltopdf.
+
+The Python dependency surface is intentionally small: pdfkit wraps an external
+``wkhtmltopdf`` binary. On Lambda, the binary is typically supplied by the
+support layer at ``/opt/bin/wkhtmltopdf`` with companion shared libraries in
+``/opt/lib``.
+
+Usage::
+
+    from velocity.misc.pdf import html_to_pdf
+
+    pdf_bytes = html_to_pdf("<h1>Hello</h1><p>World</p>")
+
+    pdf_bytes = html_to_pdf(
+        html,
+        page_size="Letter",
+        orientation="landscape",
+        margin="0.5in",
+        footer_right="Page {page} of {pages}",
+    )
+
+    from velocity.misc.pdf import wrap_html, html_to_pdf
+
+    html = wrap_html("My Report", "<p>Content here</p>")
+    pdf_bytes = html_to_pdf(html)
+
+Requires the ``pdf`` extra plus a runnable ``wkhtmltopdf`` binary::
+
+    pip install velocity-python[pdf]
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+from typing import Optional
+
+logger = logging.getLogger("velocity.misc.pdf")
+
+_pdfkit_import_error: Exception | None = None
+
+try:
+    import pdfkit
+except ImportError as exc:
+    _pdfkit_import_error = exc
+    pdfkit = None  # type: ignore[assignment]
+
+
+_DEFAULT_BODY_CSS = """\
+body {
+    font-family: Arial, Helvetica, sans-serif;
+    font-size: 11pt;
+    line-height: 1.6;
+    color: #222;
+    margin: 0;
+    padding: 24px;
+}
+h1 { font-size: 20px; margin-bottom: 16px; }
+p  { margin: 0 0 12px; line-height: 1.6; }
+ol, ul { padding-left: 24px; }
+li { margin-bottom: 8px; }
+"""
+
+
+def _prepend_env_path(name: str, *paths: str) -> None:
+    current = os.environ.get(name, "")
+    existing = [path for path in current.split(":") if path]
+    merged: list[str] = []
+
+    for path in paths:
+        if path and os.path.isdir(path) and path not in merged:
+            merged.append(path)
+
+    for path in existing:
+        if path not in merged:
+            merged.append(path)
+
+    if merged:
+        os.environ[name] = ":".join(merged)
+
+
+def _configure_wkhtml_runtime() -> None:
+    if "AWS_LAMBDA_FUNCTION_NAME" not in os.environ:
+        return
+
+    os.environ.setdefault("FONTCONFIG_PATH", "/opt/fonts")
+    os.environ.setdefault("HOME", "/tmp")
+    os.environ.setdefault("XDG_RUNTIME_DIR", "/tmp")
+    os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+    _prepend_env_path("LD_LIBRARY_PATH", "/opt/lib")
+
+
+def _find_wkhtmltopdf() -> str | None:
+    configured = os.environ.get("WKHTMLTOPDF_PATH")
+    candidates = [
+        configured,
+        shutil.which("wkhtmltopdf"),
+        "/opt/bin/wkhtmltopdf",
+        "/opt/wkhtmltopdf",
+        "/opt/python/bin/wkhtmltopdf",
+        "/var/task/bin/wkhtmltopdf",
+    ]
+
+    for candidate in candidates:
+        if candidate and os.path.exists(candidate) and os.access(candidate, os.X_OK):
+            return candidate
+    return None
+
+
+def _normalize_footer_text(text: str) -> str:
+    return text.replace("{page}", "[page]").replace("{pages}", "[topage]")
+
+
+def _normalize_footer_font_size(value: str) -> str:
+    normalized = str(value or "8").strip().lower()
+    if normalized.endswith("pt"):
+        normalized = normalized[:-2].strip()
+    return normalized or "8"
+
+
+def _require_pdf_backend() -> tuple[object, object]:
+    if pdfkit is None:
+        base_message = (
+            "pdfkit is required for PDF generation. "
+            "Install it with: pip install velocity-python[pdf] or pip install pdfkit"
+        )
+        if _pdfkit_import_error is not None:
+            raise ImportError(
+                f"{base_message} Root cause: {_pdfkit_import_error!r}"
+            ) from _pdfkit_import_error
+        raise ImportError(base_message)
+
+    _configure_wkhtml_runtime()
+    wkhtmltopdf_path = _find_wkhtmltopdf()
+    if not wkhtmltopdf_path:
+        raise ImportError(
+            "wkhtmltopdf binary not available for PDF generation. "
+            "Expected it in PATH, WKHTMLTOPDF_PATH, or the Lambda layer under /opt/bin."
+        )
+
+    return pdfkit, pdfkit.configuration(wkhtmltopdf=wkhtmltopdf_path)
+
+
+def html_to_pdf(
+    html: str,
+    *,
+    page_size: str = "Letter",
+    orientation: str = "portrait",
+    margin: Optional[str] = None,
+    margin_top: Optional[str] = None,
+    margin_right: Optional[str] = None,
+    margin_bottom: Optional[str] = None,
+    margin_left: Optional[str] = None,
+    footer_right: Optional[str] = None,
+    footer_center: Optional[str] = None,
+    footer_font_size: str = "8pt",
+) -> bytes:
+    """Convert an HTML string to PDF bytes."""
+    pdf_backend, configuration = _require_pdf_backend()
+
+    options: dict[str, str] = {
+        "encoding": "UTF-8",
+        "page-size": page_size,
+        "orientation": orientation.capitalize(),
+        "enable-local-file-access": "",
+        "quiet": "",
+    }
+
+    if margin:
+        options["margin-top"] = margin
+        options["margin-right"] = margin
+        options["margin-bottom"] = margin
+        options["margin-left"] = margin
+    else:
+        options["margin-top"] = margin_top or "0.5in"
+        options["margin-right"] = margin_right or "0.5in"
+        options["margin-bottom"] = margin_bottom or "0.75in"
+        options["margin-left"] = margin_left or "0.5in"
+
+    if footer_right:
+        options["footer-right"] = _normalize_footer_text(footer_right)
+    if footer_center:
+        options["footer-center"] = _normalize_footer_text(footer_center)
+    if footer_right or footer_center:
+        options["footer-font-size"] = _normalize_footer_font_size(footer_font_size)
+
+    try:
+        return pdf_backend.from_string(
+            html,
+            False,
+            configuration=configuration,
+            options=options,
+        )
+    except Exception as exc:
+        logger.exception("wkhtmltopdf PDF generation failed")
+        raise RuntimeError(f"PDF generation failed: {exc}") from exc
+
+
+def wrap_html(title: str, body: str, css: str = "") -> str:
+    """Wrap a body fragment in a complete HTML document with default styles."""
+    all_css = _DEFAULT_BODY_CSS + "\n" + css
+    return f"""<!DOCTYPE html>
+<html>
+<head>
+<meta charset=\"utf-8\">
+<title>{title}</title>
+<style>
+{all_css}
+</style>
+</head>
+<body>
+<h1>{title}</h1>
+{body}
+</body>
+</html>"""

{velocity_python-0.1.17 → velocity_python-0.1.20/src/velocity_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.17
+Version: 0.1.20
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -30,7 +30,7 @@ Requires-Dist: openpyxl>=3.1.0; extra == "excel"
 Provides-Extra: templates
 Requires-Dist: jinja2>=3.1.0; extra == "templates"
 Provides-Extra: pdf
-Requires-Dist: weasyprint>=62.0; extra == "pdf"
+Requires-Dist: pdfkit>=1.0.0; extra == "pdf"
 Provides-Extra: http
 Requires-Dist: requests>=2.32.0; extra == "http"
 Provides-Extra: mysql

{velocity_python-0.1.17 → velocity_python-0.1.20}/src/velocity_python.egg-info/requires.txt

@@ -34,7 +34,7 @@ stripe>=12.0.0
 braintree>=4.30.0
 
 [pdf]
-weasyprint>=62.0
+pdfkit>=1.0.0
 
 [postgres]
 psycopg[binary]>=3.2.0

velocity_python-0.1.20/tests/test_pdf.py

@@ -0,0 +1,154 @@
+"""Tests for velocity.misc.pdf — HTML-to-PDF generation."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from velocity.misc.pdf import _DEFAULT_BODY_CSS, html_to_pdf, wrap_html
+
+
+class TestWrapHtml:
+
+    def test_produces_full_document(self):
+        result = wrap_html("My Title", "<p>Hello</p>")
+        assert "<!DOCTYPE html>" in result
+        assert "<title>My Title</title>" in result
+        assert "<h1>My Title</h1>" in result
+        assert "<p>Hello</p>" in result
+
+    def test_includes_default_css(self):
+        result = wrap_html("T", "<p>body</p>")
+        assert "font-family:" in result
+        assert _DEFAULT_BODY_CSS.strip()[:30] in result
+
+    def test_includes_custom_css(self):
+        result = wrap_html("T", "<p>body</p>", css=".custom { color: red; }")
+        assert ".custom { color: red; }" in result
+
+    def test_empty_body(self):
+        result = wrap_html("T", "")
+        assert "<h1>T</h1>" in result
+
+
+class TestHtmlToPdf:
+
+    def test_raises_without_pdfkit(self):
+        with patch("velocity.misc.pdf.pdfkit", None), patch(
+            "velocity.misc.pdf._pdfkit_import_error", ImportError("missing pdfkit")
+        ):
+            with pytest.raises(ImportError, match="pdfkit is required"):
+                html_to_pdf("<h1>test</h1>")
+
+    def test_raises_without_wkhtmltopdf_binary(self):
+        mock_pdfkit = MagicMock()
+
+        with patch("velocity.misc.pdf.pdfkit", mock_pdfkit), patch(
+            "velocity.misc.pdf._find_wkhtmltopdf", return_value=None
+        ):
+            with pytest.raises(ImportError, match="wkhtmltopdf binary not available"):
+                html_to_pdf("<h1>test</h1>")
+
+    def test_calls_pdfkit_with_defaults(self):
+        mock_pdfkit = MagicMock()
+        mock_config = object()
+        mock_pdfkit.configuration.return_value = mock_config
+        mock_pdfkit.from_string.return_value = b"%PDF-fake"
+
+        with patch("velocity.misc.pdf.pdfkit", mock_pdfkit), patch(
+            "velocity.misc.pdf._find_wkhtmltopdf", return_value="/opt/bin/wkhtmltopdf"
+        ):
+            result = html_to_pdf("<h1>Hello</h1>")
+
+        assert result == b"%PDF-fake"
+        mock_pdfkit.configuration.assert_called_once_with(
+            wkhtmltopdf="/opt/bin/wkhtmltopdf"
+        )
+        mock_pdfkit.from_string.assert_called_once()
+        call_args = mock_pdfkit.from_string.call_args
+        assert call_args.args[0] == "<h1>Hello</h1>"
+        assert call_args.args[1] is False
+        assert call_args.kwargs["configuration"] is mock_config
+        options = call_args.kwargs["options"]
+        assert options["page-size"] == "Letter"
+        assert options["orientation"] == "Portrait"
+        assert options["margin-top"] == "0.5in"
+        assert options["margin-right"] == "0.5in"
+        assert options["margin-bottom"] == "0.75in"
+        assert options["margin-left"] == "0.5in"
+        assert options["enable-local-file-access"] == ""
+
+    def test_passes_footer_and_margin_options(self):
+        mock_pdfkit = MagicMock()
+        mock_pdfkit.configuration.return_value = object()
+        mock_pdfkit.from_string.return_value = b"%PDF"
+
+        with patch("velocity.misc.pdf.pdfkit", mock_pdfkit), patch(
+            "velocity.misc.pdf._find_wkhtmltopdf", return_value="/opt/bin/wkhtmltopdf"
+        ):
+            html_to_pdf(
+                "<h1>report</h1>",
+                page_size="A4",
+                orientation="landscape",
+                margin_top="0.5in",
+                margin_right="0.45in",
+                margin_bottom="0.55in",
+                margin_left="0.45in",
+                footer_right="Page {page} of {pages}",
+                footer_center="CaringCent, LLC",
+                footer_font_size="8pt",
+            )
+
+        options = mock_pdfkit.from_string.call_args.kwargs["options"]
+        assert options["page-size"] == "A4"
+        assert options["orientation"] == "Landscape"
+        assert options["margin-top"] == "0.5in"
+        assert options["margin-right"] == "0.45in"
+        assert options["margin-bottom"] == "0.55in"
+        assert options["margin-left"] == "0.45in"
+        assert options["footer-right"] == "Page [page] of [topage]"
+        assert options["footer-center"] == "CaringCent, LLC"
+        assert options["footer-font-size"] == "8"
+
+    def test_shorthand_margin_applies_to_all_sides(self):
+        mock_pdfkit = MagicMock()
+        mock_pdfkit.configuration.return_value = object()
+        mock_pdfkit.from_string.return_value = b"%PDF"
+
+        with patch("velocity.misc.pdf.pdfkit", mock_pdfkit), patch(
+            "velocity.misc.pdf._find_wkhtmltopdf", return_value="/opt/bin/wkhtmltopdf"
+        ):
+            html_to_pdf("<h1>report</h1>", margin="1in", footer_font_size="10pt")
+
+        options = mock_pdfkit.from_string.call_args.kwargs["options"]
+        assert options["margin-top"] == "1in"
+        assert options["margin-right"] == "1in"
+        assert options["margin-bottom"] == "1in"
+        assert options["margin-left"] == "1in"
+
+    def test_wrap_then_convert(self):
+        mock_pdfkit = MagicMock()
+        mock_pdfkit.configuration.return_value = object()
+        mock_pdfkit.from_string.return_value = b"%PDF-wrapped"
+
+        html = wrap_html("Report", "<p>Content</p>")
+
+        with patch("velocity.misc.pdf.pdfkit", mock_pdfkit), patch(
+            "velocity.misc.pdf._find_wkhtmltopdf", return_value="/opt/bin/wkhtmltopdf"
+        ):
+            result = html_to_pdf(html)
+
+        assert result == b"%PDF-wrapped"
+        passed_html = mock_pdfkit.from_string.call_args.args[0]
+        assert "<title>Report</title>" in passed_html
+        assert "<p>Content</p>" in passed_html
+
+    def test_wraps_backend_errors(self):
+        mock_pdfkit = MagicMock()
+        mock_pdfkit.configuration.return_value = object()
+        mock_pdfkit.from_string.side_effect = OSError("boom")
+
+        with patch("velocity.misc.pdf.pdfkit", mock_pdfkit), patch(
+            "velocity.misc.pdf._find_wkhtmltopdf", return_value="/opt/bin/wkhtmltopdf"
+        ):
+            with pytest.raises(RuntimeError, match="PDF generation failed: boom"):
+                html_to_pdf("<h1>test</h1>")