markdown-to-confluence 0.5.2__py3-none-any.whl → 0.5.3__py3-none-any.whl

md2conf/png.py

@@ -0,0 +1,202 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from io import BytesIO
+from pathlib import Path
+from struct import unpack
+from typing import BinaryIO, Iterable, overload
+
+
+class _Chunk:
+    "Data chunk in binary data as per the PNG image format."
+
+    __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) -> _Chunk | None:
+    "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("expected: 4 bytes storing chunk length")
+
+    length = int.from_bytes(length_bytes, "big")
+
+    data_length = 4 + length + 4
+    data_bytes = f.read(data_length)
+    actual_length = len(data_bytes)
+    if actual_length != data_length:
+        raise ValueError(f"expected: {length} bytes storing chunk data; got: {actual_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 _extract_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 (Image Header) 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,  # pyright: ignore[reportUnusedVariable]
+        color_type,  # pyright: ignore[reportUnusedVariable]
+        compression,  # pyright: ignore[reportUnusedVariable]
+        filter,  # pyright: ignore[reportUnusedVariable]
+        interlace,  # pyright: ignore[reportUnusedVariable]
+    ) = unpack(">IIBBBBB", ihdr.data)  # spellchecker:disable-line
+    return width, height
+
+
+@overload
+def extract_png_dimensions(*, data: bytes) -> tuple[int, int]: ...
+
+
+@overload
+def extract_png_dimensions(*, path: str | Path) -> tuple[int, int]: ...
+
+
+def extract_png_dimensions(*, data: bytes | None = None, path: 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 _extract_png_dimensions(f)
+    elif path is not None:
+        with open(path, "rb") as f:
+            return _extract_png_dimensions(f)
+    else:
+        raise TypeError("expected: either `data` or `path`; got: neither")
+
+
+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 _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)
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_data: bytes) -> bytes: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_path: str | Path) -> bytes: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_data: bytes, target_path: str | Path) -> None: ...
+
+
+@overload
+def remove_png_chunks(names: Iterable[str], *, source_path: str | Path, target_path: str | Path) -> None: ...
+
+
+def remove_png_chunks(
+    names: Iterable[str], *, source_data: bytes | None = None, source_path: str | Path | None = None, target_path: str | Path | None = None
+) -> bytes | None:
+    """
+    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

md2conf/processor.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -15,16 +15,18 @@ from typing import Iterable
 
 from .collection import ConfluencePageCollection
 from .converter import ConfluenceDocument
-from .domain import ConfluenceDocumentOptions, ConfluencePageID
 from .environment import ArgumentError
 from .matcher import DirectoryEntry, FileEntry, Matcher, MatcherOptions
 from .metadata import ConfluenceSiteMetadata
+from .options import ConfluencePageID, DocumentOptions
 from .scanner import Scanner
 
 LOGGER = logging.getLogger(__name__)
 
 
 class DocumentNode:
+    "Represents a Markdown document in a hierarchy."
+
     absolute_path: Path
     page_id: str | None
     space_key: str | None
@@ -49,24 +51,42 @@ class DocumentNode:
         self._children = []
 
     def count(self) -> int:
+        "Number of descendants in the sub-tree spanned by this node (excluding the top-level node)."
+
         c = len(self._children)
         for child in self._children:
             c += child.count()
         return c
 
     def add_child(self, child: "DocumentNode") -> None:
+        "Adds a new node to the list of direct children."
+
         self._children.append(child)
 
     def children(self) -> Iterable["DocumentNode"]:
+        "Direct children of this node."
+
         for child in self._children:
             yield child
 
     def descendants(self) -> Iterable["DocumentNode"]:
+        """
+        Descendants of this node, part of its sub-tree.
+
+        Traversal follows depth-first search.
+        """
+
         for child in self._children:
             yield child
             yield from child.descendants()
 
     def all(self) -> Iterable["DocumentNode"]:
+        """
+        Descendants of this node, part of the sub-tree including the top-level node.
+
+        Traversal follows depth-first search.
+        """
+
         yield self
         for child in self._children:
             yield from child.all()
@@ -77,7 +97,7 @@ class Processor:
     Processes a single Markdown page or a directory of Markdown pages.
     """
 
-    options: ConfluenceDocumentOptions
+    options: DocumentOptions
     site: ConfluenceSiteMetadata
     root_dir: Path
 
@@ -85,7 +105,7 @@ class Processor:
 
     def __init__(
         self,
-        options: ConfluenceDocumentOptions,
+        options: DocumentOptions,
         site: ConfluenceSiteMetadata,
         root_dir: Path,
     ) -> None:
@@ -140,7 +160,7 @@ class Processor:
         self._update_page(page_id, document, path)
 
     @abstractmethod
-    def _synchronize_tree(self, root: DocumentNode, root_id: ConfluencePageID | None) -> None:
+    def _synchronize_tree(self, tree: DocumentNode, root_id: ConfluencePageID | None) -> None:
         """
         Creates the cross-reference index and synchronizes the directory tree structure with the Confluence page hierarchy.
 
@@ -228,12 +248,13 @@ class Processor:
         # extract information from a Markdown document found in a local directory.
         document = Scanner().read(path)
 
+        props = document.properties
         return DocumentNode(
             absolute_path=path,
-            page_id=document.page_id,
-            space_key=document.space_key,
-            title=document.title,
-            synchronized=document.synchronized if document.synchronized is not None else True,
+            page_id=props.page_id,
+            space_key=props.space_key,
+            title=props.title,
+            synchronized=props.synchronized if props.synchronized is not None else True,
         )
 
     def _generate_hash(self, absolute_path: Path) -> str:
@@ -247,10 +268,10 @@ class Processor:
 
 
 class ProcessorFactory:
-    options: ConfluenceDocumentOptions
+    options: DocumentOptions
     site: ConfluenceSiteMetadata
 
-    def __init__(self, options: ConfluenceDocumentOptions, site: ConfluenceSiteMetadata) -> None:
+    def __init__(self, options: DocumentOptions, site: ConfluenceSiteMetadata) -> None:
         self.options = options
         self.site = site
 

md2conf/publisher.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -10,12 +10,13 @@ import logging
 from pathlib import Path
 
 from .api import ConfluenceContentProperty, ConfluenceLabel, ConfluenceSession, ConfluenceStatus
-from .converter import ConfluenceDocument, attachment_name, get_volatile_attributes, get_volatile_elements
+from .attachment import attachment_name
+from .compatibility import override, path_relative_to
+from .converter import ConfluenceDocument, get_volatile_attributes, get_volatile_elements
 from .csf import AC_ATTR, elements_from_string
-from .domain import ConfluenceDocumentOptions, ConfluencePageID
 from .environment import PageError
-from .extra import override, path_relative_to
 from .metadata import ConfluencePageMetadata
+from .options import ConfluencePageID, DocumentOptions
 from .processor import Converter, DocumentNode, Processor, ProcessorFactory
 from .xml import is_xml_equal, unwrap_substitute
 
@@ -29,7 +30,7 @@ class SynchronizingProcessor(Processor):
 
     api: ConfluenceSession
 
-    def __init__(self, api: ConfluenceSession, options: ConfluenceDocumentOptions, root_dir: Path) -> None:
+    def __init__(self, api: ConfluenceSession, options: DocumentOptions, root_dir: Path) -> None:
         """
         Initializes a new processor instance.
 
@@ -42,7 +43,7 @@ class SynchronizingProcessor(Processor):
         self.api = api
 
     @override
-    def _synchronize_tree(self, root: DocumentNode, root_id: ConfluencePageID | None) -> None:
+    def _synchronize_tree(self, tree: DocumentNode, root_id: ConfluencePageID | None) -> None:
         """
         Creates the cross-reference index and synchronizes the directory tree structure with the Confluence page hierarchy.
 
@@ -51,21 +52,16 @@ class SynchronizingProcessor(Processor):
         Updates the original Markdown document to add tags to associate the document with its corresponding Confluence page.
         """
 
-        if root.page_id is None and root_id is None:
-            raise PageError(f"expected: root page ID in options, or explicit page ID in {root.absolute_path}")
-        elif root.page_id is not None and root_id is not None:
-            if root.page_id != root_id.page_id:
-                raise PageError(f"mismatched inferred page ID of {root_id.page_id} and explicit page ID in {root.absolute_path}")
-
-            real_id = root_id
+        if tree.page_id is None and root_id is None:
+            raise PageError(f"expected: root page ID in options, or explicit page ID in {tree.absolute_path}")
+        elif tree.page_id is not None:
+            real_id = ConfluencePageID(tree.page_id)  # explicit page ID takes precedence
         elif root_id is not None:
             real_id = root_id
-        elif root.page_id is not None:
-            real_id = ConfluencePageID(root.page_id)
         else:
             raise NotImplementedError("condition not exhaustive")
 
-        self._synchronize_subtree(root, real_id)
+        self._synchronize_subtree(tree, real_id)
 
     def _synchronize_subtree(self, node: DocumentNode, parent_id: ConfluencePageID) -> None:
         if node.page_id is not None:
@@ -212,7 +208,7 @@ class SynchronizingProcessor(Processor):
 class SynchronizingProcessorFactory(ProcessorFactory):
     api: ConfluenceSession
 
-    def __init__(self, api: ConfluenceSession, options: ConfluenceDocumentOptions) -> None:
+    def __init__(self, api: ConfluenceSession, options: DocumentOptions) -> None:
         super().__init__(options, api.site)
         self.api = api
 
@@ -227,5 +223,5 @@ class Publisher(Converter):
     This is the class instantiated by the command-line application.
     """
 
-    def __init__(self, api: ConfluenceSession, options: ConfluenceDocumentOptions) -> None:
+    def __init__(self, api: ConfluenceSession, options: DocumentOptions) -> None:
         super().__init__(SynchronizingProcessorFactory(api, options))

md2conf/scanner.py

@@ -1,55 +1,34 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
 
-import re
-import typing
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Literal, TypeVar
+from typing import TypeVar
 
-import yaml
-
-from .mermaid import MermaidConfigProperties
+from .coalesce import coalesce
+from .frontmatter import extract_frontmatter_json, extract_value
+from .options import LayoutOptions
 from .serializer import JsonType, json_to_object
 
 T = TypeVar("T")
 
 
-def extract_value(pattern: str, text: str) -> tuple[str | None, str]:
-    values: list[str] = []
-
-    def _repl_func(match: re.Match[str]) -> str:
-        values.append(match.group(1))
-        return ""
-
-    text = re.sub(pattern, _repl_func, text, count=1, flags=re.ASCII)
-    value = values[0] if values else None
-    return value, text
-
-
-def extract_frontmatter_block(text: str) -> tuple[str | None, str]:
-    "Extracts the front-matter from a Markdown document as a blob of unparsed text."
-
-    return extract_value(r"(?ms)\A---$(.+?)^---$", text)
-
-
-def extract_frontmatter_properties(text: str) -> tuple[dict[str, JsonType] | None, str]:
-    "Extracts the front-matter from a Markdown document as a dictionary."
-
-    block, text = extract_frontmatter_block(text)
+@dataclass
+class AliasProperties:
+    """
+    An object that holds properties extracted from the front-matter of a Markdown document.
 
-    properties: dict[str, Any] | None = None
-    if block is not None:
-        data = yaml.safe_load(block)
-        if isinstance(data, dict):
-            properties = typing.cast(dict[str, JsonType], data)
+    :param confluence_page_id: Confluence page ID. (Alternative name for JSON de-serialization.)
+    :param confluence_space_key: Confluence space key. (Alternative name for JSON de-serialization.)
+    """
 
-    return properties, text
+    confluence_page_id: str | None = None
+    confluence_space_key: str | None = None
 
 
 @dataclass
@@ -59,26 +38,22 @@ class DocumentProperties:
 
     :param page_id: Confluence page ID.
     :param space_key: Confluence space key.
-    :param confluence_page_id: Confluence page ID. (Alternative name for JSON de-serialization.)
-    :param confluence_space_key: Confluence space key. (Alternative name for JSON de-serialization.)
     :param generated_by: Text identifying the tool that generated the document.
     :param title: The title extracted from front-matter.
     :param tags: A list of tags (content labels) extracted from front-matter.
     :param synchronized: True if the document content is parsed and synchronized with Confluence.
     :param properties: A dictionary of key-value pairs extracted from front-matter to apply as page properties.
-    :param alignment: Alignment for block-level images and formulas.
+    :param layout: Layout options for content on a Confluence page.
     """
 
     page_id: str | None = None
     space_key: str | None = None
-    confluence_page_id: str | None = None
-    confluence_space_key: str | None = None
     generated_by: str | None = None
     title: str | None = None
     tags: list[str] | None = None
     synchronized: bool | None = None
     properties: dict[str, JsonType] | None = None
-    alignment: Literal["center", "left", "right"] | None = None
+    layout: LayoutOptions | None = None
 
 
 @dataclass
@@ -86,25 +61,11 @@ class ScannedDocument:
     """
     An object that holds properties extracted from a Markdown document, including remaining source text.
 
-    :param page_id: Confluence page ID.
-    :param space_key: Confluence space key.
-    :param generated_by: Text identifying the tool that generated the document.
-    :param title: The title extracted from front-matter.
-    :param tags: A list of tags (content labels) extracted from front-matter.
-    :param synchronized: True if the document content is parsed and synchronized with Confluence.
-    :param properties: A dictionary of key-value pairs extracted from front-matter to apply as page properties.
-    :param alignment: Alignment for block-level images and formulas.
+    :param properties: Properties extracted from the front-matter of a Markdown document.
     :param text: Text that remains after front-matter and inline properties have been extracted.
     """
 
-    page_id: str | None
-    space_key: str | None
-    generated_by: str | None
-    title: str | None
-    tags: list[str] | None
-    synchronized: bool | None
-    properties: dict[str, JsonType] | None
-    alignment: Literal["center", "left", "right"] | None
+    properties: DocumentProperties
     text: str
 
 
@@ -127,77 +88,19 @@ class Scanner:
         # extract 'generated-by' tag text
         generated_by, text = extract_value(r"<!--\s+generated[-_]by:\s*(.*)\s+-->", text)
 
-        title: str | None = None
-        tags: list[str] | None = None
-        synchronized: bool | None = None
-        properties: dict[str, JsonType] | None = None
-        alignment: Literal["center", "left", "right"] | None = None
+        body_props = DocumentProperties(page_id=page_id, space_key=space_key, generated_by=generated_by)
 
         # extract front-matter
-        data, text = extract_frontmatter_properties(text)
+        data, text = extract_frontmatter_json(text)
         if data is not None:
-            p = json_to_object(DocumentProperties, data)
-            page_id = page_id or p.confluence_page_id or p.page_id
-            space_key = space_key or p.confluence_space_key or p.space_key
-            generated_by = generated_by or p.generated_by
-            title = p.title
-            tags = p.tags
-            synchronized = p.synchronized
-            properties = p.properties
-            alignment = p.alignment
-
-        return ScannedDocument(
-            page_id=page_id,
-            space_key=space_key,
-            generated_by=generated_by,
-            title=title,
-            tags=tags,
-            synchronized=synchronized,
-            properties=properties,
-            alignment=alignment,
-            text=text,
-        )
-
-
-@dataclass
-class MermaidProperties:
-    """
-    An object that holds the front-matter properties structure for Mermaid diagrams.
-
-    :param title: The title of the diagram.
-    :param config: Configuration options for rendering.
-    """
-
-    title: str | None = None
-    config: MermaidConfigProperties | None = None
-
-
-class MermaidScanner:
-    """
-    Extracts properties from the JSON/YAML front-matter of a Mermaid diagram.
-    """
-
-    def read(self, content: str) -> MermaidProperties:
-        """
-        Extracts rendering preferences from a Mermaid front-matter content.
-
-        ```
-        ---
-        title: Tiny flow diagram
-        config:
-            scale: 1
-        ---
-        flowchart LR
-            A[Component A] --> B[Component B]
-            B --> C[Component C]
-        ```
-        """
-
-        properties, _ = extract_frontmatter_properties(content)
-        if properties is not None:
-            front_matter = json_to_object(MermaidProperties, properties)
-            config = front_matter.config or MermaidConfigProperties()
-
-            return MermaidProperties(title=front_matter.title, config=config)
-
-        return MermaidProperties()
+            frontmatter_props = json_to_object(DocumentProperties, data)
+            alias_props = json_to_object(AliasProperties, data)
+            if alias_props.confluence_page_id is not None:
+                frontmatter_props.page_id = alias_props.confluence_page_id
+            if alias_props.confluence_space_key is not None:
+                frontmatter_props.space_key = alias_props.confluence_space_key
+            props = coalesce(body_props, frontmatter_props)
+        else:
+            props = body_props
+
+        return ScannedDocument(properties=props, text=text)

md2conf/serializer.py

@@ -1,7 +1,7 @@
 """
 Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -10,7 +10,7 @@ import sys
 from datetime import datetime
 from typing import TypeVar
 
-from cattrs.preconf.orjson import make_converter
+from cattrs.preconf.orjson import make_converter  # spellchecker:disable-line
 
 JsonType = None | bool | int | float | str | dict[str, "JsonType"] | list["JsonType"]
 JsonComposite = dict[str, "JsonType"] | list["JsonType"]

md2conf/svg.py

@@ -1,7 +1,7 @@
 """
-SVG dimension extraction utilities.
+Publish Markdown files to Confluence wiki.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -317,3 +317,25 @@ def _parse_viewbox(viewbox: str) -> tuple[int | None, int | None]:
         return width, height
     except ValueError:
         return None, None
+
+
+def fix_svg_get_dimensions(image_data: bytes) -> tuple[bytes, int | None, int | None]:
+    """
+    Post-processes SVG diagram data by fixing dimensions and extracting metadata.
+
+    This handles the common pattern for SVG diagrams:
+
+    1. fixes SVG dimensions (converts percentage-based to explicit pixels), and
+    2. extracts width/height from the SVG.
+
+    :param image_data: Raw SVG data as bytes.
+    :returns: Tuple of update raw data, image width, image height.
+    """
+
+    # fix SVG to have explicit width/height instead of percentages
+    image_data = fix_svg_dimensions(image_data)
+
+    # extract dimensions from the fixed SVG
+    width, height = get_svg_dimensions_from_bytes(image_data)
+
+    return image_data, width, height