markdown-to-confluence 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

md2conf/application.py

@@ -6,8 +6,8 @@ Copyright 2022-2025, Levente Hunyadi
 :see: https://github.com/hunyadi/md2conf
 """
 
+import hashlib
 import logging
-import os.path
 from pathlib import Path
 from typing import Optional
 
@@ -15,155 +15,43 @@ from .api import ConfluencePage, ConfluenceSession
 from .converter import (
     ConfluenceDocument,
     ConfluenceDocumentOptions,
-    ConfluencePageMetadata,
-    ConfluenceQualifiedID,
+    ConfluencePageID,
     attachment_name,
     extract_frontmatter_title,
     extract_qualified_id,
-    read_qualified_id,
 )
-from .matcher import Matcher, MatcherOptions
+from .metadata import ConfluencePageMetadata
+from .processor import Converter, Processor, ProcessorFactory
+from .properties import PageError
 
 LOGGER = logging.getLogger(__name__)
 
 
-class Application:
-    "The entry point for Markdown to Confluence conversion."
+class SynchronizingProcessor(Processor):
+    """
+    Synchronizes a single Markdown page or a directory of Markdown pages with Confluence.
+    """
 
     api: ConfluenceSession
-    options: ConfluenceDocumentOptions
 
     def __init__(
-        self, api: ConfluenceSession, options: ConfluenceDocumentOptions
-    ) -> None:
-        self.api = api
-        self.options = options
-
-    def synchronize(self, path: Path) -> None:
-        "Synchronizes a single Markdown page or a directory of Markdown pages."
-
-        path = path.resolve(True)
-        if path.is_dir():
-            self.synchronize_directory(path)
-        elif path.is_file():
-            self.synchronize_page(path)
-        else:
-            raise ValueError(f"expected: valid file or directory path; got: {path}")
-
-    def synchronize_page(
-        self, page_path: Path, root_dir: Optional[Path] = None
-    ) -> None:
-        "Synchronizes a single Markdown page with Confluence."
-
-        page_path = page_path.resolve(True)
-        if root_dir is None:
-            root_dir = page_path.parent
-        else:
-            root_dir = root_dir.resolve(True)
-
-        self._synchronize_page(page_path, root_dir, {})
-
-    def synchronize_directory(
-        self, local_dir: Path, root_dir: Optional[Path] = None
-    ) -> None:
-        "Synchronizes a directory of Markdown pages with Confluence."
-
-        local_dir = local_dir.resolve(True)
-        if root_dir is None:
-            root_dir = local_dir
-        else:
-            root_dir = root_dir.resolve(True)
-
-        LOGGER.info("Synchronizing directory: %s", local_dir)
-
-        # Step 1: build index of all page metadata
-        page_metadata: dict[Path, ConfluencePageMetadata] = {}
-        root_id = (
-            ConfluenceQualifiedID(self.options.root_page_id, self.api.space_key)
-            if self.options.root_page_id
-            else None
-        )
-        self._index_directory(local_dir, root_id, page_metadata)
-        LOGGER.info("Indexed %d page(s)", len(page_metadata))
-
-        # Step 2: convert each page
-        for page_path in page_metadata.keys():
-            self._synchronize_page(page_path, root_dir, page_metadata)
-
-    def _synchronize_page(
-        self,
-        page_path: Path,
-        root_dir: Path,
-        page_metadata: dict[Path, ConfluencePageMetadata],
+        self, api: ConfluenceSession, options: ConfluenceDocumentOptions, root_dir: Path
     ) -> None:
-        base_path = page_path.parent
-
-        LOGGER.info("Synchronizing page: %s", page_path)
-        document = ConfluenceDocument(page_path, self.options, root_dir, page_metadata)
-        self._update_document(document, base_path)
-
-    def _index_directory(
-        self,
-        local_dir: Path,
-        root_id: Optional[ConfluenceQualifiedID],
-        page_metadata: dict[Path, ConfluencePageMetadata],
-    ) -> None:
-        "Indexes Markdown files in a directory recursively."
-
-        LOGGER.info("Indexing directory: %s", local_dir)
-
-        matcher = Matcher(MatcherOptions(source=".mdignore", extension="md"), local_dir)
-
-        files: list[Path] = []
-        directories: list[Path] = []
-        for entry in os.scandir(local_dir):
-            if matcher.is_excluded(entry.name, entry.is_dir()):
-                continue
-
-            if entry.is_file():
-                files.append(Path(local_dir) / entry.name)
-            elif entry.is_dir():
-                directories.append(Path(local_dir) / entry.name)
-
-        # make page act as parent node in Confluence
-        parent_doc: Optional[Path] = None
-        if (Path(local_dir) / "index.md") in files:
-            parent_doc = Path(local_dir) / "index.md"
-        elif (Path(local_dir) / "README.md") in files:
-            parent_doc = Path(local_dir) / "README.md"
-        elif (Path(local_dir) / f"{local_dir.name}.md") in files:
-            parent_doc = Path(local_dir) / f"{local_dir.name}.md"
-
-        if parent_doc is None and self.options.keep_hierarchy:
-            parent_doc = Path(local_dir) / "index.md"
-
-            # create a blank page in Confluence for the directory entry
-            with open(parent_doc, "w"):
-                pass
-
-        if parent_doc is not None:
-            files.remove(parent_doc)
-
-            metadata = self._get_or_create_page(parent_doc, root_id)
-            LOGGER.debug("Indexed parent %s with metadata: %s", parent_doc, metadata)
-            page_metadata[parent_doc] = metadata
-
-            parent_id = read_qualified_id(parent_doc) or root_id
-        else:
-            parent_id = root_id
+        """
+        Initializes a new processor instance.
 
-        for doc in files:
-            metadata = self._get_or_create_page(doc, parent_id)
-            LOGGER.debug("Indexed %s with metadata: %s", doc, metadata)
-            page_metadata[doc] = metadata
+        :param api: Holds information about an open session to a Confluence server.
+        :param options: Options that control the generated page content.
+        :param root_dir: File system directory that acts as topmost root node.
+        """
 
-        for directory in directories:
-            self._index_directory(directory, parent_id, page_metadata)
+        super().__init__(options, api.site, root_dir)
+        self.api = api
 
     def _get_or_create_page(
         self,
         absolute_path: Path,
-        parent_id: Optional[ConfluenceQualifiedID],
+        parent_id: Optional[ConfluencePageID],
         *,
         title: Optional[str] = None,
     ) -> ConfluencePageMetadata:
@@ -173,54 +61,60 @@ class Application:
 
         # parse file
         with open(absolute_path, "r", encoding="utf-8") as f:
-            document = f.read()
+            text = f.read()
 
-        qualified_id, document = extract_qualified_id(document)
-        frontmatter_title, _ = extract_frontmatter_title(document)
+        qualified_id, text = extract_qualified_id(text)
 
-        if qualified_id is not None:
-            confluence_page = self.api.get_page(qualified_id.page_id)
-        else:
+        overwrite = False
+        if qualified_id is None:
+            # create new Confluence page
             if parent_id is None:
-                raise ValueError(
+                raise PageError(
                     f"expected: parent page ID for Markdown file with no linked Confluence page: {absolute_path}"
                 )
 
-            # assign title from frontmatter if present
-            confluence_page = self._create_page(
-                absolute_path, document, title or frontmatter_title, parent_id
-            )
+            # assign title from front-matter if present
+            if title is None:
+                title, _ = extract_frontmatter_title(text)
+
+            # use file name (without extension) and path hash if no title is supplied
+            if title is None:
+                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, text, title, parent_id)
+        else:
+            # look up existing Confluence page
+            confluence_page = self.api.get_page(qualified_id.page_id)
 
         space_key = (
             self.api.space_id_to_key(confluence_page.space_id)
             if confluence_page.space_id
-            else self.api.space_key
+            else self.site.space_key
         )
 
         return ConfluencePageMetadata(
-            domain=self.api.domain,
-            base_path=self.api.base_path,
             page_id=confluence_page.id,
             space_key=space_key,
-            title=confluence_page.title or "",
+            title=confluence_page.title,
+            overwrite=overwrite,
         )
 
     def _create_page(
         self,
         absolute_path: Path,
         document: str,
-        title: Optional[str],
-        parent_id: ConfluenceQualifiedID,
+        title: str,
+        parent_id: ConfluencePageID,
     ) -> ConfluencePage:
-        "Creates a new Confluence page when Markdown file doesn't have an embedded page ID yet."
-
-        # use file name without extension if no title is supplied
-        if title is None:
-            title = absolute_path.stem
+        """
+        Creates a new Confluence page when Markdown file doesn't have an embedded page ID yet.
+        """
 
-        confluence_page = self.api.get_or_create_page(
-            title, parent_id.page_id, space_key=parent_id.space_key
-        )
+        confluence_page = self.api.get_or_create_page(title, parent_id.page_id)
         self._update_markdown(
             absolute_path,
             document,
@@ -229,9 +123,14 @@ class Application:
         )
         return confluence_page
 
-    def _update_document(self, document: ConfluenceDocument, base_path: Path) -> None:
-        "Saves a new version of a Confluence document."
+    def _save_document(self, document: ConfluenceDocument, path: Path) -> None:
+        """
+        Saves a new version of a Confluence document.
+
+        Invokes Confluence REST API to persist the new version.
+        """
 
+        base_path = path.parent
         for image in document.images:
             self.api.upload_attachment(
                 document.id.page_id,
@@ -247,8 +146,12 @@ class Application:
             )
 
         content = document.xhtml()
+
+        # leave title as it is for existing pages, update title for pages with randomly assigned title
+        title = document.title if self.page_metadata[path].overwrite else None
+
         LOGGER.debug("Generated Confluence Storage Format document:\n%s", content)
-        self.api.update_page(document.id.page_id, content, title=document.title)
+        self.api.update_page(document.id.page_id, content, title=title)
 
     def _update_markdown(
         self,
@@ -257,7 +160,9 @@ class Application:
         page_id: str,
         space_key: Optional[str],
     ) -> None:
-        "Writes the Confluence page ID and space key at the beginning of the Markdown file."
+        """
+        Writes the Confluence page ID and space key at the beginning of the Markdown file.
+        """
 
         content: list[str] = []
 
@@ -277,3 +182,27 @@ class Application:
 
         with open(path, "w", encoding="utf-8") as file:
             file.write("\n".join(content))
+
+
+class SynchronizingProcessorFactory(ProcessorFactory):
+    api: ConfluenceSession
+
+    def __init__(
+        self, api: ConfluenceSession, options: ConfluenceDocumentOptions
+    ) -> None:
+        super().__init__(options, api.site)
+        self.api = api
+
+    def create(self, root_dir: Path) -> Processor:
+        return SynchronizingProcessor(self.api, self.options, root_dir)
+
+
+class Application(Converter):
+    """
+    The entry point for Markdown to Confluence conversion.
+    """
+
+    def __init__(
+        self, api: ConfluenceSession, options: ConfluenceDocumentOptions
+    ) -> None:
+        super().__init__(SynchronizingProcessorFactory(api, options))