markdown-to-confluence 0.4.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

{markdown_to_confluence-0.4.0.dist-info → markdown_to_confluence-0.4.1.dist-info}/METADATA

@@ -1,15 +1,16 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.4.0
+Version: 0.4.1
 Summary: Publish Markdown files to Confluence wiki
-Home-page: https://github.com/hunyadi/md2conf
-Author: Levente Hunyadi
-Author-email: hunyadi@gmail.com
-License: MIT
+Author-email: Levente Hunyadi <hunyadi@gmail.com>
+Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hunyadi/md2conf
+Project-URL: Source, https://github.com/hunyadi/md2conf
+Keywords: markdown,converter,confluence
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 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.9
@@ -17,21 +18,26 @@ 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: Programming Language :: Python :: 3 :: Only
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: json_strong_typing>=0.3.9
-Requires-Dist: lxml>=5.4
-Requires-Dist: types-lxml>=2025.3.30
+Requires-Dist: lxml>=6.0
 Requires-Dist: markdown>=3.8
-Requires-Dist: types-markdown>=3.8
 Requires-Dist: pymdown-extensions>=10.16
 Requires-Dist: PyYAML>=6.0
-Requires-Dist: types-PyYAML>=6.0
 Requires-Dist: requests>=2.32
-Requires-Dist: types-requests>=2.32
 Requires-Dist: typing_extensions>=4.14; python_version < "3.12"
+Provides-Extra: dev
+Requires-Dist: markdown_doc>=0.1.4; python_version >= "3.10" and extra == "dev"
+Requires-Dist: types-lxml>=2025.3.30; extra == "dev"
+Requires-Dist: types-markdown>=3.8; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Requires-Dist: types-requests>=2.32; extra == "dev"
+Requires-Dist: mypy>=1.16; extra == "dev"
+Requires-Dist: ruff>=0.12; extra == "dev"
 Dynamic: license-file
 
 # Publish Markdown files to Confluence wiki
@@ -326,6 +332,22 @@ Any previously assigned labels are discarded. As per Confluence terminology, new
 
 If a document has no `tags` attribute, existing Confluence labels are left intact.
 
+### Content properties
+
+The front-matter attribute `properties` in a Markdown document allows setting Confluence content properties on a page. Confluence content properties are a way to store structured metadata in the form of key-value pairs directly on Confluence content. The values in content properties are represented as JSON objects.
+
+Some content properties have special meaning to Confluence. For example, the following properties cause Confluence to display a wiki page with content confined to a fixed width in regular view mode, and taking the full page width in draft mode:
+
+```yaml
+---
+properties:
+  content-appearance-published: fixed-width
+  content-appearance-draft: full-width
+---
+```
+
+The attribute `properties` is parsed as a dictionary with keys of type string and values of type JSON. *md2conf* passes JSON values to Confluence REST API 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:

markdown_to_confluence-0.4.1.dist-info/RECORD

@@ -0,0 +1,25 @@
+markdown_to_confluence-0.4.1.dist-info/licenses/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
+md2conf/__init__.py,sha256=K6ZE42N5KJjN5o2GqIFa_lcPZvMMCXPMMRWEkvlmcp0,402
+md2conf/__main__.py,sha256=MJm9U75savKWKYm4dLREqlsyBWEqkTtaM4YTWkEeo0E,8388
+md2conf/api.py,sha256=RQ_nb0Z0VnhJma1BU9ABeb4MQZvZEfFS5mTXXKcY6bk,37584
+md2conf/application.py,sha256=cXYXYdEdmMXwhxF69eUiPPG2Ixt4xtlWHXa28wTq150,7571
+md2conf/collection.py,sha256=EAXuIFcIRBO-Giic2hdU2d4Hpj0_ZFBAWI3aKQ2fjrI,775
+md2conf/converter.py,sha256=x2LAY1Hpw5mTVFNJE5_Zm-o7p5y6TTds6KfrpdM5qQk,38823
+md2conf/emoji.py,sha256=UzDrxqFo59wHmbbJmMNdn0rYFDXbZE4qirOM-_egzXc,2603
+md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
+md2conf/extra.py,sha256=VuMxuOnnC2Qwy6y52ukIxsaYhrZArRqMmRHRE4QZl8g,687
+md2conf/local.py,sha256=MVwGxy_n00uqCInLK8FVGaaVnaOp1nfn28PVrWz3cCQ,3496
+md2conf/matcher.py,sha256=izgL_MAMqbXjKPvAz3KpFv5OTDsaJ9GplTJbixrT3oY,4918
+md2conf/mermaid.py,sha256=f0x7ISj-41ZMh4zTAFPhIWwr94SDcsVZUc1NWqmH_G4,2508
+md2conf/metadata.py,sha256=TxgUrskqsWor_pvlQx-p86C0-0qRJ2aeQhuDcXU9Dpc,886
+md2conf/processor.py,sha256=yWVRYtbc9UHSUfRxqyPDsgeVqO7gx0s3RiGL1GzMotE,9405
+md2conf/properties.py,sha256=RC1jY_TKVbOv2bJxXn27Fj4fNWzyoNUQt6ltgUyVQAQ,3987
+md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
+md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/scanner.py,sha256=qXfnJkaEwDbz6G6Z9llqifBp2TLAlrXAIP4qkCbGdWo,4964
+markdown_to_confluence-0.4.1.dist-info/METADATA,sha256=rAXtL2mR1LHmc_pwkmnwrGpIDMEw-7kZjIJOnMi-NLA,24864
+markdown_to_confluence-0.4.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+markdown_to_confluence-0.4.1.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.4.1.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.4.1.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.4.1.dist-info/RECORD,,

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.4.0"
+__version__ = "0.4.1"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2025, Levente Hunyadi"
 __license__ = "MIT"

md2conf/__main__.py

@@ -26,11 +26,7 @@ from .converter import ConfluenceDocumentOptions, ConfluencePageID
 from .extra import override
 from .local import LocalConverter
 from .metadata import ConfluenceSiteMetadata
-from .properties import (
-    ArgumentError,
-    ConfluenceConnectionProperties,
-    ConfluenceSiteProperties,
-)
+from .properties import ArgumentError, ConfluenceConnectionProperties, ConfluenceSiteProperties
 
 
 class Arguments(argparse.Namespace):
@@ -71,7 +67,7 @@ class KwargsAppendAction(argparse.Action):
             raise argparse.ArgumentError(
                 self,
                 f'Could not parse argument "{values}". It should follow the format: k1=v1 k2=v2 ...',
-            )
+            ) from None
         setattr(namespace, self.dest, d)
 
 
@@ -79,13 +75,9 @@ def main() -> None:
     parser = argparse.ArgumentParser()
     parser.prog = os.path.basename(os.path.dirname(__file__))
     parser.add_argument("--version", action="version", version=__version__)
-    parser.add_argument(
-        "mdpath", help="Path to Markdown file or directory to convert and publish."
-    )
+    parser.add_argument("mdpath", help="Path to Markdown file or directory to convert and publish.")
     parser.add_argument("-d", "--domain", help="Confluence organization domain.")
-    parser.add_argument(
-        "-p", "--path", help="Base path for Confluence (default: '/wiki/')."
-    )
+    parser.add_argument("-p", "--path", help="Base path for Confluence (default: '/wiki/').")
     parser.add_argument(
         "--api-url",
         dest="api_url",

md2conf/api.py

@@ -8,7 +8,6 @@ Copyright 2022-2025, Levente Hunyadi
 
 import datetime
 import enum
-import functools
 import io
 import logging
 import mimetypes
@@ -16,26 +15,16 @@ import typing
 from dataclasses import dataclass
 from pathlib import Path
 from types import TracebackType
-from typing import Optional, TypeVar
+from typing import Any, Optional, TypeVar
 from urllib.parse import urlencode, urlparse, urlunparse
 
 import requests
 from strong_typing.core import JsonType
-from strong_typing.serialization import (
-    DeserializerOptions,
-    json_dump_string,
-    json_to_object,
-    object_to_json,
-)
+from strong_typing.serialization import DeserializerOptions, json_dump_string, json_to_object, object_to_json
 
 from .converter import ParseError, sanitize_confluence
 from .metadata import ConfluenceSiteMetadata
-from .properties import (
-    ArgumentError,
-    ConfluenceConnectionProperties,
-    ConfluenceError,
-    PageError,
-)
+from .properties import ArgumentError, ConfluenceConnectionProperties, ConfluenceError, PageError
 
 T = TypeVar("T")
 
@@ -106,6 +95,7 @@ class ConfluenceRepresentation(enum.Enum):
 class ConfluenceStatus(enum.Enum):
     CURRENT = "current"
     DRAFT = "draft"
+    ARCHIVED = "archived"
 
 
 @enum.unique
@@ -265,6 +255,41 @@ class ConfluenceIdentifiedLabel(ConfluenceLabel):
     id: str
 
 
+@dataclass(frozen=True)
+class ConfluenceContentProperty:
+    """
+    Represents a content property.
+
+    :param key: Property key.
+    :param value: Property value as JSON.
+    """
+
+    key: str
+    value: JsonType
+
+
+@dataclass(frozen=True)
+class ConfluenceVersionedContentProperty(ConfluenceContentProperty):
+    """
+    Represents a content property.
+
+    :param version: Version information about the property.
+    """
+
+    version: ConfluenceContentVersion
+
+
+@dataclass(frozen=True)
+class ConfluenceIdentifiedContentProperty(ConfluenceVersionedContentProperty):
+    """
+    Represents a content property.
+
+    :param id: Property ID.
+    """
+
+    id: str
+
+
 @dataclass(frozen=True)
 class ConfluenceCreatePageRequest:
     spaceId: str
@@ -300,9 +325,7 @@ class ConfluenceAPI:
     properties: ConfluenceConnectionProperties
     session: Optional["ConfluenceSession"] = None
 
-    def __init__(
-        self, properties: Optional[ConfluenceConnectionProperties] = None
-    ) -> None:
+    def __init__(self, properties: Optional[ConfluenceConnectionProperties] = None) -> None:
         self.properties = properties or ConfluenceConnectionProperties()
 
     def __enter__(self) -> "ConfluenceSession":
@@ -310,9 +333,7 @@ class ConfluenceAPI:
         if self.properties.user_name:
             session.auth = (self.properties.user_name, self.properties.api_key)
         else:
-            session.headers.update(
-                {"Authorization": f"Bearer {self.properties.api_key}"}
-            )
+            session.headers.update({"Authorization": f"Bearer {self.properties.api_key}"})
 
         if self.properties.headers:
             session.headers.update(self.properties.headers)
@@ -366,9 +387,7 @@ class ConfluenceSession:
             self.api_url = api_url
 
             if not domain or not base_path:
-                payload = self._invoke(
-                    ConfluenceVersion.VERSION_2, "/spaces", {"limit": "1"}
-                )
+                payload = self._invoke(ConfluenceVersion.VERSION_2, "/spaces", {"limit": "1"})
                 data = json_to_object(ConfluenceResultSet, payload)
                 base_url = data._links.base
 
@@ -377,13 +396,9 @@ class ConfluenceSession:
                     base_path = f"{base_path}/"
 
         if not domain:
-            raise ArgumentError(
-                "Confluence domain not specified and cannot be inferred"
-            )
+            raise ArgumentError("Confluence domain not specified and cannot be inferred")
         if not base_path:
-            raise ArgumentError(
-                "Confluence base path not specified and cannot be inferred"
-            )
+            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}"
@@ -425,9 +440,7 @@ class ConfluenceSession:
         response.raise_for_status()
         return typing.cast(JsonType, response.json())
 
-    def _fetch(
-        self, path: str, query: Optional[dict[str, str]] = None
-    ) -> list[JsonType]:
+    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] = []
@@ -506,9 +519,7 @@ class ConfluenceSession:
 
         return id
 
-    def get_space_id(
-        self, *, space_id: Optional[str] = None, space_key: Optional[str] = None
-    ) -> Optional[str]:
+    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.
 
@@ -529,9 +540,7 @@ class ConfluenceSession:
         # 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:
+    def get_attachment_by_name(self, page_id: str, filename: str) -> ConfluenceAttachment:
         """
         Retrieves a Confluence page attachment by an unprefixed file name.
         """
@@ -583,6 +592,9 @@ class ConfluenceSession:
                 name = attachment_name
             content_type, _ = mimetypes.guess_type(name, strict=True)
 
+            if content_type is None:
+                content_type = "application/octet-stream"
+
         if attachment_path is not None and not attachment_path.is_file():
             raise PageError(f"file not found: {attachment_path}")
 
@@ -610,8 +622,13 @@ class ConfluenceSession:
 
         if attachment_path is not None:
             with open(attachment_path, "rb") as attachment_file:
-                file_to_upload = {
-                    "comment": comment,
+                file_to_upload: dict[str, tuple[Optional[str], Any, str, dict[str, str]]] = {
+                    "comment": (
+                        None,
+                        comment,
+                        "text/plain; charset=utf-8",
+                        {},
+                    ),
                     "file": (
                         attachment_name,  # will truncate path component
                         attachment_file,
@@ -622,7 +639,7 @@ class ConfluenceSession:
                 LOGGER.info("Uploading attachment: %s", attachment_name)
                 response = self.session.post(
                     url,
-                    files=file_to_upload,  # type: ignore[arg-type]
+                    files=file_to_upload,
                     headers={
                         "X-Atlassian-Token": "no-check",
                         "Accept": "application/json",
@@ -634,17 +651,22 @@ class ConfluenceSession:
             raw_file = io.BytesIO(raw_data)
             raw_file.name = attachment_name
             file_to_upload = {
-                "comment": comment,
+                "comment": (
+                    None,
+                    comment,
+                    "text/plain; charset=utf-8",
+                    {},
+                ),
                 "file": (
                     attachment_name,  # will truncate path component
-                    raw_file,  # type: ignore[dict-item]
+                    raw_file,
                     content_type,
                     {"Expires": "0"},
                 ),
             }
             response = self.session.post(
                 url,
-                files=file_to_upload,  # type: ignore[arg-type]
+                files=file_to_upload,
                 headers={
                     "X-Atlassian-Token": "no-check",
                     "Accept": "application/json",
@@ -667,9 +689,7 @@ class ConfluenceSession:
         # ensure path component is retained in attachment name
         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
-    ) -> None:
+    def _update_attachment(self, page_id: str, attachment_id: str, version: int, attachment_title: str) -> None:
         id = attachment_id.removeprefix("att")
         path = f"/content/{page_id}/child/attachment/{id}"
         request = ConfluenceUpdateAttachmentRequest(
@@ -730,7 +750,6 @@ class ConfluenceSession:
         payload = self._invoke(ConfluenceVersion.VERSION_2, path, query)
         return _json_to_object(ConfluencePage, payload)
 
-    @functools.cache
     def get_page_properties(self, page_id: str) -> ConfluencePageProperties:
         """
         Retrieves Confluence wiki page details.
@@ -784,14 +803,8 @@ class ConfluenceSession:
             id=page_id,
             status=ConfluenceStatus.CURRENT,
             title=new_title,
-            body=ConfluencePageBody(
-                storage=ConfluencePageStorage(
-                    representation=ConfluenceRepresentation.STORAGE, value=new_content
-                )
-            ),
-            version=ConfluenceContentVersion(
-                number=page.version.number + 1, minorEdit=True
-            ),
+            body=ConfluencePageBody(storage=ConfluencePageStorage(representation=ConfluenceRepresentation.STORAGE, value=new_content)),
+            version=ConfluenceContentVersion(number=page.version.number + 1, minorEdit=True),
         )
         LOGGER.info("Updating page: %s", page_id)
         self._save(ConfluenceVersion.VERSION_2, path, object_to_json(request))
@@ -973,7 +986,7 @@ class ConfluenceSession:
                 LOGGER.debug("Received HTTP payload:\n%s", response.text)
             response.raise_for_status()
 
-    def update_labels(self, page_id: str, labels: list[ConfluenceLabel]) -> None:
+    def update_labels(self, page_id: str, labels: list[ConfluenceLabel], *, keep_existing: bool = False) -> None:
         """
         Assigns the specified labels to a Confluence page. Existing labels are removed.
 
@@ -982,10 +995,7 @@ class ConfluenceSession:
         """
 
         new_labels = set(labels)
-        old_labels = set(
-            ConfluenceLabel(name=label.name, prefix=label.prefix)
-            for label in self.get_labels(page_id)
-        )
+        old_labels = set(ConfluenceLabel(name=label.name, prefix=label.prefix) for label in self.get_labels(page_id))
 
         add_labels = list(new_labels - old_labels)
         remove_labels = list(old_labels - new_labels)
@@ -993,6 +1003,123 @@ class ConfluenceSession:
         if add_labels:
             add_labels.sort()
             self.add_labels(page_id, add_labels)
-        if remove_labels:
+        if not keep_existing and remove_labels:
             remove_labels.sort()
             self.remove_labels(page_id, remove_labels)
+
+    def get_content_properties_for_page(self, page_id: str) -> list[ConfluenceIdentifiedContentProperty]:
+        """
+        Retrieves content properties for a Confluence page.
+
+        :param page_id: The Confluence page ID.
+        :returns: A list of content properties.
+        """
+
+        path = f"/pages/{page_id}/properties"
+        results = self._fetch(path)
+        return _json_to_object(list[ConfluenceIdentifiedContentProperty], results)
+
+    def add_content_property_to_page(self, page_id: str, property: ConfluenceContentProperty) -> ConfluenceIdentifiedContentProperty:
+        """
+        Adds a new content property to a Confluence page.
+
+        :param page_id: The Confluence page ID.
+        :param property: Content property to add.
+        """
+
+        path = f"/pages/{page_id}/properties"
+        url = self._build_url(ConfluenceVersion.VERSION_2, path)
+        response = self.session.post(
+            url,
+            data=json_dump_string(object_to_json(property)),
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+        )
+        if response.text:
+            LOGGER.debug("Received HTTP payload:\n%s", response.text)
+        response.raise_for_status()
+        return _json_to_object(ConfluenceIdentifiedContentProperty, response.json())
+
+    def remove_content_property_from_page(self, page_id: str, property_id: str) -> None:
+        """
+        Removes a content property from a Confluence page.
+
+        :param page_id: The Confluence page ID.
+        :param property_id: Property ID, which uniquely identifies the property.
+        """
+
+        path = f"/pages/{page_id}/properties/{property_id}"
+        url = self._build_url(ConfluenceVersion.VERSION_2, path)
+        response = self.session.delete(url)
+        response.raise_for_status()
+
+    def update_content_property_for_page(
+        self, page_id: str, property_id: str, version: int, property: ConfluenceContentProperty
+    ) -> ConfluenceIdentifiedContentProperty:
+        """
+        Updates an existing content property associated with a Confluence page.
+
+        :param page_id: The Confluence page ID.
+        :param property_id: Property ID, which uniquely identifies the property.
+        :param version: Version number to assign.
+        :param property: Content property data to assign.
+        :returns: Updated content property data.
+        """
+
+        path = f"/pages/{page_id}/properties/{property_id}"
+        url = self._build_url(ConfluenceVersion.VERSION_2, path)
+        response = self.session.put(
+            url,
+            data=json_dump_string(
+                object_to_json(
+                    ConfluenceVersionedContentProperty(
+                        key=property.key,
+                        value=property.value,
+                        version=ConfluenceContentVersion(number=version),
+                    )
+                )
+            ),
+            headers={"Content-Type": "application/json"},
+        )
+        if response.text:
+            LOGGER.debug("Received HTTP payload:\n%s", response.text)
+        response.raise_for_status()
+        return json_to_object(ConfluenceIdentifiedContentProperty, response.json())
+
+    def update_content_properties_for_page(self, page_id: str, properties: list[ConfluenceContentProperty], *, keep_existing: bool = False) -> None:
+        """
+        Updates content properties associated with a Confluence page.
+
+        :param page_id: The Confluence page ID.
+        :param properties: A list of content property data to update.
+        :param keep_existing: Whether to keep content property data whose key is not included in the list of properties passed as an argument.
+        """
+
+        old_mapping = {p.key: p for p in self.get_content_properties_for_page(page_id)}
+        new_mapping = {p.key: p for p in properties}
+
+        new_props = set(p.key for p in properties)
+        old_props = set(old_mapping.keys())
+
+        add_props = list(new_props - old_props)
+        remove_props = list(old_props - new_props)
+        update_props = list(old_props & new_props)
+
+        if add_props:
+            add_props.sort()
+            for key in add_props:
+                self.add_content_property_to_page(page_id, new_mapping[key])
+        if not keep_existing and remove_props:
+            remove_props.sort()
+            for key in remove_props:
+                self.remove_content_property_from_page(page_id, old_mapping[key].id)
+        if update_props:
+            update_props.sort()
+            for key in update_props:
+                old_prop = old_mapping[key]
+                new_prop = new_mapping[key]
+                if old_prop.value == new_prop.value:
+                    continue
+                self.update_content_property_for_page(page_id, old_prop.id, old_prop.version.number + 1, new_prop)