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

md2conf/text.py

@@ -0,0 +1,54 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+
+def wrap_text(text: str, line_length: int = 160) -> str:
+    """
+    Wraps text by replacing individual whitespace characters with a linefeed such that lines in the output honor the specified line length.
+
+    :param text: Input text, optionally with existing UNIX line endings.
+    :param line_length: Desired line length.
+    :returns: Wrapped output text. Long words that exceed the specified line length are not broken.
+    """
+
+    if line_length < 1:
+        raise ValueError("expected: line_length > 0")
+
+    input = text.encode("utf-8")
+    output = bytearray(len(input))
+    pos = 0
+    length = len(input)
+
+    while pos < length:
+        end = min(pos + line_length, length)
+
+        # find any linefeed already in input
+        left = pos
+        while left < end and input[left] != 0x0A:
+            left += 1
+        if left != end:
+            output[pos : left + 1] = input[pos : left + 1]
+            pos = left + 1  # include linefeed
+            continue
+
+        # find the nearest whitespace before end of line
+        right = end
+        while right > pos and input[right - 1] not in b"\t\v\f\r ":
+            right -= 1
+
+        if right == pos or end == length:
+            # no whitespace found or at end of input; copy the rest
+            output[pos:end] = input[pos:end]
+            pos = end
+        else:
+            # replace the whitespace with a newline
+            output[pos : right - 1] = input[pos : right - 1]
+            output[right - 1] = 0x0A  # linefeed '\n'
+            pos = right  # skip the whitespace (already replaced)
+
+    return output.decode("utf-8")

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,86 @@ 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.
 
+    Elements may be excluded, in which case they compare equal to any element of the same type that has the same tail text.
+
     :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()
+
+
+def unwrap_substitute(name: str, root: ET._Element) -> None:
+    """
+    Substitutes all occurrences of an element with its contents.
+
+    :param name: Element tag name to find and replace.
+    :param root: Top-most element at which to start.
+    """
+
+    for node in root.iterdescendants(name):
+        if node.text:
+            # append first piece of text in this element at the end of previous sibling, or text contained by parent
+            if (prev_node := node.getprevious()) is not None:
+                prev_node.tail = (prev_node.tail or "") + node.text
+            elif (parent_node := node.getparent()) is not None:  # always true except for root
+                parent_node.text = (parent_node.text or "") + node.text
+            else:
+                raise NotImplementedError("must always have a previous sibling or a parent")
+        if node.tail:
+            if len(node) > 0:
+                # append text immediately following the closing tag of this element to the last child element of this element
+                last_node = node[-1]
+                last_node.tail = (last_node.tail or "") + node.tail
+            else:  # node has no child elements, only text
+                if (prev_node := node.getprevious()) is not None:
+                    prev_node.tail = (prev_node.tail or "") + node.tail
+                elif (parent_node := node.getparent()) is not None:  # always true except for root
+                    parent_node.text = (parent_node.text or "") + node.tail
+                else:
+                    raise NotImplementedError("must always have a previous sibling or a parent")
+        for child in node.iterchildren(reversed=True):
+            node.addnext(child)
+        if (parent_node := node.getparent()) is not None:  # always true except for root
+            parent_node.remove(node)

markdown_to_confluence-0.4.3.dist-info/RECORD

@@ -1,29 +0,0 @@
-markdown_to_confluence-0.4.3.dist-info/licenses/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
-md2conf/__init__.py,sha256=ZEoZwOt29zT2OnQNpbYW9lO3zJEJ6soXwwjYX9PwNNo,402
-md2conf/__main__.py,sha256=RImfFrO2m9C5iebmBrHKlLjosy_A8AY4O7PK9CmiWSw,11120
-md2conf/api.py,sha256=DbG1udDb9ti4OjqgSW3DSuHwxKNFPVDTkhjnaB1GNMI,37193
-md2conf/application.py,sha256=MsumqUFw1WPo6-57r06Poq4wg2DPd3hQ4jA5qC4Oios,8212
-md2conf/collection.py,sha256=EobgMRJgkYloWlY03NZJ52MRC_SGLpTVCHkltDbQyt0,837
-md2conf/converter.py,sha256=mr5UvEhOnM7ZYRIGsgrW85PpxmlpXFjsKYsa8uGFxp0,50475
-md2conf/domain.py,sha256=tA9V0vb5Vo9Nt0eQvwAFARaM9TX88LBVQ73nVvdcaqA,1851
-md2conf/drawio.py,sha256=P_t7Wp7Tg9XkZM2ZchWCWWEdBaU1KgZ_YX9ZlkZo4Dk,8293
-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=Cicfp9SJDJuX0aUWZPWCfWKPfQQWxEbifUsmqwxFjDU,3733
-md2conf/markdown.py,sha256=9BQbYD4GfpBYmx-3N1M36u2nVWY0VJ9UWKye2Jtnmnk,2901
-md2conf/matcher.py,sha256=m5rZjYZSjhKfdeKS8JdPq7cG861Mc6rVZBkrIOZTHGE,6916
-md2conf/mermaid.py,sha256=f0x7ISj-41ZMh4zTAFPhIWwr94SDcsVZUc1NWqmH_G4,2508
-md2conf/metadata.py,sha256=LzZM-oPNnzCULmLhF516tPlV5zZBknccwMHt8Nan-xg,1007
-md2conf/processor.py,sha256=z2d2KMPEYWaxflOtH2UTwrjzpPU8TtLSEUvor85ez1Q,9732
-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=Cyvjab8tBvKgubttQvNagS8nailuTvFBqUGoiX5MNp8,5351
-md2conf/xml.py,sha256=HoKJfF1yRZ3Gk8jTS-kRpOqVs0nQJZyr56l0Fo3y9fs,2193
-markdown_to_confluence-0.4.3.dist-info/METADATA,sha256=sU45yX796M_cZ0ssGMaDtuxb0xwtKaPTktNAy2rczMg,29119
-markdown_to_confluence-0.4.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-markdown_to_confluence-0.4.3.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
-markdown_to_confluence-0.4.3.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.4.3.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.4.3.dist-info/RECORD,,

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)