velocity-python 0.1.12__tar.gz → 0.1.13__tar.gz

{velocity_python-0.1.12/src/velocity_python.egg-info → velocity_python-0.1.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.12
+Version: 0.1.13
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -29,6 +29,8 @@ Provides-Extra: excel
 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"
 Provides-Extra: http
 Requires-Dist: requests>=2.32.0; extra == "http"
 Provides-Extra: mysql
@@ -41,7 +43,7 @@ Provides-Extra: payment
 Requires-Dist: stripe>=12.0.0; extra == "payment"
 Requires-Dist: braintree>=4.30.0; extra == "payment"
 Provides-Extra: all
-Requires-Dist: velocity-python[aws,excel,http,payment,postgres,templates]; extra == "all"
+Requires-Dist: velocity-python[aws,excel,http,payment,pdf,postgres,templates]; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=6.0.0; extra == "dev"

{velocity_python-0.1.12 → velocity_python-0.1.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.12"
+version = "0.1.13"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]
@@ -48,6 +48,9 @@ excel = [
 templates = [
   "jinja2>=3.1.0",
 ]
+pdf = [
+  "weasyprint>=62.0",
+]
 http = [
   "requests>=2.32.0",
 ]
@@ -65,7 +68,7 @@ payment = [
   "braintree>=4.30.0",
 ]
 all = [
-  "velocity-python[postgres,aws,excel,templates,http,payment]",
+  "velocity-python[postgres,aws,excel,templates,http,payment,pdf]",
 ]
 dev = [
   "pytest>=8.0.0",

{velocity_python-0.1.12 → velocity_python-0.1.13}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.12"
+__version__ = version = "0.1.13"
 
 import importlib as _importlib
 

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

@@ -0,0 +1,199 @@
+"""
+HTML-to-PDF generation using WeasyPrint.
+
+Provides a simple API for converting HTML strings to PDF bytes,
+with support for page size, orientation, margins, and page footers.
+
+Usage::
+
+    from velocity.misc.pdf import html_to_pdf
+
+    # Simple conversion
+    pdf_bytes = html_to_pdf("<h1>Hello</h1><p>World</p>")
+
+    # With options
+    pdf_bytes = html_to_pdf(
+        html,
+        page_size="Letter",
+        orientation="landscape",
+        margin="0.5in",
+        footer_right="Page {page} of {pages}",
+    )
+
+    # Wrap a body fragment with a full HTML document + default styles
+    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::
+
+    pip install velocity-python[pdf]
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional
+
+logger = logging.getLogger("velocity.misc.pdf")
+
+# On AWS Lambda, fontconfig needs to know where fonts.conf lives.
+# The py-lib-support layer ships fonts/ at /opt/fonts/.
+if "AWS_LAMBDA_FUNCTION_NAME" in os.environ:
+    os.environ.setdefault("FONTCONFIG_PATH", "/opt/fonts")
+
+try:
+    import weasyprint
+except ImportError:
+    weasyprint = 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 _require_weasyprint():
+    if weasyprint is None:
+        raise ImportError(
+            "weasyprint is required for PDF generation. "
+            "Install it with: pip install velocity-python[pdf]"
+        )
+
+
+def _build_page_css(
+    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",
+) -> str:
+    """Build a ``@page`` CSS rule from the given options."""
+    parts = [f"size: {page_size} {orientation};"]
+
+    if margin:
+        parts.append(f"margin: {margin};")
+    else:
+        mt = margin_top or "0.5in"
+        mr = margin_right or "0.5in"
+        mb = margin_bottom or "0.75in"
+        ml = margin_left or "0.5in"
+        parts.append(f"margin: {mt} {mr} {mb} {ml};")
+
+    footer_blocks = []
+    if footer_right:
+        content = footer_right.replace("{page}", '" counter(page) "').replace("{pages}", '" counter(pages) "')
+        content = f'"  {content}  "'
+        footer_blocks.append(
+            f"@bottom-right {{ content: {content}; font-size: {footer_font_size}; color: #666; }}"
+        )
+    if footer_center:
+        content = footer_center.replace("{page}", '" counter(page) "').replace("{pages}", '" counter(pages) "')
+        content = f'"  {content}  "'
+        footer_blocks.append(
+            f"@bottom-center {{ content: {content}; font-size: {footer_font_size}; color: #666; }}"
+        )
+
+    rule_body = "\n    ".join(parts)
+    footer_body = "\n    ".join(footer_blocks)
+    return f"@page {{\n    {rule_body}\n    {footer_body}\n}}"
+
+
+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.
+
+    Args:
+        html: Complete HTML document string.
+        page_size: CSS page size (e.g. "Letter", "A4"). Default "Letter".
+        orientation: "portrait" or "landscape". Default "portrait".
+        margin: Shorthand margin for all sides (e.g. "0.5in").
+        margin_top/right/bottom/left: Individual margins (override ``margin``).
+        footer_right: Right-aligned footer text. Use ``{page}`` and ``{pages}``
+            for page numbering (e.g. ``"Page {page} of {pages}"``).
+        footer_center: Center-aligned footer text. Same placeholders.
+        footer_font_size: CSS font size for footer. Default "8pt".
+
+    Returns:
+        PDF file contents as bytes.
+
+    Raises:
+        ImportError: If weasyprint is not installed.
+    """
+    _require_weasyprint()
+
+    page_css = _build_page_css(
+        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,
+    )
+
+    css = weasyprint.CSS(string=page_css)
+    doc = weasyprint.HTML(string=html)
+    return doc.write_pdf(stylesheets=[css])
+
+
+def wrap_html(title: str, body: str, css: str = "") -> str:
+    """
+    Wrap an HTML body fragment in a full HTML document with default styles.
+
+    Args:
+        title: Document ``<title>`` and ``<h1>`` heading.
+        body: HTML body content (fragment, not full document).
+        css: Additional CSS to include after the default body styles.
+
+    Returns:
+        Complete HTML document string ready for :func:`html_to_pdf`.
+    """
+    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.12 → velocity_python-0.1.13/src/velocity_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.12
+Version: 0.1.13
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -29,6 +29,8 @@ Provides-Extra: excel
 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"
 Provides-Extra: http
 Requires-Dist: requests>=2.32.0; extra == "http"
 Provides-Extra: mysql
@@ -41,7 +43,7 @@ Provides-Extra: payment
 Requires-Dist: stripe>=12.0.0; extra == "payment"
 Requires-Dist: braintree>=4.30.0; extra == "payment"
 Provides-Extra: all
-Requires-Dist: velocity-python[aws,excel,http,payment,postgres,templates]; extra == "all"
+Requires-Dist: velocity-python[aws,excel,http,payment,pdf,postgres,templates]; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=6.0.0; extra == "dev"

{velocity_python-0.1.12 → velocity_python-0.1.13}/src/velocity_python.egg-info/SOURCES.txt

@@ -121,6 +121,7 @@ src/velocity/misc/export.py
 src/velocity/misc/format.py
 src/velocity/misc/mail.py
 src/velocity/misc/merge.py
+src/velocity/misc/pdf.py
 src/velocity/misc/timer.py
 src/velocity/misc/tools.py
 src/velocity/misc/conv/__init__.py
@@ -170,6 +171,7 @@ tests/test_payment_demo_profiles.py
 tests/test_payment_profiles.py
 tests/test_payment_router.py
 tests/test_payment_stripe_adapter.py
+tests/test_pdf.py
 tests/test_prepared_statements.py
 tests/test_psycopg3_upgrade.py
 tests/test_query_cache.py

{velocity_python-0.1.12 → velocity_python-0.1.13}/src/velocity_python.egg-info/requires.txt

@@ -1,7 +1,7 @@
 sqlparse>=0.5.0
 
 [all]
-velocity-python[aws,excel,http,payment,postgres,templates]
+velocity-python[aws,excel,http,payment,pdf,postgres,templates]
 
 [aws]
 boto3>=1.35.0
@@ -33,6 +33,9 @@ mysql-connector-python>=9.0.0
 stripe>=12.0.0
 braintree>=4.30.0
 
+[pdf]
+weasyprint>=62.0
+
 [postgres]
 psycopg[binary]>=3.2.0
 

velocity_python-0.1.13/tests/test_pdf.py

@@ -0,0 +1,188 @@
+"""Tests for velocity.misc.pdf — HTML-to-PDF generation."""
+
+import pytest
+from unittest.mock import patch, MagicMock
+
+from velocity.misc.pdf import (
+    html_to_pdf,
+    wrap_html,
+    _build_page_css,
+    _DEFAULT_BODY_CSS,
+)
+
+
+# ── 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
+
+
+# ── _build_page_css ─────────────────────────────────────────────────
+
+
+class TestBuildPageCss:
+
+    def test_defaults(self):
+        css = _build_page_css()
+        assert "size: Letter portrait;" in css
+        assert "margin:" in css
+
+    def test_landscape(self):
+        css = _build_page_css(orientation="landscape")
+        assert "size: Letter landscape;" in css
+
+    def test_a4(self):
+        css = _build_page_css(page_size="A4")
+        assert "size: A4 portrait;" in css
+
+    def test_shorthand_margin(self):
+        css = _build_page_css(margin="1in")
+        assert "margin: 1in;" in css
+
+    def test_individual_margins(self):
+        css = _build_page_css(
+            margin_top="0.5in",
+            margin_right="0.45in",
+            margin_bottom="0.55in",
+            margin_left="0.45in",
+        )
+        assert "margin: 0.5in 0.45in 0.55in 0.45in;" in css
+
+    def test_footer_right(self):
+        css = _build_page_css(footer_right="Page {page} of {pages}")
+        assert "@bottom-right" in css
+        assert 'counter(page)' in css
+        assert 'counter(pages)' in css
+
+    def test_footer_center(self):
+        css = _build_page_css(footer_center="CaringCent, LLC")
+        assert "@bottom-center" in css
+        assert "CaringCent, LLC" in css
+
+    def test_footer_font_size(self):
+        css = _build_page_css(footer_right="pg", footer_font_size="10pt")
+        assert "font-size: 10pt;" in css
+
+    def test_no_footers(self):
+        css = _build_page_css()
+        assert "@bottom-right" not in css
+        assert "@bottom-center" not in css
+
+
+# ── html_to_pdf ─────────────────────────────────────────────────────
+
+
+class TestHtmlToPdf:
+
+    def test_raises_without_weasyprint(self):
+        with patch("velocity.misc.pdf.weasyprint", None):
+            with pytest.raises(ImportError, match="weasyprint is required"):
+                html_to_pdf("<h1>test</h1>")
+
+    def test_calls_weasyprint(self):
+        mock_wp = MagicMock()
+        mock_doc = MagicMock()
+        mock_doc.write_pdf.return_value = b"%PDF-fake"
+        mock_wp.HTML.return_value = mock_doc
+        mock_wp.CSS.return_value = MagicMock()
+
+        with patch("velocity.misc.pdf.weasyprint", mock_wp):
+            result = html_to_pdf("<h1>Hello</h1>")
+
+        assert result == b"%PDF-fake"
+        mock_wp.HTML.assert_called_once()
+        call_kwargs = mock_wp.HTML.call_args
+        assert "<h1>Hello</h1>" in call_kwargs[1]["string"]
+        mock_doc.write_pdf.assert_called_once()
+
+    def test_passes_page_css_as_stylesheet(self):
+        mock_wp = MagicMock()
+        mock_doc = MagicMock()
+        mock_doc.write_pdf.return_value = b"%PDF"
+        mock_wp.HTML.return_value = mock_doc
+        mock_css_obj = MagicMock()
+        mock_wp.CSS.return_value = mock_css_obj
+
+        with patch("velocity.misc.pdf.weasyprint", mock_wp):
+            html_to_pdf(
+                "<h1>test</h1>",
+                page_size="A4",
+                orientation="landscape",
+                footer_right="Page {page}",
+            )
+
+        # CSS should contain @page with landscape A4
+        css_string = mock_wp.CSS.call_args[1]["string"]
+        assert "A4 landscape" in css_string
+        assert "@bottom-right" in css_string
+
+        # write_pdf should receive the CSS object
+        mock_doc.write_pdf.assert_called_once_with(stylesheets=[mock_css_obj])
+
+    def test_landscape_with_margins(self):
+        mock_wp = MagicMock()
+        mock_doc = MagicMock()
+        mock_doc.write_pdf.return_value = b"%PDF"
+        mock_wp.HTML.return_value = mock_doc
+        mock_wp.CSS.return_value = MagicMock()
+
+        with patch("velocity.misc.pdf.weasyprint", mock_wp):
+            html_to_pdf(
+                "<h1>report</h1>",
+                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_font_size="8pt",
+            )
+
+        css_string = mock_wp.CSS.call_args[1]["string"]
+        assert "landscape" in css_string
+        assert "0.5in 0.45in 0.55in 0.45in" in css_string
+        assert "counter(page)" in css_string
+        assert "counter(pages)" in css_string
+
+
+# ── Integration with wrap_html + html_to_pdf ────────────────────────
+
+
+class TestIntegration:
+
+    def test_wrap_then_convert(self):
+        mock_wp = MagicMock()
+        mock_doc = MagicMock()
+        mock_doc.write_pdf.return_value = b"%PDF-wrapped"
+        mock_wp.HTML.return_value = mock_doc
+        mock_wp.CSS.return_value = MagicMock()
+
+        html = wrap_html("Report", "<p>Content</p>")
+
+        with patch("velocity.misc.pdf.weasyprint", mock_wp):
+            result = html_to_pdf(html)
+
+        assert result == b"%PDF-wrapped"
+        passed_html = mock_wp.HTML.call_args[1]["string"]
+        assert "<title>Report</title>" in passed_html
+        assert "<p>Content</p>" in passed_html