markdown-to-confluence 0.5.1__py3-none-any.whl → 0.5.3__py3-none-any.whl

md2conf/api.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
 """
@@ -11,7 +11,9 @@ import enum
 import io
 import logging
 import mimetypes
+import random
 import ssl
+import time
 import typing
 from dataclasses import dataclass
 from pathlib import Path
@@ -23,20 +25,23 @@ import requests
 import truststore
 from requests.adapters import HTTPAdapter
 
-from .environment import ArgumentError, ConfluenceConnectionProperties, ConfluenceError, PageError
-from .extra import override
+from .compatibility import override
+from .environment import ArgumentError, ConfluenceError, ConnectionProperties, PageError
 from .metadata import ConfluenceSiteMetadata
 from .serializer import JsonType, json_to_object, object_to_json_payload
 
 T = TypeVar("T")
 
+# spellchecker: disable
 mimetypes.add_type("application/vnd.openxmlformats-officedocument.wordprocessingml.document", ".docx", strict=True)
 mimetypes.add_type("text/vnd.mermaid", ".mmd", strict=True)
+mimetypes.add_type("text/vnd.plantuml", ".puml", strict=True)
 mimetypes.add_type("application/vnd.oasis.opendocument.presentation", ".odp", strict=True)
 mimetypes.add_type("application/vnd.oasis.opendocument.spreadsheet", ".ods", strict=True)
 mimetypes.add_type("application/vnd.oasis.opendocument.text", ".odt", strict=True)
 mimetypes.add_type("application/vnd.openxmlformats-officedocument.presentationml.presentation", ".pptx", strict=True)
 mimetypes.add_type("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", ".xlsx", strict=True)
+# spellchecker: enable
 
 
 def build_url(base_url: str, query: dict[str, str] | None = None) -> str:
@@ -366,11 +371,11 @@ class ConfluenceAPI:
     Encapsulates operations that can be invoked via the [Confluence REST API](https://developer.atlassian.com/cloud/confluence/rest/v2/).
     """
 
-    properties: ConfluenceConnectionProperties
+    properties: ConnectionProperties
     session: "ConfluenceSession | None" = None
 
-    def __init__(self, properties: ConfluenceConnectionProperties | None = None) -> None:
-        self.properties = properties or ConfluenceConnectionProperties()
+    def __init__(self, properties: ConnectionProperties | None = None) -> None:
+        self.properties = properties or ConnectionProperties()
 
     def __enter__(self) -> "ConfluenceSession":
         """
@@ -622,7 +627,16 @@ class ConfluenceSession:
 
         return id
 
+    @overload
+    def get_space_id(self, *, space_id: str | None = None) -> str | None: ...
+
+    @overload
+    def get_space_id(self, *, space_key: str | None = None) -> str | None: ...
+
     def get_space_id(self, *, space_id: str | None = None, space_key: str | None = None) -> str | None:
+        return self._get_space_id(space_id=space_id, space_key=space_key)
+
+    def _get_space_id(self, *, space_id: str | None = None, space_key: str | None = None) -> str | None:
         """
         Coalesces a space ID or space key into a space ID, accounting for site default.
 
@@ -643,6 +657,15 @@ class ConfluenceSession:
         # space ID and key are unset, and no default space is configured
         return None
 
+    def get_homepage_id(self, space_id: str) -> str:
+        """
+        Returns the page ID corresponding to the space home page.
+        """
+
+        path = f"/spaces/{space_id}"
+        data = self._get(ConfluenceVersion.VERSION_2, path, dict[str, JsonType])
+        return typing.cast(str, data["homepageId"])
+
     def get_attachment_by_name(self, page_id: str, filename: str) -> ConfluenceAttachment:
         """
         Retrieves a Confluence page attachment by an unprefixed file name.
@@ -827,7 +850,7 @@ class ConfluenceSession:
         query = {
             "title": title,
         }
-        space_id = self.get_space_id(space_id=space_id, space_key=space_key)
+        space_id = self._get_space_id(space_id=space_id, space_key=space_key)
         if space_id is not None:
             query["space-id"] = space_id
 
@@ -839,16 +862,38 @@ class ConfluenceSession:
         page = json_to_object(ConfluencePageProperties, results[0])
         return page
 
-    def get_page(self, page_id: str) -> ConfluencePage:
+    def get_page(self, page_id: str, *, retries: int = 3, retry_delay: float = 1.0) -> ConfluencePage:
         """
         Retrieves Confluence wiki page details and content.
 
+        Includes retry logic to handle eventual consistency issues when fetching
+        a newly created page that may not be immediately available via the API.
+
         :param page_id: The Confluence page ID.
+        :param retries: Number of retry attempts for 404 errors (default: 3).
+        :param retry_delay: Initial delay in seconds between retries, doubles each attempt (default: 1.0).
         :returns: Confluence page info and content.
         """
 
         path = f"/pages/{page_id}"
-        return self._get(ConfluenceVersion.VERSION_2, path, ConfluencePage, query={"body-format": "storage"})
+        last_error: requests.HTTPError | None = None
+
+        for attempt in range(retries + 1):
+            try:
+                return self._get(ConfluenceVersion.VERSION_2, path, ConfluencePage, query={"body-format": "storage"})
+            except requests.HTTPError as e:
+                if e.response is not None and e.response.status_code == 404 and attempt < retries:
+                    delay = retry_delay * (2**attempt) + random.uniform(0, 1)
+                    LOGGER.debug("Page %s not found, retrying in %.1f seconds (attempt %d/%d)", page_id, delay, attempt + 1, retries)
+                    time.sleep(delay)
+                    last_error = e
+                else:
+                    raise
+
+        # This should not be reached, but satisfies type checker
+        if last_error is not None:
+            raise last_error
+        raise ConfluenceError(f"Failed to get page {page_id}")
 
     def get_page_properties(self, page_id: str) -> ConfluencePageProperties:
         """
@@ -980,7 +1025,7 @@ class ConfluenceSession:
         :returns: Confluence page ID of a matching page (if found), or `None`.
         """
 
-        space_id = self.get_space_id(space_id=space_id, space_key=space_key)
+        space_id = self._get_space_id(space_id=space_id, space_key=space_key)
         path = "/pages"
         query = {"title": title}
         if space_id is not None:

md2conf/attachment.py

@@ -0,0 +1,72 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class ImageData:
+    path: Path
+    description: str | None = None
+
+
+@dataclass
+class EmbeddedFileData:
+    data: bytes
+    description: str | None = None
+
+
+class AttachmentCatalog:
+    "Maintains a list of files and binary data to be uploaded to Confluence as attachments."
+
+    images: list[ImageData]
+    embedded_files: dict[str, EmbeddedFileData]
+
+    def __init__(self) -> None:
+        self.images = []
+        self.embedded_files = {}
+
+    def add_image(self, data: ImageData) -> None:
+        self.images.append(data)
+
+    def add_embed(self, filename: str, data: EmbeddedFileData) -> None:
+        self.embedded_files[filename] = data
+
+
+def attachment_name(ref: Path | str) -> str:
+    """
+    Safe name for use with attachment uploads.
+
+    Mutates a relative path such that it meets Confluence's attachment naming requirements.
+
+    Allowed characters:
+
+    * Alphanumeric characters: 0-9, a-z, A-Z
+    * Special characters: hyphen (-), underscore (_), period (.)
+    """
+
+    if isinstance(ref, Path):
+        path = ref
+    else:
+        path = Path(ref)
+
+    if path.drive or path.root:
+        raise ValueError(f"required: relative path; got: {ref}")
+
+    regexp = re.compile(r"[^\-0-9A-Za-z_.]", re.UNICODE)
+
+    def replace_part(part: str) -> str:
+        if part == "..":
+            return "PAR"
+        else:
+            return regexp.sub("_", part)
+
+    parts = [replace_part(p) for p in path.parts]
+    return Path(*parts).as_posix().replace("/", "_")

md2conf/coalesce.py

@@ -0,0 +1,43 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import copy
+import dataclasses
+from typing import Any, ClassVar, Protocol, TypeVar
+
+
+class DataclassInstance(Protocol):
+    __dataclass_fields__: ClassVar[dict[str, dataclasses.Field[Any]]]
+
+
+D = TypeVar("D", bound=DataclassInstance)
+
+
+def coalesce(target: D, source: D) -> D:
+    """
+    Implements nullish coalescing assignment on each field of a data-class.
+
+    Iterates over each field of the data-class, and evaluates the right operand and assigns it to the left only if
+    the left operand is `None`. Applies recursively when the field is a data-class.
+
+    :returns: A newly created data-class instance.
+    """
+
+    updates: dict[str, Any] = {}
+    for field in dataclasses.fields(target):
+        target_field = getattr(target, field.name, None)
+        source_field = getattr(source, field.name, None)
+
+        if target_field is None:
+            if source_field is not None:
+                updates[field.name] = copy.deepcopy(source_field)
+        elif dataclasses.is_dataclass(field.type):
+            if source_field is not None:
+                updates[field.name] = coalesce(target_field, source_field)
+
+    return dataclasses.replace(target, **updates)

md2conf/collection.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
 """

md2conf/{extra.py → compatibility.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
 """