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

md2conf/png.py

@@ -0,0 +1,206 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from io import BytesIO
+from pathlib import Path
+from struct import unpack
+from typing import BinaryIO, Iterable, overload
+
+
+class ImageFormatError(RuntimeError):
+    pass
+
+
+class _Chunk:
+    "Data chunk in binary data as per the PNG image format."
+
+    __slots__ = ("length", "name", "data", "crc")
+
+    length: int
+    name: bytes
+    data: bytes
+    crc: bytes
+
+    def __init__(self, length: int, name: bytes, data: bytes, crc: bytes):
+        self.length = length
+        self.name = name
+        self.data = data
+        self.crc = crc
+
+
+def _read_signature(f: BinaryIO) -> None:
+    "Reads and checks PNG signature (first 8 bytes)."
+
+    signature = f.read(8)
+    if signature != b"\x89PNG\r\n\x1a\n":
+        raise ImageFormatError("not a valid PNG file")
+
+
+def _read_chunk(f: BinaryIO) -> _Chunk | None:
+    "Reads and parses a PNG chunk such as `IHDR` or `tEXt`."
+
+    length_bytes = f.read(4)
+    if not length_bytes:
+        return None
+
+    if len(length_bytes) != 4:
+        raise ImageFormatError("expected: 4 bytes storing chunk length")
+
+    length = int.from_bytes(length_bytes, "big")
+
+    data_length = 4 + length + 4
+    data_bytes = f.read(data_length)
+    actual_length = len(data_bytes)
+    if actual_length != data_length:
+        raise ImageFormatError(f"expected: {length} bytes storing chunk data; got: {actual_length}")
+
+    chunk_type = data_bytes[0:4]
+    chunk_data = data_bytes[4:-4]
+    crc = data_bytes[-4:]
+
+    return _Chunk(length, chunk_type, chunk_data, crc)
+
+
+def _extract_png_dimensions(source_file: BinaryIO) -> tuple[int, int]:
+    """
+    Returns the width and height of a PNG image inspecting its header.
+
+    :param source_file: A binary file opened for reading that contains PNG image data.
+    :returns: A tuple of the image's width and height in pixels.
+    """
+
+    _read_signature(source_file)
+
+    # validate IHDR (Image Header) chunk
+    ihdr = _read_chunk(source_file)
+    if ihdr is None:
+        raise ImageFormatError("missing IHDR chunk")
+
+    if ihdr.length != 13:
+        raise ImageFormatError("invalid chunk length")
+    if ihdr.name != b"IHDR":
+        raise ImageFormatError(f"expected: IHDR chunk; got: {ihdr.name!r}")
+
+    (
+        width,
+        height,
+        bit_depth,  # pyright: ignore[reportUnusedVariable]
+        color_type,  # pyright: ignore[reportUnusedVariable]
+        compression,  # pyright: ignore[reportUnusedVariable]
+        filter,  # pyright: ignore[reportUnusedVariable]
+        interlace,  # pyright: ignore[reportUnusedVariable]
+    ) = unpack(">IIBBBBB", ihdr.data)  # spellchecker:disable-line
+    return width, height
+
+
+@overload
+def extract_png_dimensions(*, data: bytes) -> tuple[int, int]: ...
+
+
+@overload
+def extract_png_dimensions(*, path: str | Path) -> tuple[int, int]: ...
+
+
+def extract_png_dimensions(*, data: bytes | None = None, path: str | Path | None = None) -> tuple[int, int]:
+    """
+    Returns the width and height of a PNG image inspecting its header.
+
+    :param data: PNG image data.
+    :param path: Path to the PNG image file.
+    :returns: A tuple of the image's width and height in pixels.
+    """
+
+    if data is not None and path is not None:
+        raise TypeError("expected: either `data` or `path`; got: both")
+    elif data is not None:
+        with BytesIO(data) as f:
+            return _extract_png_dimensions(f)
+    elif path is not None:
+        with open(path, "rb") as f:
+            return _extract_png_dimensions(f)
+    else:
+        raise TypeError("expected: either `data` or `path`; got: neither")
+
+
+def _write_chunk(f: BinaryIO, chunk: _Chunk) -> None:
+    f.write(chunk.length.to_bytes(4, "big"))
+    f.write(chunk.name)
+    f.write(chunk.data)
+    f.write(chunk.crc)
+
+
+def _remove_png_chunks(names: Iterable[str], source_file: BinaryIO, target_file: BinaryIO) -> None:
+    """
+    Rewrites a PNG file by removing chunks with the specified names.
+
+    :param source_file: A binary file opened for reading that contains PNG image data.
+    :param target_file: A binary file opened for writing to receive PNG image data.
+    """
+
+    exclude_set = set(name.encode("ascii") for name in names)
+
+    _read_signature(source_file)
+    target_file.write(b"\x89PNG\r\n\x1a\n")
+
+    while True:
+        chunk = _read_chunk(source_file)
+        if chunk is None:
+            break
+
+        if chunk.name not in exclude_set:
+            _write_chunk(target_file, chunk)
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_data: bytes) -> bytes: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_path: str | Path) -> bytes: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_data: bytes, target_path: str | Path) -> None: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_path: str | Path, target_path: str | Path) -> None: ...
+
+
+def remove_png_chunks(
+    names: Iterable[str], *, source_data: bytes | None = None, source_path: str | Path | None = None, target_path: str | Path | None = None
+) -> bytes | None:
+    """
+    Rewrites a PNG file by removing chunks with the specified names.
+
+    :param source_data: PNG image data.
+    :param source_path: Path to the file to read from.
+    :param target_path: Path to the file to write to.
+    """
+
+    if source_data is not None and source_path is not None:
+        raise TypeError("expected: either `source_data` or `source_path`; got: both")
+    elif source_data is not None:
+
+        def source_reader() -> BinaryIO:
+            return BytesIO(source_data)
+    elif source_path is not None:
+
+        def source_reader() -> BinaryIO:
+            return open(source_path, "rb")
+    else:
+        raise TypeError("expected: either `source_data` or `source_path`; got: neither")
+
+    if target_path is None:
+        with source_reader() as source_file, BytesIO() as memory_file:
+            _remove_png_chunks(names, source_file, memory_file)
+            return memory_file.getvalue()
+    else:
+        with source_reader() as source_file, open(target_path, "wb") as target_file:
+            _remove_png_chunks(names, source_file, target_file)
+            return None

md2conf/processor.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
 """
@@ -15,16 +15,19 @@ from typing import Iterable
 
 from .collection import ConfluencePageCollection
 from .converter import ConfluenceDocument
-from .domain import ConfluenceDocumentOptions, ConfluencePageID
-from .environment import ArgumentError
+from .environment import ArgumentError, PageError
 from .matcher import DirectoryEntry, FileEntry, Matcher, MatcherOptions
 from .metadata import ConfluenceSiteMetadata
+from .options import ConfluencePageID, DocumentOptions
 from .scanner import Scanner
+from .toc import unique_title
 
 LOGGER = logging.getLogger(__name__)
 
 
 class DocumentNode:
+    "Represents a Markdown document in a hierarchy."
+
     absolute_path: Path
     page_id: str | None
     space_key: str | None
@@ -49,24 +52,42 @@ class DocumentNode:
         self._children = []
 
     def count(self) -> int:
+        "Number of descendants in the sub-tree spanned by this node (excluding the top-level node)."
+
         c = len(self._children)
         for child in self._children:
             c += child.count()
         return c
 
     def add_child(self, child: "DocumentNode") -> None:
+        "Adds a new node to the list of direct children."
+
         self._children.append(child)
 
     def children(self) -> Iterable["DocumentNode"]:
+        "Direct children of this node."
+
         for child in self._children:
             yield child
 
     def descendants(self) -> Iterable["DocumentNode"]:
+        """
+        Descendants of this node, part of its sub-tree.
+
+        Traversal follows depth-first search.
+        """
+
         for child in self._children:
             yield child
             yield from child.descendants()
 
     def all(self) -> Iterable["DocumentNode"]:
+        """
+        Descendants of this node, part of the sub-tree including the top-level node.
+
+        Traversal follows depth-first search.
+        """
+
         yield self
         for child in self._children:
             yield from child.all()
@@ -77,7 +98,7 @@ class Processor:
     Processes a single Markdown page or a directory of Markdown pages.
     """
 
-    options: ConfluenceDocumentOptions
+    options: DocumentOptions
     site: ConfluenceSiteMetadata
     root_dir: Path
 
@@ -85,7 +106,7 @@ class Processor:
 
     def __init__(
         self,
-        options: ConfluenceDocumentOptions,
+        options: DocumentOptions,
         site: ConfluenceSiteMetadata,
         root_dir: Path,
     ) -> None:
@@ -123,6 +144,22 @@ class Processor:
         Processes a sub-tree rooted at an ancestor node.
         """
 
+        # verify if pages have a unique title to avoid overwrites within synchronized set
+        title_to_path: dict[str, Path] = {}
+        duplicates: set[Path] = set()
+        for node in root.all():
+            if node.title is not None:
+                path = title_to_path.get(node.title)
+                if path is not None:
+                    duplicates.add(path)
+                    duplicates.add(node.absolute_path)
+                else:
+                    title_to_path[node.title] = node.absolute_path
+        if duplicates:
+            raise PageError(
+                f"expected: each synchronized page to have a unique title but duplicates found in files: {', '.join(str(p) for p in sorted(list(duplicates)))}"
+            )
+
         # synchronize directory tree structure with page hierarchy in space (find matching pages in Confluence)
         self._synchronize_tree(root, self.options.root_page_id)
 
@@ -140,7 +177,7 @@ class Processor:
         self._update_page(page_id, document, path)
 
     @abstractmethod
-    def _synchronize_tree(self, root: DocumentNode, root_id: ConfluencePageID | None) -> None:
+    def _synchronize_tree(self, tree: DocumentNode, root_id: ConfluencePageID | None) -> None:
         """
         Creates the cross-reference index and synchronizes the directory tree structure with the Confluence page hierarchy.
 
@@ -226,14 +263,19 @@ class Processor:
         LOGGER.info("Indexing file: %s", path)
 
         # extract information from a Markdown document found in a local directory.
-        document = Scanner().read(path)
+        with open(path, "r", encoding="utf-8") as f:
+            text = f.read()
+
+        document = Scanner().parse(text)
+        props = document.properties
+        title = props.title or unique_title(text)
 
         return DocumentNode(
             absolute_path=path,
-            page_id=document.page_id,
-            space_key=document.space_key,
-            title=document.title,
-            synchronized=document.synchronized if document.synchronized is not None else True,
+            page_id=props.page_id,
+            space_key=props.space_key,
+            title=title,
+            synchronized=props.synchronized if props.synchronized is not None else True,
         )
 
     def _generate_hash(self, absolute_path: Path) -> str:
@@ -247,10 +289,10 @@ class Processor:
 
 
 class ProcessorFactory:
-    options: ConfluenceDocumentOptions
+    options: DocumentOptions
     site: ConfluenceSiteMetadata
 
-    def __init__(self, options: ConfluenceDocumentOptions, site: ConfluenceSiteMetadata) -> None:
+    def __init__(self, options: DocumentOptions, site: ConfluenceSiteMetadata) -> None:
         self.options = options
         self.site = site
 

md2conf/publisher.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,18 +10,78 @@ import logging
 from pathlib import Path
 
 from .api import ConfluenceContentProperty, ConfluenceLabel, ConfluenceSession, ConfluenceStatus
-from .converter import ConfluenceDocument, attachment_name, get_volatile_attributes, get_volatile_elements
+from .attachment import attachment_name
+from .compatibility import override, path_relative_to
+from .converter import ConfluenceDocument, get_volatile_attributes, get_volatile_elements
 from .csf import AC_ATTR, elements_from_string
-from .domain import ConfluenceDocumentOptions, ConfluencePageID
 from .environment import PageError
-from .extra import override, path_relative_to
 from .metadata import ConfluencePageMetadata
+from .options import ConfluencePageID, DocumentOptions
 from .processor import Converter, DocumentNode, Processor, ProcessorFactory
 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.
@@ -29,7 +89,7 @@ class SynchronizingProcessor(Processor):
 
     api: ConfluenceSession
 
-    def __init__(self, api: ConfluenceSession, options: ConfluenceDocumentOptions, root_dir: Path) -> None:
+    def __init__(self, api: ConfluenceSession, options: DocumentOptions, root_dir: Path) -> None:
         """
         Initializes a new processor instance.
 
@@ -42,7 +102,7 @@ class SynchronizingProcessor(Processor):
         self.api = api
 
     @override
-    def _synchronize_tree(self, root: DocumentNode, root_id: ConfluencePageID | None) -> None:
+    def _synchronize_tree(self, tree: DocumentNode, root_id: ConfluencePageID | None) -> None:
         """
         Creates the cross-reference index and synchronizes the directory tree structure with the Confluence page hierarchy.
 
@@ -51,26 +111,25 @@ class SynchronizingProcessor(Processor):
         Updates the original Markdown document to add tags to associate the document with its corresponding Confluence page.
         """
 
-        if root.page_id is None and root_id is None:
-            raise PageError(f"expected: root page ID in options, or explicit page ID in {root.absolute_path}")
-        elif root.page_id is not None and root_id is not None:
-            if root.page_id != root_id.page_id:
-                raise PageError(f"mismatched inferred page ID of {root_id.page_id} and explicit page ID in {root.absolute_path}")
-
-            real_id = root_id
+        if tree.page_id is None and root_id is None:
+            raise PageError(f"expected: root page ID in options, or explicit page ID in {tree.absolute_path}")
+        elif tree.page_id is not None:
+            real_id = ConfluencePageID(tree.page_id)  # explicit page ID takes precedence
         elif root_id is not None:
             real_id = root_id
-        elif root.page_id is not None:
-            real_id = ConfluencePageID(root.page_id)
         else:
-            raise NotImplementedError("condition not exhaustive")
+            raise NotImplementedError("condition not exhaustive for synchronizing tree")
 
-        self._synchronize_subtree(root, 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:
@@ -81,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,
@@ -110,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:
@@ -140,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)
@@ -183,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.
@@ -212,7 +300,7 @@ class SynchronizingProcessor(Processor):
 class SynchronizingProcessorFactory(ProcessorFactory):
     api: ConfluenceSession
 
-    def __init__(self, api: ConfluenceSession, options: ConfluenceDocumentOptions) -> None:
+    def __init__(self, api: ConfluenceSession, options: DocumentOptions) -> None:
         super().__init__(options, api.site)
         self.api = api
 
@@ -227,5 +315,5 @@ class Publisher(Converter):
     This is the class instantiated by the command-line application.
     """
 
-    def __init__(self, api: ConfluenceSession, options: ConfluenceDocumentOptions) -> None:
+    def __init__(self, api: ConfluenceSession, options: DocumentOptions) -> None:
         super().__init__(SynchronizingProcessorFactory(api, options))