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

md2conf/publisher.py

@@ -23,6 +23,65 @@ from .xml import is_xml_equal, unwrap_substitute
 LOGGER = logging.getLogger(__name__)
 
 
+class _MissingType:
+    pass
+
+
+_MissingDefault = _MissingType()
+
+
+class ParentCatalog:
+    "Maintains a catalog of child-parent relationships."
+
+    _api: ConfluenceSession
+    _child_to_parent: dict[str, str | None]
+    _known: set[str]
+
+    def __init__(self, api: ConfluenceSession) -> None:
+        self._api = api
+        self._child_to_parent = {}
+        self._known = set()
+
+    def add_known(self, page_id: str) -> None:
+        """
+        Adds a new well-known page such as the root page or a page paired with a Markdown file using an explicit page ID.
+        """
+
+        self._known.add(page_id)
+
+    def add_parent(self, *, page_id: str, parent_id: str | None) -> None:
+        """
+        Adds a new child-parent relationship.
+
+        This method is useful to persist information acquired by a previous API call.
+        """
+
+        self._child_to_parent[page_id] = parent_id
+
+    def is_traceable(self, page_id: str) -> bool:
+        """
+        Verifies if a page traces back to a well-known root page.
+
+        :param page_id: The page to check.
+        """
+
+        if page_id in self._known:
+            return True
+
+        known_parent_id = self._child_to_parent.get(page_id, _MissingDefault)
+        if not isinstance(known_parent_id, _MissingType):
+            parent_id = known_parent_id
+        else:
+            page = self._api.get_page_properties(page_id)
+            parent_id = page.parentId
+            self._child_to_parent[page_id] = parent_id
+
+        if parent_id is None:
+            return False
+
+        return self.is_traceable(parent_id)
+
+
 class SynchronizingProcessor(Processor):
     """
     Synchronizes a single Markdown page or a directory of Markdown pages with Confluence.
@@ -59,14 +118,18 @@ class SynchronizingProcessor(Processor):
         elif root_id is not None:
             real_id = root_id
         else:
-            raise NotImplementedError("condition not exhaustive")
+            raise NotImplementedError("condition not exhaustive for synchronizing tree")
 
-        self._synchronize_subtree(tree, real_id)
+        catalog = ParentCatalog(self.api)
+        catalog.add_known(real_id.page_id)
+        self._synchronize_subtree(tree, real_id, catalog)
 
-    def _synchronize_subtree(self, node: DocumentNode, parent_id: ConfluencePageID) -> None:
+    def _synchronize_subtree(self, node: DocumentNode, parent_id: ConfluencePageID, catalog: ParentCatalog) -> None:
         if node.page_id is not None:
             # verify if page exists
             page = self.api.get_page_properties(node.page_id)
+            catalog.add_known(page.id)
+            catalog.add_parent(page_id=page.id, parent_id=page.parentId)
             update = False
         else:
             if node.title is not None:
@@ -77,20 +140,26 @@ class SynchronizingProcessor(Processor):
                 digest = self._generate_hash(node.absolute_path)
                 title = f"{node.absolute_path.stem} [{digest}]"
 
-            if self.options.title_prefix is not None:
-                title = f"{self.options.title_prefix} {title}"
+            title = self._get_extended_title(title)
 
             # look up page by (possibly auto-generated) title
             page = self.api.get_or_create_page(title, parent_id.page_id)
+            catalog.add_parent(page_id=page.id, parent_id=page.parentId)
 
             if page.status is ConfluenceStatus.ARCHIVED:
-                # user has archived a page with this (auto-generated) title
-                raise PageError(f"unable to update archived page with ID {page.id}")
+                # user has archived a page with this (possibly auto-generated) title
+                raise PageError(f"unable to update archived page with ID {page.id} when synchronizing {node.absolute_path}")
+
+            if not catalog.is_traceable(page.id):
+                raise PageError(
+                    f"expected: page with ID {page.id} to be a descendant of the root page or one of the pages paired with a Markdown file using an explicit "
+                    f"page ID when synchronizing {node.absolute_path}"
+                )
 
             update = True
 
         space_key = self.api.space_id_to_key(page.spaceId)
-        if update:
+        if update and not self.options.skip_update:
             self._update_markdown(
                 node.absolute_path,
                 page_id=page.id,
@@ -106,7 +175,7 @@ class SynchronizingProcessor(Processor):
         self.page_metadata.add(node.absolute_path, data)
 
         for child_node in node.children():
-            self._synchronize_subtree(child_node, ConfluencePageID(page.id))
+            self._synchronize_subtree(child_node, ConfluencePageID(page.id), catalog)
 
     @override
     def _update_page(self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path) -> None:
@@ -136,19 +205,7 @@ class SynchronizingProcessor(Processor):
         content = document.xhtml()
         LOGGER.debug("Generated Confluence Storage Format document:\n%s", content)
 
-        title = None
-        if document.title is not None:
-            meta = self.page_metadata.get(path)
-            if meta is not None and meta.title != document.title:
-                conflicting_page_id = self.api.page_exists(document.title, space_id=self.api.space_key_to_id(meta.space_key))
-                if conflicting_page_id is None:
-                    title = document.title
-                else:
-                    LOGGER.info(
-                        "Document title of %s conflicts with Confluence page title of %s",
-                        path,
-                        conflicting_page_id,
-                    )
+        title = self._get_unique_title(document, path)
 
         # fetch existing page
         page = self.api.get_page(page_id.page_id)
@@ -179,6 +236,41 @@ class SynchronizingProcessor(Processor):
         if document.properties is not None:
             self.api.update_content_properties_for_page(page_id.page_id, [ConfluenceContentProperty(key, value) for key, value in document.properties.items()])
 
+    def _get_extended_title(self, title: str) -> str:
+        """
+        Returns a title with the title prefix applied (if any).
+        """
+
+        if self.options.title_prefix is not None:
+            return f"{self.options.title_prefix} {title}"
+        else:
+            return title
+
+    def _get_unique_title(self, document: ConfluenceDocument, path: Path) -> str | None:
+        """
+        Determines the (new) document title to assign to the Confluence page.
+
+        Ensures that the title is unique across the Confluence space.
+        """
+
+        # document has no title (neither in front-matter nor as unique top-level heading)
+        if document.title is None:
+            return None
+
+        # add configured title prefix
+        title = self._get_extended_title(document.title)
+
+        # compare current document title with title discovered during directory traversal
+        meta = self.page_metadata.get(path)
+        if meta is not None and meta.title != title:
+            # title has changed, check if new title is available
+            page_id = self.api.page_exists(title, space_id=self.api.space_key_to_id(meta.space_key))
+            if page_id is not None:
+                LOGGER.info("Unrelated Confluence page with ID %s has the same inferred title as the Markdown file: %s", page_id, path)
+                return None
+
+        return title
+
     def _update_markdown(self, path: Path, *, page_id: str, space_key: str) -> None:
         """
         Writes the Confluence page ID and space key at the beginning of the Markdown file.

md2conf/scanner.py

@@ -75,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)
 

md2conf/svg.py

@@ -9,6 +9,7 @@ Copyright 2022-2026, 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_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:
-        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
+        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.
-    """
 
-    try:
-        root = ET.fromstring(data)
-        return _extract_dimensions_from_root(root)
+    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 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,32 +308,32 @@ 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(image_data: bytes) -> tuple[bytes, int | None, int | 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.
 
@@ -328,14 +342,19 @@ def fix_svg_get_dimensions(image_data: bytes) -> tuple[bytes, int | None, int |
     1. fixes SVG dimensions (converts percentage-based to explicit pixels), and
     2. extracts width/height from the SVG.
 
-    :param image_data: Raw SVG data as bytes.
+    :param data: Raw SVG data as bytes.
     :returns: Tuple of update raw data, image width, image height.
     """
 
-    # fix SVG to have explicit width/height instead of percentages
-    image_data = fix_svg_dimensions(image_data)
-
-    # extract dimensions from the fixed SVG
-    width, height = get_svg_dimensions_from_bytes(image_data)
+    try:
+        # fix SVG to have explicit width/height instead of percentages
+        data = fix_svg_dimensions(data)
 
-    return image_data, width, height
+        # 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/toc.py

@@ -6,7 +6,9 @@ Copyright 2022-2026, Levente Hunyadi
 :see: https://github.com/hunyadi/md2conf
 """
 
+import re
 from dataclasses import dataclass
+from typing import Iterable, Iterator
 
 
 @dataclass(eq=True)
@@ -86,3 +88,73 @@ class TableOfContentsBuilder:
             return self.tree[0].text
         else:
             return None
+
+
+_FENCED_CODE_REGEXP = re.compile(r"^\s*(?:`{3,}|~{3,})", re.MULTILINE)
+_ATX_HEADING_REGEXP = re.compile(r"^(#{1,6})\s+(.*?)$", re.MULTILINE)
+_SETEXT_HEADING_REGEXP = re.compile(r"^(=+|-+)\s*?$", re.MULTILINE)
+
+
+def headings(lines: Iterable[str]) -> Iterator[tuple[int, str]]:
+    fence_marker: str | None = None
+    heading_text: str | None = None
+
+    for line in lines:
+        # fenced code blocks
+        fence_match = _FENCED_CODE_REGEXP.match(line)
+        if fence_match:
+            marker = fence_match.group()
+            if fence_marker is None:
+                fence_marker = marker
+            elif marker == fence_marker:
+                fence_marker = None
+            heading_text = None
+            continue
+
+        if fence_marker is not None:
+            heading_text = None
+            continue
+
+        # ATX headings
+        atx = _ATX_HEADING_REGEXP.match(line)
+        if atx is not None:
+            level = len(atx.group(1))
+            title = atx.group(2).rstrip().rstrip("#").rstrip()  # remove decorative text: `## Section 1.2 ##`
+            yield level, title
+
+            heading_text = None
+            continue
+
+        # Setext headings
+        setext = _SETEXT_HEADING_REGEXP.match(line)
+        if setext is not None and heading_text is not None:
+            match setext.group(1)[0:1]:
+                case "=":
+                    level = 1
+                case "-":
+                    level = 2
+                case _:
+                    level = 0
+            yield level, heading_text.rstrip()
+
+            heading_text = None
+            continue
+
+        # candidate for Setext title
+        heading_text = line
+
+
+def unique_title(content: str) -> str | None:
+    """
+    Returns a proposed document title.
+
+    The proposed title is text of the top-level heading if and only if that heading is unique.
+
+    :returns: Title text, or `None` if no title can be inferred.
+    """
+
+    builder = TableOfContentsBuilder()
+    for heading in headings(content.splitlines(keepends=True)):
+        level, text = heading
+        builder.add(level, text)
+    return builder.get_title()