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

{markdown_to_confluence-0.2.7.dist-info → markdown_to_confluence-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: markdown-to-confluence
-Version: 0.2.7
+Version: 0.3.0
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -12,20 +12,20 @@ Classifier: Intended Audience :: End Users/Desktop
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: lxml>=5.3
-Requires-Dist: types-lxml>=2024.11.8
+Requires-Dist: types-lxml>=2024.12.13
 Requires-Dist: markdown>=3.7
 Requires-Dist: types-markdown>=3.7
-Requires-Dist: pymdown-extensions>=10.12
+Requires-Dist: pymdown-extensions>=10.14
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: types-PyYAML>=6.0
 Requires-Dist: requests>=2.32
@@ -57,6 +57,8 @@ This Python package
 * [Collapsed sections](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
 * [Mermaid diagrams](https://mermaid.live/) in code blocks (converted to images)
 
+Whenever possible, the implementation uses [Confluence REST API v2](https://developer.atlassian.com/cloud/confluence/rest/v2/) to fetch space properties, and get, create or update page content.
+
 ## Installation
 
 Install the core package from PyPI:
@@ -160,6 +162,41 @@ First, *md2conf* builds an index of pages in the directory hierarchy. The index
 
 If a Markdown file doesn't yet pair up with a Confluence page, *md2conf* creates a new page and assigns a parent. Parent-child relationships are reflected in the navigation panel in Confluence. You can set a root page ID with the command-line option `-r`, which constitutes the topmost parent. (This could correspond to the landing page of your Confluence space. The Confluence page ID is always revealed when you edit a page.) Whenever a directory contains the file `index.md` or `README.md`, this page becomes the future parent page, and all Markdown files in this directory (and possibly nested directories) become its child pages (unless they already have a page ID). However, if an `index.md` or `README.md` file is subsequently found in one of the nested directories, it becomes the parent page of that directory, and any of its subdirectories.
 
+The concepts above are illustrated in the following sections.
+
+#### File-system directory hierarchy
+
+The title of each Markdown file (either the text of the first heading (`#`), or the title specified in front-matter) is shown next to the file name.
+
+```
+.
+├── computer-science
+│   ├── index.md: Introduction to computer science
+│   ├── algebra.md: Linear algebra
+│   └── algorithms.md: Theory of algorithms
+└── machine-learning
+    ├── README.md: AI and ML
+    ├── awareness.md: Consciousness and intelligence
+    └── statistics
+        ├── index.md: Introduction to statistics
+        └── median.md: Mean vs. median
+```
+
+#### Page hierarchy in Confluence
+
+Observe how `index.md` and `README.md` files have assumed parent (or ancestor) role for any Markdown files in the same directory (or below).
+
+```
+root
+├── Introduction to computer science
+│   ├── Linear algebra
+│   └── Theory of algorithms
+└── AI and ML
+    ├── Consciousness and intelligence
+    └── Introduction to statistics
+        └── Mean vs. median
+```
+
 ### Ignoring files
 
 Skip files in a directory with rules defined in `.mdignore`. Each rule should occupy a single line. Rules follow the syntax of [fnmatch](https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatch). Specifically, `?` matches any single character, and `*` matches zero or more characters. For example, use `up-*.md` to exclude Markdown files that start with `up-`. Lines that start with `#` are treated as comments.
@@ -214,7 +251,7 @@ options:
   --local               Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.
   --headers [KEY=VALUE ...]
                         Apply custom headers to all Confluence API requests.
-  --webui-links         Enable Confluence Web UI links.
+  --webui-links         Enable Confluence Web UI links. (Typically required for on-prem versions of Confluence.)
 ```
 
 ### Using the Docker container

markdown_to_confluence-0.3.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+md2conf/__init__.py,sha256=Lveuwj776s0e_lokulqzAtv64eStsiMROB96DimCLd0,402
+md2conf/__main__.py,sha256=Sga_W_b5E1YokJcBAXcmZVnYk-us8A0kkhfkmdHogsg,6883
+md2conf/api.py,sha256=KIZNwdsMGXYy9i4FHSe0XbbCjjVJzTTlnryGesxM-GI,19312
+md2conf/application.py,sha256=Udp79iB0bGc7sPmE3jD7PSK35yedS_XBhfTEVap91-o,8777
+md2conf/converter.py,sha256=BlS51hjiJd0lgrh5wJkun1_FZ9kAtmInKjEYhr5YOLA,36620
+md2conf/emoji.py,sha256=IZeguWqcboeOyJkGLTVONDMO4ZXfYXPgfkp56PTI-hE,1924
+md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
+md2conf/matcher.py,sha256=FgMFPvGiOqGezCs8OyerfsVo-iIHFoI6LRMzdcjM5UY,3693
+md2conf/mermaid.py,sha256=82NGv6x_LNrN3c-VPx368KCBO87_Sv8-uz2ue40DzKg,2192
+md2conf/processor.py,sha256=G-MIh1jGq9jjgogHnlnRUSrNgiV6_xO6Fy7ct9alqgM,4769
+md2conf/properties.py,sha256=HqFveB-Wgg29e60tARHSk21l8b-SCk953eb_Mw-nI80,1984
+md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
+md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/util.py,sha256=Ct7T21oI2AUs6hIZVNljPhq5HbNscjnFXMpVCzRlRHw,743
+markdown_to_confluence-0.3.0.dist-info/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
+markdown_to_confluence-0.3.0.dist-info/METADATA,sha256=oAWMGSnPXtLZZyDiwNdbb4QWwEP0uXPxzKiBqY9mfT0,14936
+markdown_to_confluence-0.3.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+markdown_to_confluence-0.3.0.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.3.0.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.3.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.3.0.dist-info/RECORD,,

{markdown_to_confluence-0.2.7.dist-info → markdown_to_confluence-0.3.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.6.0)
+Generator: setuptools (75.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

md2conf/__init__.py

@@ -5,9 +5,9 @@ Parses Markdown files, converts Markdown content into the Confluence Storage For
 Confluence API endpoints to upload images and content.
 """
 
-__version__ = "0.2.7"
+__version__ = "0.3.0"
 __author__ = "Levente Hunyadi"
-__copyright__ = "Copyright 2022-2024, Levente Hunyadi"
+__copyright__ = "Copyright 2022-2025, Levente Hunyadi"
 __license__ = "MIT"
 __maintainer__ = "Levente Hunyadi"
 __status__ = "Production"

md2conf/__main__.py

@@ -4,7 +4,7 @@ Publish Markdown files to Confluence wiki.
 Parses Markdown files, converts Markdown content into the Confluence Storage Format (XHTML), and invokes
 Confluence API endpoints to upload images and content.
 
-Copyright 2022-2024, Levente Hunyadi
+Copyright 2022-2025, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -41,6 +41,8 @@ class Arguments(argparse.Namespace):
     generated_by: Optional[str]
     render_mermaid: bool
     diagram_output_format: Literal["png", "svg"]
+    local: bool
+    headers: dict[str, str]
     webui_links: bool
 
 
@@ -169,14 +171,12 @@ def main() -> None:
         "--webui-links",
         action="store_true",
         default=False,
-        help="Enable Confluence Web UI links.",
+        help="Enable Confluence Web UI links. (Typically required for on-prem versions of Confluence.)",
     )
 
     args = Arguments()
     parser.parse_args(namespace=args)
 
-    # NOTE:  If we switch to modern type aware CLI tool like typer
-    #  the following line won't be necessary
     args.mdpath = Path(args.mdpath)
 
     logging.basicConfig(

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,7 +447,6 @@ class ConfluenceSession:
         page_id: str,
         new_content: str,
         *,
-        space_key: Optional[str] = None,
         title: Optional[str] = None,
     ) -> None:
         """
@@ -431,7 +458,7 @@ class ConfluenceSession:
         :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 +469,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 +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),
@@ -482,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,7 +9,7 @@ Copyright 2022-2024, Levente Hunyadi
 import logging
 import os.path
 from pathlib import Path
-from typing import Dict, List, Optional
+from typing import Optional
 
 from .api import ConfluencePage, ConfluenceSession
 from .converter import (
@@ -77,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
@@ -94,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."
 
@@ -119,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
@@ -175,9 +170,7 @@ class Application:
         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(
@@ -189,11 +182,17 @@ class Application:
                 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 "",
         )
 
@@ -217,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
 
@@ -251,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

md2conf/converter.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
 """
@@ -18,7 +18,7 @@ import uuid
 import xml.etree.ElementTree
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Dict, List, Literal, Optional, Tuple, Union
+from typing import Any, Literal, Optional, Union
 from urllib.parse import ParseResult, urlparse, urlunparse
 
 import lxml.etree as ET
@@ -46,7 +46,7 @@ class ParseError(RuntimeError):
     pass
 
 
-def starts_with_any(text: str, prefixes: List[str]) -> bool:
+def starts_with_any(text: str, prefixes: list[str]) -> bool:
     "True if text starts with any of the listed prefixes."
 
     for prefix in prefixes:
@@ -73,7 +73,7 @@ def emoji_generator(
     alt: str,
     title: Optional[str],
     category: Optional[str],
-    options: Dict[str, Any],
+    options: dict[str, Any],
     md: markdown.Markdown,
 ) -> xml.etree.ElementTree.Element:
     name = (alias or shortname).strip(":")
@@ -107,7 +107,7 @@ def markdown_to_html(content: str) -> str:
     )
 
 
-def _elements_from_strings(dtd_path: Path, items: List[str]) -> ET._Element:
+def _elements_from_strings(dtd_path: Path, items: list[str]) -> ET._Element:
     """
     Creates a fragment of several XML nodes from their string representation wrapped in a root element.
 
@@ -141,7 +141,7 @@ def _elements_from_strings(dtd_path: Path, items: List[str]) -> ET._Element:
         raise ParseError(e)
 
 
-def elements_from_strings(items: List[str]) -> ET._Element:
+def elements_from_strings(items: list[str]) -> ET._Element:
     "Creates a fragment of several XML nodes from their string representation wrapped in a root element."
 
     if sys.version_info >= (3, 9):
@@ -287,7 +287,7 @@ class ConfluenceConverterOptions:
         conversion rules for the identifier.
     :param render_mermaid: Whether to pre-render Mermaid diagrams into PNG/SVG images.
     :param diagram_output_format: Target image format for diagrams.
-    :param web_links: When true, convert relative URLs to Confluence Web UI links.
+    :param webui_links: When true, convert relative URLs to Confluence Web UI links.
     """
 
     ignore_invalid_url: bool = False
@@ -304,17 +304,17 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
     path: Path
     base_dir: Path
     root_dir: Path
-    links: List[str]
-    images: List[Path]
-    embedded_images: Dict[str, bytes]
-    page_metadata: Dict[Path, ConfluencePageMetadata]
+    links: list[str]
+    images: list[Path]
+    embedded_images: dict[str, bytes]
+    page_metadata: dict[Path, ConfluencePageMetadata]
 
     def __init__(
         self,
         options: ConfluenceConverterOptions,
         path: Path,
         root_dir: Path,
-        page_metadata: Dict[Path, ConfluencePageMetadata],
+        page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
         super().__init__()
         self.options = options
@@ -438,7 +438,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         if not src:
             raise DocumentError("image lacks `src` attribute")
 
-        attributes: Dict[str, Any] = {
+        attributes: dict[str, Any] = {
             ET.QName(namespaces["ac"], "align"): "center",
             ET.QName(namespaces["ac"], "layout"): "center",
         }
@@ -457,11 +457,11 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             return self._transform_attached_image(Path(src), caption, attributes)
 
     def _transform_external_image(
-        self, url: str, caption: Optional[str], attributes: Dict[str, Any]
+        self, url: str, caption: Optional[str], attributes: dict[str, Any]
     ) -> ET._Element:
         "Emits Confluence Storage Format XHTML for an external image."
 
-        elements: List[ET._Element] = []
+        elements: list[ET._Element] = []
         elements.append(
             RI(
                 "url",
@@ -475,7 +475,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         return AC("image", attributes, *elements)
 
     def _transform_attached_image(
-        self, path: Path, caption: Optional[str], attributes: Dict[str, Any]
+        self, path: Path, caption: Optional[str], attributes: dict[str, Any]
     ) -> ET._Element:
         "Emits Confluence Storage Format XHTML for an attached image."
 
@@ -487,7 +487,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         self.images.append(path)
         image_name = attachment_name(path)
 
-        elements: List[ET._Element] = []
+        elements: list[ET._Element] = []
         elements.append(
             RI(
                 "attachment",
@@ -525,7 +525,7 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
             AC(
                 "parameter",
                 {ET.QName(namespaces["ac"], "name"): "theme"},
-                "Midnight",
+                "Default",
             ),
             AC(
                 "parameter",
@@ -899,8 +899,8 @@ class DocumentError(RuntimeError):
     pass
 
 
-def extract_value(pattern: str, text: str) -> Tuple[Optional[str], str]:
-    values: List[str] = []
+def extract_value(pattern: str, text: str) -> tuple[Optional[str], str]:
+    values: list[str] = []
 
     def _repl_func(matchobj: re.Match) -> str:
         values.append(matchobj.group(1))
@@ -921,7 +921,7 @@ class ConfluenceQualifiedID:
         self.space_key = space_key
 
 
-def extract_qualified_id(text: str) -> Tuple[Optional[ConfluenceQualifiedID], str]:
+def extract_qualified_id(text: str) -> tuple[Optional[ConfluenceQualifiedID], str]:
     "Extracts the Confluence page ID and space key from a Markdown document."
 
     page_id, text = extract_value(r"<!--\s+confluence-page-id:\s*(\d+)\s+-->", text)
@@ -935,13 +935,13 @@ def extract_qualified_id(text: str) -> Tuple[Optional[ConfluenceQualifiedID], st
     return ConfluenceQualifiedID(page_id, space_key), text
 
 
-def extract_frontmatter(text: str) -> Tuple[Optional[str], str]:
+def extract_frontmatter(text: str) -> tuple[Optional[str], str]:
     "Extracts the front matter from a Markdown document."
 
     return extract_value(r"(?ms)\A---$(.+?)^---$", text)
 
 
-def extract_frontmatter_title(text: str) -> Tuple[Optional[str], str]:
+def extract_frontmatter_title(text: str) -> tuple[Optional[str], str]:
     frontmatter, text = extract_frontmatter(text)
 
     title: Optional[str] = None
@@ -974,8 +974,8 @@ class ConfluenceDocumentOptions:
         plain text; when false, raise an exception.
     :param heading_anchors: When true, emit a structured macro *anchor* for each section heading using GitHub
         conversion rules for the identifier.
-    :param generated_by: Text to use as the generated-by prompt.
-    :param show_generated: Whether to display a prompt "This page has been generated with a tool."
+    :param generated_by: Text to use as the generated-by prompt (or `None` to omit a prompt).
+    :param root_page_id: Confluence page to assume root page role for publishing a directory of Markdown files.
     :param render_mermaid: Whether to pre-render Mermaid diagrams into PNG/SVG images.
     :param diagram_output_format: Target image format for diagrams.
     :param webui_links: When true, convert relative URLs to Confluence Web UI links.
@@ -993,8 +993,8 @@ class ConfluenceDocumentOptions:
 class ConfluenceDocument:
     id: ConfluenceQualifiedID
     title: Optional[str]
-    links: List[str]
-    images: List[Path]
+    links: list[str]
+    images: list[Path]
 
     options: ConfluenceDocumentOptions
     root: ET._Element
@@ -1004,7 +1004,7 @@ class ConfluenceDocument:
         path: Path,
         options: ConfluenceDocumentOptions,
         root_dir: Path,
-        page_metadata: Dict[Path, ConfluencePageMetadata],
+        page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
         self.options = options
         path = path.resolve(True)

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

md2conf/matcher.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
 """
@@ -10,12 +10,17 @@ import os.path
 from dataclasses import dataclass
 from fnmatch import fnmatch
 from pathlib import Path
-from typing import Iterable, List, Optional
+from typing import Iterable, Optional
 
 
 @dataclass
 class Entry:
-    "Represents a file or directory entry."
+    """
+    Represents a file or directory entry.
+
+    :param name: Name of the file-system entry.
+    :param is_dir: True if the entry is a directory.
+    """
 
     name: str
     is_dir: bool
@@ -42,7 +47,7 @@ class Matcher:
     "Compares file and directory names against a list of exclude/include patterns."
 
     options: MatcherOptions
-    rules: List[str]
+    rules: list[str]
 
     def __init__(self, options: MatcherOptions, directory: Path) -> None:
         self.options = options
@@ -92,7 +97,7 @@ class Matcher:
 
         return not self.is_excluded(name, is_dir)
 
-    def filter(self, items: Iterable[Entry]) -> List[Entry]:
+    def filter(self, items: Iterable[Entry]) -> list[Entry]:
         """
         Returns only those elements from the input that don't match any of the exclusion rules.
 
@@ -102,7 +107,7 @@ class Matcher:
 
         return [item for item in items if self.is_included(item.name, item.is_dir)]
 
-    def scandir(self, path: Path) -> List[Entry]:
+    def scandir(self, path: Path) -> list[Entry]:
         """
         Returns only those entries in a directory whose name doesn't match any of the exclusion rules.
 

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

md2conf/processor.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
 """
@@ -10,7 +10,7 @@ import hashlib
 import logging
 import os
 from pathlib import Path
-from typing import Dict, List, Optional
+from typing import Optional
 
 from .converter import (
     ConfluenceDocument,
@@ -60,7 +60,7 @@ class Processor:
         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] = {}
         self._index_directory(local_dir, page_metadata)
         LOGGER.info("Indexed %d page(s)", len(page_metadata))
 
@@ -83,7 +83,7 @@ class Processor:
         self,
         path: Path,
         root_dir: Path,
-        page_metadata: Dict[Path, ConfluencePageMetadata],
+        page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
         "Processes a single Markdown file."
 
@@ -95,7 +95,7 @@ class Processor:
     def _index_directory(
         self,
         local_dir: Path,
-        page_metadata: Dict[Path, ConfluencePageMetadata],
+        page_metadata: dict[Path, ConfluencePageMetadata],
     ) -> None:
         "Indexes Markdown files in a directory recursively."
 
@@ -103,8 +103,8 @@ class Processor:
 
         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

md2conf/properties.py

@@ -1,13 +1,13 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2024, Levente Hunyadi
+Copyright 2022-2025, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
 
 import os
-from typing import Dict, Optional
+from typing import Optional
 
 
 class ConfluenceError(RuntimeError):
@@ -20,7 +20,7 @@ class ConfluenceProperties:
     space_key: str
     user_name: Optional[str]
     api_key: str
-    headers: Optional[Dict[str, str]]
+    headers: Optional[dict[str, str]]
 
     def __init__(
         self,
@@ -29,7 +29,7 @@ class ConfluenceProperties:
         user_name: Optional[str] = None,
         api_key: Optional[str] = None,
         space_key: Optional[str] = None,
-        headers: Optional[Dict[str, str]] = None,
+        headers: Optional[dict[str, str]] = None,
     ) -> None:
         opt_domain = domain or os.getenv("CONFLUENCE_DOMAIN")
         opt_base_path = base_path or os.getenv("CONFLUENCE_PATH")

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

markdown_to_confluence-0.2.7.dist-info/RECORD

@@ -1,21 +0,0 @@
-md2conf/__init__.py,sha256=U8zdop7-AIrfwCYzWiwKfhCEPF_1QEKPt4Zwq-38LlU,402
-md2conf/__main__.py,sha256=6iOI28W_d71tlnCMFpZwvkBmBt5-HazlZsz69gS4Oak,6894
-md2conf/api.py,sha256=NmAbNWTrTSi2ZDGYymy70Fw6HcgrmB-Ua4re4yLJvVc,17715
-md2conf/application.py,sha256=-kFpMRtSpQUU1hsiW5O73gL1X9McQWpvyAAEUxEnpuU,8869
-md2conf/converter.py,sha256=S8Kka35Y99w0J00CYi-DQwsKzlHAvBfaSCf10mb1FZk,36596
-md2conf/emoji.py,sha256=w9oiOIxzObAE7HTo3f6aETT1_D3t3yZwr88ynU4ENm0,1924
-md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
-md2conf/matcher.py,sha256=mYMltZOLypK4O-SJugLgicOwUMem67hiNLg_kPFoJkU,3583
-md2conf/mermaid.py,sha256=gqA6Hg6WcPDdR7JOClezAgNZj2Gq4pXJSgmOUlUt6Dk,2192
-md2conf/processor.py,sha256=E-Na-a8tNp4CaoRPA5etcXdHXNRdgyMrf6bfKa9P7O4,4781
-md2conf/properties.py,sha256=iVIc0h0XtS3Y2LCywX1C9cvmVQ0WljOMt8pl2MDMVCI,1990
-md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
-md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-md2conf/util.py,sha256=ftf60MiW7S7rW45ipWX6efP_Sv2F2qpyIDHrGA0cBiw,743
-markdown_to_confluence-0.2.7.dist-info/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
-markdown_to_confluence-0.2.7.dist-info/METADATA,sha256=76K_O_5b__MnKT7FuLXgCHX6hR5dZio3mK6RWR4DyCA,13551
-markdown_to_confluence-0.2.7.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-markdown_to_confluence-0.2.7.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
-markdown_to_confluence-0.2.7.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.2.7.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.2.7.dist-info/RECORD,,