markdown-to-confluence 0.4.5__py3-none-any.whl → 0.4.7__py3-none-any.whl

md2conf/api.py

@@ -11,19 +11,28 @@ import enum
 import io
 import logging
 import mimetypes
+import ssl
+import sys
 import typing
 from dataclasses import dataclass
 from pathlib import Path
 from types import TracebackType
-from typing import Any, Optional, TypeVar
+from typing import Any, Optional, TypeVar, overload
 from urllib.parse import urlencode, urlparse, urlunparse
 
 import requests
+from requests.adapters import HTTPAdapter
 from strong_typing.core import JsonType
 from strong_typing.serialization import DeserializerOptions, json_dump_string, json_to_object, object_to_json
 
+from .environment import ArgumentError, ConfluenceConnectionProperties, ConfluenceError, PageError
+from .extra import override
 from .metadata import ConfluenceSiteMetadata
-from .properties import ArgumentError, ConfluenceConnectionProperties, ConfluenceError, PageError
+
+if sys.version_info >= (3, 10):
+    import truststore
+else:
+    import certifi
 
 T = TypeVar("T")
 
@@ -62,16 +71,24 @@ 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:
+@overload
+def response_cast(response_type: None, response: requests.Response) -> None: ...
+
+
+@overload
+def response_cast(response_type: type[T], response: requests.Response) -> T: ...
+
+
+def response_cast(response_type: Optional[type[T]], response: requests.Response) -> Optional[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:
+    if response_type is None:
         return None
+    else:
+        return _json_to_object(response_type, response.json())
 
 
 @enum.unique
@@ -336,9 +353,33 @@ class ConfluenceUpdateAttachmentRequest:
     version: ConfluenceContentVersion
 
 
+class TruststoreAdapter(HTTPAdapter):
+    """
+    Provides a general-case interface for HTTPS sessions to connect to HTTPS URLs.
+
+    This class implements the Transport Adapter interface in the Python library `requests`.
+
+    This class will usually be created by the :class:`requests.Session` class under the covers.
+    """
+
+    @override
+    def init_poolmanager(self, connections: int, maxsize: int, block: bool = False, **pool_kwargs: Any) -> None:
+        """
+        Adapts the pool manager to use the provided SSL context instead of the default.
+        """
+
+        if sys.version_info >= (3, 10):
+            ctx = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        else:
+            ctx = ssl.create_default_context(ssl.Purpose.SERVER_AUTH, cafile=certifi.where())
+        ctx.check_hostname = True
+        ctx.verify_mode = ssl.CERT_REQUIRED
+        super().init_poolmanager(connections, maxsize, block, ssl_context=ctx, **pool_kwargs)  # type: ignore[no-untyped-call]
+
+
 class ConfluenceAPI:
     """
-    Represents an active connection to a Confluence server.
+    Encapsulates operations that can be invoked via the [Confluence REST API](https://developer.atlassian.com/cloud/confluence/rest/v2/).
     """
 
     properties: ConfluenceConnectionProperties
@@ -348,7 +389,13 @@ class ConfluenceAPI:
         self.properties = properties or ConfluenceConnectionProperties()
 
     def __enter__(self) -> "ConfluenceSession":
+        """
+        Opens a connection to a Confluence server.
+        """
+
         session = requests.Session()
+        session.mount("https://", TruststoreAdapter())
+
         if self.properties.user_name:
             session.auth = (self.properties.user_name, self.properties.api_key)
         else:
@@ -372,6 +419,10 @@ class ConfluenceAPI:
         exc_val: Optional[BaseException],
         exc_tb: Optional[TracebackType],
     ) -> None:
+        """
+        Closes an open connection.
+        """
+
         if self.session is not None:
             self.session.close()
             self.session = None
@@ -379,7 +430,7 @@ class ConfluenceAPI:
 
 class ConfluenceSession:
     """
-    Information about an open session to a Confluence server.
+    Represents an active connection to a Confluence server.
     """
 
     session: requests.Session
@@ -407,7 +458,7 @@ class ConfluenceSession:
 
             if not domain or not base_path:
                 data = self._get(ConfluenceVersion.VERSION_2, "/spaces", ConfluenceResultSet, query={"limit": "1"})
-                base_url = data._links.base
+                base_url = data._links.base  # pyright: ignore[reportPrivateUsage]
 
                 _, domain, base_path, _, _, _ = urlparse(base_url)
                 if not base_path.endswith("/"):
@@ -418,8 +469,31 @@ class ConfluenceSession:
         if not base_path:
             raise ArgumentError("Confluence base path not specified and cannot be inferred")
         self.site = ConfluenceSiteMetadata(domain, base_path, space_key)
+
         if not api_url:
-            self.api_url = f"https://{self.site.domain}{self.site.base_path}"
+            LOGGER.info("Discovering Confluence REST API URL")
+            try:
+                # obtain cloud ID to build URL for access with scoped token
+                response = self.session.get(f"https://{self.site.domain}/_edge/tenant_info", headers={"Accept": "application/json"}, verify=True)
+                if response.text:
+                    LOGGER.debug("Received HTTP payload:\n%s", response.text)
+                response.raise_for_status()
+                cloud_id = response.json()["cloudId"]
+
+                # try next-generation REST API URL
+                LOGGER.info("Probing scoped Confluence REST API URL")
+                self.api_url = f"https://api.atlassian.com/ex/confluence/{cloud_id}/"
+                url = self._build_url(ConfluenceVersion.VERSION_2, "/spaces", {"limit": "1"})
+                response = self.session.get(url, headers={"Accept": "application/json"}, verify=True)
+                if response.text:
+                    LOGGER.debug("Received HTTP payload:\n%s", response.text)
+                response.raise_for_status()
+
+                LOGGER.info("Configured scoped Confluence REST API URL: %s", self.api_url)
+            except requests.exceptions.HTTPError:
+                # fall back to classic REST API URL
+                self.api_url = f"https://{self.site.domain}{self.site.base_path}"
+                LOGGER.info("Configured classic Confluence REST API URL: %s", self.api_url)
 
     def close(self) -> None:
         self.session.close()
@@ -454,7 +528,7 @@ class ConfluenceSession:
         "Executes an HTTP request via Confluence API."
 
         url = self._build_url(version, path, query)
-        response = self.session.get(url, headers={"Accept": "application/json"})
+        response = self.session.get(url, headers={"Accept": "application/json"}, verify=True)
         if response.text:
             LOGGER.debug("Received HTTP payload:\n%s", response.text)
         response.raise_for_status()
@@ -466,7 +540,7 @@ class ConfluenceSession:
         items: list[JsonType] = []
         url = self._build_url(ConfluenceVersion.VERSION_2, path, query)
         while True:
-            response = self.session.get(url, headers={"Accept": "application/json"})
+            response = self.session.get(url, headers={"Accept": "application/json"}, verify=True)
             response.raise_for_status()
 
             payload = typing.cast(dict[str, JsonType], response.json())
@@ -482,42 +556,42 @@ class ConfluenceSession:
 
         return items
 
-    def _build_request(self, version: ConfluenceVersion, path: str, body: Any, response_type: type[T]) -> tuple[str, dict[str, str], bytes]:
+    def _build_request(self, version: ConfluenceVersion, path: str, body: Any, response_type: Optional[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",
-            }
+        headers = {"Content-Type": "application/json"}
+        if response_type is not None:
+            headers["Accept"] = "application/json"
         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:
+    @overload
+    def _post(self, version: ConfluenceVersion, path: str, body: Any, response_type: None) -> None: ...
+
+    @overload
+    def _post(self, version: ConfluenceVersion, path: str, body: Any, response_type: type[T]) -> T: ...
+
+    def _post(self, version: ConfluenceVersion, path: str, body: Any, response_type: Optional[type[T]]) -> Optional[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,
-        )
+        response = self.session.post(url, data=data, headers=headers, verify=True)
+        response.raise_for_status()
         return response_cast(response_type, response)
 
-    def _put(self, version: ConfluenceVersion, path: str, body: Any, response_type: type[T]) -> T:
+    @overload
+    def _put(self, version: ConfluenceVersion, path: str, body: Any, response_type: None) -> None: ...
+
+    @overload
+    def _put(self, version: ConfluenceVersion, path: str, body: Any, response_type: type[T]) -> T: ...
+
+    def _put(self, version: ConfluenceVersion, path: str, body: Any, response_type: Optional[type[T]]) -> Optional[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=data,
-            headers=headers,
-        )
+        response = self.session.put(url, data=data, headers=headers, verify=True)
+        response.raise_for_status()
         return response_cast(response_type, response)
 
     def space_id_to_key(self, id: str) -> str:
@@ -687,6 +761,7 @@ class ConfluenceSession:
                         "X-Atlassian-Token": "no-check",
                         "Accept": "application/json",
                     },
+                    verify=True,
                 )
         elif raw_data is not None:
             LOGGER.info("Uploading raw data: %s", attachment_name)
@@ -714,6 +789,7 @@ class ConfluenceSession:
                     "X-Atlassian-Token": "no-check",
                     "Accept": "application/json",
                 },
+                verify=True,
             )
         else:
             raise NotImplementedError("parameter match not exhaustive")
@@ -744,7 +820,7 @@ class ConfluenceSession:
         )
 
         LOGGER.info("Updating attachment: %s", attachment_id)
-        self._put(ConfluenceVersion.VERSION_1, path, request, type(None))
+        self._put(ConfluenceVersion.VERSION_1, path, request, None)
 
     def get_page_properties_by_title(
         self,
@@ -837,7 +913,7 @@ class ConfluenceSession:
             version=ConfluenceContentVersion(number=version, minorEdit=True),
         )
         LOGGER.info("Updating page: %s", page_id)
-        self._put(ConfluenceVersion.VERSION_2, path, request, type(None))
+        self._put(ConfluenceVersion.VERSION_2, path, request, None)
 
     def create_page(
         self,
@@ -872,9 +948,10 @@ class ConfluenceSession:
             url,
             data=json_dump_string(object_to_json(request)).encode("utf-8"),
             headers={
-                "Content-Type": "application/json; charset=utf-8",
+                "Content-Type": "application/json",
                 "Accept": "application/json",
             },
+            verify=True,
         )
         response.raise_for_status()
         return _json_to_object(ConfluencePage, response.json())
@@ -892,7 +969,7 @@ class ConfluenceSession:
         # 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 = self.session.delete(url, verify=True)
         response.raise_for_status()
 
         if purge:
@@ -900,7 +977,7 @@ class ConfluenceSession:
             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 = self.session.delete(url, verify=True)
             response.raise_for_status()
 
     def page_exists(
@@ -932,9 +1009,10 @@ class ConfluenceSession:
             url,
             params=query,
             headers={
-                "Content-Type": "application/json; charset=utf-8",
+                "Content-Type": "application/json",
                 "Accept": "application/json",
             },
+            verify=True,
         )
         response.raise_for_status()
         data = typing.cast(dict[str, JsonType], response.json())
@@ -984,7 +1062,7 @@ class ConfluenceSession:
         """
 
         path = f"/content/{page_id}/label"
-        self._post(ConfluenceVersion.VERSION_1, path, labels, type(None))
+        self._post(ConfluenceVersion.VERSION_1, path, labels, None)
 
     def remove_labels(self, page_id: str, labels: list[ConfluenceLabel]) -> None:
         """
@@ -999,7 +1077,7 @@ class ConfluenceSession:
             query = {"name": label.name}
 
             url = self._build_url(ConfluenceVersion.VERSION_1, path, query)
-            response = self.session.delete(url)
+            response = self.session.delete(url, verify=True)
             if response.text:
                 LOGGER.debug("Received HTTP payload:\n%s", response.text)
             response.raise_for_status()
@@ -1058,7 +1136,7 @@ class ConfluenceSession:
 
         path = f"/pages/{page_id}/properties/{property_id}"
         url = self._build_url(ConfluenceVersion.VERSION_2, path)
-        response = self.session.delete(url)
+        response = self.session.delete(url, verify=True)
         response.raise_for_status()
 
     def update_content_property_for_page(