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

md2conf/processor.py

@@ -6,98 +6,96 @@ 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,
-    extract_qualified_id,
-)
+from .converter import ConfluenceDocument, ConfluenceDocumentOptions, ConfluencePageID
 from .matcher import Matcher, MatcherOptions
-from .properties import ConfluenceProperties
+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
-    properties: ConfluenceProperties
+    site: ConfluenceSiteMetadata
+    root_dir: Path
+
+    page_metadata: dict[Path, ConfluencePageMetadata]
 
     def __init__(
-        self, options: ConfluenceDocumentOptions, properties: ConfluenceProperties
+        self,
+        options: ConfluenceDocumentOptions,
+        site: ConfluenceSiteMetadata,
+        root_dir: Path,
     ) -> None:
         self.options = options
-        self.properties = properties
-
-    def process(self, path: Path) -> None:
-        "Processes a single Markdown file or a directory of Markdown files."
+        self.site = site
+        self.root_dir = root_dir
 
-        path = path.resolve(True)
-        if path.is_dir():
-            self.process_directory(path)
-        elif path.is_file():
-            self.process_page(path)
-        else:
-            raise ValueError(f"expected: valid file or directory path; got: {path}")
+        self.page_metadata = {}
 
-    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)
+        LOGGER.info("Processing page: %s", path)
+        self._index_page(path, self.options.root_page_id)
+        self._process_page(path)
 
-        self._process_page(path, root_dir, {})
+    def _process_page(self, path: Path) -> None:
+        document = ConfluenceDocument.create(
+            path, self.options, self.root_dir, self.site, self.page_metadata
+        )
+        self._save_document(document, path)
 
-    def _process_page(
+    @abstractmethod
+    def _get_or_create_page(
         self,
-        path: Path,
-        root_dir: Path,
-        page_metadata: dict[Path, ConfluencePageMetadata],
-    ) -> None:
-        "Processes a single Markdown file."
-
-        document = ConfluenceDocument(path, self.options, root_dir, page_metadata)
-        content = document.xhtml()
-        with open(path.with_suffix(".csf"), "w", encoding="utf-8") as f:
-            f.write(content)
+        absolute_path: Path,
+        parent_id: Optional[ConfluencePageID],
+        *,
+        title: Optional[str] = None,
+    ) -> ConfluencePageMetadata:
+        """
+        Creates a new Confluence page if no page is linked in the Markdown document.
+        """
+        ...
+
+    @abstractmethod
+    def _save_document(self, 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)
 
@@ -114,34 +112,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 ValueError("required: page ID for local output")
-
-        return ConfluencePageMetadata(
-            domain=self.properties.domain,
-            base_path=self.properties.base_path,
-            page_id=qualified_id.page_id,
-            space_key=qualified_id.space_key or self.properties.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)

md2conf/properties.py

@@ -10,50 +10,74 @@ import os
 from typing import Optional
 
 
+class ArgumentError(ValueError):
+    "Raised when wrong arguments are passed to a function call."
+
+
+class PageError(ValueError):
+    "Raised in case there is an issue with a Confluence page."
+
+
 class ConfluenceError(RuntimeError):
-    pass
+    "Raised when a Confluence API call fails."
 
 
-class ConfluenceProperties:
+class ConfluenceSiteProperties:
     domain: str
     base_path: str
     space_key: Optional[str]
-    user_name: Optional[str]
-    api_key: str
-    headers: Optional[dict[str, str]]
 
     def __init__(
         self,
         domain: Optional[str] = None,
         base_path: Optional[str] = None,
-        user_name: Optional[str] = None,
-        api_key: Optional[str] = None,
         space_key: Optional[str] = None,
-        headers: Optional[dict[str, str]] = None,
     ) -> None:
         opt_domain = domain or os.getenv("CONFLUENCE_DOMAIN")
         opt_base_path = base_path or os.getenv("CONFLUENCE_PATH")
-        opt_user_name = user_name or os.getenv("CONFLUENCE_USER_NAME")
-        opt_api_key = api_key or os.getenv("CONFLUENCE_API_KEY")
         opt_space_key = space_key or os.getenv("CONFLUENCE_SPACE_KEY")
 
         if not opt_domain:
-            raise ConfluenceError("Confluence domain not specified")
+            raise ArgumentError("Confluence domain not specified")
         if not opt_base_path:
             opt_base_path = "/wiki/"
-        if not opt_api_key:
-            raise ConfluenceError("Confluence API key not specified")
 
         if opt_domain.startswith(("http://", "https://")) or opt_domain.endswith("/"):
-            raise ConfluenceError(
+            raise ArgumentError(
                 "Confluence domain looks like a URL; only host name required"
             )
         if not opt_base_path.startswith("/") or not opt_base_path.endswith("/"):
-            raise ConfluenceError("Confluence base path must start and end with a '/'")
+            raise ArgumentError("Confluence base path must start and end with a '/'")
 
         self.domain = opt_domain
         self.base_path = opt_base_path
+        self.space_key = opt_space_key
+
+
+class ConfluenceConnectionProperties(ConfluenceSiteProperties):
+    "Properties related to connecting to Confluence."
+
+    user_name: Optional[str]
+    api_key: str
+    headers: Optional[dict[str, str]]
+
+    def __init__(
+        self,
+        domain: Optional[str] = None,
+        base_path: Optional[str] = None,
+        user_name: Optional[str] = None,
+        api_key: Optional[str] = None,
+        space_key: Optional[str] = None,
+        headers: Optional[dict[str, str]] = None,
+    ) -> None:
+        super().__init__(domain, base_path, space_key)
+
+        opt_user_name = user_name or os.getenv("CONFLUENCE_USER_NAME")
+        opt_api_key = api_key or os.getenv("CONFLUENCE_API_KEY")
+
+        if not opt_api_key:
+            raise ArgumentError("Confluence API key not specified")
+
         self.user_name = opt_user_name
         self.api_key = opt_api_key
-        self.space_key = opt_space_key
         self.headers = headers

markdown_to_confluence-0.3.2.dist-info/RECORD

@@ -1,20 +0,0 @@
-markdown_to_confluence-0.3.2.dist-info/licenses/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
-md2conf/__init__.py,sha256=IyztAgNkEXTxDlsTrxZOAkeNIzLSSzjNV0ZHg2SvDDE,402
-md2conf/__main__.py,sha256=ypjV_5mE0smlIRBFrpikgzXq18as2hY43HJxMLpzGp4,7145
-md2conf/api.py,sha256=-bneMbfpspfat4J63Z7bY0kdlW8yJguRRNbx6CaOkGY,20101
-md2conf/application.py,sha256=5K-nCPHJZfIahjubrLtXTwI-zsTiD140fdYXDnh3GSk,9161
-md2conf/converter.py,sha256=MoGbXqh5rE4qkdxxY8RHcnoZ5mz0aEuFz9nmUnt0WdM,36397
-md2conf/emoji.py,sha256=IZeguWqcboeOyJkGLTVONDMO4ZXfYXPgfkp56PTI-hE,1924
-md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
-md2conf/matcher.py,sha256=FgMFPvGiOqGezCs8OyerfsVo-iIHFoI6LRMzdcjM5UY,3693
-md2conf/mermaid.py,sha256=Alzkv0BY-lju4ojtBdW2qtCLZ59MO9kaS2RpQO6Kyfk,2304
-md2conf/processor.py,sha256=G-MIh1jGq9jjgogHnlnRUSrNgiV6_xO6Fy7ct9alqgM,4769
-md2conf/properties.py,sha256=WaVVOYSck7drVQfcBJmBMa7Mb0KVOZl9UZHvLS1Du8U,1892
-md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
-md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-markdown_to_confluence-0.3.2.dist-info/METADATA,sha256=2exvsuRCcD3L9CN7fl0gqki1gsqQgHDxGyjnKhDeYmw,14958
-markdown_to_confluence-0.3.2.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-markdown_to_confluence-0.3.2.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
-markdown_to_confluence-0.3.2.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.3.2.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.3.2.dist-info/RECORD,,