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

md2conf/local.py

@@ -0,0 +1,125 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import hashlib
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+from .converter import ConfluenceDocument, ConfluenceDocumentOptions, ConfluencePageID
+from .metadata import ConfluencePageMetadata, ConfluenceSiteMetadata
+from .processor import Converter, Processor, ProcessorFactory
+from .properties import PageError
+from .scanner import Scanner
+
+LOGGER = logging.getLogger(__name__)
+
+
+class LocalProcessor(Processor):
+    """
+    Transforms a single Markdown page or a directory of Markdown pages into Confluence Storage Format (CSF) documents.
+    """
+
+    def __init__(
+        self,
+        options: ConfluenceDocumentOptions,
+        site: ConfluenceSiteMetadata,
+        *,
+        out_dir: Optional[Path],
+        root_dir: Path,
+    ) -> None:
+        """
+        Initializes a new processor instance.
+
+        :param options: Options that control the generated page content.
+        :param site: Data associated with a Confluence wiki site.
+        :param out_dir: File system directory to write generated CSF documents to.
+        :param root_dir: File system directory that acts as topmost root node.
+        """
+
+        super().__init__(options, site, root_dir)
+        self.out_dir = out_dir or root_dir
+
+    def _get_or_create_page(
+        self, absolute_path: Path, parent_id: Optional[ConfluencePageID]
+    ) -> ConfluencePageMetadata:
+        """
+        Extracts metadata from a Markdown file.
+        """
+
+        # parse file
+        document = Scanner().read(absolute_path)
+        if document.page_id is not None:
+            page_id = document.page_id
+            space_key = document.space_key or self.site.space_key or "HOME"
+        else:
+            if parent_id is None:
+                raise PageError(
+                    f"expected: parent page ID for Markdown file with no linked Confluence page: {absolute_path}"
+                )
+
+            hash = hashlib.md5(document.text.encode("utf-8"))
+            digest = "".join(f"{c:x}" for c in hash.digest())
+            LOGGER.info("Identifier %s assigned to page: %s", digest, absolute_path)
+            page_id = digest
+            space_key = self.site.space_key or "HOME"
+
+        return ConfluencePageMetadata(
+            page_id=page_id,
+            space_key=space_key,
+            title="",
+            overwrite=True,
+        )
+
+    def _save_document(
+        self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path
+    ) -> None:
+        """
+        Saves a new version of a Confluence document.
+
+        A derived class may invoke Confluence REST API to persist the new version.
+        """
+
+        content = document.xhtml()
+        out_path = self.out_dir / path.relative_to(self.root_dir).with_suffix(".csf")
+        os.makedirs(out_path.parent, exist_ok=True)
+        with open(out_path, "w", encoding="utf-8") as f:
+            f.write(content)
+
+
+class LocalProcessorFactory(ProcessorFactory):
+    out_dir: Optional[Path]
+
+    def __init__(
+        self,
+        options: ConfluenceDocumentOptions,
+        site: ConfluenceSiteMetadata,
+        out_dir: Optional[Path] = None,
+    ) -> None:
+        super().__init__(options, site)
+        self.out_dir = out_dir
+
+    def create(self, root_dir: Path) -> Processor:
+        return LocalProcessor(
+            self.options, self.site, out_dir=self.out_dir, root_dir=root_dir
+        )
+
+
+class LocalConverter(Converter):
+    """
+    The entry point for Markdown to Confluence conversion.
+    """
+
+    def __init__(
+        self,
+        options: ConfluenceDocumentOptions,
+        site: ConfluenceSiteMetadata,
+        out_dir: Optional[Path] = None,
+    ) -> None:
+        super().__init__(LocalProcessorFactory(options, site, out_dir))

md2conf/matcher.py

@@ -10,15 +10,15 @@ import os.path
 from dataclasses import dataclass
 from fnmatch import fnmatch
 from pathlib import Path
-from typing import Iterable, Optional
+from typing import Iterable, Optional, Union, overload
 
 
-@dataclass
+@dataclass(frozen=True)
 class Entry:
     """
     Represents a file or directory entry.
 
-    :param name: Name of the file-system entry.
+    :param name: Name of the file-system entry to match against the rule-set.
     :param is_dir: True if the entry is a directory.
     """
 
@@ -43,6 +43,15 @@ class MatcherOptions:
             self.extension = f".{self.extension}"
 
 
+def _entry_name_dir(entry: Union[Entry, os.DirEntry[str]]) -> tuple[str, bool]:
+    if isinstance(entry, Entry):
+        return entry.name, entry.is_dir
+    elif isinstance(entry, os.DirEntry):
+        return entry.name, entry.is_dir()
+    else:
+        raise NotImplementedError("type match not exhaustive")
+
+
 class Matcher:
     "Compares file and directory names against a list of exclude/include patterns."
 
@@ -58,20 +67,40 @@ class Matcher:
         else:
             self.rules = []
 
+        for rule in self.rules:
+            if "/" in rule or os.path.sep in rule:
+                raise ValueError(f"nested matching not supported: {rule}")
+
     def extension_matches(self, name: str) -> bool:
         "True if the file name has the expected extension."
 
         return self.options.extension is None or name.endswith(self.options.extension)
 
-    def is_excluded(self, name: str, is_dir: bool) -> bool:
+    @overload
+    def is_excluded(self, entry: Entry) -> bool:
+        """
+        True if the file or directory name matches any of the exclusion patterns.
+
+        :param entry: A data-class object.
+        :returns: True if the name matches at least one of the exclusion patterns.
+        """
+
+        ...
+
+    @overload
+    def is_excluded(self, entry: os.DirEntry[str]) -> bool:
         """
         True if the file or directory name matches any of the exclusion patterns.
 
-        :param name: Name to match against the rule-set.
-        :param is_dir: Whether the name identifies a directory.
+        :param entry: An object returned by `scandir`.
         :returns: True if the name matches at least one of the exclusion patterns.
         """
 
+        ...
+
+    def is_excluded(self, entry: Union[Entry, os.DirEntry[str]]) -> bool:
+        name, is_dir = _entry_name_dir(entry)
+
         # skip hidden files and directories
         if name.startswith("."):
             return True
@@ -86,26 +115,38 @@ class Matcher:
         else:
             return False
 
-    def is_included(self, name: str, is_dir: bool) -> bool:
+    @overload
+    def is_included(self, entry: Entry) -> bool:
+        """
+        True if the file or directory name matches none of the exclusion patterns.
+
+        :param entry: A data-class object.
+        :returns: True if the name doesn't match any of the exclusion patterns.
+        """
+        ...
+
+    @overload
+    def is_included(self, entry: os.DirEntry[str]) -> bool:
         """
         True if the file or directory name matches none of the exclusion patterns.
 
-        :param name: Name to match against the rule-set.
-        :param is_dir: Whether the name identifies a directory.
+        :param entry: An object returned by `scandir`.
         :returns: True if the name doesn't match any of the exclusion patterns.
         """
+        ...
 
-        return not self.is_excluded(name, is_dir)
+    def is_included(self, entry: Union[Entry, os.DirEntry[str]]) -> bool:
+        return not self.is_excluded(entry)
 
-    def filter(self, items: Iterable[Entry]) -> list[Entry]:
+    def filter(self, entries: Iterable[Entry]) -> list[Entry]:
         """
         Returns only those elements from the input that don't match any of the exclusion rules.
 
-        :param items: A list of names to filter.
+        :param entries: A list of names to filter.
         :returns: A filtered list of names that didn't match any of the exclusion rules.
         """
 
-        return [item for item in items if self.is_included(item.name, item.is_dir)]
+        return [entry for entry in entries if self.is_included(entry)]
 
     def scandir(self, path: Path) -> list[Entry]:
         """

md2conf/mermaid.py

@@ -79,10 +79,16 @@ def render_diagram(source: str, output_format: Literal["png", "svg"] = "png") ->
         )
         stdout, stderr = proc.communicate(input=source.encode("utf-8"))
         if proc.returncode:
-            raise RuntimeError(
-                f"failed to convert Mermaid diagram; exit code: {proc.returncode}, "
-                f"output:\n{stdout.decode('utf-8')}\n{stderr.decode('utf-8')}"
-            )
+            messages = [
+                f"failed to convert Mermaid diagram; exit code: {proc.returncode}"
+            ]
+            console_output = stdout.decode("utf-8")
+            if console_output:
+                messages.append(f"output:\n{console_output}")
+            console_error = stderr.decode("utf-8")
+            if console_error:
+                messages.append(f"error:\n{console_error}")
+            raise RuntimeError("\n".join(messages))
         with open(filename, "rb") as image:
             return image.read()
 

md2conf/metadata.py

@@ -0,0 +1,42 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ConfluenceSiteMetadata:
+    """
+    Data associated with a Confluence wiki site.
+
+    :param domain: Confluence organization domain (e.g. `levente-hunyadi.atlassian.net`).
+    :param base_path: Base path for Confluence (default: `/wiki/`).
+    :param space_key: Confluence space key for new pages (e.g. `~hunyadi` or `INST`).
+    """
+
+    domain: str
+    base_path: str
+    space_key: Optional[str]
+
+
+@dataclass
+class ConfluencePageMetadata:
+    """
+    Data associated with a Confluence page.
+
+    :param page_id: Confluence page ID.
+    :param space_key: Confluence space key.
+    :param title: Document title.
+    :param overwrite: True if operations are allowed to update document properties (e.g. title).
+    """
+
+    page_id: str
+    space_key: str
+    title: str
+    overwrite: bool

md2conf/processor.py

@@ -6,101 +6,94 @@ Copyright 2022-2025, Levente Hunyadi
 :see: https://github.com/hunyadi/md2conf
 """
 
-import hashlib
 import logging
 import os
+from abc import abstractmethod
 from pathlib import Path
 from typing import Optional
 
-from .converter import (
-    ConfluenceDocument,
-    ConfluenceDocumentOptions,
-    ConfluencePageMetadata,
-    ConfluenceQualifiedID,
-    ConfluenceSiteMetadata,
-    extract_qualified_id,
-)
+from .converter import ConfluenceDocument, ConfluenceDocumentOptions, ConfluencePageID
 from .matcher import Matcher, MatcherOptions
+from .metadata import ConfluencePageMetadata, ConfluenceSiteMetadata
 from .properties import ArgumentError
 
 LOGGER = logging.getLogger(__name__)
 
 
 class Processor:
+    """
+    Processes a single Markdown page or a directory of Markdown pages.
+    """
+
     options: ConfluenceDocumentOptions
-    site_metadata: ConfluenceSiteMetadata
+    site: ConfluenceSiteMetadata
+    root_dir: Path
+
+    page_metadata: dict[Path, ConfluencePageMetadata]
 
     def __init__(
-        self, options: ConfluenceDocumentOptions, site_metadata: ConfluenceSiteMetadata
+        self,
+        options: ConfluenceDocumentOptions,
+        site: ConfluenceSiteMetadata,
+        root_dir: Path,
     ) -> None:
         self.options = options
-        self.site_metadata = site_metadata
+        self.site = site
+        self.root_dir = root_dir
 
-    def process(self, path: Path) -> None:
-        "Processes a single Markdown file or a directory of Markdown files."
+        self.page_metadata = {}
 
-        path = path.resolve(True)
-        if path.is_dir():
-            self.process_directory(path)
-        elif path.is_file():
-            self.process_page(path)
-        else:
-            raise ArgumentError(f"expected: valid file or directory path; got: {path}")
-
-    def process_directory(
-        self, local_dir: Path, root_dir: Optional[Path] = None
-    ) -> None:
-        "Recursively scans a directory hierarchy for Markdown files."
+    def process_directory(self, local_dir: Path) -> None:
+        """
+        Recursively scans a directory hierarchy for Markdown files, and processes each, resolving cross-references.
+        """
 
         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)
+        LOGGER.info("Processing directory: %s", local_dir)
 
         # Step 1: build index of all page metadata
-        page_metadata: dict[Path, ConfluencePageMetadata] = {}
-        self._index_directory(local_dir, page_metadata)
-        LOGGER.info("Indexed %d page(s)", len(page_metadata))
+        self._index_directory(local_dir, self.options.root_page_id)
+        LOGGER.info("Indexed %d page(s)", len(self.page_metadata))
 
         # Step 2: convert each page
-        for page_path in page_metadata.keys():
-            self._process_page(page_path, root_dir, page_metadata)
+        for page_path in self.page_metadata.keys():
+            self._process_page(page_path)
 
-    def process_page(self, path: Path, root_dir: Optional[Path] = None) -> None:
-        "Processes a single Markdown file."
+    def process_page(self, path: Path) -> None:
+        """
+        Processes a single Markdown file.
+        """
 
-        path = path.resolve(True)
-        if root_dir is None:
-            root_dir = path.parent
-        else:
-            root_dir = root_dir.resolve(True)
-
-        self._process_page(path, root_dir, {})
-
-    def _process_page(
-        self,
-        path: Path,
-        root_dir: Path,
-        page_metadata: dict[Path, ConfluencePageMetadata],
-    ) -> None:
-        "Processes a single Markdown file."
+        LOGGER.info("Processing page: %s", path)
+        self._index_page(path, self.options.root_page_id)
+        self._process_page(path)
 
-        document = ConfluenceDocument.create(
-            path, self.options, root_dir, self.site_metadata, page_metadata
+    def _process_page(self, path: Path) -> None:
+        page_id, document = ConfluenceDocument.create(
+            path, self.options, self.root_dir, self.site, self.page_metadata
         )
-        content = document.xhtml()
-        with open(path.with_suffix(".csf"), "w", encoding="utf-8") as f:
-            f.write(content)
+        self._save_document(page_id, document, path)
+
+    @abstractmethod
+    def _get_or_create_page(
+        self, absolute_path: Path, parent_id: Optional[ConfluencePageID]
+    ) -> ConfluencePageMetadata:
+        """
+        Creates a new Confluence page if no page is linked in the Markdown document.
+        """
+        ...
+
+    @abstractmethod
+    def _save_document(
+        self, page_id: ConfluencePageID, document: ConfluenceDocument, path: Path
+    ) -> None: ...
 
     def _index_directory(
-        self,
-        local_dir: Path,
-        page_metadata: dict[Path, ConfluencePageMetadata],
+        self, local_dir: Path, parent_id: Optional[ConfluencePageID]
     ) -> None:
-        "Indexes Markdown files in a directory recursively."
+        """
+        Indexes Markdown files in a directory hierarchy recursively.
+        """
 
         LOGGER.info("Indexing directory: %s", local_dir)
 
@@ -109,7 +102,7 @@ class Processor:
         files: list[Path] = []
         directories: list[Path] = []
         for entry in os.scandir(local_dir):
-            if matcher.is_excluded(entry.name, entry.is_dir()):
+            if matcher.is_excluded(entry):
                 continue
 
             if entry.is_file():
@@ -117,32 +110,107 @@ class Processor:
             elif entry.is_dir():
                 directories.append(Path(local_dir) / entry.name)
 
+        # make page act as parent node
+        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 for directory entry
+            with open(parent_doc, "w"):
+                pass
+
+        if parent_doc is not None:
+            if parent_doc in files:
+                files.remove(parent_doc)
+
+            # use latest parent as parent for index page
+            metadata = self._get_or_create_page(parent_doc, parent_id)
+            LOGGER.debug("Indexed parent %s with metadata: %s", parent_doc, metadata)
+            self.page_metadata[parent_doc] = metadata
+
+            # assign new index page as new parent
+            parent_id = ConfluencePageID(metadata.page_id)
+
         for doc in files:
-            metadata = self._get_page(doc)
-            LOGGER.debug("Indexed %s with metadata: %s", doc, metadata)
-            page_metadata[doc] = metadata
+            self._index_page(doc, parent_id)
 
         for directory in directories:
-            self._index_directory(directory, page_metadata)
-
-    def _get_page(self, absolute_path: Path) -> ConfluencePageMetadata:
-        "Extracts metadata from a Markdown file."
-
-        with open(absolute_path, "r", encoding="utf-8") as f:
-            document = f.read()
-
-        qualified_id, document = extract_qualified_id(document)
-        if qualified_id is None:
-            if self.options.root_page_id is not None:
-                hash = hashlib.md5(document.encode("utf-8"))
-                digest = "".join(f"{c:x}" for c in hash.digest())
-                LOGGER.info("Identifier %s assigned to page: %s", digest, absolute_path)
-                qualified_id = ConfluenceQualifiedID(digest)
-            else:
-                raise ArgumentError("required: page ID for local output")
-
-        return ConfluencePageMetadata(
-            page_id=qualified_id.page_id,
-            space_key=qualified_id.space_key,
-            title="",
-        )
+            self._index_directory(directory, parent_id)
+
+    def _index_page(self, path: Path, parent_id: Optional[ConfluencePageID]) -> None:
+        """
+        Indexes a single Markdown file.
+        """
+
+        metadata = self._get_or_create_page(path, parent_id)
+        LOGGER.debug("Indexed %s with metadata: %s", path, metadata)
+        self.page_metadata[path] = metadata
+
+
+class ProcessorFactory:
+    options: ConfluenceDocumentOptions
+    site: ConfluenceSiteMetadata
+
+    def __init__(
+        self, options: ConfluenceDocumentOptions, site: ConfluenceSiteMetadata
+    ) -> None:
+        self.options = options
+        self.site = site
+
+    @abstractmethod
+    def create(self, root_dir: Path) -> Processor: ...
+
+
+class Converter:
+    factory: ProcessorFactory
+
+    def __init__(self, factory: ProcessorFactory) -> None:
+        self.factory = factory
+
+    def process(self, path: Path) -> None:
+        """
+        Processes a single Markdown file or a directory of Markdown files.
+        """
+
+        path = path.resolve(True)
+        if path.is_dir():
+            self.process_directory(path)
+        elif path.is_file():
+            self.process_page(path)
+        else:
+            raise ArgumentError(f"expected: valid file or directory path; got: {path}")
+
+    def process_directory(
+        self, local_dir: Path, root_dir: Optional[Path] = None
+    ) -> None:
+        """
+        Recursively scans a directory hierarchy for Markdown files, and processes each, resolving cross-references.
+        """
+
+        local_dir = local_dir.resolve(True)
+        if root_dir is None:
+            root_dir = local_dir
+        else:
+            root_dir = root_dir.resolve(True)
+
+        self.factory.create(root_dir).process_directory(local_dir)
+
+    def process_page(self, path: Path, root_dir: Optional[Path] = None) -> None:
+        """
+        Processes a single Markdown file.
+        """
+
+        path = path.resolve(True)
+        if root_dir is None:
+            root_dir = path.parent
+        else:
+            root_dir = root_dir.resolve(True)
+
+        self.factory.create(root_dir).process_page(path)