markdown-to-confluence 0.4.3__py3-none-any.whl → 0.4.4__py3-none-any.whl

md2conf/csf.py

@@ -0,0 +1,151 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import importlib.resources as resources
+import re
+from pathlib import Path
+from typing import Callable, TypeVar
+
+import lxml.etree as ET
+from lxml.builder import ElementMaker
+
+# XML namespaces typically associated with Confluence Storage Format documents
+_namespaces = {
+    "ac": "http://atlassian.com/content",
+    "ri": "http://atlassian.com/resource/identifier",
+}
+for key, value in _namespaces.items():
+    ET.register_namespace(key, value)
+
+HTML = ElementMaker()
+AC_ELEM = ElementMaker(namespace=_namespaces["ac"])
+RI_ELEM = ElementMaker(namespace=_namespaces["ri"])
+
+
+class ParseError(RuntimeError):
+    pass
+
+
+def _qname(namespace_uri: str, name: str) -> str:
+    return ET.QName(namespace_uri, name).text
+
+
+def AC_ATTR(name: str) -> str:
+    return _qname(_namespaces["ac"], name)
+
+
+def RI_ATTR(name: str) -> str:
+    return _qname(_namespaces["ri"], name)
+
+
+R = TypeVar("R")
+
+
+def with_entities(func: Callable[[Path], R]) -> R:
+    "Invokes a callable in the context of an entity definition file."
+
+    resource_path = resources.files(__package__).joinpath("entities.dtd")
+    with resources.as_file(resource_path) as dtd_path:
+        return func(dtd_path)
+
+
+def _elements_from_strings(dtd_path: Path, items: list[str]) -> ET._Element:
+    """
+    Creates an XML document tree from XML fragment strings.
+
+    This function
+    * adds an XML declaration,
+    * wraps the content in a root element,
+    * adds namespace declarations associated with Confluence documents.
+
+    :param dtd_path: Path to a DTD document that defines entities like `¢` or `©`.
+    :param items: Strings to parse into XML fragments.
+    :returns: An XML document as an element tree.
+    """
+
+    parser = ET.XMLParser(
+        remove_blank_text=True,
+        remove_comments=True,
+        strip_cdata=False,
+        load_dtd=True,
+    )
+
+    ns_attr_list = "".join(f' xmlns:{key}="{value}"' for key, value in _namespaces.items())
+
+    data = [
+        '<?xml version="1.0"?>',
+        f'<!DOCTYPE ac:confluence PUBLIC "-//Atlassian//Confluence 4 Page//EN" "{dtd_path.as_posix()}"><root{ns_attr_list}>',
+    ]
+    data.extend(items)
+    data.append("</root>")
+
+    try:
+        return ET.fromstringlist(data, parser=parser)
+    except ET.XMLSyntaxError as ex:
+        raise ParseError() from ex
+
+
+def elements_from_strings(items: list[str]) -> ET._Element:
+    """
+    Creates a Confluence Storage Format XML document tree from XML fragment strings.
+
+    A root element is created to hold several XML fragments.
+
+    :param items: Strings to parse into XML fragments.
+    :returns: An XML document as an element tree.
+    """
+
+    return with_entities(lambda dtd_path: _elements_from_strings(dtd_path, items))
+
+
+def elements_from_string(content: str) -> ET._Element:
+    """
+    Creates a Confluence Storage Format XML document tree from an XML string.
+
+    :param content: String to parse into XML.
+    :returns: An XML document as an element tree.
+    """
+
+    return elements_from_strings([content])
+
+
+def _content_to_string(dtd_path: Path, content: str) -> str:
+    tree = _elements_from_strings(dtd_path, [content])
+    return ET.tostring(tree, pretty_print=True).decode("utf-8")
+
+
+def content_to_string(content: str) -> str:
+    """
+    Converts a Confluence Storage Format document returned by the Confluence REST API into a readable XML document.
+
+    This function
+    * adds an XML declaration,
+    * wraps the content in a root element,
+    * adds namespace declarations associated with Confluence documents.
+
+    :param content: Confluence Storage Format content as a string.
+    :returns: XML as a string.
+    """
+
+    return with_entities(lambda dtd_path: _content_to_string(dtd_path, content))
+
+
+def elements_to_string(root: ET._Element) -> str:
+    """
+    Converts a Confluence Storage Format element tree into an XML string to push to Confluence REST API.
+
+    :param root: Synthesized XML element tree of a Confluence Storage Format document.
+    :returns: XML as a string.
+    """
+
+    xml = ET.tostring(root, encoding="utf8", method="xml").decode("utf8")
+    m = re.match(r"^<root\s+[^>]*>(.*)</root>\s*$", xml, re.DOTALL)
+    if m:
+        return m.group(1)
+    else:
+        raise ValueError("expected: Confluence content")

md2conf/local.py

@@ -83,7 +83,7 @@ class LocalProcessor(Processor):
         os.makedirs(csf_dir, exist_ok=True)
         with open(csf_path, "w", encoding="utf-8") as f:
             f.write(content)
-        for name, data in document.embedded_images.items():
+        for name, data in document.embedded_files.items():
             with open(csf_dir / name, "wb") as f:
                 f.write(data)
 

md2conf/markdown.py

@@ -28,18 +28,19 @@ def _emoji_generator(
     """
 
     name = (alias or shortname).strip(":")
-    span = xml.etree.ElementTree.Element("span", {"data-emoji-shortname": name})
+    emoji = xml.etree.ElementTree.Element("x-emoji", {"data-shortname": name})
     if uc is not None:
-        span.attrib["data-emoji-unicode"] = uc
+        emoji.attrib["data-unicode"] = uc
 
         # convert series of Unicode code point hexadecimal values into characters
-        span.text = "".join(chr(int(item, base=16)) for item in uc.split("-"))
+        emoji.text = "".join(chr(int(item, base=16)) for item in uc.split("-"))
     else:
-        span.text = alt
-    return span
+        emoji.text = alt
 
+    return emoji
 
-def _math_formatter(
+
+def _verbatim_formatter(
     source: str,
     language: str,
     css_class: str,
@@ -51,7 +52,9 @@ def _math_formatter(
     **kwargs: Any,
 ) -> str:
     """
-    Custom formatter for language `math` in `pymdownx.superfences`.
+    Custom formatter for `pymdownx.superfences`.
+
+    Used by language `math` (a.k.a. `pymdownx.arithmatex`) and pseudo-language `csf` (Confluence Storage Format pass-through).
     """
 
     if classes is None:
@@ -83,13 +86,16 @@ _CONVERTER = markdown.Markdown(
     extension_configs={
         "footnotes": {"BACKLINK_TITLE": ""},
         "pymdownx.arithmatex": {"generic": True, "preview": False, "tex_inline_wrap": ["", ""], "tex_block_wrap": ["", ""]},
-        "pymdownx.emoji": {
-            "emoji_generator": _emoji_generator,
-        },
+        "pymdownx.emoji": {"emoji_generator": _emoji_generator, "strict": True},
         "pymdownx.highlight": {
             "use_pygments": False,
         },
-        "pymdownx.superfences": {"custom_fences": [{"name": "math", "class": "arithmatex", "format": _math_formatter}]},
+        "pymdownx.superfences": {
+            "custom_fences": [
+                {"name": "math", "class": "arithmatex", "format": _verbatim_formatter},
+                {"name": "csf", "class": "csf", "format": _verbatim_formatter},
+            ]
+        },
     },
 )
 

md2conf/toc.py

@@ -0,0 +1,89 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(eq=True)
+class TableOfContentsEntry:
+    """
+    Represents a table of contents entry.
+
+    :param level: The heading level assigned to the entry. Each entry can only contain children whose level is strictly greater than of its parent.
+    :param text: The heading text.
+    :param children: Direct descendants whose parent is this entry.
+    """
+
+    level: int
+    text: str
+    children: list["TableOfContentsEntry"]
+
+    def __init__(self, level: int, text: str, children: Optional[list["TableOfContentsEntry"]] = None) -> None:
+        self.level = level
+        self.text = text
+        self.children = children or []
+
+
+class TableOfContentsBuilder:
+    """
+    Builds a table of contents from Markdown headings.
+    """
+
+    _root: TableOfContentsEntry
+    _stack: list[TableOfContentsEntry]
+
+    def __init__(self) -> None:
+        self._root = TableOfContentsEntry(0, "<root>")
+        self._stack = [self._root]
+
+    @property
+    def tree(self) -> list[TableOfContentsEntry]:
+        """
+        Table of contents as a hierarchy of headings.
+        """
+
+        return self._root.children
+
+    def add(self, level: int, text: str) -> None:
+        """
+        Adds a heading to the table of contents.
+
+        :param level: Markdown heading level (e.g. `1` for first-level heading).
+        :param text: Markdown heading text.
+        """
+
+        if level < 1:
+            raise ValueError("expected: Markdown heading level >= 1")
+
+        # remove any stack items deeper than the current level
+        top = self._stack[-1]
+        while top.level >= level:
+            self._stack.pop()
+            top = self._stack[-1]
+
+        # add the new section under the current top level
+        item = TableOfContentsEntry(level, text)
+        top.children.append(item)
+
+        # push new level onto the stack
+        self._stack.append(item)
+
+    def get_title(self) -> Optional[str]:
+        """
+        Returns a proposed document title.
+
+        The proposed title is text of the top-level heading if and only if that heading is unique.
+
+        :returns: Title text, or `None` if no title can be inferred.
+        """
+
+        if len(self.tree) == 1:
+            return self.tree[0].text
+        else:
+            return None

md2conf/uri.py

@@ -0,0 +1,46 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import hashlib
+import urllib.parse
+import uuid
+from urllib.parse import urlparse
+
+
+def to_data_uri(mime: str, data: str) -> str:
+    "Generates a data URI with the specified MIME type."
+
+    # URL-encode data
+    encoded = urllib.parse.quote(data, safe=";/?:@&=+$,-_.!~*'()#")  # minimal encoding
+    return f"data:{mime},{encoded}"
+
+
+def to_uuid(data: str) -> uuid.UUID:
+    "Generates a UUID that represents the data."
+
+    # create SHA-1 hash of the SVG content
+    sha1_hash = hashlib.sha1(data.encode("utf-8")).digest()
+
+    # generate UUID using the first 16 bytes of the hash
+    return uuid.UUID(bytes=sha1_hash[:16])
+
+
+def to_uuid_urn(data: str) -> str:
+    "Generates a UUID URN that represents the data."
+
+    return f"urn:uuid:{str(to_uuid(data))}"
+
+
+def is_absolute_url(url: str) -> bool:
+    urlparts = urlparse(url)
+    return bool(urlparts.scheme) or bool(urlparts.netloc)
+
+
+def is_relative_url(url: str) -> bool:
+    urlparts = urlparse(url)
+    return not bool(urlparts.scheme) and not bool(urlparts.netloc)

md2conf/xml.py

@@ -1,11 +1,21 @@
-from typing import Iterable, Optional, Union
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from typing import Iterable, Optional
 
 import lxml.etree as ET
 
 
-def _attrs_equal_excluding(attrs1: ET._Attrib, attrs2: ET._Attrib, exclude: set[Union[str, ET.QName]]) -> bool:
+def _attrs_equal_excluding(attrs1: ET._Attrib, attrs2: ET._Attrib, exclude: set[str]) -> bool:
     """
     Compares two dictionary objects, excluding keys in the skip set.
+
+    :param exclude: Attributes to exclude, in `{namespace}name` notation.
     """
 
     # create key sets to compare, excluding keys to be skipped
@@ -23,10 +33,19 @@ def _attrs_equal_excluding(attrs1: ET._Attrib, attrs2: ET._Attrib, exclude: set[
 
 
 class ElementComparator:
-    skip_attributes: set[Union[str, ET.QName]]
+    skip_attributes: set[str]
+    skip_elements: set[str]
+
+    def __init__(self, *, skip_attributes: Optional[Iterable[str]] = None, skip_elements: Optional[Iterable[str]] = None):
+        """
+        Initializes a new element tree comparator.
+
+        :param skip_attributes: Attributes to exclude, in `{namespace}name` notation.
+        :param skip_elements: Elements to exclude, in `{namespace}name` notation.
+        """
 
-    def __init__(self, *, skip_attributes: Optional[Iterable[Union[str, ET.QName]]] = None):
         self.skip_attributes = set(skip_attributes) if skip_attributes else set()
+        self.skip_elements = set(skip_elements) if skip_elements else set()
 
     def is_equal(self, e1: ET._Element, e2: ET._Element) -> bool:
         """
@@ -36,35 +55,49 @@ class ElementComparator:
         if e1.tag != e2.tag:
             return False
 
-        e1_text = e1.text.strip() if e1.text else ""
-        e2_text = e2.text.strip() if e2.text else ""
-        if e1_text != e2_text:
-            return False
-
+        # compare tail first, which is outside of element
         e1_tail = e1.tail.strip() if e1.tail else ""
         e2_tail = e2.tail.strip() if e2.tail else ""
         if e1_tail != e2_tail:
             return False
 
+        # skip element (and content) if on ignore list
+        if e1.tag in self.skip_elements:
+            return True
+
+        # compare text second, which is encapsulated by element
+        e1_text = e1.text.strip() if e1.text else ""
+        e2_text = e2.text.strip() if e2.text else ""
+        if e1_text != e2_text:
+            return False
+
+        # compare attributes, disregarding definition order
         if not _attrs_equal_excluding(e1.attrib, e2.attrib, self.skip_attributes):
             return False
+
+        # compare children recursively
         if len(e1) != len(e2):
             return False
         return all(self.is_equal(c1, c2) for c1, c2 in zip(e1, e2))
 
 
 def is_xml_equal(
-    tree1: ET._Element,
-    tree2: ET._Element,
-    *,
-    skip_attributes: Optional[Iterable[Union[str, ET.QName]]] = None,
+    tree1: ET._Element, tree2: ET._Element, *, skip_attributes: Optional[Iterable[str]] = None, skip_elements: Optional[Iterable[str]] = None
 ) -> bool:
     """
     Compare two XML documents for equivalence, ignoring leading/trailing whitespace differences and attribute definition order.
 
     :param tree1: XML document as an element tree.
     :param tree2: XML document as an element tree.
+    :param skip_attributes: Attributes to exclude, in `{namespace}name` notation.
+    :param skip_elements: Elements to exclude, in `{namespace}name` notation.
     :returns: True if equivalent, False otherwise.
     """
 
-    return ElementComparator(skip_attributes=skip_attributes).is_equal(tree1, tree2)
+    return ElementComparator(skip_attributes=skip_attributes, skip_elements=skip_elements).is_equal(tree1, tree2)
+
+
+def element_to_text(node: ET._Element) -> str:
+    "Returns all text contained in an element as a concatenated string."
+
+    return "".join(node.itertext()).strip()

md2conf/emoji.py

@@ -1,83 +0,0 @@
-"""
-Publish Markdown files to Confluence wiki.
-
-Copyright 2022-2025, Levente Hunyadi
-
-:see: https://github.com/hunyadi/md2conf
-"""
-
-import pathlib
-
-import pymdownx.emoji1_db as emoji_db
-
-EMOJI_PAGE_ID = "13500452"
-
-
-def to_html(cp: int) -> str:
-    """
-    Returns the safe HTML representation for a Unicode code point.
-
-    Converts non-ASCII and non-printable characters into HTML entities with decimal notation.
-
-    :param cp: Unicode code point.
-    :returns: An HTML representation of the Unicode character.
-    """
-
-    ch = chr(cp)
-    if ch.isascii() and ch.isalnum():
-        return ch
-    else:
-        return f"&#{cp};"
-
-
-def generate_source(path: pathlib.Path) -> None:
-    "Generates a source Markdown document for testing emojis."
-
-    emojis = emoji_db.emoji
-
-    with open(path, "w") as f:
-        print(f"<!-- confluence-page-id: {EMOJI_PAGE_ID} -->", file=f)
-        print("<!-- This file has been generated by a script. -->", file=f)
-        print(file=f)
-        print("## Emoji", file=f)
-        print(file=f)
-        print("| Icon | Emoji code |", file=f)
-        print("| ---- | ---------- |", file=f)
-        for key in emojis.keys():
-            key = key.strip(":")
-            print(f"| :{key}: | `:{key}:` |", file=f)
-
-
-def generate_target(path: pathlib.Path) -> None:
-    "Generates a target Confluence Storage Format (XML) document for testing emojis."
-
-    emojis = emoji_db.emoji
-
-    with open(path, "w") as f:
-        print('<ac:structured-macro ac:name="info" ac:schema-version="1">', file=f)
-        print("<ac:rich-text-body>", file=f)
-        print("<p>This page has been generated with a tool.</p>", file=f)
-        print("</ac:rich-text-body>", file=f)
-        print("</ac:structured-macro>", file=f)
-        print("<h2>Emoji</h2>", file=f)
-        print("<table>", file=f)
-        print("<thead><tr><th>Icon</th><th>Emoji code</th></tr></thead>", file=f)
-        print("<tbody>", file=f)
-        for key, data in emojis.items():
-            unicode = data["unicode"]
-            key = key.strip(":")
-            html = "".join(to_html(int(item, base=16)) for item in unicode.split("-"))
-
-            print(
-                f"<tr>\n"
-                f"  <td>\n"
-                f'    <ac:emoticon ac:name="{key}" ac:emoji-shortname=":{key}:" ac:emoji-id="{unicode}" ac:emoji-fallback="{html}"/>\n'
-                f"  </td>\n"
-                f"  <td>\n"
-                f"    <code>:{key}:</code>\n"
-                f"  </td>\n"
-                f"</tr>",
-                file=f,
-            )
-        print("</tbody>", file=f)
-        print("</table>", file=f)