markdown-to-confluence 0.5.2__py3-none-any.whl → 0.5.4__py3-none-any.whl

md2conf/scanner.py

@@ -1,55 +1,34 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
 
-import re
-import typing
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Literal, TypeVar
+from typing import TypeVar
 
-import yaml
-
-from .mermaid import MermaidConfigProperties
+from .coalesce import coalesce
+from .frontmatter import extract_frontmatter_json, extract_value
+from .options import LayoutOptions
 from .serializer import JsonType, json_to_object
 
 T = TypeVar("T")
 
 
-def extract_value(pattern: str, text: str) -> tuple[str | None, str]:
-    values: list[str] = []
-
-    def _repl_func(match: re.Match[str]) -> str:
-        values.append(match.group(1))
-        return ""
-
-    text = re.sub(pattern, _repl_func, text, count=1, flags=re.ASCII)
-    value = values[0] if values else None
-    return value, text
-
-
-def extract_frontmatter_block(text: str) -> tuple[str | None, str]:
-    "Extracts the front-matter from a Markdown document as a blob of unparsed text."
-
-    return extract_value(r"(?ms)\A---$(.+?)^---$", text)
-
-
-def extract_frontmatter_properties(text: str) -> tuple[dict[str, JsonType] | None, str]:
-    "Extracts the front-matter from a Markdown document as a dictionary."
-
-    block, text = extract_frontmatter_block(text)
+@dataclass
+class AliasProperties:
+    """
+    An object that holds properties extracted from the front-matter of a Markdown document.
 
-    properties: dict[str, Any] | None = None
-    if block is not None:
-        data = yaml.safe_load(block)
-        if isinstance(data, dict):
-            properties = typing.cast(dict[str, JsonType], data)
+    :param confluence_page_id: Confluence page ID. (Alternative name for JSON de-serialization.)
+    :param confluence_space_key: Confluence space key. (Alternative name for JSON de-serialization.)
+    """
 
-    return properties, text
+    confluence_page_id: str | None = None
+    confluence_space_key: str | None = None
 
 
 @dataclass
@@ -59,26 +38,22 @@ class DocumentProperties:
 
     :param page_id: Confluence page ID.
     :param space_key: Confluence space key.
-    :param confluence_page_id: Confluence page ID. (Alternative name for JSON de-serialization.)
-    :param confluence_space_key: Confluence space key. (Alternative name for JSON de-serialization.)
     :param generated_by: Text identifying the tool that generated the document.
     :param title: The title extracted from front-matter.
     :param tags: A list of tags (content labels) extracted from front-matter.
     :param synchronized: True if the document content is parsed and synchronized with Confluence.
     :param properties: A dictionary of key-value pairs extracted from front-matter to apply as page properties.
-    :param alignment: Alignment for block-level images and formulas.
+    :param layout: Layout options for content on a Confluence page.
     """
 
     page_id: str | None = None
     space_key: str | None = None
-    confluence_page_id: str | None = None
-    confluence_space_key: str | None = None
     generated_by: str | None = None
     title: str | None = None
     tags: list[str] | None = None
     synchronized: bool | None = None
     properties: dict[str, JsonType] | None = None
-    alignment: Literal["center", "left", "right"] | None = None
+    layout: LayoutOptions | None = None
 
 
 @dataclass
@@ -86,25 +61,11 @@ class ScannedDocument:
     """
     An object that holds properties extracted from a Markdown document, including remaining source text.
 
-    :param page_id: Confluence page ID.
-    :param space_key: Confluence space key.
-    :param generated_by: Text identifying the tool that generated the document.
-    :param title: The title extracted from front-matter.
-    :param tags: A list of tags (content labels) extracted from front-matter.
-    :param synchronized: True if the document content is parsed and synchronized with Confluence.
-    :param properties: A dictionary of key-value pairs extracted from front-matter to apply as page properties.
-    :param alignment: Alignment for block-level images and formulas.
+    :param properties: Properties extracted from the front-matter of a Markdown document.
     :param text: Text that remains after front-matter and inline properties have been extracted.
     """
 
-    page_id: str | None
-    space_key: str | None
-    generated_by: str | None
-    title: str | None
-    tags: list[str] | None
-    synchronized: bool | None
-    properties: dict[str, JsonType] | None
-    alignment: Literal["center", "left", "right"] | None
+    properties: DocumentProperties
     text: str
 
 
@@ -114,10 +75,16 @@ class Scanner:
         Extracts essential properties from a Markdown document.
         """
 
-        # parse file
         with open(absolute_path, "r", encoding="utf-8") as f:
             text = f.read()
 
+        return self.parse(text)
+
+    def parse(self, text: str) -> ScannedDocument:
+        """
+        Extracts essential properties from a Markdown document.
+        """
+
         # extract Confluence page ID
         page_id, text = extract_value(r"<!--\s+confluence[-_]page[-_]id:\s*(\d+)\s+-->", text)
 
@@ -127,77 +94,19 @@ class Scanner:
         # extract 'generated-by' tag text
         generated_by, text = extract_value(r"<!--\s+generated[-_]by:\s*(.*)\s+-->", text)
 
-        title: str | None = None
-        tags: list[str] | None = None
-        synchronized: bool | None = None
-        properties: dict[str, JsonType] | None = None
-        alignment: Literal["center", "left", "right"] | None = None
+        body_props = DocumentProperties(page_id=page_id, space_key=space_key, generated_by=generated_by)
 
         # extract front-matter
-        data, text = extract_frontmatter_properties(text)
+        data, text = extract_frontmatter_json(text)
         if data is not None:
-            p = json_to_object(DocumentProperties, data)
-            page_id = page_id or p.confluence_page_id or p.page_id
-            space_key = space_key or p.confluence_space_key or p.space_key
-            generated_by = generated_by or p.generated_by
-            title = p.title
-            tags = p.tags
-            synchronized = p.synchronized
-            properties = p.properties
-            alignment = p.alignment
-
-        return ScannedDocument(
-            page_id=page_id,
-            space_key=space_key,
-            generated_by=generated_by,
-            title=title,
-            tags=tags,
-            synchronized=synchronized,
-            properties=properties,
-            alignment=alignment,
-            text=text,
-        )
-
-
-@dataclass
-class MermaidProperties:
-    """
-    An object that holds the front-matter properties structure for Mermaid diagrams.
-
-    :param title: The title of the diagram.
-    :param config: Configuration options for rendering.
-    """
-
-    title: str | None = None
-    config: MermaidConfigProperties | None = None
-
-
-class MermaidScanner:
-    """
-    Extracts properties from the JSON/YAML front-matter of a Mermaid diagram.
-    """
-
-    def read(self, content: str) -> MermaidProperties:
-        """
-        Extracts rendering preferences from a Mermaid front-matter content.
-
-        ```
-        ---
-        title: Tiny flow diagram
-        config:
-            scale: 1
-        ---
-        flowchart LR
-            A[Component A] --> B[Component B]
-            B --> C[Component C]
-        ```
-        """
-
-        properties, _ = extract_frontmatter_properties(content)
-        if properties is not None:
-            front_matter = json_to_object(MermaidProperties, properties)
-            config = front_matter.config or MermaidConfigProperties()
-
-            return MermaidProperties(title=front_matter.title, config=config)
-
-        return MermaidProperties()
+            frontmatter_props = json_to_object(DocumentProperties, data)
+            alias_props = json_to_object(AliasProperties, data)
+            if alias_props.confluence_page_id is not None:
+                frontmatter_props.page_id = alias_props.confluence_page_id
+            if alias_props.confluence_space_key is not None:
+                frontmatter_props.space_key = alias_props.confluence_space_key
+            props = coalesce(body_props, frontmatter_props)
+        else:
+            props = body_props
+
+        return ScannedDocument(properties=props, text=text)

md2conf/serializer.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -10,7 +10,7 @@ import sys
 from datetime import datetime
 from typing import TypeVar
 
-from cattrs.preconf.orjson import make_converter
+from cattrs.preconf.orjson import make_converter  # spellchecker:disable-line
 
 JsonType = None | bool | int | float | str | dict[str, "JsonType"] | list["JsonType"]
 JsonComposite = dict[str, "JsonType"] | list["JsonType"]

md2conf/svg.py

@@ -1,7 +1,7 @@
 """
-SVG dimension extraction utilities.
+Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -9,6 +9,7 @@ Copyright 2022-2025, Levente Hunyadi
 import logging
 import re
 from pathlib import Path
+from typing import overload
 
 import lxml.etree as ET
 
@@ -19,6 +20,10 @@ LOGGER = logging.getLogger(__name__)
 SVG_NAMESPACE = "http://www.w3.org/2000/svg"
 
 
+class SVGParseError(RuntimeError):
+    pass
+
+
 def _check_svg(root: ElementType) -> bool:
     "Tests if the element is a plain or scoped SVG element."
 
@@ -31,7 +36,7 @@ def _check_svg(root: ElementType) -> bool:
     return qname.localname == "svg" and (not qname.namespace or qname.namespace == SVG_NAMESPACE)
 
 
-def _extract_dimensions_from_root(root: ElementType) -> tuple[int | None, int | None]:
+def _extract_dimensions_from_root(root: ElementType) -> tuple[int, int] | None:
     """
     Extracts width and height from an SVG root element.
 
@@ -40,11 +45,11 @@ def _extract_dimensions_from_root(root: ElementType) -> tuple[int | None, int |
     2. The viewBox attribute if width/height are not specified
 
     :param root: The root element of the SVG document.
-    :returns: A tuple of (width, height) in pixels, or (None, None) if dimensions cannot be determined.
+    :returns: A tuple of (width, height) in pixels, or `None` if dimensions cannot be determined.
     """
 
     if not _check_svg(root):
-        return None, None
+        raise SVGParseError("SVG file does not have an <svg> root element")
 
     width_attr = root.get("width")
     height_attr = root.get("height")
@@ -52,69 +57,86 @@ def _extract_dimensions_from_root(root: ElementType) -> tuple[int | None, int |
     width = _parse_svg_length(width_attr) if width_attr else None
     height = _parse_svg_length(height_attr) if height_attr else None
 
-    # If width/height not specified, try to derive from viewBox
+    # if width/height not specified, try to derive from view-box
     if width is None or height is None:
-        viewbox = root.get("viewBox")
-        if viewbox:
-            vb_width, vb_height = _parse_viewbox(viewbox)
-            if width is None:
-                width = vb_width
-            if height is None:
-                height = vb_height
+        viewbox_attr = root.get("viewBox")
+        if viewbox_attr:
+            viewbox = _parse_viewbox(viewbox_attr)
+            if viewbox is not None:
+                vb_width, vb_height = viewbox
+                if width is not None:
+                    height = width * vb_height // vb_width
+                elif height is not None:
+                    width = height * vb_width // vb_height
+                else:
+                    width = vb_width
+                    height = vb_height
+
+    if width is None or height is None:
+        return None
 
     return width, height
 
 
-def get_svg_dimensions(path: Path) -> tuple[int | None, int | None]:
+@overload
+def get_svg_dimensions(svg: Path) -> tuple[int, int] | None:
     """
     Extracts width and height from an SVG file.
 
     Attempts to read dimensions from:
-    1. Explicit width/height attributes on the root <svg> element
-    2. The viewBox attribute if width/height are not specified
 
-    :param path: Path to the SVG file.
-    :returns: A tuple of (width, height) in pixels, or (None, None) if dimensions cannot be determined.
-    """
-
-    try:
-        tree = ET.parse(str(path))
-        root = tree.getroot()
-        width, height = _extract_dimensions_from_root(root)
-        if width is None and height is None:
-            LOGGER.warning("SVG file %s does not have an <svg> root element", path)
-        return width, height
+    1. Explicit `width` and `height` attributes on the root `<svg>` element
+    2. The `viewBox` attribute if `width` or `height` is not specified
 
-    except ET.XMLSyntaxError as ex:
-        LOGGER.warning("Failed to parse SVG file %s: %s", path, ex)
-        return None, None
-    except Exception as ex:
-        LOGGER.warning("Unexpected error reading SVG dimensions from %s: %s", path, ex)
-        return None, None
+    :param svg: Path to the SVG file.
+    :returns: A tuple of (width, height) in pixels, or `None` if dimensions cannot be determined.
+    """
+    ...
 
 
-def get_svg_dimensions_from_bytes(data: bytes) -> tuple[int | None, int | None]:
+@overload
+def get_svg_dimensions(svg: bytes | str) -> tuple[int, int] | None:
     """
     Extracts width and height from SVG data in memory.
 
     Attempts to read dimensions from:
-    1. Explicit width/height attributes on the root <svg> element
-    2. The viewBox attribute if width/height are not specified
 
-    :param data: The SVG content as bytes.
-    :returns: A tuple of (width, height) in pixels, or (None, None) if dimensions cannot be determined.
-    """
+    1. Explicit `width` and `height` attributes on the root `<svg>` element
+    2. The `viewBox` attribute if `width` or `height` is not specified
 
-    try:
-        root = ET.fromstring(data)
-        return _extract_dimensions_from_root(root)
-
-    except ET.XMLSyntaxError as ex:
-        LOGGER.warning("Failed to parse SVG data: %s", ex)
-        return None, None
-    except Exception as ex:
-        LOGGER.warning("Unexpected error reading SVG dimensions from data: %s", ex)
-        return None, None
+    :param svg: The SVG content as bytes.
+    :returns: A tuple of (width, height) in pixels, or `None` if dimensions cannot be determined.
+    """
+    ...
+
+
+def get_svg_dimensions(svg: Path | bytes | str) -> tuple[int, int] | None:
+    if isinstance(svg, Path):
+        path = svg
+        try:
+            tree = ET.parse(path)
+            root = tree.getroot()
+            return _extract_dimensions_from_root(root)
+        except OSError as ex:
+            LOGGER.warning("Failed to open SVG file: %s", path, exc_info=ex)
+            return None
+        except ET.XMLSyntaxError as ex:
+            LOGGER.warning("Failed to parse SVG file: %s", path, exc_info=ex)
+            return None
+        except SVGParseError as ex:
+            LOGGER.warning("Failed to extract dimensions from SVG file: %s", path, exc_info=ex)
+            return None
+    else:
+        data = svg
+        try:
+            root = ET.fromstring(data)
+            return _extract_dimensions_from_root(root)
+        except ET.XMLSyntaxError as ex:
+            LOGGER.warning("Failed to parse SVG data", exc_info=ex)
+            return None
+        except SVGParseError as ex:
+            LOGGER.warning("Failed to extract dimensions from SVG data", exc_info=ex)
+            return None
 
 
 def _serialize_svg_opening_tag(root: ElementType) -> str:
@@ -128,7 +150,7 @@ def _serialize_svg_opening_tag(root: ElementType) -> str:
     # Build the opening tag from element name and attributes
     root_tag = root.tag
     if not isinstance(root_tag, str):
-        raise TypeError("expected: tag names as `str`")
+        raise SVGParseError("expected: tag names as `str`")
     tag_name = ET.QName(root_tag).localname
     parts = [f"<{tag_name}"]
 
@@ -180,64 +202,56 @@ def fix_svg_dimensions(data: bytes) -> bytes:
     :returns: The modified SVG content with explicit dimensions, or original data if modification fails.
     """
 
-    try:
-        text = data.decode("utf-8")
-
-        # Skip SVGs with foreignObject - Confluence has issues rendering
-        # foreignObject content when explicit width/height are set on the SVG
-        if "<foreignObject" in text:
-            LOGGER.debug("Skipping dimension fix for SVG with foreignObject elements")
-            return data
-
-        # Parse the SVG to extract root element attributes
-        root = ET.fromstring(data)
-
-        # Verify it's an SVG element
-        if not _check_svg(root):
-            return data
-
-        # Check if we need to fix (has width="100%" or similar percentage)
-        width_attr = root.get("width")
-        if width_attr != "100%":
-            # Check if it already has a valid numeric width
-            if width_attr is not None and _parse_svg_length(width_attr) is not None:
-                return data  # Already has numeric width
+    # Skip SVGs with foreignObject - Confluence has issues rendering
+    # foreignObject content when explicit width/height are set on the SVG
+    if b"<foreignObject" in data:
+        LOGGER.debug("Skipping dimension fix for SVG with foreignObject elements")
+        return data
 
-        # Get viewBox dimensions
-        viewbox = root.get("viewBox")
-        if not viewbox:
-            return data
+    # Parse the SVG to extract root element attributes
+    root = ET.fromstring(data)
 
-        vb_width, vb_height = _parse_viewbox(viewbox)
-        if vb_width is None or vb_height is None:
-            return data
+    # Verify it's an SVG element
+    if not _check_svg(root):
+        return data
 
-        # Extract the original opening tag from the text
-        svg_tag_match = re.search(r"<svg\b[^>]*>", text)
-        if not svg_tag_match:
-            return data
+    # Check if we need to fix (has width="100%" or similar percentage)
+    width_attr = root.get("width")
+    if width_attr != "100%":
+        # Check if it already has a valid numeric width
+        if width_attr is not None and _parse_svg_length(width_attr) is not None:
+            return data  # Already has numeric width
+
+    # Get viewBox dimensions
+    viewbox_attr = root.get("viewBox")
+    if not viewbox_attr:
+        return data
 
-        original_tag = svg_tag_match.group(0)
+    viewbox = _parse_viewbox(viewbox_attr)
+    if viewbox is None:
+        return data
+    vb_width, vb_height = viewbox
 
-        # Modify the root element's attributes
-        root.set("width", str(vb_width))
+    # Extract the original opening tag from the text
+    svg_tag_match = re.search(rb"<svg\b[^>]*>", data)
+    if not svg_tag_match:
+        return data
 
-        # Set height if missing or if it's a percentage
-        height_attr = root.get("height")
-        if height_attr is None or height_attr == "100%":
-            root.set("height", str(vb_height))
+    original_tag = svg_tag_match.group(0)
 
-        # Serialize just the opening tag with modified attributes
-        new_tag = _serialize_svg_opening_tag(root)
+    # Modify the root element's attributes
+    root.set("width", str(vb_width))
 
-        # Replace the original opening tag with the new one
-        text = text.replace(original_tag, new_tag, 1)
+    # Set height if missing or if it's a percentage
+    height_attr = root.get("height")
+    if height_attr is None or height_attr == "100%":
+        root.set("height", str(vb_height))
 
-        return text.encode("utf-8")
+    # Serialize just the opening tag with modified attributes
+    new_tag = _serialize_svg_opening_tag(root).encode("utf-8")
 
-    except Exception as ex:
-        LOGGER.warning("Unexpected error fixing SVG dimensions: %s", ex)
-        return data
+    # Replace the original opening tag with the new one
+    return data.replace(original_tag, new_tag, 1)
 
 
 def _parse_svg_length(value: str) -> int | None:
@@ -294,26 +308,53 @@ def _parse_svg_length(value: str) -> int | None:
     return int(round(pixels))
 
 
-def _parse_viewbox(viewbox: str) -> tuple[int | None, int | None]:
+def _parse_viewbox(viewbox: str) -> tuple[int, int] | None:
     """
     Parses an SVG viewBox attribute and extracts width and height.
 
     :param viewbox: The viewBox string (e.g., "0 0 100 200").
-    :returns: A tuple of (width, height) in pixels, or (None, None) if parsing fails.
+    :returns: A tuple of (width, height) in pixels, or `None` if parsing fails.
     """
 
     if not viewbox:
-        return None, None
+        return None
 
     # viewBox format: "min-x min-y width height"
     # Values can be separated by whitespace and/or commas
     parts = re.split(r"[\s,]+", viewbox.strip())
     if len(parts) != 4:
-        return None, None
+        return None
 
     try:
         width = int(round(float(parts[2])))
         height = int(round(float(parts[3])))
         return width, height
     except ValueError:
-        return None, None
+        return None
+
+
+def fix_svg_get_dimensions(data: bytes) -> tuple[bytes, tuple[int, int] | None]:
+    """
+    Post-processes SVG diagram data by fixing dimensions and extracting metadata.
+
+    This handles the common pattern for SVG diagrams:
+
+    1. fixes SVG dimensions (converts percentage-based to explicit pixels), and
+    2. extracts width/height from the SVG.
+
+    :param data: Raw SVG data as bytes.
+    :returns: Tuple of update raw data, image width, image height.
+    """
+
+    try:
+        # fix SVG to have explicit width/height instead of percentages
+        data = fix_svg_dimensions(data)
+
+        # extract dimensions from the fixed SVG
+        return data, get_svg_dimensions(data)
+    except ET.XMLSyntaxError as ex:
+        LOGGER.warning("Failed to parse SVG data", exc_info=ex)
+        return data, None
+    except SVGParseError as ex:
+        LOGGER.warning("Failed to extract dimensions from SVG data", exc_info=ex)
+        return data, None

md2conf/text.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """