markdown-to-confluence 0.3.3__py3-none-any.whl → 0.3.5__py3-none-any.whl

{markdown_to_confluence-0.3.3.dist-info → markdown_to_confluence-0.3.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.3.3
+Version: 0.3.5
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -21,12 +21,12 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: lxml>=5.3
-Requires-Dist: types-lxml>=2024.12.13
-Requires-Dist: markdown>=3.7
-Requires-Dist: types-markdown>=3.7
-Requires-Dist: pymdown-extensions>=10.14
-Requires-Dist: pyyaml>=6.0
+Requires-Dist: lxml>=5.4
+Requires-Dist: types-lxml>=2025.3.30
+Requires-Dist: markdown>=3.8
+Requires-Dist: types-markdown>=3.8
+Requires-Dist: pymdown-extensions>=10.15
+Requires-Dist: PyYAML>=6.0
 Requires-Dist: types-PyYAML>=6.0
 Requires-Dist: requests>=2.32
 Requires-Dist: types-requests>=2.32
@@ -62,13 +62,13 @@ Whenever possible, the implementation uses [Confluence REST API v2](https://deve
 
 ## Installation
 
-Install the core package from PyPI:
+**Required.** Install the core package from [PyPI](https://pypi.org/project/markdown-to-confluence/):
 
 ```sh
 pip install markdown-to-confluence
 ```
 
-Converting code blocks of Mermaid diagrams into Confluence image attachments requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli):
+**Optional.** Converting code blocks of Mermaid diagrams into Confluence image attachments requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli):
 
 ```sh
 npm install -g @mermaid-js/mermaid-cli
@@ -198,20 +198,26 @@ root
         └── Mean vs. median
 ```
 
+### Lists and tables
+
+If your Markdown lists or tables don't appear in Confluence as expected, verify that the list or table is delimited by a blank line both before and after, as per strict Markdown syntax. While some previewers accept a more lenient syntax (e.g. an itemized list immediately following a paragraph), *md2conf* uses [Python-Markdown](https://python-markdown.github.io/) internally to convert Markdown into XHTML, which expects the Markdown document to adhere to the stricter syntax.
+
 ### Publishing images
 
 Local images referenced in a Markdown file are automatically published to Confluence as attachments to the page.
 
-Unfortunately, Confluence struggles with SVG images, e.g. they may only show in *edit* mode, display in a wrong size or text labels in the image may be truncated. In order to mitigate the issue, whenever *md2conf* encounters a reference to an SVG image in a Markdown file, it checks whether a corresponding PNG image also exists in the same directory, and if a PNG image is found, it is published instead.
+Unfortunately, Confluence struggles with SVG images, e.g. they may only show in *edit* mode, display in a wrong size or text labels in the image may be truncated. (This seems to be a known issue in Confluence.) In order to mitigate the issue, whenever *md2conf* encounters a reference to an SVG image in a Markdown file, it checks whether a corresponding PNG image also exists in the same directory, and if a PNG image is found, it is published instead.
 
 External images referenced with an absolute URL retain the original URL.
 
 ### 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.
+Skip files in a directory with rules defined in `.mdignore`. Each rule should occupy a single line. Rules follow the syntax (and constraints) 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.
 
 Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into.
 
+Relative paths to items in a nested directory are not supported. You must put `.mdignore` in the same directory where the items to be skipped reside.
+
 ### Page title
 
 *md2conf* makes a best-effort attempt at setting the Confluence wiki page title when it publishes a Markdown document the first time. The following are probed in this order:
@@ -222,6 +228,13 @@ Files that don't have the extension `*.md` are skipped automatically. Hidden dir
 
 If a matching Confluence page already exists for a Markdown file, the page title in Confluence is left unchanged.
 
+### Converting diagrams
+
+You can include [Mermaid diagrams](https://mermaid.js.org/) in your Markdown documents to create visual representations of systems, processes, and relationships. When a Markdown document contains a code block with the language specifier `mermaid`, *md2conf* offers two options to publish the diagram:
+
+1. Pre-render into an image. The code block is interpreted by and converted into a PNG or SVG image with the Mermaid diagram utility [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). The generated image is then uploaded to Confluence as an attachment to the page. This is the approach we use and support.
+2. Render on demand. The code block is transformed into a [diagram macro](https://atlasauthority.atlassian.net/wiki/spaces/MARKDOWNCLOUD/pages/2946826241/Diagram+Macro), which is processed by Confluence. You need a [Confluence plugin](https://marketplace.atlassian.com/apps/1211438/markdown-html-plantuml-latex-diagrams-open-api-mermaid) to turn macro definitions into images when a Confluence page is visited. This is a contributed feature. As authors of *md2conf*, we don't endorse or support any particular Confluence plugin.
+
 ### Running the tool
 
 You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:

markdown_to_confluence-0.3.5.dist-info/RECORD

@@ -0,0 +1,23 @@
+markdown_to_confluence-0.3.5.dist-info/licenses/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
+md2conf/__init__.py,sha256=Uaqb3maQScpYs3FiH8kuM6pUh5JzE4Vy52MgU9pvMTw,402
+md2conf/__main__.py,sha256=bFcfmSnTWeuhmDm7bJ3jJabZ2S8W9biuAP6_R-Cc9As,8034
+md2conf/api.py,sha256=VxrAJ4yCsdGFVAEQQWw5aONwsMz0b6KvN4EMLXCKOwE,26905
+md2conf/application.py,sha256=SIM4yLHaLnvG7wRJLbRvptrkc0q4JMuAhDnanqsuYzA,6697
+md2conf/converter.py,sha256=ASXhs7g79dOU4x1QhfvKL8mtwth508GTGcb3AUHigC4,37286
+md2conf/emoji.py,sha256=48QJtOD0F3Be1laYLvAOwe0GxrJS-vcfjtCdiBsNcAc,1960
+md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
+md2conf/local.py,sha256=998bBRpDAOywA-L0KD4_VyuL2Xftflv0ler-uNPQZn4,3866
+md2conf/matcher.py,sha256=y5WEZNklTpUoJtMJlulTvfhl_v-UMU6wySJAKit91ig,4940
+md2conf/mermaid.py,sha256=ZETocFDKi_fSYyVR1pJ7fo207YYFSuT44MSYFQ8-cZ0,2562
+md2conf/metadata.py,sha256=Xozg2PjJnis7VQYQT_edIvTb8u0cs_ZizPOAxc1N8vg,1003
+md2conf/processor.py,sha256=jSLFy8hqZJXf3b79jp31Fn9-cm4j9xq4HDChp9pyhP0,6706
+md2conf/properties.py,sha256=TOCXLdTfYkKjRwZaMgvXw0mNCI4opEUwpBXro2Kv2B4,2467
+md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
+md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/scanner.py,sha256=iF8NCQAFO6Yut5aAQr7uxfWzVMMt9j3T5ADoVVSJWKQ,3543
+markdown_to_confluence-0.3.5.dist-info/METADATA,sha256=NiXwBXtQ5WhHce_JX7TBUSefQSR5jk5fERe46BL4vwE,18462
+markdown_to_confluence-0.3.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+markdown_to_confluence-0.3.5.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.3.5.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.3.5.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.3.5.dist-info/RECORD,,

{markdown_to_confluence-0.3.3.dist-info → markdown_to_confluence-0.3.5.dist-info}/WHEEL

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

md2conf/__init__.py

@@ -5,7 +5,7 @@ Parses Markdown files, converts Markdown content into the Confluence Storage For
 Confluence API endpoints to upload images and content.
 """
 
-__version__ = "0.3.3"
+__version__ = "0.3.5"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2025, Levente Hunyadi"
 __license__ = "MIT"

md2conf/__main__.py

@@ -22,8 +22,9 @@ import requests
 from . import __version__
 from .api import ConfluenceAPI
 from .application import Application
-from .converter import ConfluenceDocumentOptions, ConfluenceSiteMetadata
-from .processor import Processor
+from .converter import ConfluenceDocumentOptions, ConfluencePageID
+from .local import LocalConverter
+from .metadata import ConfluenceSiteMetadata
 from .properties import (
     ArgumentError,
     ConfluenceConnectionProperties,
@@ -199,7 +200,7 @@ def main() -> None:
         heading_anchors=args.heading_anchors,
         ignore_invalid_url=args.ignore_invalid_url,
         generated_by=args.generated_by,
-        root_page_id=args.root_page,
+        root_page_id=ConfluencePageID(args.root_page) if args.root_page else None,
         keep_hierarchy=args.keep_hierarchy,
         render_mermaid=args.render_mermaid,
         diagram_output_format=args.diagram_output_format,
@@ -219,7 +220,7 @@ def main() -> None:
             base_path=site_properties.base_path,
             space_key=site_properties.space_key,
         )
-        Processor(options, site_metadata).process(args.mdpath)
+        LocalConverter(options, site_metadata).process(args.mdpath)
     else:
         try:
             properties = ConfluenceConnectionProperties(
@@ -237,7 +238,7 @@ def main() -> None:
                 Application(
                     api,
                     options,
-                ).synchronize(args.mdpath)
+                ).process(args.mdpath)
         except requests.exceptions.HTTPError as err:
             logging.error(err)
 

md2conf/api.py

@@ -7,6 +7,7 @@ Copyright 2022-2025, Levente Hunyadi
 """
 
 import enum
+import functools
 import io
 import json
 import logging
@@ -21,6 +22,7 @@ from urllib.parse import urlencode, urlparse, urlunparse
 import requests
 
 from .converter import ParseError, sanitize_confluence
+from .metadata import ConfluenceSiteMetadata
 from .properties import (
     ArgumentError,
     ConfluenceConnectionProperties,
@@ -41,13 +43,23 @@ JsonType = Union[
 
 
 class ConfluenceVersion(enum.Enum):
+    """
+    Confluence REST API version an HTTP request corresponds to.
+
+    For some operations, Confluence Cloud supports v2 endpoints exclusively. However, for other operations, only v1 endpoints are available via REST API.
+    Some versions of Confluence Server and Data Center, unfortunately, don't support v2 endpoints at all.
+
+    The principal use case for *md2conf* is Confluence Cloud. As such, *md2conf* uses v2 endpoints when available, and resorts to v1 endpoints only when
+    necessary.
+    """
+
     VERSION_1 = "rest/api"
     VERSION_2 = "api/v2"
 
 
 class ConfluencePageParentContentType(enum.Enum):
     """
-    Content types that can be a parent to a Confluence page
+    Content types that can be a parent to a Confluence page.
     """
 
     PAGE = "page"
@@ -76,26 +88,75 @@ def build_url(base_url: str, query: Optional[dict[str, str]] = None) -> str:
 LOGGER = logging.getLogger(__name__)
 
 
-@dataclass
+@dataclass(frozen=True)
 class ConfluenceAttachment:
+    """
+    Holds data for an object uploaded to Confluence as a page attachment.
+
+    :param id: Unique ID for the attachment.
+    :param media_type: MIME type for the attachment.
+    :param file_size: Size in bytes.
+    :param comment: Description for the attachment.
+    """
+
     id: str
     media_type: str
     file_size: int
     comment: str
 
 
-@dataclass
-class ConfluencePage:
+@dataclass(frozen=True)
+class ConfluencePageProperties:
+    """
+    Holds Confluence page properties used for page synchronization.
+
+    :param id: Confluence page ID.
+    :param space_id: Confluence space ID.
+    :param parent_id: Confluence page ID of the immediate parent.
+    :param parent_type: Identifies the content type of the parent.
+    :param title: Page title.
+    :param version: Page version. Incremented when the page is updated.
+    """
+
     id: str
     space_id: str
     parent_id: str
     parent_type: Optional[ConfluencePageParentContentType]
     title: str
     version: int
+
+
+@dataclass(frozen=True)
+class ConfluencePage(ConfluencePageProperties):
+    """
+    Holds Confluence page data used for page synchronization.
+
+    :param content: Page content in Confluence Storage Format.
+    """
+
     content: str
 
 
+@dataclass(frozen=True)
+class ConfluenceLabel:
+    """
+    Holds information about a single label.
+
+    :param id: ID of the label.
+    :param name: Name of the label.
+    :param prefix: Prefix of the label.
+    """
+
+    id: str
+    name: str
+    prefix: str
+
+
 class ConfluenceAPI:
+    """
+    Represents an active connection to a Confluence server.
+    """
+
     properties: ConfluenceConnectionProperties
     session: Optional["ConfluenceSession"] = None
 
@@ -136,10 +197,12 @@ class ConfluenceAPI:
 
 
 class ConfluenceSession:
+    """
+    Information about an open session to a Confluence server.
+    """
+
     session: requests.Session
-    domain: str
-    base_path: str
-    space_key: Optional[str]
+    site: ConfluenceSiteMetadata
 
     _space_id_to_key: dict[str, str]
     _space_key_to_id: dict[str, str]
@@ -152,9 +215,7 @@ class ConfluenceSession:
         space_key: Optional[str] = None,
     ) -> None:
         self.session = session
-        self.domain = domain
-        self.base_path = base_path
-        self.space_key = space_key
+        self.site = ConfluenceSiteMetadata(domain, base_path, space_key)
 
         self._space_id_to_key = {}
         self._space_key_to_id = {}
@@ -178,7 +239,9 @@ class ConfluenceSession:
         :returns: A full URL.
         """
 
-        base_url = f"https://{self.domain}{self.base_path}{version.value}{path}"
+        base_url = (
+            f"https://{self.site.domain}{self.site.base_path}{version.value}{path}"
+        )
         return build_url(base_url, query)
 
     def _invoke(
@@ -187,7 +250,7 @@ class ConfluenceSession:
         path: str,
         query: Optional[dict[str, str]] = None,
     ) -> JsonType:
-        "Execute an HTTP request via Confluence API."
+        "Executes an HTTP request via Confluence API."
 
         url = self._build_url(version, path, query)
         response = self.session.get(url)
@@ -196,7 +259,33 @@ class ConfluenceSession:
         response.raise_for_status()
         return response.json()
 
-    def _save(self, version: ConfluenceVersion, path: str, data: dict) -> None:
+    def _fetch(
+        self, path: str, query: Optional[dict[str, str]] = None
+    ) -> list[JsonType]:
+        "Retrieves all results of a REST API v2 paginated result-set."
+
+        items: list[JsonType] = []
+        url = self._build_url(ConfluenceVersion.VERSION_2, path, query)
+        while True:
+            response = self.session.get(url)
+            response.raise_for_status()
+
+            payload = typing.cast(dict[str, JsonType], response.json())
+            results = typing.cast(list[JsonType], payload["results"])
+            items.extend(results)
+
+            links = typing.cast(dict[str, JsonType], payload.get("_links", {}))
+            link = typing.cast(str, links.get("next", ""))
+            if link:
+                url = f"https://{self.site.domain}{link}"
+            else:
+                break
+
+        return items
+
+    def _save(self, version: ConfluenceVersion, path: str, data: JsonType) -> None:
+        "Persists data via Confluence REST API."
+
         url = self._build_url(version, path)
         response = self.session.put(
             url,
@@ -251,9 +340,36 @@ class ConfluenceSession:
 
         return id
 
+    def get_space_id(
+        self, *, space_id: Optional[str] = None, space_key: Optional[str] = None
+    ) -> Optional[str]:
+        """
+        Coalesces a space ID or space key into a space ID, accounting for site default.
+
+        :param space_id: A Confluence space ID.
+        :param space_key: A Confluence space key.
+        """
+
+        if space_id is not None and space_key is not None:
+            raise ConfluenceError("either space ID or space key is required; not both")
+
+        if space_id is not None:
+            return space_id
+
+        space_key = space_key or self.site.space_key
+        if space_key is not None:
+            return self.space_key_to_id(space_key)
+
+        # space ID and key are unset, and no default space is configured
+        return None
+
     def get_attachment_by_name(
         self, page_id: str, filename: str
     ) -> ConfluenceAttachment:
+        """
+        Retrieves a Confluence page attachment by an unprefixed file name.
+        """
+
         path = f"/pages/{page_id}/attachments"
         query = {"filename": filename}
         data = typing.cast(
@@ -282,6 +398,18 @@ class ConfluenceSession:
         comment: Optional[str] = None,
         force: bool = False,
     ) -> None:
+        """
+        Uploads a new attachment to a Confluence page.
+
+        :param page_id: Confluence page ID.
+        :param attachment_name: Unprefixed name unique to the page.
+        :param attachment_path: Path to the file to upload as an attachment.
+        :param raw_data: Raw data to upload as an attachment.
+        :param content_type: Attachment MIME type.
+        :param comment: Attachment description.
+        :param force: Overwrite an existing attachment even if there seem to be no changes.
+        """
+
         if attachment_path is None and raw_data is None:
             raise ArgumentError("required: `attachment_path` or `raw_data`")
 
@@ -378,7 +506,7 @@ class ConfluenceSession:
     ) -> None:
         id = attachment_id.removeprefix("att")
         path = f"/content/{page_id}/child/attachment/{id}"
-        data = {
+        data: JsonType = {
             "id": attachment_id,
             "type": "attachment",
             "status": "current",
@@ -393,13 +521,15 @@ class ConfluenceSession:
         self,
         title: str,
         *,
+        space_id: Optional[str] = None,
         space_key: Optional[str] = None,
     ) -> str:
         """
-        Look up a Confluence wiki page ID by title.
+        Looks up a Confluence wiki page ID by title.
 
         :param title: The page title.
-        :param space_key: The Confluence space key (unless the default space is to be used).
+        :param space_id: The Confluence space ID (unless the default space is to be used). Exclusive with space key.
+        :param space_key: The Confluence space key (unless the default space is to be used). Exclusive with space ID.
         :returns: Confluence page ID.
         """
 
@@ -408,9 +538,9 @@ class ConfluenceSession:
         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)
+        space_id = self.get_space_id(space_id=space_id, space_key=space_key)
+        if space_id is not None:
+            query["space-id"] = space_id
 
         payload = self._invoke(ConfluenceVersion.VERSION_2, path, query)
         payload = typing.cast(dict[str, JsonType], payload)
@@ -425,10 +555,10 @@ class ConfluenceSession:
 
     def get_page(self, page_id: str) -> ConfluencePage:
         """
-        Retrieve Confluence wiki page details.
+        Retrieves Confluence wiki page details and content.
 
         :param page_id: The Confluence page ID.
-        :returns: Confluence page info.
+        :returns: Confluence page info and content.
         """
 
         path = f"/pages/{page_id}"
@@ -453,9 +583,36 @@ class ConfluenceSession:
             content=typing.cast(str, storage["value"]),
         )
 
+    @functools.cache
+    def get_page_properties(self, page_id: str) -> ConfluencePageProperties:
+        """
+        Retrieves Confluence wiki page details.
+
+        :param page_id: The Confluence page ID.
+        :returns: Confluence page info.
+        """
+
+        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 ConfluencePageProperties(
+            id=page_id,
+            space_id=typing.cast(str, data["spaceId"]),
+            parent_id=typing.cast(str, data["parentId"]),
+            parent_type=(
+                ConfluencePageParentContentType(typing.cast(str, data["parentType"]))
+                if data["parentType"] is not None
+                else None
+            ),
+            title=typing.cast(str, data["title"]),
+            version=typing.cast(int, version["number"]),
+        )
+
     def get_page_version(self, page_id: str) -> int:
         """
-        Retrieve a Confluence wiki page version.
+        Retrieves a Confluence wiki page version.
 
         :param page_id: The Confluence page ID.
         :returns: Confluence page version.
@@ -475,7 +632,7 @@ class ConfluenceSession:
         title: Optional[str] = None,
     ) -> None:
         """
-        Update a page via the Confluence API.
+        Updates a page via the Confluence API.
 
         :param page_id: The Confluence page ID.
         :param new_content: Confluence Storage Format XHTML.
@@ -494,7 +651,7 @@ class ConfluenceSession:
             LOGGER.warning(exc)
 
         path = f"/pages/{page_id}"
-        data = {
+        data: JsonType = {
             "id": page_id,
             "status": "current",
             "title": new_title,
@@ -507,26 +664,21 @@ class ConfluenceSession:
 
     def create_page(
         self,
-        parent_page_id: str,
+        parent_id: str,
         title: str,
         new_content: str,
-        *,
-        space_key: Optional[str] = None,
     ) -> ConfluencePage:
         """
-        Create a new page via Confluence API.
+        Creates a new page via Confluence API.
         """
 
-        coalesced_space_key = space_key or self.space_key
-        if coalesced_space_key is None:
-            raise ArgumentError("Confluence space key required for creating a new page")
-
+        parent_page = self.get_page_properties(parent_id)
         path = "/pages/"
         query = {
-            "spaceId": self.space_key_to_id(coalesced_space_key),
+            "spaceId": parent_page.space_id,
             "status": "current",
             "title": title,
-            "parentId": parent_page_id,
+            "parentId": parent_id,
             "body": {"storage": {"value": new_content, "representation": "storage"}},
         }
 
@@ -561,10 +713,10 @@ class ConfluenceSession:
 
     def delete_page(self, page_id: str, *, purge: bool = False) -> None:
         """
-        Delete a page via Confluence API.
+        Deletes 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.
+        :param purge: `True` to completely purge the page, `False` to move to trash only.
         """
 
         path = f"/pages/{page_id}"
@@ -584,13 +736,26 @@ class ConfluenceSession:
             response.raise_for_status()
 
     def page_exists(
-        self, title: str, *, space_key: Optional[str] = None
+        self,
+        title: str,
+        *,
+        space_id: Optional[str] = None,
+        space_key: Optional[str] = None,
     ) -> Optional[str]:
+        """
+        Checks if a Confluence page exists with the given title.
+
+        :param title: Page title. Pages in the same Confluence space must have a unique title.
+        :param space_key: Identifies the Confluence space.
+
+        :returns: Confluence page ID of a matching page (if found), or `None`.
+        """
+
+        space_id = self.get_space_id(space_id=space_id, space_key=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)
+        if space_id is not None:
+            query["space-id"] = space_id
 
         LOGGER.info("Checking if page exists with title: %s", title)
 
@@ -609,14 +774,39 @@ class ConfluenceSession:
         else:
             return None
 
-    def get_or_create_page(
-        self, title: str, parent_id: str, *, space_key: Optional[str] = None
-    ) -> ConfluencePage:
-        page_id = self.page_exists(title)
+    def get_or_create_page(self, title: str, parent_id: str) -> ConfluencePage:
+        """
+        Finds a page with the given title, or creates a new page if no such page exists.
+
+        :param title: Page title. Pages in the same Confluence space must have a unique title.
+        :param parent_id: Identifies the parent page for a new child page.
+        """
+
+        parent_page = self.get_page_properties(parent_id)
+        page_id = self.page_exists(title, space_id=parent_page.space_id)
 
         if page_id is not None:
             LOGGER.debug("Retrieving existing page: %s", page_id)
             return self.get_page(page_id)
         else:
             LOGGER.debug("Creating new page with title: %s", title)
-            return self.create_page(parent_id, title, "", space_key=space_key)
+            return self.create_page(parent_id, title, "")
+
+    def get_labels(self, page_id: str) -> list[ConfluenceLabel]:
+        """
+        Retrieves labels for a Confluence page.
+
+        :param page_id: The Confluence page ID.
+        :returns: A list of page labels.
+        """
+
+        items: list[ConfluenceLabel] = []
+        path = f"/pages/{page_id}/labels"
+        results = self._fetch(path)
+        for r in results:
+            result = typing.cast(dict[str, JsonType], r)
+            id = typing.cast(str, result["id"])
+            name = typing.cast(str, result["name"])
+            prefix = typing.cast(str, result["prefix"])
+            items.append(ConfluenceLabel(id, name, prefix))
+        return items