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

md2conf/api.py

@@ -22,7 +22,6 @@ import requests
 from strong_typing.core import JsonType
 from strong_typing.serialization import DeserializerOptions, json_dump_string, json_to_object, object_to_json
 
-from .converter import ParseError, sanitize_confluence
 from .metadata import ConfluenceSiteMetadata
 from .properties import ArgumentError, ConfluenceConnectionProperties, ConfluenceError, PageError
 
@@ -55,6 +54,18 @@ def build_url(base_url: str, query: Optional[dict[str, str]] = None) -> str:
 LOGGER = logging.getLogger(__name__)
 
 
+def response_cast(response_type: type[T], response: requests.Response) -> T:
+    "Converts a response body into the expected type."
+
+    if response.text:
+        LOGGER.debug("Received HTTP payload:\n%s", response.text)
+    response.raise_for_status()
+    if response_type is not type(None):
+        return _json_to_object(response_type, response.json())
+    else:
+        return None
+
+
 @enum.unique
 class ConfluenceVersion(enum.Enum):
     """
@@ -150,7 +161,7 @@ class ConfluenceAttachment:
     createdAt: datetime.datetime
     pageId: str
     mediaType: str
-    mediaTypeDescription: str
+    mediaTypeDescription: Optional[str]
     comment: Optional[str]
     fileId: str
     fileSize: int
@@ -387,8 +398,7 @@ class ConfluenceSession:
             self.api_url = api_url
 
             if not domain or not base_path:
-                payload = self._invoke(ConfluenceVersion.VERSION_2, "/spaces", {"limit": "1"})
-                data = json_to_object(ConfluenceResultSet, payload)
+                data = self._get(ConfluenceVersion.VERSION_2, "/spaces", ConfluenceResultSet, query={"limit": "1"})
                 base_url = data._links.base
 
                 _, domain, base_path, _, _, _ = urlparse(base_url)
@@ -425,12 +435,14 @@ class ConfluenceSession:
         base_url = f"{self.api_url}{version.value}{path}"
         return build_url(base_url, query)
 
-    def _invoke(
+    def _get(
         self,
         version: ConfluenceVersion,
         path: str,
+        response_type: type[T],
+        *,
         query: Optional[dict[str, str]] = None,
-    ) -> JsonType:
+    ) -> T:
         "Executes an HTTP request via Confluence API."
 
         url = self._build_url(version, path, query)
@@ -438,7 +450,7 @@ class ConfluenceSession:
         if response.text:
             LOGGER.debug("Received HTTP payload:\n%s", response.text)
         response.raise_for_status()
-        return typing.cast(JsonType, response.json())
+        return _json_to_object(response_type, response.json())
 
     def _fetch(self, path: str, query: Optional[dict[str, str]] = None) -> list[JsonType]:
         "Retrieves all results of a REST API v2 paginated result-set."
@@ -462,30 +474,55 @@ class ConfluenceSession:
 
         return items
 
-    def _save(self, version: ConfluenceVersion, path: str, data: JsonType) -> None:
-        "Persists data via Confluence REST API."
+    def _build_request(self, version: ConfluenceVersion, path: str, body: Any, response_type: type[T]) -> tuple[str, dict[str, str], bytes]:
+        "Generates URL, headers and raw payload for a typed request/response."
 
         url = self._build_url(version, path)
+        if response_type is not type(None):
+            headers = {
+                "Content-Type": "application/json; charset=utf-8",
+                "Accept": "application/json",
+            }
+        else:
+            headers = {
+                "Content-Type": "application/json; charset=utf-8",
+            }
+        data = json_dump_string(object_to_json(body)).encode("utf-8")
+        return url, headers, data
+
+    def _post(self, version: ConfluenceVersion, path: str, body: Any, response_type: type[T]) -> T:
+        "Creates a new object via Confluence REST API."
+
+        url, headers, data = self._build_request(version, path, body, response_type)
+        response = self.session.post(
+            url,
+            data=data,
+            headers=headers,
+        )
+        return response_cast(response_type, response)
+
+    def _put(self, version: ConfluenceVersion, path: str, body: Any, response_type: type[T]) -> T:
+        "Updates an existing object via Confluence REST API."
+
+        url, headers, data = self._build_request(version, path, body, response_type)
         response = self.session.put(
             url,
-            data=json_dump_string(data),
-            headers={"Content-Type": "application/json"},
+            data=data,
+            headers=headers,
         )
-        if response.text:
-            LOGGER.debug("Received HTTP payload:\n%s", response.text)
-        response.raise_for_status()
+        return response_cast(response_type, response)
 
     def space_id_to_key(self, id: str) -> str:
         "Finds the Confluence space key for a space ID."
 
         key = self._space_id_to_key.get(id)
         if key is None:
-            payload = self._invoke(
+            data = self._get(
                 ConfluenceVersion.VERSION_2,
                 "/spaces",
-                {"ids": id, "status": "current"},
+                dict[str, JsonType],
+                query={"ids": id, "status": "current"},
             )
-            data = typing.cast(dict[str, JsonType], payload)
             results = typing.cast(list[JsonType], data["results"])
             if len(results) != 1:
                 raise ConfluenceError(f"unique space not found with id: {id}")
@@ -502,12 +539,12 @@ class ConfluenceSession:
 
         id = self._space_key_to_id.get(key)
         if id is None:
-            payload = self._invoke(
+            data = self._get(
                 ConfluenceVersion.VERSION_2,
                 "/spaces",
-                {"keys": key, "status": "current"},
+                dict[str, JsonType],
+                query={"keys": key, "status": "current"},
             )
-            data = typing.cast(dict[str, JsonType], payload)
             results = typing.cast(list[JsonType], data["results"])
             if len(results) != 1:
                 raise ConfluenceError(f"unique space not found with key: {key}")
@@ -546,9 +583,7 @@ class ConfluenceSession:
         """
 
         path = f"/pages/{page_id}/attachments"
-        query = {"filename": filename}
-        payload = self._invoke(ConfluenceVersion.VERSION_2, path, query)
-        data = typing.cast(dict[str, JsonType], payload)
+        data = self._get(ConfluenceVersion.VERSION_2, path, dict[str, JsonType], query={"filename": filename})
 
         results = typing.cast(list[JsonType], data["results"])
         if len(results) != 1:
@@ -701,7 +736,7 @@ class ConfluenceSession:
         )
 
         LOGGER.info("Updating attachment: %s", attachment_id)
-        self._save(ConfluenceVersion.VERSION_1, path, object_to_json(request))
+        self._put(ConfluenceVersion.VERSION_1, path, request, type(None))
 
     def get_page_properties_by_title(
         self,
@@ -728,8 +763,7 @@ class ConfluenceSession:
         if space_id is not None:
             query["space-id"] = space_id
 
-        payload = self._invoke(ConfluenceVersion.VERSION_2, path, query)
-        data = typing.cast(dict[str, JsonType], payload)
+        data = self._get(ConfluenceVersion.VERSION_2, path, dict[str, JsonType], query=query)
         results = typing.cast(list[JsonType], data["results"])
         if len(results) != 1:
             raise ConfluenceError(f"unique page not found with title: {title}")
@@ -746,9 +780,7 @@ class ConfluenceSession:
         """
 
         path = f"/pages/{page_id}"
-        query = {"body-format": "storage"}
-        payload = self._invoke(ConfluenceVersion.VERSION_2, path, query)
-        return _json_to_object(ConfluencePage, payload)
+        return self._get(ConfluenceVersion.VERSION_2, path, ConfluencePage, query={"body-format": "storage"})
 
     def get_page_properties(self, page_id: str) -> ConfluencePageProperties:
         """
@@ -759,8 +791,7 @@ class ConfluenceSession:
         """
 
         path = f"/pages/{page_id}"
-        payload = self._invoke(ConfluenceVersion.VERSION_2, path)
-        return _json_to_object(ConfluencePageProperties, payload)
+        return self._get(ConfluenceVersion.VERSION_2, path, ConfluencePageProperties)
 
     def get_page_version(self, page_id: str) -> int:
         """
@@ -775,39 +806,30 @@ class ConfluenceSession:
     def update_page(
         self,
         page_id: str,
-        new_content: str,
+        content: str,
         *,
-        title: Optional[str] = None,
+        title: str,
+        version: int,
     ) -> None:
         """
         Updates a page via the Confluence API.
 
         :param page_id: The Confluence page ID.
-        :param new_content: Confluence Storage Format XHTML.
+        :param content: Confluence Storage Format XHTML.
         :param title: New title to assign to the page. Needs to be unique within a space.
+        :param version: New version to assign to the page.
         """
 
-        page = self.get_page(page_id)
-        new_title = title or page.title
-
-        try:
-            old_content = sanitize_confluence(page.content)
-            if page.title == new_title and old_content == new_content:
-                LOGGER.info("Up-to-date page: %s", page_id)
-                return
-        except ParseError as exc:
-            LOGGER.warning(exc)
-
         path = f"/pages/{page_id}"
         request = ConfluenceUpdatePageRequest(
             id=page_id,
             status=ConfluenceStatus.CURRENT,
-            title=new_title,
-            body=ConfluencePageBody(storage=ConfluencePageStorage(representation=ConfluenceRepresentation.STORAGE, value=new_content)),
-            version=ConfluenceContentVersion(number=page.version.number + 1, minorEdit=True),
+            title=title,
+            body=ConfluencePageBody(storage=ConfluencePageStorage(representation=ConfluenceRepresentation.STORAGE, value=content)),
+            version=ConfluenceContentVersion(number=version, minorEdit=True),
         )
         LOGGER.info("Updating page: %s", page_id)
-        self._save(ConfluenceVersion.VERSION_2, path, object_to_json(request))
+        self._put(ConfluenceVersion.VERSION_2, path, request, type(None))
 
     def create_page(
         self,
@@ -840,9 +862,9 @@ class ConfluenceSession:
         url = self._build_url(ConfluenceVersion.VERSION_2, path)
         response = self.session.post(
             url,
-            data=json_dump_string(object_to_json(request)),
+            data=json_dump_string(object_to_json(request)).encode("utf-8"),
             headers={
-                "Content-Type": "application/json",
+                "Content-Type": "application/json; charset=utf-8",
                 "Accept": "application/json",
             },
         )
@@ -902,7 +924,7 @@ class ConfluenceSession:
             url,
             params=query,
             headers={
-                "Content-Type": "application/json",
+                "Content-Type": "application/json; charset=utf-8",
                 "Accept": "application/json",
             },
         )
@@ -954,19 +976,7 @@ class ConfluenceSession:
         """
 
         path = f"/content/{page_id}/label"
-
-        url = self._build_url(ConfluenceVersion.VERSION_1, path)
-        response = self.session.post(
-            url,
-            data=json_dump_string(object_to_json(labels)),
-            headers={
-                "Content-Type": "application/json",
-                "Accept": "application/json",
-            },
-        )
-        if response.text:
-            LOGGER.debug("Received HTTP payload:\n%s", response.text)
-        response.raise_for_status()
+        self._post(ConfluenceVersion.VERSION_1, path, labels, type(None))
 
     def remove_labels(self, page_id: str, labels: list[ConfluenceLabel]) -> None:
         """
@@ -1028,19 +1038,7 @@ class ConfluenceSession:
         """
 
         path = f"/pages/{page_id}/properties"
-        url = self._build_url(ConfluenceVersion.VERSION_2, path)
-        response = self.session.post(
-            url,
-            data=json_dump_string(object_to_json(property)),
-            headers={
-                "Content-Type": "application/json",
-                "Accept": "application/json",
-            },
-        )
-        if response.text:
-            LOGGER.debug("Received HTTP payload:\n%s", response.text)
-        response.raise_for_status()
-        return _json_to_object(ConfluenceIdentifiedContentProperty, response.json())
+        return self._post(ConfluenceVersion.VERSION_2, path, property, ConfluenceIdentifiedContentProperty)
 
     def remove_content_property_from_page(self, page_id: str, property_id: str) -> None:
         """
@@ -1069,24 +1067,16 @@ class ConfluenceSession:
         """
 
         path = f"/pages/{page_id}/properties/{property_id}"
-        url = self._build_url(ConfluenceVersion.VERSION_2, path)
-        response = self.session.put(
-            url,
-            data=json_dump_string(
-                object_to_json(
-                    ConfluenceVersionedContentProperty(
-                        key=property.key,
-                        value=property.value,
-                        version=ConfluenceContentVersion(number=version),
-                    )
-                )
+        return self._put(
+            ConfluenceVersion.VERSION_2,
+            path,
+            ConfluenceVersionedContentProperty(
+                key=property.key,
+                value=property.value,
+                version=ConfluenceContentVersion(number=version),
             ),
-            headers={"Content-Type": "application/json"},
+            ConfluenceIdentifiedContentProperty,
         )
-        if response.text:
-            LOGGER.debug("Received HTTP payload:\n%s", response.text)
-        response.raise_for_status()
-        return json_to_object(ConfluenceIdentifiedContentProperty, response.json())
 
     def update_content_properties_for_page(self, page_id: str, properties: list[ConfluenceContentProperty], *, keep_existing: bool = False) -> None:
         """

md2conf/application.py

@@ -11,11 +11,12 @@ from pathlib import Path
 from typing import Optional
 
 from .api import ConfluenceContentProperty, ConfluenceLabel, ConfluenceSession, ConfluenceStatus
-from .converter import ConfluenceDocument, ConfluenceDocumentOptions, ConfluencePageID, attachment_name
+from .converter import ConfluenceDocument, ConfluenceDocumentOptions, ConfluencePageID, attachment_name, elements_from_string, get_volatile_attributes
 from .extra import override, path_relative_to
 from .metadata import ConfluencePageMetadata
 from .processor import Converter, DocumentNode, Processor, ProcessorFactory
 from .properties import PageError
+from .xml import is_xml_equal
 
 LOGGER = logging.getLogger(__name__)
 
@@ -97,6 +98,7 @@ class SynchronizingProcessor(Processor):
             page_id=page.id,
             space_key=space_key,
             title=page.title,
+            synchronized=node.synchronized,
         )
         self.page_metadata.add(node.absolute_path, data)
 
@@ -143,7 +145,20 @@ class SynchronizingProcessor(Processor):
                         conflicting_page_id,
                     )
 
-        self.api.update_page(page_id.page_id, content, title=title)
+        # fetch existing page
+        page = self.api.get_page(page_id.page_id)
+        if not title:  # empty or `None`
+            title = page.title
+
+        # check if page has any changes
+        if page.title != title or not is_xml_equal(
+            document.root,
+            elements_from_string(page.content),
+            skip_attributes=get_volatile_attributes(),
+        ):
+            self.api.update_page(page_id.page_id, content, title=title, version=page.version.number + 1)
+        else:
+            LOGGER.info("Up-to-date page: %s", page_id)
 
         if document.labels is not None:
             self.api.update_labels(

md2conf/collection.py

@@ -7,25 +7,31 @@ Copyright 2022-2025, Levente Hunyadi
 """
 
 from pathlib import Path
-from typing import Iterable, Optional
+from typing import Generic, Iterable, Optional, TypeVar
 
 from .metadata import ConfluencePageMetadata
 
+K = TypeVar("K")
+V = TypeVar("V")
 
-class ConfluencePageCollection:
-    _metadata: dict[Path, ConfluencePageMetadata]
+
+class KeyValueCollection(Generic[K, V]):
+    _collection: dict[K, V]
 
     def __init__(self) -> None:
-        self._metadata = {}
+        self._collection = {}
 
     def __len__(self) -> int:
-        return len(self._metadata)
+        return len(self._collection)
+
+    def add(self, key: K, data: V) -> None:
+        self._collection[key] = data
+
+    def get(self, key: K) -> Optional[V]:
+        return self._collection.get(key)
 
-    def add(self, path: Path, data: ConfluencePageMetadata) -> None:
-        self._metadata[path] = data
+    def items(self) -> Iterable[tuple[K, V]]:
+        return self._collection.items()
 
-    def get(self, path: Path) -> Optional[ConfluencePageMetadata]:
-        return self._metadata.get(path)
 
-    def items(self) -> Iterable[tuple[Path, ConfluencePageMetadata]]:
-        return self._metadata.items()
+class ConfluencePageCollection(KeyValueCollection[Path, ConfluencePageMetadata]): ...