pdfrender 0.1.0__py3-none-any.whl

pdf_render/md/extensions/flex_wrap.py

@@ -0,0 +1,52 @@
+from xml.etree import ElementTree
+
+from markdown import Extension
+from markdown.inlinepatterns import InlineProcessor
+
+# Pattern to match %( content )%
+FLEX_WRAP_RE = r"%\(\s*(.*?)\s*\)%"
+
+
+class FlexWrapInlineProcessor(InlineProcessor):
+    def __init__(self, pattern, md=None):
+        super().__init__(pattern, md)
+
+    def handleMatch(self, match, data):
+        # Extract the content between %( and )%
+        content = match.group(1)
+
+        # Split on || to get individual items
+        items = [item.strip() for item in content.split("||")]
+
+        # Create the container div
+        container = ElementTree.Element("div")
+        container.set("class", "flex-wrap")
+
+        # Create each item as a bubble
+        for item_text in items:
+            if item_text:  # Only create bubbles for non-empty items
+                bubble = ElementTree.SubElement(container, "div")
+                bubble.set("class", "bubble")
+                bubble.text = item_text
+
+        return container, match.start(0), match.end(0)
+
+
+class FlexWrapExtension(Extension):
+    """Markdown extension for the `%( item1 || item2 || ... )%` inline syntax.
+
+    Renders the given `||`-separated items as a `<div class="flex-wrap">`
+    containing one `<div class="bubble">` per non-empty item, for wrapping
+    lists of tags/badges.
+    """
+
+    def extendMarkdown(self, md):
+        processor = FlexWrapInlineProcessor(FLEX_WRAP_RE, md)
+
+        # Add with priority to ensure it runs before other inline processors
+        md.inlinePatterns.register(processor, "flex_wrap", 175)
+
+
+# noinspection PyPep8Naming
+def makeExtension(**kwargs):
+    return FlexWrapExtension(**kwargs)

pdf_render/md/extensions/muted_text.py

@@ -0,0 +1,42 @@
+import xml.etree.ElementTree as ElementTree
+
+from markdown import Extension
+from markdown.inlinepatterns import InlineProcessor
+
+# Pattern to match %% content %%
+MUTED_TEXT_RE = r"%m\s*(.*?)\s*m%"
+
+
+class MutedTextInlineProcessor(InlineProcessor):
+    def __init__(self, pattern, md=None):
+        super().__init__(pattern, md)
+
+    def handleMatch(self, match, data):
+        # Extract the content between %m and m%
+        content = match.group(1)
+
+        # Create the container div
+        container = ElementTree.Element("span")
+        container.set("class", "muted-text")
+        container.text = content.strip()
+
+        return container, match.start(0), match.end(0)
+
+
+class MutedTextExtension(Extension):
+    """Markdown extension for the `%m text m%` inline syntax.
+
+    Renders the enclosed text as a `<span class="muted-text">`, for
+    de-emphasized inline text.
+    """
+
+    def extendMarkdown(self, md):
+        processor = MutedTextInlineProcessor(MUTED_TEXT_RE, md)
+
+        # Add with priority to ensure it runs before other inline processors
+        md.inlinePatterns.register(processor, "muted_text", 175)
+
+
+# noinspection PyPep8Naming
+def makeExtension(**kwargs):
+    return MutedTextExtension(**kwargs)

pdf_render/md/extensions/nerdfont_glyph.py

@@ -0,0 +1,37 @@
+from xml.etree import ElementTree
+
+from markdown import Extension
+from markdown.inlinepatterns import InlineProcessor
+
+GLYPH_RE = r"%\+(\S)\+%"
+
+
+class NerdfontGlyphInlineProcessor(InlineProcessor):
+    def __init__(self, pattern, md=None):
+        super().__init__(pattern, md)
+
+    def handleMatch(self, match, data):
+
+        container = ElementTree.Element("span")
+        container.set("class", "nf")
+        container.text = match.group(1)
+
+        return container, match.start(0), match.end(0)
+
+
+class NerdfontGlyphExtension(Extension):
+    """Markdown extension for the `%+<glyph>+%` inline syntax.
+
+    Renders the single enclosed character as a `<span class="nf">`, for
+    embedding a Nerd Font icon glyph inline.
+    """
+
+    def extendMarkdown(self, md):
+
+        processor = NerdfontGlyphInlineProcessor(GLYPH_RE, md)
+        md.inlinePatterns.register(processor, "nerdfont_glyph", 175)
+
+
+# noinspection PyPep8Naming
+def makeExtension(**kwargs):
+    return NerdfontGlyphExtension(**kwargs)

pdf_render/md/extensions/page_break.py

@@ -0,0 +1,39 @@
+from xml.etree import ElementTree
+
+from markdown import Extension
+from markdown.inlinepatterns import InlineProcessor
+
+# Pattern to match %( content )%
+PAGE_BREAK_RE = r"%:pg:%"
+
+
+class PageBreakInlineProcessor(InlineProcessor):
+    def __init__(self, pattern, md=None):
+        super().__init__(pattern, md)
+
+    def handleMatch(self, match, data):
+
+        container = ElementTree.Element("div")
+        container.set("class", "page")
+
+        return container, match.start(0), match.end(0)
+
+
+class PageBreakExtension(Extension):
+    """Markdown extension for the `%:pg:%` inline syntax.
+
+    Renders an empty `<div class="page">`, intended to be styled with a CSS
+    page-break rule when rendering to PDF.
+    """
+
+    def extendMarkdown(self, md):
+
+        processor = PageBreakInlineProcessor(PAGE_BREAK_RE, md)
+
+        # Add with priority to ensure it runs before other inline processors
+        md.inlinePatterns.register(processor, "page_break", 175)
+
+
+# noinspection PyPep8Naming
+def makeExtension(**kwargs):
+    return PageBreakExtension(**kwargs)

pdf_render/md/rendering.py

@@ -0,0 +1,29 @@
+from markdown import Markdown
+
+from pdf_render.import_functions import import_submodules
+
+
+def create_markdown_renderer(*markdown_extensions_modules: str) -> Markdown:
+    """Build a `markdown.Markdown` renderer with pdf_render's extensions enabled.
+
+    Discovers and registers every extension module under
+    `pdf_render.md.extensions` and `pymdownx` (any submodule exposing a
+    `makeExtension` callable), plus any additional extension modules passed
+    in.
+
+    Args:
+        *markdown_extensions_modules: Additional dotted module paths to
+            search for extensions exposing a `makeExtension` callable.
+
+    Returns:
+        A configured `markdown.Markdown` instance.
+    """
+    markdown_extensions = import_submodules("pdf_render.md.extensions", has_attr_filter="makeExtension")
+    markdown_extensions.update(import_submodules("pymdownx", has_attr_filter="makeExtension"))
+    for extension_dir in markdown_extensions_modules:
+        if not isinstance(extension_dir, str):
+            continue
+
+        markdown_extensions.update(import_submodules(extension_dir, has_attr_filter="makeExtension"))
+
+    return Markdown(extensions=markdown_extensions)

pdf_render/pdf/__init__.py

@@ -0,0 +1,5 @@
+from .metadata import PDFMetadata
+from .options import PDFOptions
+from .rendering import render_pdf
+
+__all__ = ["PDFOptions", "PDFMetadata", "render_pdf"]

pdf_render/pdf/document_template.py

@@ -0,0 +1,45 @@
+from typing import Any
+
+from jinja2 import Environment
+
+from pdf_render.pdf.metadata import PDFMetadata
+
+BASE_HTML_TEMPLATE = """
+<!DOCTYPE html>
+<html lang="{{ title }}">
+<head>
+<title>{{ title }}</title>
+<meta http-equiv="Content-type" content="text/html;charset=UTF-8">
+{% for author in authors %}
+<meta name="author" content="{{ author }}">
+{% endfor %}
+<meta name="generator" content="{{ generator }}">
+<meta name="keyword" content="{{ keywords | join(",") }}">
+<meta name="dcterms.created" content="{{ created.strftime('%Y-%m-%d') }}">
+<meta name="dcterms.modified" content="{{ modified.strftime('%Y-%m-%d') }}">
+<meta name="description" content="{{ description }}">
+{% for key in custom %}
+<meta name="{{ key }}" content="{{ custom[key] }}">
+{% endfor %}
+<style>
+{{ css }}
+</style>
+</head>
+<body>
+<div class="markdown-container">
+    {{ html }}
+</div>
+</body>
+</html>
+"""
+
+
+def finalize(value: Any):
+    return value if value is not None else ""
+
+
+def render_document_html(html: str, css: str, metadata: PDFMetadata):
+    jinja2_env = Environment(finalize=finalize)
+    template_globals = {"html": html, "css": css, **metadata.model_dump()}
+
+    return jinja2_env.from_string(BASE_HTML_TEMPLATE, globals=template_globals).render()

pdf_render/pdf/metadata.py

@@ -0,0 +1,38 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class PDFMetadata(BaseModel):
+    """Document metadata to embed in a rendered PDF.
+
+    Attributes:
+        title: The document title.
+        description: The document description/subject.
+        generator: The name of the tool that generated the document.
+        language: The document's language tag (e.g. "en-us").
+        keywords: Keywords describing the document. Commas are stripped from
+            each entry, since WeasyPrint uses commas to separate keywords.
+        authors: The document's author names.
+        created: The document's creation timestamp.
+        modified: The document's last-modified timestamp.
+        custom: Additional custom metadata fields.
+    """
+
+    title: str | None = None
+    description: str | None = None
+    generator: str | None = None
+    language: str | None = "en-us"
+    keywords: list[str] | None = []
+    authors: list[str] | None = []
+    created: datetime | None = Field(default_factory=datetime.now)
+    modified: datetime | None = Field(default_factory=datetime.now)
+    custom: dict | None = {}
+
+    @field_validator("keywords")
+    @classmethod
+    def sanitize_for_commas(cls, value: Any):
+        if isinstance(value, list):
+            return [list_item.replace(",", "") for list_item in value]
+        return value

pdf_render/pdf/options.py

@@ -0,0 +1,64 @@
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, field_validator
+from weasyprint import CSS, Attachment
+
+
+class PDFOptions(BaseModel):
+    """Typed wrapper around WeasyPrint's PDF rendering options.
+
+    Mirrors the keyword arguments accepted by `weasyprint.HTML.render`/
+    `weasyprint.Document.write_pdf` (see `weasyprint.DEFAULT_OPTIONS`), so an
+    instance can be passed straight through via
+    `model_dump(exclude_none=True)`.
+
+    Attributes:
+        stylesheets: Additional CSS to apply, as `weasyprint.CSS` objects or paths/URLs.
+        attachments: Files to embed in the PDF as attachments.
+        attachment_relationships: The PDF/A-3 AFRelationship value for attachments.
+        pdf_identifier: The document's PDF identifier.
+        pdf_variant: The target PDF variant (e.g. "pdf/a-3b", "pdf/ua-1").
+        pdf_version: The target PDF version (e.g. "1.7").
+        pdf_forms: Whether to keep interactive form fields in the output.
+        pdf_tags: Whether to include structure tags for accessibility.
+        uncompressed_pdf: Whether to disable PDF stream compression.
+        xmp_metadata: Whether to include an XMP metadata stream.
+        custom_metadata: Whether to include WeasyPrint's custom PDF metadata.
+        presentational_hints: Whether to honor CSS presentational hints.
+        output_intent: An ICC output intent identifier.
+        optimize_images: Whether to re-encode images to reduce PDF size.
+        jpeg_quality: JPEG re-encoding quality, clamped to 1-100.
+        dpi: Maximum image resolution, in dots per inch.
+        full_fonts: Whether to embed full font files instead of subsets.
+        hinting: Whether to keep font hinting instructions.
+        cache: A dict or path used to cache fetched resources across renders.
+    """
+
+    # weasprint.__init__.DEFAULT_OPTIONS
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    stylesheets: list[CSS | str] | None = None
+    attachments: list[Attachment | str] | None = None
+    attachment_relationships: str | None = None
+    pdf_identifier: bytes | None = None
+    pdf_variant: str | None = None
+    pdf_version: str | None = None
+    pdf_forms: bool | None = None
+    pdf_tags: bool = False
+    uncompressed_pdf: bool = False
+    xmp_metadata: bool | None = None
+    custom_metadata: bool = False
+    presentational_hints: bool | None = None
+    output_intent: str | None = None
+    optimize_images: bool = False
+    jpeg_quality: int | None = None
+    dpi: int | None = None
+    full_fonts: bool = False
+    hinting: bool = False
+    cache: dict[str, Any] | str | None = None
+
+    @field_validator("jpeg_quality")
+    @classmethod
+    def clamp_jpeg_quality(cls, value: Any):
+        if isinstance(value, int) and not (1 <= value <= 100):
+            raise ValueError("jpeg_quality must be within range of 1-100")
+        return value

pdf_render/pdf/rendering.py

@@ -0,0 +1,40 @@
+from pathlib import Path
+
+from weasyprint import HTML
+from weasyprint.text.fonts import FontConfiguration
+
+from pdf_render.pdf.document_template import render_document_html
+from pdf_render.pdf.metadata import PDFMetadata
+from pdf_render.pdf.options import PDFOptions
+
+
+def render_pdf(
+    out_file: Path,
+    html: str,
+    css: str,
+    pdf_metadata: PDFMetadata = None,
+    pdf_options: PDFOptions = None,
+):
+    """Render HTML/CSS to a PDF file using WeasyPrint.
+
+    Args:
+        out_file: The path to write the rendered PDF to. Also used as the
+            base URL for resolving relative resources in `html`, and as the
+            default document title when `pdf_metadata` is not given.
+        html: The document body as an HTML string.
+        css: Additional CSS to apply to the document.
+        pdf_metadata: Metadata to embed in the PDF. Defaults to a
+            `PDFMetadata` titled after `out_file`'s filename.
+        pdf_options: WeasyPrint rendering options. Defaults to `PDFOptions()`.
+    """
+    pdf_metadata = pdf_metadata or PDFMetadata(title=out_file.stem)
+    pdf_options = pdf_options or PDFOptions()
+    pdf_options.custom_metadata = bool(pdf_metadata.custom)
+
+    font_config: FontConfiguration = FontConfiguration()
+
+    document_html = render_document_html(html=html, css=css, metadata=pdf_metadata)
+    options = pdf_options.model_dump(exclude_none=True)
+    html = HTML(string=document_html, base_url=out_file)
+    pdf_document = html.render(font_config=font_config, **options)
+    pdf_document.write_pdf(target=out_file, **options)

pdf_render/templates/__init__.py

@@ -0,0 +1,4 @@
+from .environment import TypedVariableEnvironment
+from .rendering import new_template_environment
+
+__all__ = ["new_template_environment", "TypedVariableEnvironment"]

pdf_render/templates/environment.py

@@ -0,0 +1,158 @@
+import builtins
+import logging
+import re
+from typing import Any, MutableMapping, Optional, Type, Union
+
+from click import Choice
+from jinja2 import FileSystemLoader, TemplateSyntaxError
+from jinja2.environment import Environment, Template
+from jinja2.meta import find_undeclared_variables
+from jinja2.runtime import StrictUndefined
+
+logger = logging.getLogger(__name__)
+
+
+class TypedVariableEnvironment(Environment):
+    """A `jinja2.Environment` that pre-processes templates to support typed variables.
+
+    Allows template authors to specify variable types using PEP 484
+    annotation syntax. Typed variables can be useful when prompting users for
+    the value of undefined variables.
+
+    Variables won't appear in `undeclared_variables` until the template is
+    read via `get_template()`. Resist the urge to call `get_template()` and
+    `Template.render()` back-to-back in the same loop; instead:
+
+    1. Iterate through `list_templates()`, calling `get_template()` on each
+       item and storing the resulting `Template` in a list.
+    2. Use the keys/values of `undeclared_variables` to prompt the user for
+       missing values.
+    3. Update `globals` with the user's inputs.
+    4. Validate the values in `globals` against the types recorded in
+       `type_registry`.
+    5. Finally, render the list of `Template` objects.
+
+    Attributes:
+        type_registry: Maps every variable name found while pre-processing a
+            template to its declared (or inferred) type. Populated during
+            `preprocess()`; a variable with no explicit type annotation
+            defaults to `str`.
+        undeclared_variables: The subset of `type_registry` whose variables
+            have no defined value yet, populated by `update_undeclared_variables()`.
+    """
+
+    loader: FileSystemLoader
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs, undefined=StrictUndefined)
+        """
+        StrictUndefined is required as jinja2.meta.find_undeclared_variables will not detect any
+        undeclared variables when the default of jinja2.runtime.Undefined is used.
+        """
+
+        self.type_registry: dict[str, type | object] = {}
+        """
+        Used to assign types to keys in self.undeclared_variables.
+        Is populated during pre-process, marking a variable as the found type. Type defaults to str if none is found.
+        Should contain every variable.
+        """
+
+        self.undeclared_variables: dict[str, type] = {}
+        """
+        The keys/values from self.type_registry who have no defined value.
+        """
+
+    def preprocess(self, source, name=None, filename=None):
+        """
+        - Extracts the PEP 484 type from the template variable tag, if it exists.
+        - The variable name and type are stored in a dict 'Environment.type_registry'.
+        - If no type annotation is found, the variable will be mapped to type 'str'.
+        - The type annotation (: $type_name) is removed from the template source before handing it back
+          to the parent class jinja2.environment.Environment's 'preprocess' method.
+        """
+
+        # In case it's not '{{' and '}}', we need to escape them because they probably still contain braces
+        start_string = "".join(["\\" + char for char in self.variable_start_string])
+        end_string = "".join(["\\" + char for char in self.variable_end_string])
+        var_pattern = r"(\w+)"
+        type_pattern = r"(\w+)"
+        type_args_pattern = r"([\(\[]\[.+\][\)\]])"
+        match_pattern = (
+            start_string
+            + r"\s*"
+            + var_pattern
+            + r"\s*:\s*"
+            + type_pattern
+            + r"\s*(?:"
+            + type_args_pattern
+            + r")?\s*"
+            + end_string
+        )
+
+        for match in re.finditer(match_pattern, source):
+            var_name, var_type_str, var_type_args = match.groups()
+            var_type_str = var_type_str if var_name is not None else "str"
+
+            if "Choice" == var_type_str.strip():
+                choice_args = var_type_args.lstrip("(").rstrip(")")
+                self.type_registry[var_name] = Choice(eval(choice_args))
+
+                continue
+
+            var_type = getattr(builtins, var_type_str) if hasattr(builtins, var_type_str) else str
+            self.type_registry[var_name] = var_type
+
+        clean_source = re.sub(
+            match_pattern,
+            rf"{self.variable_start_string} \1 {self.variable_end_string}",
+            source,
+        )
+
+        return super().preprocess(clean_source, name, filename)
+
+    def update_undeclared_variables(self, source: str):
+        ast = self.parse(source)
+        undeclared_variables = list(find_undeclared_variables(ast))
+        if undeclared_variables:
+            input_variables = {var_name: self.type_registry.get(var_name, str) for var_name in undeclared_variables}
+            self.undeclared_variables.update(input_variables)
+
+    def get_template(
+        self,
+        name: Union[str, "Template"],
+        parent: Optional[str] = None,
+        _globals: Optional[MutableMapping[str, Any]] = None,
+    ) -> "Template":
+        """
+        Based on jinja2.Environment's original get_template method, adding the call to update_undeclared_variables.
+        """
+        if isinstance(name, Template):
+            return name
+
+        if parent is not None:
+            name: str = self.join_path(name, parent)
+
+        source, _, _ = self.loader.get_source(self, name)
+
+        try:
+            self.update_undeclared_variables(source)
+        except TemplateSyntaxError as e:
+            logger.error(f"Syntax error at: {name}:{e.lineno}")
+            raise e
+
+        template = self._load_template(name, _globals)
+        return template
+
+    def from_string(
+        self,
+        source: Union[str],
+        _globals: Optional[MutableMapping[str, Any]] = None,
+        template_class: Optional[Type[Template]] = None,
+    ) -> "Template":
+        """
+        Based on jinja2.Environment's original from_string method, adding the call to update_undeclared_variables.
+        """
+        self.update_undeclared_variables(source)
+        gs = self.make_globals(_globals)
+        cls = template_class or self.template_class
+        return cls.from_code(self, self.compile(source), gs, None)

pdf_render/templates/filters/__init__.py

@@ -0,0 +1,9 @@
+from .format_filters import jinja_filter_month_year_fmt, jinja_filter_phone_num_fmt
+from .getter_filters import jinja_filter_get_list_item_by_attr, jinja_filter_with_item_attr_first
+
+__all__ = [
+    "jinja_filter_month_year_fmt",
+    "jinja_filter_phone_num_fmt",
+    "jinja_filter_with_item_attr_first",
+    "jinja_filter_get_list_item_by_attr",
+]

pdf_render/templates/filters/format_filters.py

@@ -0,0 +1,34 @@
+import datetime
+
+
+def jinja_filter_phone_num_fmt(phone_num: str):
+    """Format an 11-digit US/Canadian phone number string.
+
+    Args:
+        phone_num: A string of digits, assumed to be a valid 11-digit
+            US/Canadian phone number (country code + area code + number).
+            Returned unchanged if it isn't exactly 11 digits.
+
+    Returns:
+        The formatted string, e.g. "1-800-222-2222".
+    """
+    phone_num = str(phone_num)
+    if not phone_num.isdigit():
+        return phone_num
+
+    if len(phone_num) != 11:
+        return phone_num
+
+    return f"{phone_num[0]}-{phone_num[1:4]}-{phone_num[4:7]}-{phone_num[7:]}"
+
+
+def jinja_filter_month_year_fmt(_datetime: datetime.datetime):
+    """Format a datetime as its full month name and year.
+
+    Args:
+        _datetime: The datetime to format.
+
+    Returns:
+        The formatted string, e.g. "January 2024".
+    """
+    return _datetime.strftime("%B %Y")

pdf_render/templates/filters/getter_filters.py

@@ -0,0 +1,45 @@
+def jinja_filter_get_list_item_by_attr(list_in: list, attr: str, attr_value: str):
+    """Return the first item in a list whose attribute matches a value.
+
+    Similar to Jinja2's built-in `selectattr` filter, but returns only the
+    first match instead of an iterable of all matches.
+
+    Args:
+        list_in: The list of objects to search.
+        attr: The attribute name to compare.
+        attr_value: The value `attr` must equal.
+
+    Returns:
+        The first matching item, or `""` if none match.
+    """
+    for item in list_in:
+        if getattr(item, attr) == attr_value:
+            return item
+    return ""
+
+
+def jinja_filter_with_item_attr_first(list_in: list, attr: str, attr_values: str | list[str]):
+    """Reorder a list so items matching given attribute value(s) come first.
+
+    Args:
+        list_in: The list of objects to reorder.
+        attr: The attribute name to compare.
+        attr_values: One or more values of `attr` to move to the front, in
+            priority order. If neither a `str` nor a `list`, `list_in` is
+            returned unchanged.
+
+    Returns:
+        A new list with matching items first (in `attr_values` priority
+        order), followed by the remaining items in their original order.
+    """
+    if not isinstance(attr_values, str) and not isinstance(attr_values, list):
+        return list_in
+
+    if isinstance(attr_values, str):
+        attr_values = [attr_values]
+
+    result_list = []
+    for attr_value in attr_values:
+        result_list += [item for item in list_in if getattr(item, attr) == attr_value]
+
+    return result_list + [item for item in list_in if item not in result_list]