velocity-python 0.1.91__tar.gz → 0.1.93__tar.gz

{velocity_python-0.1.91/src/velocity_python.egg-info → velocity_python-0.1.93}/PKG-INFO

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

{velocity_python-0.1.91 → velocity_python-0.1.93}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.91"
+version = "0.1.93"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]
@@ -57,6 +57,10 @@ templates = [
 pdf = [
   "pdfkit>=1.0.0",
 ]
+# Maintained HTML→PDF engine; native libs (Pango/Cairo) come from the OS or a layer.
+pdf-weasyprint = [
+  "weasyprint>=60.0",
+]
 http = [
   "requests>=2.32.0",
 ]

{velocity_python-0.1.91 → velocity_python-0.1.93}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.91"
+__version__ = version = "0.1.93"
 
 import importlib as _importlib
 

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

@@ -0,0 +1,494 @@
+"""
+HTML-to-PDF rendering behind a swappable adapter.
+
+Public surface
+--------------
+``html_to_pdf(html, **page_options)`` — the facade every consumer should call.
+It picks a renderer (see *Engine selection*) and returns PDF bytes. Its keyword
+contract is unchanged from the original pdfkit-only implementation, so existing
+callers keep working; ``engine=``, ``base_url=`` and ``extra_css=`` are additive.
+
+``BasePdfRenderer`` — the adapter interface. A renderer turns
+``(html, PageOptions, base_url, extra_css)`` into bytes. Two ship here:
+
+* ``WkhtmltopdfRenderer`` — the original path: pdfkit + the external
+  ``wkhtmltopdf`` binary (``/opt/bin/wkhtmltopdf`` + ``/opt/lib`` on Lambda).
+  That binary is an Amazon Linux 2 build and cannot load on Amazon Linux 2023
+  runtimes (python3.12+; ``libssl.so.10`` is gone), and upstream was archived in
+  2023 — it is kept, unchanged in behaviour, for existing python3.11/AL2 stacks.
+* ``WeasyPrintRenderer`` — WeasyPrint, a maintained pure-Python engine
+  (Pango/Cairo/HarfBuzz underneath). On Lambda the native libraries come from a
+  layer (e.g. kotify/cloud-print-utils' AL2023 build) with
+  ``LD_LIBRARY_PATH=/opt/lib`` and ``FONTCONFIG_PATH=/opt/fonts``. Page size,
+  orientation, margins and footers become CSS Paged Media (``@page``).
+  WeasyPrint honours CSS pixels literally — it has no "smart shrinking" — so
+  documents authored wider than the page for wkhtmltopdf must be restyled.
+
+Swapping the backend later (Chromium, a PDF microservice, a SaaS API, …) means
+subclassing ``BasePdfRenderer`` and calling ``register_renderer(name, instance)``;
+no caller changes.
+
+Engine selection (``get_renderer``)
+-----------------------------------
+1. an explicit ``engine="..."`` argument,
+2. else the ``VELOCITY_PDF_ENGINE`` environment variable,
+3. else the first *available* renderer in preference order (WeasyPrint, then
+   wkhtmltopdf) — which preserves the historical behaviour on stacks that only
+   have pdfkit + the binary.
+
+Usage::
+
+    from velocity.misc.pdf import html_to_pdf
+
+    pdf_bytes = html_to_pdf(html, page_size="Letter", margin="0in",
+                            base_url="/opt/templates")          # auto engine
+    pdf_bytes = html_to_pdf(html, engine="weasyprint",
+                            footer_right="Page {page} of {pages}")
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import shutil
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Dict, List, 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; }
+"""
+
+
+# ── Page options (engine-neutral) ──────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class PageOptions:
+    """Everything a renderer needs to know about the page, engine-neutral.
+
+    Margins default to the historical pdfkit values (0.5in / 0.5in / 0.75in /
+    0.5in) unless ``margin`` (all four) or individual sides are given. Footer
+    text may contain ``{page}`` / ``{pages}`` placeholders.
+    """
+
+    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"
+
+    def margins(self) -> tuple[str, str, str, str]:
+        if self.margin:
+            return (self.margin,) * 4
+        return (
+            self.margin_top or "0.5in",
+            self.margin_right or "0.5in",
+            self.margin_bottom or "0.75in",
+            self.margin_left or "0.5in",
+        )
+
+    @property
+    def landscape(self) -> bool:
+        return self.orientation.strip().lower() == "landscape"
+
+
+# ── Adapter interface ──────────────────────────────────────────────────────────
+
+
+class BasePdfRenderer(ABC):
+    """One HTML→PDF backend. Subclass, implement ``render``/``available``, then
+    ``register_renderer(name, instance)``."""
+
+    #: Registry key and the value accepted by ``engine=`` / VELOCITY_PDF_ENGINE.
+    name: str = "base"
+
+    @abstractmethod
+    def available(self) -> bool:
+        """True when this backend can run in the current process."""
+
+    @abstractmethod
+    def render(
+        self,
+        html: str,
+        page: PageOptions,
+        *,
+        base_url: Optional[str] = None,
+        extra_css: Optional[str] = None,
+    ) -> bytes:
+        """Return PDF bytes. Raise ``ImportError`` when the backend is missing
+        and ``RuntimeError`` when rendering fails."""
+
+
+# ── wkhtmltopdf adapter (original behaviour, unchanged) ────────────────────────
+
+
+def _prepend_env_path(name: str, *paths: str) -> None:
+    existing = os.environ.get(name, "")
+    parts = [p for p in paths if p and os.path.isdir(p)]
+    if not parts:
+        return
+    current = [p for p in existing.split(os.pathsep) if p]
+    merged = parts + [p for p in current if p not in parts]
+    os.environ[name] = os.pathsep.join(merged)
+
+
+def _configure_wkhtml_runtime() -> None:
+    # Lambda layers put the binary in /opt/bin and its shared libs in /opt/lib.
+    _prepend_env_path("PATH", "/opt/bin")
+    _prepend_env_path("LD_LIBRARY_PATH", "/opt/lib")
+    if os.path.isdir("/opt/fonts") and not os.environ.get("FONTCONFIG_PATH"):
+        os.environ["FONTCONFIG_PATH"] = "/opt/fonts"
+
+
+def _find_wkhtmltopdf() -> str | None:
+    explicit = os.environ.get("WKHTMLTOPDF_PATH") or os.environ.get("wkhtmltopdf")
+    if explicit and os.path.isfile(explicit) and os.access(explicit, os.X_OK):
+        return explicit
+    found = shutil.which("wkhtmltopdf")
+    if found:
+        return found
+    layer_binary = "/opt/bin/wkhtmltopdf"
+    if os.path.isfile(layer_binary) and os.access(layer_binary, os.X_OK):
+        return layer_binary
+    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:
+    text = str(value).strip()
+    if text.endswith("pt"):
+        text = text[:-2]
+    return text 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)
+
+
+class WkhtmltopdfRenderer(BasePdfRenderer):
+    """pdfkit + external wkhtmltopdf binary. Behaviour is byte-for-byte the
+    original ``html_to_pdf``; ``base_url`` is not supported by this backend and
+    is ignored (wkhtmltopdf resolves relative assets itself with
+    ``enable-local-file-access``)."""
+
+    name = "wkhtmltopdf"
+
+    def available(self) -> bool:
+        if pdfkit is None:
+            return False
+        _configure_wkhtml_runtime()
+        return _find_wkhtmltopdf() is not None
+
+    def options(self, page: PageOptions) -> dict[str, str]:
+        top, right, bottom, left = page.margins()
+        options: dict[str, str] = {
+            "encoding": "UTF-8",
+            "page-size": page.page_size,
+            "orientation": page.orientation.capitalize(),
+            "enable-local-file-access": "",
+            "quiet": "",
+            "margin-top": top,
+            "margin-right": right,
+            "margin-bottom": bottom,
+            "margin-left": left,
+        }
+        if page.footer_right:
+            options["footer-right"] = _normalize_footer_text(page.footer_right)
+        if page.footer_center:
+            options["footer-center"] = _normalize_footer_text(page.footer_center)
+        if page.footer_right or page.footer_center:
+            options["footer-font-size"] = _normalize_footer_font_size(page.footer_font_size)
+        return options
+
+    def render(self, html, page, *, base_url=None, extra_css=None):
+        pdf_backend, configuration = _require_pdf_backend()
+        if extra_css:
+            html = _inject_css(html, extra_css)
+        try:
+            return pdf_backend.from_string(
+                html, False, configuration=configuration, options=self.options(page)
+            )
+        except Exception as exc:
+            logger.exception("wkhtmltopdf PDF generation failed")
+            raise RuntimeError(f"PDF generation failed: {exc}") from exc
+
+
+# ── WeasyPrint adapter ─────────────────────────────────────────────────────────
+
+_weasyprint_import_error: Exception | None = None
+_FOOTER_TOKEN_RE = re.compile(r"(\{page\}|\{pages\})")
+
+
+def _load_weasyprint():
+    """Import WeasyPrint lazily: it loads Pango/Cairo at import time, and a
+    missing shared library surfaces as OSError rather than ImportError."""
+    global _weasyprint_import_error
+    try:
+        import weasyprint  # type: ignore[import-not-found]
+
+        return weasyprint
+    except Exception as exc:
+        _weasyprint_import_error = exc
+        return None
+
+
+def _css_font_size(value: str) -> str:
+    text = str(value).strip() or "8pt"
+    return text if re.search(r"[a-z%]$", text) else f"{text}pt"
+
+
+def _footer_content(text: str) -> str:
+    """'Page {page} of {pages}' → CSS ``content`` with page counters."""
+    pieces: list[str] = []
+    for token in _FOOTER_TOKEN_RE.split(text):
+        if not token:
+            continue
+        if token == "{page}":
+            pieces.append("counter(page)")
+        elif token == "{pages}":
+            pieces.append("counter(pages)")
+        else:
+            pieces.append('"' + token.replace("\\", "\\\\").replace('"', '\\"') + '"')
+    return " ".join(pieces) if pieces else '""'
+
+
+#: wkhtmltopdf/Qt page names that CSS Paged Media has no keyword for, as
+#: portrait (width height). CSS-native names (Letter, Legal, A4, …) pass through.
+_CSS_PAGE_SIZES = {
+    "comm10e": ("4.125in", "9.5in"),
+    "comm10": ("4.125in", "9.5in"),
+    "tabloid": ("11in", "17in"),
+    "executive": ("7.25in", "10.5in"),
+}
+
+
+def _css_page_size(page: PageOptions) -> str:
+    named = _CSS_PAGE_SIZES.get(page.page_size.strip().lower())
+    if named:
+        width, height = named
+        # CSS allows `landscape` only with named sizes; swap explicit lengths.
+        return f"{height} {width}" if page.landscape else f"{width} {height}"
+    return page.page_size.strip() + (" landscape" if page.landscape else "")
+
+
+def page_css(page: PageOptions) -> str:
+    """Translate PageOptions into a CSS ``@page`` rule (pure; unit-tested)."""
+    size = _css_page_size(page)
+    top, right, bottom, left = page.margins()
+    parts = [f"size: {size};", f"margin: {top} {right} {bottom} {left};"]
+    for slot, text in (("bottom-right", page.footer_right), ("bottom-center", page.footer_center)):
+        if text:
+            parts.append(
+                f"@{slot} {{ content: {_footer_content(text)}; "
+                f"font-size: {_css_font_size(page.footer_font_size)}; }}"
+            )
+    return "@page { " + " ".join(parts) + " }"
+
+
+class WeasyPrintRenderer(BasePdfRenderer):
+    name = "weasyprint"
+
+    def available(self) -> bool:
+        return _load_weasyprint() is not None
+
+    def render(self, html, page, *, base_url=None, extra_css=None):
+        weasyprint = _load_weasyprint()
+        if weasyprint is None:
+            raise ImportError(
+                "WeasyPrint is required for engine='weasyprint'. Install it with: "
+                "pip install velocity-python[pdf-weasyprint] (on Lambda, attach a layer "
+                "that carries its Pango/Cairo libraries and set LD_LIBRARY_PATH=/opt/lib, "
+                f"FONTCONFIG_PATH=/opt/fonts). Root cause: {_weasyprint_import_error!r}"
+            )
+        css_text = page_css(page)
+        if extra_css:
+            css_text += "\n" + extra_css
+        try:
+            document = weasyprint.HTML(string=html, base_url=base_url)
+            return document.write_pdf(stylesheets=[weasyprint.CSS(string=css_text)])
+        except Exception as exc:
+            logger.exception("WeasyPrint PDF generation failed")
+            raise RuntimeError(f"PDF generation failed: {exc}") from exc
+
+
+# ── Registry + facade ──────────────────────────────────────────────────────────
+
+#: Preference order for auto-selection: maintained engine first, legacy second.
+_RENDERERS: Dict[str, BasePdfRenderer] = {
+    WeasyPrintRenderer.name: WeasyPrintRenderer(),
+    WkhtmltopdfRenderer.name: WkhtmltopdfRenderer(),
+}
+
+
+def register_renderer(name: str, renderer: BasePdfRenderer, *, preferred: bool = False) -> None:
+    """Add (or replace) a backend. ``preferred=True`` makes it the first choice
+    for auto-selection."""
+    key = name.strip().lower()
+    if preferred:
+        rest = {k: v for k, v in _RENDERERS.items() if k != key}
+        _RENDERERS.clear()
+        _RENDERERS[key] = renderer
+        _RENDERERS.update(rest)
+    else:
+        _RENDERERS[key] = renderer
+
+
+def registered_renderers() -> List[str]:
+    return list(_RENDERERS)
+
+
+def available_pdf_engines() -> List[str]:
+    """Engines usable in this process, in preference order."""
+    return [name for name, r in _RENDERERS.items() if r.available()]
+
+
+def get_renderer(engine: Optional[str] = None) -> BasePdfRenderer:
+    """Resolve the backend: explicit arg → VELOCITY_PDF_ENGINE → first available."""
+    requested = (engine or os.environ.get("VELOCITY_PDF_ENGINE") or "").strip().lower()
+    if requested:
+        try:
+            return _RENDERERS[requested]
+        except KeyError:
+            raise ValueError(
+                f"Unknown PDF engine {requested!r}; registered: {', '.join(_RENDERERS)}"
+            ) from None
+    for renderer in _RENDERERS.values():
+        if renderer.available():
+            return renderer
+    # Nothing available: fall through to the legacy backend so its ImportError
+    # message (the one existing callers/tests know) is what surfaces.
+    return _RENDERERS[WkhtmltopdfRenderer.name]
+
+
+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",
+    engine: Optional[str] = None,
+    base_url: Optional[str] = None,
+    extra_css: Optional[str] = None,
+) -> bytes:
+    """Convert an HTML string to PDF bytes via the selected renderer.
+
+    Keyword contract is unchanged from the pdfkit-only original; ``engine``,
+    ``base_url`` and ``extra_css`` are additive. See the module docstring for
+    engine selection.
+    """
+    page = PageOptions(
+        page_size=page_size,
+        orientation=orientation,
+        margin=margin,
+        margin_top=margin_top,
+        margin_right=margin_right,
+        margin_bottom=margin_bottom,
+        margin_left=margin_left,
+        footer_right=footer_right,
+        footer_center=footer_center,
+        footer_font_size=footer_font_size,
+    )
+    return get_renderer(engine).render(html, page, base_url=base_url, extra_css=extra_css)
+
+
+def _inject_css(html: str, css: str) -> str:
+    """Best-effort: put extra CSS into <head> (or prepend) for engines that take
+    styles only from the document."""
+    block = f"<style>{css}</style>"
+    lowered = html.lower()
+    idx = lowered.find("</head>")
+    if idx != -1:
+        return html[:idx] + block + html[idx:]
+    return block + html
+
+
+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>"""
+
+
+__all__ = [
+    "BasePdfRenderer",
+    "PageOptions",
+    "WeasyPrintRenderer",
+    "WkhtmltopdfRenderer",
+    "available_pdf_engines",
+    "get_renderer",
+    "html_to_pdf",
+    "page_css",
+    "register_renderer",
+    "registered_renderers",
+    "wrap_html",
+]

{velocity_python-0.1.91 → velocity_python-0.1.93/src/velocity_python.egg-info}/PKG-INFO

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

{velocity_python-0.1.91 → velocity_python-0.1.93}/src/velocity_python.egg-info/requires.txt

@@ -55,6 +55,9 @@ xmltodict>=0.13.0
 [pdf]
 pdfkit>=1.0.0
 
+[pdf-weasyprint]
+weasyprint>=60.0
+
 [postgres]
 psycopg[binary]>=3.2.0