markdown-to-confluence 0.2.7__py3-none-any.whl → 0.3.1__py3-none-any.whl

md2conf/api.py

@@ -1,28 +1,27 @@
 """
 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
 
 from .converter import ParseError, sanitize_confluence
 from .properties import ConfluenceError, ConfluenceProperties
-from .util import removeprefix
 
 # a JSON type with possible `null` values
 JsonType = Union[
@@ -31,12 +30,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 +70,7 @@ class ConfluenceAttachment:
 @dataclass
 class ConfluencePage:
     id: str
-    space_key: str
+    space_id: str
     title: str
     version: int
     content: str
@@ -101,7 +105,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:
@@ -114,40 +118,67 @@ class ConfluenceSession:
     session: requests.Session
     domain: str
     base_path: str
-    space_key: str
+    space_key: Optional[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
+        self,
+        session: requests.Session,
+        domain: str,
+        base_path: str,
+        space_key: Optional[str],
     ) -> None:
         self.session = session
         self.domain = domain
         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.
+
+        :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.
+        """
 
-    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}"
+        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()
+        if len(response.text) > 240:
+            LOGGER.debug("Received HTTP payload (truncated):\n%.240s...", response.text)
+        else:
+            LOGGER.debug("Received HTTP payload:\n%s", response.text)
         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 +186,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(
@@ -184,7 +259,6 @@ class ConfluenceSession:
         raw_data: Optional[bytes] = None,
         content_type: Optional[str] = None,
         comment: Optional[str] = None,
-        space_key: Optional[str] = None,
         force: bool = False,
     ) -> None:
 
@@ -205,9 +279,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:
@@ -220,13 +292,13 @@ class ConfluenceSession:
             else:
                 raise NotImplementedError("never occurs")
 
-            id = removeprefix(attachment.id, "att")
+            id = attachment.id.removeprefix("att")
             path = f"/content/{page_id}/child/attachment/{id}/data"
 
         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:
@@ -279,32 +351,23 @@ class ConfluenceSession:
         version = result["version"]["number"] + 1
 
         # ensure path component is retained in attachment name
-        self._update_attachment(
-            page_id, attachment_id, version, attachment_name, space_key=space_key
-        )
+        self._update_attachment(page_id, attachment_id, version, attachment_name)
 
     def _update_attachment(
-        self,
-        page_id: str,
-        attachment_id: str,
-        version: int,
-        attachment_title: str,
-        *,
-        space_key: Optional[str] = None,
+        self, page_id: str, attachment_id: str, version: int, attachment_title: str
     ) -> None:
-        id = removeprefix(attachment_id, "att")
+        id = attachment_id.removeprefix("att")
         path = f"/content/{page_id}/child/attachment/{id}"
         data = {
             "id": attachment_id,
             "type": "attachment",
             "status": "current",
             "title": attachment_title,
-            "space": {"key": space_key or self.space_key},
             "version": {"minorEdit": True, "number": version},
         }
 
         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,97 +384,61 @@ 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 = {
+            "title": title,
+        }
+        coalesced_space_key = space_key or self.space_key
+        if coalesced_space_key is not None:
+            query["space-id"] = self.space_key_to_id(coalesced_space_key)
 
-        results = typing.cast(List[JsonType], data["results"])
+        payload = self._invoke(ConfluenceVersion.VERSION_2, path, query)
+        payload = typing.cast(dict[str, JsonType], payload)
+
+        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.
 
         :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 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,7 +446,6 @@ class ConfluenceSession:
         page_id: str,
         new_content: str,
         *,
-        space_key: Optional[str] = None,
         title: Optional[str] = None,
     ) -> None:
         """
@@ -427,11 +453,10 @@ class ConfluenceSession:
 
         :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, space_key=space_key)
+        page = self.get_page(page_id)
         new_title = title or page.title
 
         try:
@@ -442,18 +467,17 @@ class ConfluenceSession:
         except ParseError as exc:
             LOGGER.warning(exc)
 
-        path = f"/content/{page_id}"
+        path = f"/pages/{page_id}"
         data = {
             "id": page_id,
-            "type": "page",
+            "status": "current",
             "title": new_title,
-            "space": {"key": space_key or self.space_key},
             "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,
@@ -463,18 +487,28 @@ class ConfluenceSession:
         *,
         space_key: Optional[str] = None,
     ) -> ConfluencePage:
-        path = "/content/"
+        """
+        Create a new page via Confluence API.
+        """
+
+        coalesced_space_key = space_key or self.space_key
+        if coalesced_space_key is None:
+            raise ConfluenceError(
+                "Confluence space key required for creating a new page"
+            )
+
+        path = "/pages/"
         query = {
-            "type": "page",
+            "spaceId": self.space_key_to_id(coalesced_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),
@@ -482,43 +516,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"
-        query = {
-            "type": "page",
-            "title": title,
-            "spaceKey": space_key or self.space_key,
-        }
+        path = "/pages"
+        coalesced_space_key = space_key or self.space_key
+        query = {"title": title}
+        if coalesced_space_key is not None:
+            query["space-id"] = self.space_key_to_id(coalesced_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