markdown-to-confluence 0.4.8__py3-none-any.whl → 0.5.1__py3-none-any.whl

md2conf/domain.py

@@ -7,7 +7,7 @@ Copyright 2022-2025, Levente Hunyadi
 """
 
 from dataclasses import dataclass
-from typing import Literal, Optional
+from typing import Literal
 
 
 @dataclass
@@ -39,8 +39,8 @@ class ConfluenceDocumentOptions:
 
     ignore_invalid_url: bool = False
     heading_anchors: bool = False
-    generated_by: Optional[str] = "This page has been generated with a tool."
-    root_page_id: Optional[ConfluencePageID] = None
+    generated_by: str | None = "This page has been generated with a tool."
+    root_page_id: ConfluencePageID | None = None
     keep_hierarchy: bool = False
     prefer_raster: bool = True
     render_drawio: bool = False

md2conf/drawio.py

@@ -51,7 +51,7 @@ def inflate(data: bytes) -> bytes:
     return zlib.decompress(data, -zlib.MAX_WBITS)
 
 
-def decompress_diagram(xml_data: typing.Union[bytes, str]) -> ElementType:
+def decompress_diagram(xml_data: bytes | str) -> ElementType:
     """
     Decompresses the text content of the `<diagram>` element in a draw.io XML document.
 

md2conf/environment.py

@@ -7,7 +7,7 @@ Copyright 2022-2025, Levente Hunyadi
 """
 
 import os
-from typing import Optional, overload
+from typing import overload
 
 
 class ArgumentError(ValueError):
@@ -27,10 +27,10 @@ def _validate_domain(domain: str) -> str: ...
 
 
 @overload
-def _validate_domain(domain: Optional[str]) -> Optional[str]: ...
+def _validate_domain(domain: str | None) -> str | None: ...
 
 
-def _validate_domain(domain: Optional[str]) -> Optional[str]:
+def _validate_domain(domain: str | None) -> str | None:
     if domain is None:
         return None
 
@@ -45,10 +45,10 @@ def _validate_base_path(base_path: str) -> str: ...
 
 
 @overload
-def _validate_base_path(base_path: Optional[str]) -> Optional[str]: ...
+def _validate_base_path(base_path: str | None) -> str | None: ...
 
 
-def _validate_base_path(base_path: Optional[str]) -> Optional[str]:
+def _validate_base_path(base_path: str | None) -> str | None:
     if base_path is None:
         return None
 
@@ -61,13 +61,13 @@ def _validate_base_path(base_path: Optional[str]) -> Optional[str]:
 class ConfluenceSiteProperties:
     domain: str
     base_path: str
-    space_key: Optional[str]
+    space_key: str | None
 
     def __init__(
         self,
-        domain: Optional[str] = None,
-        base_path: Optional[str] = None,
-        space_key: Optional[str] = None,
+        domain: str | None = None,
+        base_path: str | None = None,
+        space_key: str | None = None,
     ) -> None:
         opt_domain = domain or os.getenv("CONFLUENCE_DOMAIN")
         opt_base_path = base_path or os.getenv("CONFLUENCE_PATH")
@@ -93,24 +93,24 @@ class ConfluenceConnectionProperties:
     :param headers: Additional HTTP headers to pass to Confluence REST API calls.
     """
 
-    domain: Optional[str]
-    base_path: Optional[str]
-    space_key: Optional[str]
-    api_url: Optional[str]
-    user_name: Optional[str]
+    domain: str | None
+    base_path: str | None
+    space_key: str | None
+    api_url: str | None
+    user_name: str | None
     api_key: str
-    headers: Optional[dict[str, str]]
+    headers: dict[str, str] | None
 
     def __init__(
         self,
         *,
-        api_url: Optional[str] = None,
-        domain: Optional[str] = None,
-        base_path: Optional[str] = None,
-        user_name: Optional[str] = None,
-        api_key: Optional[str] = None,
-        space_key: Optional[str] = None,
-        headers: Optional[dict[str, str]] = None,
+        api_url: str | None = None,
+        domain: str | None = None,
+        base_path: str | None = None,
+        user_name: str | None = None,
+        api_key: str | None = None,
+        space_key: str | None = None,
+        headers: dict[str, str] | None = None,
     ) -> None:
         opt_api_url = api_url or os.getenv("CONFLUENCE_API_URL")
         opt_domain = domain or os.getenv("CONFLUENCE_DOMAIN")

md2conf/latex.py

@@ -10,7 +10,7 @@ import importlib.util
 from io import BytesIO
 from pathlib import Path
 from struct import unpack
-from typing import BinaryIO, Iterable, Literal, Optional, Union, overload
+from typing import BinaryIO, Iterable, Literal, overload
 
 
 def render_latex(expression: str, *, format: Literal["png", "svg"] = "png", dpi: int = 100, font_size: int = 12) -> bytes:
@@ -71,10 +71,10 @@ 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(*, path: str | Path) -> tuple[int, int]: ...
 
 
-def get_png_dimensions(*, data: Optional[bytes] = None, path: Union[str, Path, None] = None) -> tuple[int, int]:
+def get_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.
 
@@ -100,20 +100,20 @@ 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: ...
+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: Union[str, Path]) -> None: ...
+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: Union[str, Path], target_path: Union[str, Path]) -> None: ...
+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: Optional[bytes] = None, source_path: Union[str, Path, None] = None, target_path: Union[str, Path, None] = None
-) -> Optional[bytes]:
+    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.
 
@@ -168,7 +168,7 @@ def _read_signature(f: BinaryIO) -> None:
         raise ValueError("not a valid PNG file")
 
 
-def _read_chunk(f: BinaryIO) -> Optional[_Chunk]:
+def _read_chunk(f: BinaryIO) -> _Chunk | None:
     "Reads and parses a PNG chunk such as `IHDR` or `tEXt`."
 
     length_bytes = f.read(4)

md2conf/local.py

@@ -9,7 +9,6 @@ Copyright 2022-2025, Levente Hunyadi
 import logging
 import os
 from pathlib import Path
-from typing import Optional
 
 from .converter import ConfluenceDocument
 from .domain import ConfluenceDocumentOptions, ConfluencePageID
@@ -30,7 +29,7 @@ class LocalProcessor(Processor):
         options: ConfluenceDocumentOptions,
         site: ConfluenceSiteMetadata,
         *,
-        out_dir: Optional[Path],
+        out_dir: Path | None,
         root_dir: Path,
     ) -> None:
         """
@@ -46,7 +45,7 @@ class LocalProcessor(Processor):
         self.out_dir = out_dir or root_dir
 
     @override
-    def _synchronize_tree(self, root: DocumentNode, root_id: Optional[ConfluencePageID]) -> None:
+    def _synchronize_tree(self, root: DocumentNode, root_id: ConfluencePageID | None) -> None:
         """
         Creates the cross-reference index.
 
@@ -89,13 +88,13 @@ class LocalProcessor(Processor):
 
 
 class LocalProcessorFactory(ProcessorFactory):
-    out_dir: Optional[Path]
+    out_dir: Path | None
 
     def __init__(
         self,
         options: ConfluenceDocumentOptions,
         site: ConfluenceSiteMetadata,
-        out_dir: Optional[Path] = None,
+        out_dir: Path | None = None,
     ) -> None:
         super().__init__(options, site)
         self.out_dir = out_dir
@@ -113,6 +112,6 @@ class LocalConverter(Converter):
         self,
         options: ConfluenceDocumentOptions,
         site: ConfluenceSiteMetadata,
-        out_dir: Optional[Path] = None,
+        out_dir: Path | None = None,
     ) -> None:
         super().__init__(LocalProcessorFactory(options, site, out_dir))

md2conf/markdown.py

@@ -7,7 +7,7 @@ Copyright 2022-2025, Levente Hunyadi
 """
 
 import xml.etree.ElementTree
-from typing import Any, Optional
+from typing import Any
 
 import markdown
 
@@ -15,11 +15,11 @@ import markdown
 def _emoji_generator(
     index: str,
     shortname: str,
-    alias: Optional[str],
-    uc: Optional[str],
+    alias: str | None,
+    uc: str | None,
     alt: str,
-    title: Optional[str],
-    category: Optional[str],
+    title: str | None,
+    category: str | None,
     options: dict[str, Any],
     md: markdown.Markdown,
 ) -> xml.etree.ElementTree.Element:
@@ -46,9 +46,9 @@ def _verbatim_formatter(
     css_class: str,
     options: dict[str, Any],
     md: markdown.Markdown,
-    classes: Optional[list[str]] = None,
+    classes: list[str] | None = None,
     id_value: str = "",
-    attrs: Optional[dict[str, str]] = None,
+    attrs: dict[str, str] | None = None,
     **kwargs: Any,
 ) -> str:
     """

md2conf/matcher.py

@@ -10,7 +10,7 @@ import os.path
 from dataclasses import dataclass
 from fnmatch import fnmatch
 from pathlib import Path
-from typing import Iterable, Optional, Union, final, overload
+from typing import Iterable, final, overload
 
 
 @dataclass(frozen=True, eq=True)
@@ -95,14 +95,14 @@ class MatcherOptions:
     """
 
     source: str
-    extension: Optional[str] = None
+    extension: str | None = None
 
     def __post_init__(self) -> None:
         if self.extension is not None and not self.extension.startswith("."):
             self.extension = f".{self.extension}"
 
 
-def _entry_name_dir(entry: Union[Entry, os.DirEntry[str]]) -> tuple[str, bool]:
+def _entry_name_dir(entry: Entry | os.DirEntry[str]) -> tuple[str, bool]:
     if isinstance(entry, Entry):
         return entry.name, entry.is_dir
     else:
@@ -155,7 +155,7 @@ class Matcher:
 
         ...
 
-    def is_excluded(self, entry: Union[Entry, os.DirEntry[str]]) -> bool:
+    def is_excluded(self, entry: Entry | os.DirEntry[str]) -> bool:
         name, is_dir = _entry_name_dir(entry)
 
         # skip hidden files and directories
@@ -192,7 +192,7 @@ class Matcher:
         """
         ...
 
-    def is_included(self, entry: Union[Entry, os.DirEntry[str]]) -> bool:
+    def is_included(self, entry: Entry | os.DirEntry[str]) -> bool:
         return not self.is_excluded(entry)
 
     def filter(self, entries: Iterable[Entry]) -> list[Entry]:

md2conf/mermaid.py

@@ -12,7 +12,7 @@ import os.path
 import shutil
 import subprocess
 from dataclasses import dataclass
-from typing import Literal, Optional
+from typing import Literal
 
 LOGGER = logging.getLogger(__name__)
 
@@ -25,7 +25,7 @@ class MermaidConfigProperties:
     :param scale: Scaling factor for the rendered diagram.
     """
 
-    scale: Optional[float] = None
+    scale: float | None = None
 
 
 def is_docker() -> bool:
@@ -56,7 +56,7 @@ def has_mmdc() -> bool:
     return shutil.which(executable) is not None
 
 
-def render_diagram(source: str, output_format: Literal["png", "svg"] = "png", config: Optional[MermaidConfigProperties] = None) -> bytes:
+def render_diagram(source: str, output_format: Literal["png", "svg"] = "png", config: MermaidConfigProperties | None = None) -> bytes:
     "Generates a PNG or SVG image from a Mermaid diagram source."
 
     if config is None:

md2conf/metadata.py

@@ -7,7 +7,6 @@ Copyright 2022-2025, Levente Hunyadi
 """
 
 from dataclasses import dataclass
-from typing import Optional
 
 
 @dataclass
@@ -22,7 +21,7 @@ class ConfluenceSiteMetadata:
 
     domain: str
     base_path: str
-    space_key: Optional[str]
+    space_key: str | None
 
 
 @dataclass

md2conf/processor.py

@@ -11,7 +11,7 @@ import logging
 import os
 from abc import abstractmethod
 from pathlib import Path
-from typing import Iterable, Optional
+from typing import Iterable
 
 from .collection import ConfluencePageCollection
 from .converter import ConfluenceDocument
@@ -26,9 +26,9 @@ LOGGER = logging.getLogger(__name__)
 
 class DocumentNode:
     absolute_path: Path
-    page_id: Optional[str]
-    space_key: Optional[str]
-    title: Optional[str]
+    page_id: str | None
+    space_key: str | None
+    title: str | None
     synchronized: bool
 
     _children: list["DocumentNode"]
@@ -36,9 +36,9 @@ class DocumentNode:
     def __init__(
         self,
         absolute_path: Path,
-        page_id: Optional[str],
-        space_key: Optional[str],
-        title: Optional[str],
+        page_id: str | None,
+        space_key: str | None,
+        title: str | None,
         synchronized: bool,
     ):
         self.absolute_path = absolute_path
@@ -140,7 +140,7 @@ class Processor:
         self._update_page(page_id, document, path)
 
     @abstractmethod
-    def _synchronize_tree(self, root: DocumentNode, root_id: Optional[ConfluencePageID]) -> None:
+    def _synchronize_tree(self, root: DocumentNode, root_id: ConfluencePageID | None) -> None:
         """
         Creates the cross-reference index and synchronizes the directory tree structure with the Confluence page hierarchy.
 
@@ -157,7 +157,7 @@ class Processor:
         """
         ...
 
-    def _index_directory(self, local_dir: Path, parent: Optional[DocumentNode]) -> DocumentNode:
+    def _index_directory(self, local_dir: Path, parent: DocumentNode | None) -> DocumentNode:
         """
         Indexes Markdown files in a directory hierarchy recursively.
         """
@@ -181,7 +181,7 @@ class Processor:
         directories.sort()
 
         # make page act as parent node
-        parent_doc: Optional[Path] = None
+        parent_doc: Path | None = None
         if FileEntry("index.md") in files:
             parent_doc = local_dir / "index.md"
         elif FileEntry("README.md") in files:
@@ -277,7 +277,7 @@ class Converter:
         else:
             raise ArgumentError(f"expected: valid file or directory path; got: {path}")
 
-    def process_directory(self, local_dir: Path, root_dir: Optional[Path] = None) -> None:
+    def process_directory(self, local_dir: Path, root_dir: Path | None = None) -> None:
         """
         Recursively scans a directory hierarchy for Markdown files, and processes each, resolving cross-references.
         """
@@ -290,7 +290,7 @@ class Converter:
 
         self.factory.create(root_dir).process_directory(local_dir)
 
-    def process_page(self, path: Path, root_dir: Optional[Path] = None) -> None:
+    def process_page(self, path: Path, root_dir: Path | None = None) -> None:
         """
         Processes a single Markdown file.
         """

md2conf/publisher.py

@@ -8,7 +8,6 @@ Copyright 2022-2025, Levente Hunyadi
 
 import logging
 from pathlib import Path
-from typing import Optional
 
 from .api import ConfluenceContentProperty, ConfluenceLabel, ConfluenceSession, ConfluenceStatus
 from .converter import ConfluenceDocument, attachment_name, get_volatile_attributes, get_volatile_elements
@@ -43,7 +42,7 @@ class SynchronizingProcessor(Processor):
         self.api = api
 
     @override
-    def _synchronize_tree(self, root: DocumentNode, root_id: Optional[ConfluencePageID]) -> None:
+    def _synchronize_tree(self, root: DocumentNode, root_id: ConfluencePageID | None) -> None:
         """
         Creates the cross-reference index and synchronizes the directory tree structure with the Confluence page hierarchy.
 

md2conf/scanner.py

@@ -10,25 +10,17 @@ import re
 import typing
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Literal, Optional, TypeVar
+from typing import Any, Literal, TypeVar
 
 import yaml
-from strong_typing.core import JsonType
-from strong_typing.serialization import DeserializerOptions, json_to_object
 
 from .mermaid import MermaidConfigProperties
+from .serializer import JsonType, json_to_object
 
 T = TypeVar("T")
 
 
-def _json_to_object(
-    typ: type[T],
-    data: JsonType,
-) -> T:
-    return json_to_object(typ, data, options=DeserializerOptions(skip_unassigned=True))
-
-
-def extract_value(pattern: str, text: str) -> tuple[Optional[str], str]:
+def extract_value(pattern: str, text: str) -> tuple[str | None, str]:
     values: list[str] = []
 
     def _repl_func(matchobj: re.Match[str]) -> str:
@@ -40,18 +32,18 @@ def extract_value(pattern: str, text: str) -> tuple[Optional[str], str]:
     return value, text
 
 
-def extract_frontmatter_block(text: str) -> tuple[Optional[str], str]:
+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[Optional[dict[str, JsonType]], str]:
+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)
 
-    properties: Optional[dict[str, Any]] = None
+    properties: dict[str, Any] | None = None
     if block is not None:
         data = yaml.safe_load(block)
         if isinstance(data, dict):
@@ -77,16 +69,16 @@ class DocumentProperties:
     :param alignment: Alignment for block-level images and formulas.
     """
 
-    page_id: Optional[str]
-    space_key: Optional[str]
-    confluence_page_id: Optional[str]
-    confluence_space_key: Optional[str]
-    generated_by: Optional[str]
-    title: Optional[str]
-    tags: Optional[list[str]]
-    synchronized: Optional[bool]
-    properties: Optional[dict[str, JsonType]]
-    alignment: Optional[Literal["center", "left", "right"]]
+    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
 
 
 @dataclass
@@ -105,14 +97,14 @@ class ScannedDocument:
     :param text: Text that remains after front-matter and inline properties have been extracted.
     """
 
-    page_id: Optional[str]
-    space_key: Optional[str]
-    generated_by: Optional[str]
-    title: Optional[str]
-    tags: Optional[list[str]]
-    synchronized: Optional[bool]
-    properties: Optional[dict[str, JsonType]]
-    alignment: Optional[Literal["center", "left", "right"]]
+    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
     text: str
 
 
@@ -135,16 +127,16 @@ class Scanner:
         # extract 'generated-by' tag text
         generated_by, text = extract_value(r"<!--\s+generated[-_]by:\s*(.*)\s+-->", text)
 
-        title: Optional[str] = None
-        tags: Optional[list[str]] = None
-        synchronized: Optional[bool] = None
-        properties: Optional[dict[str, JsonType]] = None
-        alignment: Optional[Literal["center", "left", "right"]] = 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
 
         # extract front-matter
         data, text = extract_frontmatter_properties(text)
         if data is not None:
-            p = _json_to_object(DocumentProperties, data)
+            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
@@ -176,8 +168,8 @@ class MermaidProperties:
     :param config: Configuration options for rendering.
     """
 
-    title: Optional[str] = None
-    config: Optional[MermaidConfigProperties] = None
+    title: str | None = None
+    config: MermaidConfigProperties | None = None
 
 
 class MermaidScanner:
@@ -203,7 +195,7 @@ class MermaidScanner:
 
         properties, _ = extract_frontmatter_properties(content)
         if properties is not None:
-            front_matter = _json_to_object(MermaidProperties, properties)
+            front_matter = json_to_object(MermaidProperties, properties)
             config = front_matter.config or MermaidConfigProperties()
 
             return MermaidProperties(title=front_matter.title, config=config)

md2conf/serializer.py

@@ -0,0 +1,64 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2025, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+import sys
+from datetime import datetime
+from typing import TypeVar
+
+from cattrs.preconf.orjson import make_converter
+
+JsonType = None | bool | int | float | str | dict[str, "JsonType"] | list["JsonType"]
+JsonComposite = dict[str, "JsonType"] | list["JsonType"]
+
+T = TypeVar("T")
+
+
+_converter = make_converter(forbid_extra_keys=False)
+
+
+if sys.version_info < (3, 11):
+
+    @_converter.register_structure_hook
+    def datetime_structure_hook(value: str, cls: type[datetime]) -> datetime:
+        if value.endswith("Z"):
+            # fromisoformat() prior to Python version 3.11 does not support military time zones like "Zulu" for UTC
+            value = f"{value[:-1]}+00:00"
+        return datetime.fromisoformat(value)
+
+
+@_converter.register_structure_hook
+def json_type_structure_hook(value: JsonType, cls: type[JsonType]) -> JsonType:
+    return value
+
+
+@_converter.register_structure_hook
+def json_composite_structure_hook(value: JsonComposite, cls: type[JsonComposite]) -> JsonComposite:
+    return value
+
+
+def json_to_object(typ: type[T], data: JsonType) -> T:
+    """
+    Converts a raw JSON object to a structured object, validating input data.
+
+    :param typ: Target structured type.
+    :param data: Source data as a JSON object.
+    :returns: A valid object instance of the expected type.
+    """
+
+    return _converter.structure(data, typ)
+
+
+def object_to_json_payload(data: object) -> bytes:
+    """
+    Converts a structured object to a JSON string encoded in UTF-8.
+
+    :param data: Object to convert to a JSON string.
+    :returns: JSON string encoded in UTF-8.
+    """
+
+    return _converter.dumps(data)