markdown-to-confluence 0.3.5__py3-none-any.whl → 0.4.1__py3-none-any.whl

md2conf/application.py

@@ -6,22 +6,16 @@ Copyright 2022-2025, Levente Hunyadi
 :see: https://github.com/hunyadi/md2conf
 """
 
-import hashlib
 import logging
 from pathlib import Path
 from typing import Optional
 
-from .api import ConfluencePage, ConfluenceSession
-from .converter import (
-    ConfluenceDocument,
-    ConfluenceDocumentOptions,
-    ConfluencePageID,
-    attachment_name,
-)
+from .api import ConfluenceContentProperty, ConfluenceLabel, ConfluenceSession, ConfluenceStatus
+from .converter import ConfluenceDocument, ConfluenceDocumentOptions, ConfluencePageID, attachment_name
+from .extra import override, path_relative_to
 from .metadata import ConfluencePageMetadata
-from .processor import Converter, Processor, ProcessorFactory
+from .processor import Converter, DocumentNode, Processor, ProcessorFactory
 from .properties import PageError
-from .scanner import Scanner
 
 LOGGER = logging.getLogger(__name__)
 
@@ -33,9 +27,7 @@ class SynchronizingProcessor(Processor):
 
     api: ConfluenceSession
 
-    def __init__(
-        self, api: ConfluenceSession, options: ConfluenceDocumentOptions, root_dir: Path
-    ) -> None:
+    def __init__(self, api: ConfluenceSession, options: ConfluenceDocumentOptions, root_dir: Path) -> None:
         """
         Initializes a new processor instance.
 
@@ -47,71 +39,72 @@ class SynchronizingProcessor(Processor):
         super().__init__(options, api.site, root_dir)
         self.api = api
 
-    def _get_or_create_page(
-        self, absolute_path: Path, parent_id: Optional[ConfluencePageID]
-    ) -> ConfluencePageMetadata:
+    @override
+    def _synchronize_tree(self, root: DocumentNode, root_id: Optional[ConfluencePageID]) -> None:
         """
-        Creates a new Confluence page if no page is linked in the Markdown document.
+        Creates the cross-reference index and synchronizes the directory tree structure with the Confluence page hierarchy.
+
+        Creates new Confluence pages as necessary, e.g. if no page is linked in the Markdown document, or no page is found with lookup by page title.
+
+        Updates the original Markdown document to add tags to associate the document with its corresponding Confluence page.
         """
 
-        # parse file
-        document = Scanner().read(absolute_path)
-
-        overwrite = False
-        if document.page_id is None:
-            # create new Confluence page
-            if parent_id is None:
-                raise PageError(
-                    f"expected: parent page ID for Markdown file with no linked Confluence page: {absolute_path}"
-                )
-
-            # use file name (without extension) and path hash if no title is supplied
-            if document.title is not None:
-                title = document.title
-            else:
-                overwrite = True
-                relative_path = absolute_path.relative_to(self.root_dir)
-                hash = hashlib.md5(relative_path.as_posix().encode("utf-8"))
-                digest = "".join(f"{c:x}" for c in hash.digest())
-                title = f"{absolute_path.stem} [{digest}]"
-
-            confluence_page = self._create_page(
-                absolute_path, document.text, title, parent_id
-            )
+        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
+        elif root_id is not None:
+            real_id = root_id
+        elif root.page_id is not None:
+            real_id = ConfluencePageID(root.page_id)
         else:
-            # look up existing Confluence page
-            confluence_page = self.api.get_page(document.page_id)
-
-        return ConfluencePageMetadata(
-            page_id=confluence_page.id,
-            space_key=self.api.space_id_to_key(confluence_page.space_id),
-            title=confluence_page.title,
-            overwrite=overwrite,
-        )
+            raise NotImplementedError("condition not exhaustive")
 
-    def _create_page(
-        self,
-        absolute_path: Path,
-        document: str,
-        title: str,
-        parent_id: ConfluencePageID,
-    ) -> ConfluencePage:
-        """
-        Creates a new Confluence page when Markdown file doesn't have an embedded page ID yet.
-        """
+        self._synchronize_subtree(root, real_id)
+
+    def _synchronize_subtree(self, node: DocumentNode, parent_id: ConfluencePageID) -> None:
+        if node.page_id is not None:
+            # verify if page exists
+            page = self.api.get_page_properties(node.page_id)
+            update = False
+        elif node.title is not None:
+            # look up page by title
+            page = self.api.get_or_create_page(node.title, parent_id.page_id)
+
+            if page.status is ConfluenceStatus.ARCHIVED:
+                raise PageError(f"unable to update archived page with ID {page.id}")
 
-        confluence_page = self.api.get_or_create_page(title, parent_id.page_id)
-        self._update_markdown(
-            absolute_path,
-            document,
-            confluence_page.id,
-            self.api.space_id_to_key(confluence_page.space_id),
+            update = True
+        else:
+            # always create a new page
+            digest = self._generate_hash(node.absolute_path)
+            title = f"{node.absolute_path.stem} [{digest}]"
+            page = self.api.create_page(parent_id.page_id, title, "")
+            update = True
+
+        space_key = self.api.space_id_to_key(page.spaceId)
+        if update:
+            self._update_markdown(
+                node.absolute_path,
+                page_id=page.id,
+                space_key=space_key,
+            )
+
+        data = ConfluencePageMetadata(
+            page_id=page.id,
+            space_key=space_key,
+            title=page.title,
         )
-        return confluence_page
+        self.page_metadata.add(node.absolute_path, data)
+
+        for child_node in node.children():
+            self._synchronize_subtree(child_node, ConfluencePageID(page.id))
 
-    def _save_document(
-        self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path
-    ) -> None:
+    @override
+    def _update_page(self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path) -> None:
         """
         Saves a new version of a Confluence document.
 
@@ -119,11 +112,11 @@ class SynchronizingProcessor(Processor):
         """
 
         base_path = path.parent
-        for image in document.images:
+        for image_path in document.images:
             self.api.upload_attachment(
                 page_id.page_id,
-                attachment_name(image),
-                attachment_path=base_path / image,
+                attachment_name(path_relative_to(image_path, base_path)),
+                attachment_path=image_path,
             )
 
         for name, data in document.embedded_images.items():
@@ -138,13 +131,9 @@ class SynchronizingProcessor(Processor):
 
         title = None
         if document.title is not None:
-            meta = self.page_metadata[path]
-
-            # update title only for pages with randomly assigned title
-            if meta.overwrite:
-                conflicting_page_id = self.api.page_exists(
-                    document.title, space_id=self.api.space_key_to_id(meta.space_key)
-                )
+            meta = self.page_metadata.get(path)
+            if meta is not None and meta.space_key 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:
@@ -156,17 +145,23 @@ class SynchronizingProcessor(Processor):
 
         self.api.update_page(page_id.page_id, content, title=title)
 
-    def _update_markdown(
-        self,
-        path: Path,
-        document: str,
-        page_id: str,
-        space_key: Optional[str],
-    ) -> None:
+        if document.labels is not None:
+            self.api.update_labels(
+                page_id.page_id,
+                [ConfluenceLabel(name=label, prefix="global") for label in document.labels],
+            )
+
+        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 _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.
         """
 
+        with open(path, "r", encoding="utf-8") as file:
+            document = file.read()
+
         content: list[str] = []
 
         # check if the file has frontmatter
@@ -178,9 +173,7 @@ class SynchronizingProcessor(Processor):
             content.append(document[:index])
 
         content.append(f"<!-- confluence-page-id: {page_id} -->")
-        if space_key:
-            content.append(f"<!-- confluence-space-key: {space_key} -->")
-
+        content.append(f"<!-- confluence-space-key: {space_key} -->")
         content.append(document[index:])
 
         with open(path, "w", encoding="utf-8") as file:
@@ -190,9 +183,7 @@ class SynchronizingProcessor(Processor):
 class SynchronizingProcessorFactory(ProcessorFactory):
     api: ConfluenceSession
 
-    def __init__(
-        self, api: ConfluenceSession, options: ConfluenceDocumentOptions
-    ) -> None:
+    def __init__(self, api: ConfluenceSession, options: ConfluenceDocumentOptions) -> None:
         super().__init__(options, api.site)
         self.api = api
 
@@ -207,7 +198,5 @@ class Application(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: ConfluenceDocumentOptions) -> None:
         super().__init__(SynchronizingProcessorFactory(api, options))

md2conf/collection.py

@@ -0,0 +1,31 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from pathlib import Path
+from typing import Iterable, Optional
+
+from .metadata import ConfluencePageMetadata
+
+
+class ConfluencePageCollection:
+    _metadata: dict[Path, ConfluencePageMetadata]
+
+    def __init__(self) -> None:
+        self._metadata = {}
+
+    def __len__(self) -> int:
+        return len(self._metadata)
+
+    def add(self, path: Path, data: ConfluencePageMetadata) -> None:
+        self._metadata[path] = data
+
+    def get(self, path: Path) -> Optional[ConfluencePageMetadata]:
+        return self._metadata.get(path)
+
+    def items(self) -> Iterable[tuple[Path, ConfluencePageMetadata]]:
+        return self._metadata.items()