markdown-to-confluence 0.2.6__py3-none-any.whl → 0.3.0__py3-none-any.whl

md2conf/api.py

@@ -1,21 +1,21 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2024, Levente Hunyadi
+Copyright 2022-2025, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
 
+import enum
 import io
 import json
 import logging
 import mimetypes
 import typing
-from contextlib import contextmanager
 from dataclasses import dataclass
 from pathlib import Path
 from types import TracebackType
-from typing import Dict, Generator, List, Optional, Type, Union
+from typing import Optional, Union
 from urllib.parse import urlencode, urlparse, urlunparse
 
 import requests
@@ -31,12 +31,17 @@ JsonType = Union[
     int,
     float,
     str,
-    Dict[str, "JsonType"],
-    List["JsonType"],
+    dict[str, "JsonType"],
+    list["JsonType"],
 ]
 
 
-def build_url(base_url: str, query: Optional[Dict[str, str]] = None) -> str:
+class ConfluenceVersion(enum.Enum):
+    VERSION_1 = "rest/api"
+    VERSION_2 = "api/v2"
+
+
+def build_url(base_url: str, query: Optional[dict[str, str]] = None) -> str:
     "Builds a URL with scheme, host, port, path and query string parameters."
 
     scheme, netloc, path, params, query_str, fragment = urlparse(base_url)
@@ -66,7 +71,7 @@ class ConfluenceAttachment:
 @dataclass
 class ConfluencePage:
     id: str
-    space_key: str
+    space_id: str
     title: str
     version: int
     content: str
@@ -101,7 +106,7 @@ class ConfluenceAPI:
 
     def __exit__(
         self,
-        exc_type: Optional[Type[BaseException]],
+        exc_type: Optional[type[BaseException]],
         exc_val: Optional[BaseException],
         exc_tb: Optional[TracebackType],
     ) -> None:
@@ -116,6 +121,9 @@ class ConfluenceSession:
     base_path: str
     space_key: str
 
+    _space_id_to_key: dict[str, str]
+    _space_key_to_id: dict[str, str]
+
     def __init__(
         self, session: requests.Session, domain: str, base_path: str, space_key: str
     ) -> None:
@@ -124,30 +132,46 @@ class ConfluenceSession:
         self.base_path = base_path
         self.space_key = space_key
 
+        self._space_id_to_key = {}
+        self._space_key_to_id = {}
+
     def close(self) -> None:
         self.session.close()
+        self.session = requests.Session()
 
-    @contextmanager
-    def switch_space(self, new_space_key: str) -> Generator[None, None, None]:
-        old_space_key = self.space_key
-        self.space_key = new_space_key
-        try:
-            yield
-        finally:
-            self.space_key = old_space_key
+    def _build_url(
+        self,
+        version: ConfluenceVersion,
+        path: str,
+        query: Optional[dict[str, str]] = None,
+    ) -> str:
+        """
+        Builds a full URL for invoking the Confluence API.
 
-    def _build_url(self, path: str, query: Optional[Dict[str, str]] = None) -> str:
-        base_url = f"https://{self.domain}{self.base_path}rest/api{path}"
+        :param prefix: A URL path prefix that depends on the Confluence API version.
+        :param path: Path of API endpoint to invoke.
+        :param query: Query parameters to pass to the API endpoint.
+        :returns: A full URL.
+        """
+
+        base_url = f"https://{self.domain}{self.base_path}{version.value}{path}"
         return build_url(base_url, query)
 
-    def _invoke(self, path: str, query: Dict[str, str]) -> JsonType:
-        url = self._build_url(path, query)
+    def _invoke(
+        self,
+        version: ConfluenceVersion,
+        path: str,
+        query: Optional[dict[str, str]] = None,
+    ) -> JsonType:
+        "Execute an HTTP request via Confluence API."
+
+        url = self._build_url(version, path, query)
         response = self.session.get(url)
         response.raise_for_status()
         return response.json()
 
-    def _save(self, path: str, data: dict) -> None:
-        url = self._build_url(path)
+    def _save(self, version: ConfluenceVersion, path: str, data: dict) -> None:
+        url = self._build_url(version, path)
         response = self.session.put(
             url,
             data=json.dumps(data),
@@ -155,24 +179,68 @@ class ConfluenceSession:
         )
         response.raise_for_status()
 
+    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(
+                ConfluenceVersion.VERSION_2,
+                "/spaces",
+                {"ids": id, "type": "global", "status": "current"},
+            )
+            payload = typing.cast(dict[str, JsonType], payload)
+            results = typing.cast(list[JsonType], payload["results"])
+            if len(results) != 1:
+                raise ConfluenceError(f"unique space not found with id: {id}")
+
+            result = typing.cast(dict[str, JsonType], results[0])
+            key = typing.cast(str, result["key"])
+
+            self._space_id_to_key[id] = key
+
+        return key
+
+    def space_key_to_id(self, key: str) -> str:
+        "Finds the Confluence space ID for a space key."
+
+        id = self._space_key_to_id.get(key)
+        if id is None:
+            payload = self._invoke(
+                ConfluenceVersion.VERSION_2,
+                "/spaces",
+                {"keys": key, "type": "global", "status": "current"},
+            )
+            payload = typing.cast(dict[str, JsonType], payload)
+            results = typing.cast(list[JsonType], payload["results"])
+            if len(results) != 1:
+                raise ConfluenceError(f"unique space not found with key: {key}")
+
+            result = typing.cast(dict[str, JsonType], results[0])
+            id = typing.cast(str, result["id"])
+
+            self._space_key_to_id[key] = id
+
+        return id
+
     def get_attachment_by_name(
-        self, page_id: str, filename: str, *, space_key: Optional[str] = None
+        self, page_id: str, filename: str
     ) -> ConfluenceAttachment:
-        path = f"/content/{page_id}/child/attachment"
-        query = {"spaceKey": space_key or self.space_key, "filename": filename}
-        data = typing.cast(Dict[str, JsonType], self._invoke(path, query))
+        path = f"/pages/{page_id}/attachments"
+        query = {"filename": filename}
+        data = typing.cast(
+            dict[str, JsonType], self._invoke(ConfluenceVersion.VERSION_2, path, query)
+        )
 
-        results = typing.cast(List[JsonType], data["results"])
+        results = typing.cast(list[JsonType], data["results"])
         if len(results) != 1:
             raise ConfluenceError(f"no such attachment on page {page_id}: {filename}")
-        result = typing.cast(Dict[str, JsonType], results[0])
+        result = typing.cast(dict[str, JsonType], results[0])
 
         id = typing.cast(str, result["id"])
-        extensions = typing.cast(Dict[str, JsonType], result["extensions"])
-        media_type = typing.cast(str, extensions["mediaType"])
-        file_size = typing.cast(int, extensions["fileSize"])
-        comment = extensions.get("comment", "")
-        comment = typing.cast(str, comment)
+        media_type = typing.cast(str, result["mediaType"])
+        file_size = typing.cast(int, result["fileSize"])
+        comment = typing.cast(str, result.get("comment", ""))
         return ConfluenceAttachment(id, media_type, file_size, comment)
 
     def upload_attachment(
@@ -205,9 +273,7 @@ class ConfluenceSession:
             raise ConfluenceError(f"file not found: {attachment_path}")
 
         try:
-            attachment = self.get_attachment_by_name(
-                page_id, attachment_name, space_key=space_key
-            )
+            attachment = self.get_attachment_by_name(page_id, attachment_name)
 
             if attachment_path is not None:
                 if not force and attachment.file_size == attachment_path.stat().st_size:
@@ -226,7 +292,7 @@ class ConfluenceSession:
         except ConfluenceError:
             path = f"/content/{page_id}/child/attachment"
 
-        url = self._build_url(path)
+        url = self._build_url(ConfluenceVersion.VERSION_1, path)
 
         if attachment_path is not None:
             with open(attachment_path, "rb") as attachment_file:
@@ -304,7 +370,7 @@ class ConfluenceSession:
         }
 
         LOGGER.info("Updating attachment: %s", attachment_id)
-        self._save(path, data)
+        self._save(ConfluenceVersion.VERSION_1, path, data)
 
     def get_page_id_by_title(
         self,
@@ -321,82 +387,47 @@ class ConfluenceSession:
         """
 
         LOGGER.info("Looking up page with title: %s", title)
-        path = "/content"
-        query = {"title": title, "spaceKey": space_key or self.space_key}
-        data = typing.cast(Dict[str, JsonType], self._invoke(path, query))
+        path = "/pages"
+        query = {
+            "space-id": self.space_key_to_id(space_key or self.space_key),
+            "title": title,
+        }
+        payload = self._invoke(ConfluenceVersion.VERSION_2, path, query)
+        payload = typing.cast(dict[str, JsonType], payload)
 
-        results = typing.cast(List[JsonType], data["results"])
+        results = typing.cast(list[JsonType], payload["results"])
         if len(results) != 1:
-            raise ConfluenceError(f"page not found with title: {title}")
+            raise ConfluenceError(f"unique page not found with title: {title}")
 
-        result = typing.cast(Dict[str, JsonType], results[0])
+        result = typing.cast(dict[str, JsonType], results[0])
         id = typing.cast(str, result["id"])
         return id
 
-    def get_page(
-        self, page_id: str, *, space_key: Optional[str] = None
-    ) -> ConfluencePage:
+    def get_page(self, page_id: str) -> ConfluencePage:
         """
         Retrieve Confluence wiki page details.
 
         :param page_id: The Confluence page ID.
-        :param space_key: The Confluence space key (unless the default space is to be used).
         :returns: Confluence page info.
         """
 
-        path = f"/content/{page_id}"
-        query = {
-            "spaceKey": space_key or self.space_key,
-            "expand": "body.storage,version",
-        }
-
-        data = typing.cast(Dict[str, JsonType], self._invoke(path, query))
-        version = typing.cast(Dict[str, JsonType], data["version"])
-        body = typing.cast(Dict[str, JsonType], data["body"])
-        storage = typing.cast(Dict[str, JsonType], body["storage"])
+        path = f"/pages/{page_id}"
+        query = {"body-format": "storage"}
+        payload = self._invoke(ConfluenceVersion.VERSION_2, path, query)
+        data = typing.cast(dict[str, JsonType], payload)
+        version = typing.cast(dict[str, JsonType], data["version"])
+        body = typing.cast(dict[str, JsonType], data["body"])
+        storage = typing.cast(dict[str, JsonType], body["storage"])
 
         return ConfluencePage(
             id=page_id,
-            space_key=space_key or self.space_key,
+            space_id=typing.cast(str, data["spaceId"]),
             title=typing.cast(str, data["title"]),
             version=typing.cast(int, version["number"]),
             content=typing.cast(str, storage["value"]),
         )
 
-    def get_page_ancestors(
-        self, page_id: str, *, space_key: Optional[str] = None
-    ) -> Dict[str, str]:
-        """
-        Retrieve Confluence wiki page ancestors.
-
-        :param page_id: The Confluence page ID.
-        :param space_key: The Confluence space key (unless the default space is to be used).
-        :returns: Dictionary of ancestor page ID to title, with topmost ancestor first.
-        """
-
-        path = f"/content/{page_id}"
-        query = {
-            "spaceKey": space_key or self.space_key,
-            "expand": "ancestors",
-        }
-        data = typing.cast(Dict[str, JsonType], self._invoke(path, query))
-        ancestors = typing.cast(List[JsonType], data["ancestors"])
-
-        # from the JSON array of ancestors, extract the "id" and "title"
-        results: Dict[str, str] = {}
-        for node in ancestors:
-            ancestor = typing.cast(Dict[str, JsonType], node)
-            id = typing.cast(str, ancestor["id"])
-            title = typing.cast(str, ancestor["title"])
-            results[id] = title
-        return results
-
-    def get_page_version(
-        self,
-        page_id: str,
-        *,
-        space_key: Optional[str] = None,
-    ) -> int:
+    def get_page_version(self, page_id: str) -> int:
         """
         Retrieve a Confluence wiki page version.
 
@@ -405,13 +436,10 @@ class ConfluenceSession:
         :returns: Confluence page version.
         """
 
-        path = f"/content/{page_id}"
-        query = {
-            "spaceKey": space_key or self.space_key,
-            "expand": "version",
-        }
-        data = typing.cast(Dict[str, JsonType], self._invoke(path, query))
-        version = typing.cast(Dict[str, JsonType], data["version"])
+        path = f"/pages/{page_id}"
+        payload = self._invoke(ConfluenceVersion.VERSION_2, path)
+        data = typing.cast(dict[str, JsonType], payload)
+        version = typing.cast(dict[str, JsonType], data["version"])
         return typing.cast(int, version["number"])
 
     def update_page(
@@ -419,30 +447,39 @@ class ConfluenceSession:
         page_id: str,
         new_content: str,
         *,
-        space_key: Optional[str] = None,
+        title: Optional[str] = None,
     ) -> None:
-        page = self.get_page(page_id, space_key=space_key)
+        """
+        Update a page via the Confluence API.
+
+        :param page_id: The Confluence page ID.
+        :param new_content: Confluence Storage Format XHTML.
+        :param space_key: The Confluence space key (unless the default space is to be used).
+        :param title: New title to assign to the page. Needs to be unique within a space.
+        """
+
+        page = self.get_page(page_id)
+        new_title = title or page.title
 
         try:
             old_content = sanitize_confluence(page.content)
-            if old_content == new_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"/content/{page_id}"
+        path = f"/pages/{page_id}"
         data = {
             "id": page_id,
-            "type": "page",
-            "title": page.title,  # title needs to be unique within a space so the original title is maintained
-            "space": {"key": space_key or self.space_key},
+            "status": "current",
+            "title": new_title,
             "body": {"storage": {"value": new_content, "representation": "storage"}},
             "version": {"minorEdit": True, "number": page.version + 1},
         }
 
         LOGGER.info("Updating page: %s", page_id)
-        self._save(path, data)
+        self._save(ConfluenceVersion.VERSION_2, path, data)
 
     def create_page(
         self,
@@ -452,18 +489,22 @@ class ConfluenceSession:
         *,
         space_key: Optional[str] = None,
     ) -> ConfluencePage:
-        path = "/content/"
+        """
+        Create a new page via Confluence API.
+        """
+
+        path = "/pages/"
         query = {
-            "type": "page",
+            "spaceId": self.space_key_to_id(space_key or self.space_key),
+            "status": "current",
             "title": title,
-            "space": {"key": space_key or self.space_key},
+            "parentId": parent_page_id,
             "body": {"storage": {"value": new_content, "representation": "storage"}},
-            "ancestors": [{"type": "page", "id": parent_page_id}],
         }
 
         LOGGER.info("Creating page: %s", title)
 
-        url = self._build_url(path)
+        url = self._build_url(ConfluenceVersion.VERSION_2, path)
         response = self.session.post(
             url,
             data=json.dumps(query),
@@ -471,43 +512,66 @@ class ConfluenceSession:
         )
         response.raise_for_status()
 
-        data = typing.cast(Dict[str, JsonType], response.json())
-        version = typing.cast(Dict[str, JsonType], data["version"])
-        body = typing.cast(Dict[str, JsonType], data["body"])
-        storage = typing.cast(Dict[str, JsonType], body["storage"])
+        data = typing.cast(dict[str, JsonType], response.json())
+        version = typing.cast(dict[str, JsonType], data["version"])
+        body = typing.cast(dict[str, JsonType], data["body"])
+        storage = typing.cast(dict[str, JsonType], body["storage"])
 
         return ConfluencePage(
             id=typing.cast(str, data["id"]),
-            space_key=space_key or self.space_key,
+            space_id=typing.cast(str, data["spaceId"]),
             title=typing.cast(str, data["title"]),
             version=typing.cast(int, version["number"]),
             content=typing.cast(str, storage["value"]),
         )
 
+    def delete_page(self, page_id: str, *, purge: bool = False) -> None:
+        """
+        Delete a page via Confluence API.
+
+        :param page_id: The Confluence page ID.
+        :param purge: True to completely purge the page, False to move to trash only.
+        """
+
+        path = f"/pages/{page_id}"
+
+        # move to trash
+        url = self._build_url(ConfluenceVersion.VERSION_2, path)
+        LOGGER.info("Moving page to trash: %s", page_id)
+        response = self.session.delete(url)
+        response.raise_for_status()
+
+        if purge:
+            # purge from trash
+            query = {"purge": "true"}
+            url = self._build_url(ConfluenceVersion.VERSION_2, path, query)
+            LOGGER.info("Permanently deleting page: %s", page_id)
+            response = self.session.delete(url)
+            response.raise_for_status()
+
     def page_exists(
         self, title: str, *, space_key: Optional[str] = None
     ) -> Optional[str]:
-        path = "/content"
+        path = "/pages"
         query = {
-            "type": "page",
             "title": title,
-            "spaceKey": space_key or self.space_key,
+            "space-id": self.space_key_to_id(space_key or self.space_key),
         }
 
         LOGGER.info("Checking if page exists with title: %s", title)
 
-        url = self._build_url(path)
+        url = self._build_url(ConfluenceVersion.VERSION_2, path)
         response = self.session.get(
             url, params=query, headers={"Content-Type": "application/json"}
         )
         response.raise_for_status()
 
-        data = typing.cast(Dict[str, JsonType], response.json())
-        results = typing.cast(List, data["results"])
+        data = typing.cast(dict[str, JsonType], response.json())
+        results = typing.cast(list[JsonType], data["results"])
 
         if len(results) == 1:
-            page_info = typing.cast(Dict[str, JsonType], results[0])
-            return typing.cast(str, page_info["id"])
+            result = typing.cast(dict[str, JsonType], results[0])
+            return typing.cast(str, result["id"])
         else:
             return None
 

md2conf/application.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2024, Levente Hunyadi
+Copyright 2022-2025, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -9,9 +9,7 @@ Copyright 2022-2024, Levente Hunyadi
 import logging
 import os.path
 from pathlib import Path
-from typing import Dict, List, Optional
-
-import yaml
+from typing import Optional
 
 from .api import ConfluencePage, ConfluenceSession
 from .converter import (
@@ -20,7 +18,7 @@ from .converter import (
     ConfluencePageMetadata,
     ConfluenceQualifiedID,
     attachment_name,
-    extract_frontmatter,
+    extract_frontmatter_title,
     extract_qualified_id,
     read_qualified_id,
 )
@@ -79,7 +77,7 @@ class Application:
         LOGGER.info("Synchronizing directory: %s", local_dir)
 
         # Step 1: build index of all page metadata
-        page_metadata: Dict[Path, ConfluencePageMetadata] = {}
+        page_metadata: dict[Path, ConfluencePageMetadata] = {}
         root_id = (
             ConfluenceQualifiedID(self.options.root_page_id, self.api.space_key)
             if self.options.root_page_id
@@ -96,24 +94,19 @@ class Application:
         self,
         page_path: Path,
         root_dir: Path,
-        page_metadata: Dict[Path, ConfluencePageMetadata],
+        page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
         base_path = page_path.parent
 
         LOGGER.info("Synchronizing page: %s", page_path)
         document = ConfluenceDocument(page_path, self.options, root_dir, page_metadata)
-
-        if document.id.space_key:
-            with self.api.switch_space(document.id.space_key):
-                self._update_document(document, base_path)
-        else:
-            self._update_document(document, base_path)
+        self._update_document(document, base_path)
 
     def _index_directory(
         self,
         local_dir: Path,
         root_id: Optional[ConfluenceQualifiedID],
-        page_metadata: Dict[Path, ConfluencePageMetadata],
+        page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
         "Indexes Markdown files in a directory recursively."
 
@@ -121,8 +114,8 @@ class Application:
 
         matcher = Matcher(MatcherOptions(source=".mdignore", extension="md"), local_dir)
 
-        files: List[Path] = []
-        directories: List[Path] = []
+        files: list[Path] = []
+        directories: list[Path] = []
         for entry in os.scandir(local_dir):
             if matcher.is_excluded(entry.name, entry.is_dir()):
                 continue
@@ -174,12 +167,10 @@ class Application:
             document = f.read()
 
         qualified_id, document = extract_qualified_id(document)
-        frontmatter, document = extract_frontmatter(document)
+        frontmatter_title, _ = extract_frontmatter_title(document)
 
         if qualified_id is not None:
-            confluence_page = self.api.get_page(
-                qualified_id.page_id, space_key=qualified_id.space_key
-            )
+            confluence_page = self.api.get_page(qualified_id.page_id)
         else:
             if parent_id is None:
                 raise ValueError(
@@ -187,22 +178,21 @@ class Application:
                 )
 
             # assign title from frontmatter if present
-            if title is None and frontmatter is not None:
-                properties = yaml.safe_load(frontmatter)
-                if isinstance(properties, dict):
-                    property_title = properties.get("title")
-                    if isinstance(property_title, str):
-                        title = property_title
-
             confluence_page = self._create_page(
-                absolute_path, document, title, parent_id
+                absolute_path, document, title or frontmatter_title, parent_id
             )
 
+        space_key = (
+            self.api.space_id_to_key(confluence_page.space_id)
+            if confluence_page.space_id
+            else self.api.space_key
+        )
+
         return ConfluencePageMetadata(
             domain=self.api.domain,
             base_path=self.api.base_path,
             page_id=confluence_page.id,
-            space_key=confluence_page.space_key or self.api.space_key,
+            space_key=space_key,
             title=confluence_page.title or "",
         )
 
@@ -226,7 +216,7 @@ class Application:
             absolute_path,
             document,
             confluence_page.id,
-            confluence_page.space_key,
+            self.api.space_id_to_key(confluence_page.space_id),
         )
         return confluence_page
 
@@ -249,7 +239,7 @@ class Application:
 
         content = document.xhtml()
         LOGGER.debug("Generated Confluence Storage Format document:\n%s", content)
-        self.api.update_page(document.id.page_id, content)
+        self.api.update_page(document.id.page_id, content, title=document.title)
 
     def _update_markdown(
         self,
@@ -260,7 +250,7 @@ class Application:
     ) -> None:
         "Writes the Confluence page ID and space key at the beginning of the Markdown file."
 
-        content: List[str] = []
+        content: list[str] = []
 
         # check if the file has frontmatter
         index = 0