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

md2conf/csf.py

@@ -0,0 +1,217 @@
+"""
+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")
+
+
+def is_block_like(elem: ET._Element) -> bool:
+    return elem.tag in ["div", "li", "ol", "p", "pre", "ul"]
+
+
+def normalize_inline(elem: ET._Element) -> None:
+    """
+    Ensures that inline elements are direct children of an eligible block element.
+
+    The following transformations are applied:
+
+    * consecutive inline elements and text nodes that are the direct children of the parent element are wrapped into a `<p>`,
+    * block elements are left intact,
+    * leading and trailing whitespace in each block element is removed.
+
+    The above steps transform an element tree such as
+    ```
+    <li>  to <em>be</em>, <ol/> not to <em>be</em>  </li>
+    ```
+
+    into another element tree such as
+    ```
+    <li><p>to <em>be</em>,</p><ol/><p>not to <em>be</em></p></li>
+    ```
+    """
+
+    if not is_block_like(elem):
+        raise ValueError(f"expected: block element; got: {elem.tag!s}")
+
+    contents: list[ET._Element] = []
+
+    paragraph = HTML.p()
+    contents.append(paragraph)
+    if elem.text:
+        paragraph.text = elem.text
+        elem.text = None
+
+    for child in elem:
+        if is_block_like(child):
+            contents.append(child)
+            paragraph = HTML.p()
+            contents.append(paragraph)
+            if child.tail:
+                paragraph.text = child.tail
+                child.tail = None
+        else:
+            paragraph.append(child)
+
+    for item in contents:
+        # remove lead whitespace in the block element
+        if item.text:
+            item.text = item.text.lstrip()
+        if len(item) > 0:
+            # remove tail whitespace in the last child of the block element
+            last = item[-1]
+            if last.tail:
+                last.tail = last.tail.rstrip()
+        else:
+            # remove tail whitespace directly in the block element content
+            if item.text:
+                item.text = item.text.rstrip()
+
+        # ignore empty elements
+        if item.tag != "p" or len(item) > 0 or item.text:
+            elem.append(item)

md2conf/domain.py

@@ -30,6 +30,7 @@ class ConfluenceDocumentOptions:
     :param prefer_raster: Whether to choose PNG files over SVG files when available.
     :param render_drawio: Whether to pre-render (or use the pre-rendered version of) draw.io diagrams.
     :param render_mermaid: Whether to pre-render Mermaid diagrams into PNG/SVG images.
+    :param render_latex: Whether to pre-render LaTeX formulas 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.
     """
@@ -42,5 +43,6 @@ class ConfluenceDocumentOptions:
     prefer_raster: bool = True
     render_drawio: bool = False
     render_mermaid: bool = False
+    render_latex: bool = False
     diagram_output_format: Literal["png", "svg"] = "png"
     webui_links: bool = False

md2conf/drawio.py

@@ -9,9 +9,9 @@ Copyright 2022-2025, Levente Hunyadi
 import base64
 import logging
 import os
-import os.path
 import shutil
 import subprocess
+import tempfile
 import typing
 import zlib
 from pathlib import Path
@@ -153,7 +153,8 @@ def extract_xml_from_png(png_data: bytes) -> ET._Element:
         offset += 8
 
         if offset + length + 4 > len(png_data):
-            raise DrawioError(f"corrupted PNG: incomplete data for chunk {chunk_type.decode('ascii')}")
+            chunk_name = chunk_type.decode("ascii", errors="replace")
+            raise DrawioError(f"corrupted PNG: incomplete data for chunk {chunk_name}")
 
         # read chunk data
         chunk_data = png_data[offset : offset + length]
@@ -169,7 +170,7 @@ def extract_xml_from_png(png_data: bytes) -> ET._Element:
         # format: keyword\0text
         null_pos = chunk_data.find(b"\x00")
         if null_pos < 0:
-            raise DrawioError("corrupted PNG: tEXt chunk missing keyword")
+            raise DrawioError("corrupted PNG: `tEXt` chunk missing keyword or data")
 
         keyword = chunk_data[:null_pos].decode("latin1")
         if keyword != "mxfile":
@@ -236,17 +237,21 @@ def render_diagram(source: Path, output_format: typing.Literal["png", "svg"] = "
     if executable is None:
         raise DrawioError("draw.io executable not found")
 
-    target = f"tmp_drawio.{output_format}"
+    # create a temporary file and get its file descriptor and path
+    fd, target = tempfile.mkstemp(prefix="drawio_", suffix=f".{output_format}")
 
-    cmd = [executable, "--export", "--format", output_format, "--output", target]
-    if output_format == "png":
-        cmd.extend(["--scale", "2", "--transparent"])
-    elif output_format == "svg":
-        cmd.append("--embed-svg-images")
-    cmd.append(str(source))
-
-    LOGGER.debug("Executing: %s", " ".join(cmd))
     try:
+        # close the descriptor, just use the filename
+        os.close(fd)
+
+        cmd = [executable, "--export", "--format", output_format, "--output", target]
+        if output_format == "png":
+            cmd.extend(["--scale", "2", "--transparent"])
+        elif output_format == "svg":
+            cmd.append("--embed-svg-images")
+        cmd.append(str(source))
+
+        LOGGER.debug("Executing: %s", " ".join(cmd))
         proc = subprocess.Popen(
             cmd,
             stdout=subprocess.PIPE,
@@ -267,5 +272,4 @@ def render_diagram(source: Path, output_format: typing.Literal["png", "svg"] = "
             return f.read()
 
     finally:
-        if os.path.exists(target):
-            os.remove(target)
+        os.remove(target)

md2conf/latex.py

@@ -0,0 +1,245 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import importlib.util
+from io import BytesIO
+from pathlib import Path
+from struct import unpack
+from typing import BinaryIO, Iterable, Literal, Optional, Union, overload
+
+
+def render_latex(expression: str, *, format: Literal["png", "svg"] = "png", dpi: int = 100, font_size: int = 12) -> bytes:
+    """
+    Generates a PNG or SVG image of a LaTeX math expression using `matplotlib` for rendering.
+
+    :param expression: A LaTeX math expression, e.g., r'\frac{a}{b}'.
+    :param format: Output image format.
+    :param dpi: Output image resolution (if applicable).
+    :param font_size: Font size of the LaTeX text (if applicable).
+    """
+
+    with BytesIO() as f:
+        _render_latex(expression, f, format=format, dpi=dpi, font_size=font_size)
+        return f.getvalue()
+
+
+if importlib.util.find_spec("matplotlib") is None:
+    LATEX_ENABLED = False
+
+    def _render_latex(expression: str, f: BinaryIO, *, format: Literal["png", "svg"], dpi: int, font_size: int) -> None:
+        raise RuntimeError("matplotlib not installed; run: `pip install matplotlib`")
+
+else:
+    import matplotlib
+    import matplotlib.pyplot as plt
+
+    matplotlib.rcParams["mathtext.fontset"] = "cm"  # change font to "Computer Modern"
+
+    LATEX_ENABLED = True
+
+    def _render_latex(expression: str, f: BinaryIO, *, format: Literal["png", "svg"], dpi: int, font_size: int) -> None:
+        # create a figure with no axis
+        fig = plt.figure(dpi=dpi)
+
+        # transparent background
+        fig.patch.set_alpha(0)
+
+        # add LaTeX text
+        fig.text(x=0, y=0, s=f"${expression}$", fontsize=font_size)
+
+        # save the image
+        fig.savefig(
+            f,
+            transparent=True,
+            format=format,
+            bbox_inches="tight",
+            pad_inches=0.0,
+            metadata={"Title": expression} if format == "png" else None,
+        )
+
+        # close the figure to free memory
+        plt.close(fig)
+
+
+@overload
+def get_png_dimensions(*, data: bytes) -> tuple[int, int]: ...
+
+
+@overload
+def get_png_dimensions(*, path: Union[str, Path]) -> tuple[int, int]: ...
+
+
+def get_png_dimensions(*, data: Optional[bytes] = None, path: Union[str, Path, None] = None) -> tuple[int, int]:
+    """
+    Returns the width and height of a PNG image inspecting its header.
+
+    :param data: PNG image data.
+    :param path: Path to the PNG image file.
+    :returns: A tuple of the image's width and height in pixels.
+    """
+
+    if data is not None and path is not None:
+        raise TypeError("expected: either `data` or `path`; got: both")
+    elif data is not None:
+        with BytesIO(data) as f:
+            return _get_png_dimensions(f)
+    elif path is not None:
+        with open(path, "rb") as f:
+            return _get_png_dimensions(f)
+    else:
+        raise TypeError("expected: either `data` or `path`; got: neither")
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_data: bytes) -> bytes: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_path: Union[str, Path]) -> bytes: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_data: bytes, target_path: Union[str, Path]) -> None: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_path: Union[str, Path], target_path: Union[str, Path]) -> None: ...
+
+
+def remove_png_chunks(
+    names: Iterable[str], *, source_data: Optional[bytes] = None, source_path: Union[str, Path, None] = None, target_path: Union[str, Path, None] = None
+) -> Optional[bytes]:
+    """
+    Rewrites a PNG file by removing chunks with the specified names.
+
+    :param source_data: PNG image data.
+    :param source_path: Path to the file to read from.
+    :param target_path: Path to the file to write to.
+    """
+
+    if source_data is not None and source_path is not None:
+        raise TypeError("expected: either `source_data` or `source_path`; got: both")
+    elif source_data is not None:
+
+        def source_reader() -> BinaryIO:
+            return BytesIO(source_data)
+    elif source_path is not None:
+
+        def source_reader() -> BinaryIO:
+            return open(source_path, "rb")
+    else:
+        raise TypeError("expected: either `source_data` or `source_path`; got: neither")
+
+    if target_path is None:
+        with source_reader() as source_file, BytesIO() as memory_file:
+            _remove_png_chunks(names, source_file, memory_file)
+            return memory_file.getvalue()
+    else:
+        with source_reader() as source_file, open(target_path, "wb") as target_file:
+            _remove_png_chunks(names, source_file, target_file)
+            return None
+
+
+class _Chunk:
+    __slots__ = ("length", "name", "data", "crc")
+
+    length: int
+    name: bytes
+    data: bytes
+    crc: bytes
+
+    def __init__(self, length: int, name: bytes, data: bytes, crc: bytes):
+        self.length = length
+        self.name = name
+        self.data = data
+        self.crc = crc
+
+
+def _read_signature(f: BinaryIO) -> None:
+    "Reads and checks PNG signature (first 8 bytes)."
+
+    signature = f.read(8)
+    if signature != b"\x89PNG\r\n\x1a\n":
+        raise ValueError("not a valid PNG file")
+
+
+def _read_chunk(f: BinaryIO) -> Optional[_Chunk]:
+    "Reads and parses a PNG chunk such as `IHDR` or `tEXt`."
+
+    length_bytes = f.read(4)
+    if not length_bytes:
+        return None
+
+    if len(length_bytes) != 4:
+        raise ValueError("insufficient bytes to read chunk length")
+
+    length = int.from_bytes(length_bytes, "big")
+
+    data_length = 4 + length + 4
+    data_bytes = f.read(data_length)
+    if len(data_bytes) != data_length:
+        raise ValueError(f"insufficient bytes to read chunk data of length {length}")
+
+    chunk_type = data_bytes[0:4]
+    chunk_data = data_bytes[4:-4]
+    crc = data_bytes[-4:]
+
+    return _Chunk(length, chunk_type, chunk_data, crc)
+
+
+def _write_chunk(f: BinaryIO, chunk: _Chunk) -> None:
+    f.write(chunk.length.to_bytes(4, "big"))
+    f.write(chunk.name)
+    f.write(chunk.data)
+    f.write(chunk.crc)
+
+
+def _get_png_dimensions(source_file: BinaryIO) -> tuple[int, int]:
+    """
+    Returns the width and height of a PNG image inspecting its header.
+
+    :param source_file: A binary file opened for reading that contains PNG image data.
+    :returns: A tuple of the image's width and height in pixels.
+    """
+
+    _read_signature(source_file)
+
+    # validate IHDR chunk
+    ihdr = _read_chunk(source_file)
+    if ihdr is None:
+        raise ValueError("missing IHDR chunk")
+
+    if ihdr.length != 13:
+        raise ValueError("invalid chunk length")
+    if ihdr.name != b"IHDR":
+        raise ValueError(f"expected: IHDR chunk; got: {ihdr.name!r}")
+
+    (width, height, bit_depth, color_type, compression, filter, interlace) = unpack(">IIBBBBB", ihdr.data)
+    return width, height
+
+
+def _remove_png_chunks(names: Iterable[str], source_file: BinaryIO, target_file: BinaryIO) -> None:
+    """
+    Rewrites a PNG file by removing chunks with the specified names.
+
+    :param source_file: A binary file opened for reading that contains PNG image data.
+    :param target_file: A binary file opened for writing to receive PNG image data.
+    """
+
+    exclude_set = set(name.encode("ascii") for name in names)
+
+    _read_signature(source_file)
+    target_file.write(b"\x89PNG\r\n\x1a\n")
+
+    while True:
+        chunk = _read_chunk(source_file)
+        if chunk is None:
+            break
+
+        if chunk.name not in exclude_set:
+            _write_chunk(target_file, chunk)

md2conf/local.py

@@ -83,9 +83,9 @@ 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, file_data in document.embedded_files.items():
             with open(csf_dir / name, "wb") as f:
-                f.write(data)
+                f.write(file_data.data)
 
 
 class LocalProcessorFactory(ProcessorFactory):

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:
@@ -73,9 +76,11 @@ _CONVERTER = markdown.Markdown(
         "markdown.extensions.tables",
         "md_in_html",
         "pymdownx.arithmatex",
+        "pymdownx.caret",
         "pymdownx.emoji",
         "pymdownx.highlight",  # required by `pymdownx.superfences`
         "pymdownx.magiclink",
+        "pymdownx.mark",
         "pymdownx.superfences",
         "pymdownx.tilde",
         "sane_lists",
@@ -83,13 +88,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},
         "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/mermaid.py

@@ -47,14 +47,12 @@ def has_mmdc() -> bool:
 def render_diagram(source: str, output_format: Literal["png", "svg"] = "png") -> bytes:
     "Generates a PNG or SVG image from a Mermaid diagram source."
 
-    filename = f"tmp_mermaid.{output_format}"
-
     cmd = [
         get_mmdc(),
         "--input",
         "-",
         "--output",
-        filename,
+        "-",
         "--outputFormat",
         output_format,
         "--backgroundColor",
@@ -66,27 +64,23 @@ def render_diagram(source: str, output_format: Literal["png", "svg"] = "png") ->
     if is_docker():
         cmd.extend(["-p", os.path.join(root, "puppeteer-config.json")])
     LOGGER.debug("Executing: %s", " ".join(cmd))
-    try:
-        proc = subprocess.Popen(
-            cmd,
-            stdout=subprocess.PIPE,
-            stdin=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            text=False,
-        )
-        stdout, stderr = proc.communicate(input=source.encode("utf-8"))
-        if proc.returncode:
-            messages = [f"failed to convert Mermaid diagram; exit code: {proc.returncode}"]
-            console_output = stdout.decode("utf-8")
-            if console_output:
-                messages.append(f"output:\n{console_output}")
-            console_error = stderr.decode("utf-8")
-            if console_error:
-                messages.append(f"error:\n{console_error}")
-            raise RuntimeError("\n".join(messages))
-        with open(filename, "rb") as image:
-            return image.read()
-
-    finally:
-        if os.path.exists(filename):
-            os.remove(filename)
+
+    proc = subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stdin=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=False,
+    )
+    stdout, stderr = proc.communicate(input=source.encode("utf-8"))
+    if proc.returncode:
+        messages = [f"failed to convert Mermaid diagram; exit code: {proc.returncode}"]
+        console_output = stdout.decode("utf-8")
+        if console_output:
+            messages.append(f"output:\n{console_output}")
+        console_error = stderr.decode("utf-8")
+        if console_error:
+            messages.append(f"error:\n{console_error}")
+        raise RuntimeError("\n".join(messages))
+
+    return stdout