ymprint 0.1.0__py3-none-any.whl

ymprint/__init__.py

@@ -0,0 +1,2 @@
+from ymprint import config
+from ymprint import blocks

ymprint/blocks/__init__.py

@@ -0,0 +1,107 @@
+import re
+
+from typing import Callable, Optional, Union, TypeAlias, Any
+
+from reportlab.platypus import (
+    Paragraph,
+    Spacer,
+    Table,
+    Image,
+    HRFlowable,
+    KeepTogether,
+)
+from reportlab.lib.units import mm
+from ymprint.config.docstyles import ReportStyles
+from ..content_checks import check_for_variable
+
+RLFlowables: TypeAlias = Union[Paragraph, Spacer, Table, KeepTogether, Image]
+
+YAML_Values: TypeAlias =Union[str, list, dict, float, int, None]
+
+# TODO: Create a block registration function and a singleton block registry
+
+class BlockExistsError(Exception):
+    pass
+
+def create_block_registry() -> tuple[Callable, Callable, Callable]:
+    """
+    Creates the block registry
+    """
+    _BLOCK_REGISTRY = {}
+
+    def register_block(block_code: str, block_convert: Callable) -> None:
+        """
+        Returns None. Adds a new block to the block registry.
+
+        'block_code': a str of the form '_{code}' where 'code' is an alphanumeric code used
+            to identify the block.
+        'block_convert':a function with the following signature:
+            my_func(obj: dict, context: dict) -> list[Flowable] 
+
+            Where:
+                obj: a dict which has a key that starts with the block code and a value
+                    which is a user-defined data structure that contains the data needed
+                    to generate the block as a ReportLab Flowable.
+                context: a dict that contains all of the internal state of this program
+                    at the time the conversion is executed. This will get passed to your 
+                    function automatically and gives your conversion function access to 
+                    anything and everything it needs to render your custom block. 
+                    Feel free to explore the context dict by using a print(context) call
+                    in your function.
+                
+            Return:
+                A list of ReportLab Flowable from the reportlab.platypus module. Your custom
+                block may be just one flowable (like a custom-populated table) or it can
+                be a list of many flowable. 
+        """
+        _BLOCK_REGISTRY.update({block_code: block_convert})
+
+    def list_blocks():
+        return list(_BLOCK_REGISTRY.keys())
+    
+    def get_block_callable(block_code: str) -> Optional[Callable]:
+        return _BLOCK_REGISTRY.get(block_code)
+
+    return list_blocks, get_block_callable, register_block
+
+list_blocks, get_block_callable, register_block = create_block_registry()
+
+def convert_blocks(block_key: str, block_value: YAML_Values, context: dict) -> list[RLFlowables]:
+    block_code_pattern = re.compile(r"(^_[a-zA-Z0-9]+)")
+    matches = block_code_pattern.match(block_key)
+    if matches is not None:
+        block_code = matches.groups()[0]
+    else:
+        raise ValueError(f"Block code not found within block key: {block_key=}")
+    block_converter = get_block_callable(block_code)
+    block_value_w_python_objects = retrieve_block_variables(block_value, context)
+    flowables = block_converter(block_key, block_value_w_python_objects, context)
+    return flowables
+
+
+def retrieve_block_variables(block_value: YAML_Values, context: dict) -> YAML_Values:
+    """
+    Returns 'block_value' but with list values or dictionary values that have
+    the "$VAR" syntax substituted with the object values
+    """
+    if isinstance(block_value, str) and check_for_variable(block_value, context):
+        var_name = get_variable_name(block_value)
+        return context['vars'].get(var_name, block_value)
+    elif isinstance(block_value, list):
+        acc = []
+        for elem in block_value:
+            new_elem = retrieve_block_variables(elem, context)
+            acc.append(new_elem)
+        return acc
+    elif isinstance(block_value, dict):
+        acc = {}
+        for k, v in block_value.items():
+            new_v = retrieve_block_variables(v, context)
+            acc.update({k: new_v})
+        return acc
+    else:
+        return block_value
+
+
+def get_variable_name(var_string: str) -> str:
+    return var_string.lstrip('$')

ymprint/blocks/admonition_block.py

@@ -0,0 +1,42 @@
+from reportlab.platypus import Table, Paragraph, Spacer, KeepTogether
+from . import register_block
+from typing import Callable, Any
+from . import blockstyles
+
+def generate_admonition_block(kind: str) -> Callable:
+    """
+    Returns a callable to render that particular admonition type
+    """
+    
+
+    def convert_admonition_block(block_key: str, block_value: Any, context: dict) -> list[KeepTogether | Spacer]:
+        # Need an admonition block style or style modification
+        available_width = context['frames']['all_pages']['width']
+        text_spacing = context['styles']['ymprint'].body.spacing
+        text_size = context['styles']['ymprint'].body.size
+        space_around = text_spacing * text_size
+        width_ratio = 0.8
+        block_width = width_ratio * available_width
+        value = block_value
+        tablestyle = blockstyles.get_table_style(kind)
+        body_textstyle = blockstyles.get_text_styles().get(f'admonition_{kind}_body')
+        title_textstyle = blockstyles.get_text_styles().get(f'admonition_{kind}_title')
+        notice = Paragraph(text=blockstyles.admonition_title_text(kind), style=title_textstyle)
+        content = Paragraph(text=value, style=body_textstyle)
+        table = Table(
+            data=[[notice], [content]],
+            colWidths=[block_width],
+            style=tablestyle,
+            spaceBefore=space_around,
+            spaceAfter=space_around
+        )    
+        return [KeepTogether(table), Spacer(1, 10)]
+    
+    return convert_admonition_block
+
+
+register_block("_info", generate_admonition_block("info"))
+register_block("_warning", generate_admonition_block("warning"))
+register_block("_danger", generate_admonition_block("danger"))
+register_block("_tip", generate_admonition_block("tip"))
+register_block("_note", generate_admonition_block("note"))

ymprint/blocks/blockstyles.py

@@ -0,0 +1,340 @@
+"""
+styles.py
+ReportLab styles for markdown-to-PDF report generation.
+
+Covers:
+  - Admonition blocks: Info, Warning, Danger, Tip, Note
+  - Image blocks (image + caption)
+
+Usage:
+    from styles import get_styles, get_table_style
+    styles = get_styles()
+    ts = get_table_style("info")
+"""
+
+from reportlab.lib import colors
+from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
+pt = 1  # ReportLab's internal unit; 1 pt == 1 unit
+from reportlab.platypus import TableStyle
+
+# ---------------------------------------------------------------------------
+# Design tokens
+# ---------------------------------------------------------------------------
+
+# Base font
+FONT_NORMAL = "Helvetica"
+FONT_BOLD   = "Helvetica-Bold"
+FONT_ITALIC = "Helvetica-Oblique"
+FONT_MONO   = "Courier"
+
+# Base sizes
+BODY_FONT_SIZE   = 10
+LABEL_FONT_SIZE  = 8
+CAPTION_FONT_SIZE = 9
+
+# Spacing
+CELL_PADDING_H = 10   # horizontal padding inside admonition cells (pt)
+CELL_PADDING_V = 8    # vertical padding inside admonition cells (pt)
+BORDER_RADIUS  = 4    # not directly used by ReportLab, but documents intent
+
+# ---------------------------------------------------------------------------
+# Colour palette
+# ---------------------------------------------------------------------------
+
+class Palette:
+    # Neutrals
+    WHITE        = colors.HexColor("#FFFFFF")
+    BODY_TEXT    = colors.HexColor("#1A1A2E")
+    CAPTION_TEXT = colors.HexColor("#555555")
+    TABLE_BORDER = colors.HexColor("#CCCCCC")
+
+    # Info  (blue)
+    INFO_BG      = colors.HexColor("#EFF6FF")
+    INFO_BORDER  = colors.HexColor("#3B82F6")
+    INFO_TITLE   = colors.HexColor("#1D4ED8")
+    INFO_TEXT    = colors.HexColor("#1E3A5F")
+    INFO_ICON    = "ℹ"
+
+    # Warning  (amber)
+    WARNING_BG     = colors.HexColor("#FFFBEB")
+    WARNING_BORDER = colors.HexColor("#F59E0B")
+    WARNING_TITLE  = colors.HexColor("#B45309")
+    WARNING_TEXT   = colors.HexColor("#4D3A00")
+    WARNING_ICON   = "⚠"
+
+    # Danger  (red)
+    DANGER_BG     = colors.HexColor("#FEF2F2")
+    DANGER_BORDER = colors.HexColor("#EF4444")
+    DANGER_TITLE  = colors.HexColor("#B91C1C")
+    DANGER_TEXT   = colors.HexColor("#4D0000")
+    DANGER_ICON   = "✖"
+
+    # Tip  (green)
+    TIP_BG     = colors.HexColor("#F0FDF4")
+    TIP_BORDER = colors.HexColor("#22C55E")
+    TIP_TITLE  = colors.HexColor("#15803D")
+    TIP_TEXT   = colors.HexColor("#14532D")
+    TIP_ICON   = "✔"
+
+    # Note  (purple)
+    NOTE_BG     = colors.HexColor("#FAF5FF")
+    NOTE_BORDER = colors.HexColor("#A855F7")
+    NOTE_TITLE  = colors.HexColor("#7E22CE")
+    NOTE_TEXT   = colors.HexColor("#3B0764")
+    NOTE_ICON   = "✎"
+
+ # Blockquote  (neutral slate)
+    BLOCKQUOTE_BG          = colors.HexColor("#F8F9FA")
+    BLOCKQUOTE_BORDER      = colors.HexColor("#444444")   # slate-400
+    BLOCKQUOTE_TEXT        = colors.HexColor("#374151")   # slate-700
+    BLOCKQUOTE_ATTRIBUTION = colors.HexColor("#6B7280")   # slate-500
+
+# ---------------------------------------------------------------------------
+# Paragraph styles
+# ---------------------------------------------------------------------------
+
+def get_text_styles():
+    """
+    Return a dict of ParagraphStyle objects keyed by name.
+
+    Keys
+    ----
+    admonition_<kind>_title   — bold label line  (kind: info/warning/danger/tip/note)
+    admonition_<kind>_body    — body text inside the block
+    image_caption             — caption below an image
+    """
+    base = getSampleStyleSheet()
+
+    # Shared defaults for admonition body text
+    _admonition_body_defaults = dict(
+        fontName=FONT_NORMAL,
+        fontSize=BODY_FONT_SIZE,
+        leading=BODY_FONT_SIZE * 1.4,
+        spaceAfter=0,
+        spaceBefore=0,
+    )
+
+    # Shared defaults for admonition title / label
+    _admonition_title_defaults = dict(
+        fontName=FONT_BOLD,
+        fontSize=LABEL_FONT_SIZE,
+        leading=LABEL_FONT_SIZE * 1.3,
+        spaceAfter=3,
+        spaceBefore=0,
+        textTransform="uppercase",
+    )
+
+    blocks = {
+        "info":    (Palette.INFO_TITLE,    Palette.INFO_TEXT),
+        "warning": (Palette.WARNING_TITLE, Palette.WARNING_TEXT),
+        "danger":  (Palette.DANGER_TITLE,  Palette.DANGER_TEXT),
+        "tip":     (Palette.TIP_TITLE,     Palette.TIP_TEXT),
+        "note":    (Palette.NOTE_TITLE,    Palette.NOTE_TEXT),
+    }
+
+    styles = {}
+
+    for kind, (title_color, body_color) in blocks.items():
+        styles[f"admonition_{kind}_title"] = ParagraphStyle(
+            name=f"admonition_{kind}_title",
+            textColor=title_color,
+            **_admonition_title_defaults,
+        )
+        styles[f"admonition_{kind}_body"] = ParagraphStyle(
+            name=f"admonition_{kind}_body",
+            textColor=body_color,
+            **_admonition_body_defaults,
+        )
+
+    # Blockquote — quote body (italic, indented feel via left padding on the table)
+    styles["blockquote_body"] = ParagraphStyle(
+        name="blockquote_body",
+        fontName=FONT_ITALIC,
+        fontSize=BODY_FONT_SIZE + 1,        # slightly larger feels more editorial
+        leading=(BODY_FONT_SIZE + 1) * 1.5, # generous leading for readability
+        textColor=Palette.BLOCKQUOTE_TEXT,
+        spaceAfter=0,
+        spaceBefore=0,
+    )
+
+    # Blockquote — optional attribution line  ("— Author Name")
+    styles["blockquote_attribution"] = ParagraphStyle(
+        name="blockquote_attribution",
+        fontName=FONT_NORMAL,
+        fontSize=BODY_FONT_SIZE - 1,
+        leading=(BODY_FONT_SIZE - 1) * 1.4,
+        textColor=Palette.BLOCKQUOTE_ATTRIBUTION,
+        spaceAfter=0,
+        spaceBefore=6,
+        alignment=2,   # right-align attribution
+    )
+
+
+    # Image caption
+    styles["image_caption"] = ParagraphStyle(
+        name="image_caption",
+        fontName=FONT_ITALIC,
+        fontSize=CAPTION_FONT_SIZE,
+        leading=CAPTION_FONT_SIZE * 1.4,
+        textColor=Palette.CAPTION_TEXT,
+        alignment=1,   # centre
+        spaceBefore=4,
+        spaceAfter=0,
+    )
+
+    return styles
+
+
+# ---------------------------------------------------------------------------
+# Table styles
+# ---------------------------------------------------------------------------
+
+# Left-accent border width (pt)
+ACCENT_WIDTH = 4
+
+def _admonition_table_style(bg: colors.Color,
+                             border: colors.Color) -> TableStyle:
+    """
+    Build a TableStyle for a single-column admonition table.
+
+    Layout assumption:
+        Table has 1 column and 2 rows:
+          row 0 — title  (icon + label)
+          row 1 — body text
+    """
+    return TableStyle([
+        # Background
+        ("BACKGROUND",    (0, 0), (-1, -1), bg),
+
+        # Left accent bar
+        ("LINEBEFORE",    (0, 0), (0, -1), ACCENT_WIDTH, border),
+
+        # Outer border (thin, same hue as accent)
+        ("BOX",           (0, 0), (-1, -1), 0.5, border),
+
+        # No internal grid lines
+        ("INNERGRID",     (0, 0), (-1, -1), 0, colors.transparent),
+
+        # Padding
+        ("LEFTPADDING",   (0, 0), (-1, -1), CELL_PADDING_H),
+        ("RIGHTPADDING",  (0, 0), (-1, -1), CELL_PADDING_H),
+        ("TOPPADDING",    (0, 0), (0,  0),  CELL_PADDING_V),       # title row top
+        ("BOTTOMPADDING", (0, 0), (0,  0),  3),                     # title row bottom (tight)
+        ("TOPPADDING",    (0, 1), (0, -1),  4),                     # body row top
+        ("BOTTOMPADDING", (0, 1), (0, -1),  CELL_PADDING_V),        # body row bottom
+
+        # Vertical alignment
+        ("VALIGN",        (0, 0), (-1, -1), "TOP"),
+        ("ROUNDEDCORNERS", [4, 4, 4, 4])
+        # ROUNDEDCORNERS, [tl, tr, bl, br]
+    ])
+
+
+# Blockquote table style
+# Layout: 1 column, 1–2 rows
+#   row 0 — quote body text (required)
+#   row 1 — attribution     (optional; omit the row if no attribution)
+BLOCKQUOTE_ACCENT_WIDTH = 5   # slightly thicker than admonition bars
+ 
+BLOCKQUOTE_TABLE_STYLE = TableStyle([
+    # Subtle background tint
+    ("BACKGROUND",    (0, 0), (-1, -1), Palette.BLOCKQUOTE_BG),
+ 
+    # Thick left accent bar — the defining visual of a blockquote
+    ("LINEBEFORE",    (0, 0), (0, -1), BLOCKQUOTE_ACCENT_WIDTH, Palette.BLOCKQUOTE_BORDER),
+ 
+    # No outer box, no grid — keep it clean and "open"
+    ("BOX",           (0, 0), (-1, -1), 0, colors.transparent),
+    ("INNERGRID",     (0, 0), (-1, -1), 0, colors.transparent),
+ 
+    # Generous horizontal padding to offset the accent bar visually
+    ("LEFTPADDING",   (0, 0), (-1, -1), 14),
+    ("RIGHTPADDING",  (0, 0), (-1, -1), 12),
+ 
+    # Vertical padding: roomy on the quote body
+    ("TOPPADDING",    (0, 0), (0,  0),  10),
+    ("BOTTOMPADDING", (0, 0), (0,  0),  6),
+ 
+    # Attribution row (row 1) sits tight to the quote
+    ("TOPPADDING",    (0, 1), (0, -1),  0),
+    ("BOTTOMPADDING", (0, 1), (0, -1),  10),
+    ("ROUNDEDCORNERS", [4, 4, 4, 4]),
+
+    ("VALIGN",        (0, 0), (-1, -1), "TOP"),
+])
+
+
+# Pre-built table styles for each admonition kind
+ADMONITION_TABLE_STYLES: dict[str, TableStyle] = {
+    "info":    _admonition_table_style(Palette.INFO_BG,    Palette.INFO_BORDER),
+    "warning": _admonition_table_style(Palette.WARNING_BG, Palette.WARNING_BORDER),
+    "danger":  _admonition_table_style(Palette.DANGER_BG,  Palette.DANGER_BORDER),
+    "tip":     _admonition_table_style(Palette.TIP_BG,     Palette.TIP_BORDER),
+    "note":    _admonition_table_style(Palette.NOTE_BG,    Palette.NOTE_BORDER),
+}
+
+# Image/caption table style
+IMAGE_TABLE_STYLE = TableStyle([
+    # No background, no border — image block is decoration-free
+    ("BACKGROUND",   (0, 0), (-1, -1), colors.transparent),
+    ("BOX",          (0, 0), (-1, -1), 0,   colors.transparent),
+    ("INNERGRID",    (0, 0), (-1, -1), 0,   colors.transparent),
+
+    # Padding
+    ("LEFTPADDING",  (0, 0), (-1, -1), 0),
+    ("RIGHTPADDING", (0, 0), (-1, -1), 0),
+    ("TOPPADDING",   (0, 0), (-1, -1), 0),
+    ("BOTTOMPADDING",(0, 0), (0,  0),  4),   # gap between image and caption
+    ("BOTTOMPADDING",(0, 1), (0, -1),  0),
+
+    # Centre both image and caption horizontally
+    ("ALIGN",        (0, 0), (-1, -1), "CENTER"),
+    ("VALIGN",       (0, 0), (-1, -1), "TOP"),
+])
+
+
+def get_table_style(block_type: str) -> TableStyle:
+    """
+    Return the TableStyle for a given block type.
+ 
+    Parameters
+    ----------
+    block_type : str
+        One of: "info", "warning", "danger", "tip", "note", "image"
+ 
+    Returns
+    -------
+    TableStyle
+    """
+    if block_type == "image":
+        return IMAGE_TABLE_STYLE
+    if block_type == "blockquote":
+        return BLOCKQUOTE_TABLE_STYLE
+    try:
+        return ADMONITION_TABLE_STYLES[block_type]
+    except KeyError:
+        valid = list(ADMONITION_TABLE_STYLES) + ["blockquote", "image"]
+        raise ValueError(
+            f"Unknown block type '{block_type}'. Choose from: {valid}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Icon / label helpers
+# ---------------------------------------------------------------------------
+
+ADMONITION_META: dict[str, dict] = {
+    "info":    {"icon": Palette.INFO_ICON,    "label": "Info"},
+    "warning": {"icon": Palette.WARNING_ICON, "label": "Warning"},
+    "danger":  {"icon": Palette.DANGER_ICON,  "label": "Danger"},
+    "tip":     {"icon": Palette.TIP_ICON,     "label": "Tip"},
+    "note":    {"icon": Palette.NOTE_ICON,    "label": "Note"},
+}
+
+
+def admonition_title_text(kind: str, label: str | None = None) -> str:
+    """Return  '⚠  WARNING'  style label string for the title row."""
+    meta = ADMONITION_META[kind]
+    if label is not None:
+        return f"{meta['icon']}  {label.upper()}"
+    return f"{meta['icon']}  {meta['label'].upper()}"

ymprint/blocks/code_block.py

@@ -0,0 +1,25 @@
+from reportlab.platypus import Table, KeepTogether
+from . import register_block
+from .code_block_styles import generic_code_block
+from typing import Callable
+
+
+
+def convert_code_block(block_key: str, block_value: dict, context: dict) -> list[KeepTogether]:
+    # Need an admonition block style or style modification
+    source = block_value['source']
+    caption = block_value.get('caption')
+    line_numbers = block_value.get('line_numbers')
+    width_ratio = block_value.get('width_ratio', 0.75)
+    available_width = context['frames']['all_pages']['width']
+    text_spacing = context['styles']['ymprint'].body.spacing
+    text_size = context['styles']['ymprint'].body.size
+    space_around = text_spacing * text_size
+    namespace = block_value.get('namespace')
+    code_block = generic_code_block(source, available_width * width_ratio, context, caption=caption, show_line_numbers=line_numbers)
+    code_block.spaceBefore = space_around
+    code_block.spaceAfter = space_around
+    return [KeepTogether(code_block)]
+
+
+register_block("_code", convert_code_block)