markdown-to-confluence 0.5.4__py3-none-any.whl → 0.5.5__py3-none-any.whl

md2conf/api.py

@@ -402,12 +402,7 @@ class ConfluenceAPI:
         )
         return self.session
 
-    def __exit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc_val: BaseException | None,
-        exc_tb: TracebackType | None,
-    ) -> None:
+    def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) -> None:
         """
         Closes an open connection.
         """
@@ -429,15 +424,7 @@ class ConfluenceSession:
     _space_id_to_key: dict[str, str]
     _space_key_to_id: dict[str, str]
 
-    def __init__(
-        self,
-        session: requests.Session,
-        *,
-        api_url: str | None,
-        domain: str | None,
-        base_path: str | None,
-        space_key: str | None,
-    ) -> None:
+    def __init__(self, session: requests.Session, *, api_url: str | None, domain: str | None, base_path: str | None, space_key: str | None) -> None:
         self.session = session
         self._space_id_to_key = {}
         self._space_key_to_id = {}
@@ -488,12 +475,7 @@ class ConfluenceSession:
         self.session.close()
         self.session = requests.Session()
 
-    def _build_url(
-        self,
-        version: ConfluenceVersion,
-        path: str,
-        query: dict[str, str] | None = None,
-    ) -> str:
+    def _build_url(self, version: ConfluenceVersion, path: str, query: dict[str, str] | None = None) -> str:
         """
         Builds a full URL for invoking the Confluence API.
 
@@ -506,14 +488,7 @@ class ConfluenceSession:
         base_url = f"{self.api_url}{version.value}{path}"
         return build_url(base_url, query)
 
-    def _get(
-        self,
-        version: ConfluenceVersion,
-        path: str,
-        response_type: type[T],
-        *,
-        query: dict[str, str] | None = None,
-    ) -> T:
+    def _get(self, version: ConfluenceVersion, path: str, response_type: type[T], *, query: dict[str, str] | None = None) -> T:
         "Executes an HTTP request via Confluence API."
 
         url = self._build_url(version, path, query)
@@ -829,13 +804,7 @@ class ConfluenceSession:
         LOGGER.info("Updating attachment: %s", attachment_id)
         self._put(ConfluenceVersion.VERSION_1, path, request, None)
 
-    def get_page_properties_by_title(
-        self,
-        title: str,
-        *,
-        space_id: str | None = None,
-        space_key: str | None = None,
-    ) -> ConfluencePageProperties:
+    def get_page_properties_by_title(self, title: str, *, space_id: str | None = None, space_key: str | None = None) -> ConfluencePageProperties:
         """
         Looks up a Confluence wiki page ID by title.
 
@@ -916,14 +885,7 @@ class ConfluenceSession:
 
         return self.get_page_properties(page_id).version.number
 
-    def update_page(
-        self,
-        page_id: str,
-        content: str,
-        *,
-        title: str,
-        version: int,
-    ) -> None:
+    def update_page(self, page_id: str, content: str, *, title: str, version: int, message: str) -> None:
         """
         Updates a page via the Confluence API.
 
@@ -939,35 +901,28 @@ class ConfluenceSession:
             status=ConfluenceStatus.CURRENT,
             title=title,
             body=ConfluencePageBody(storage=ConfluencePageStorage(representation=ConfluenceRepresentation.STORAGE, value=content)),
-            version=ConfluenceContentVersion(number=version, minorEdit=True),
+            version=ConfluenceContentVersion(number=version, minorEdit=True, message=message),
         )
         LOGGER.info("Updating page: %s", page_id)
         self._put(ConfluenceVersion.VERSION_2, path, request, None)
 
-    def create_page(
-        self,
-        parent_id: str,
-        title: str,
-        new_content: str,
-    ) -> ConfluencePage:
+    def create_page(self, *, title: str, content: str, parent_id: str, space_id: str) -> ConfluencePage:
         """
         Creates a new page via Confluence API.
         """
 
         LOGGER.info("Creating page: %s", title)
 
-        parent_page = self.get_page_properties(parent_id)
-
         path = "/pages/"
         request = ConfluenceCreatePageRequest(
-            spaceId=parent_page.spaceId,
+            spaceId=space_id,
             status=ConfluenceStatus.CURRENT,
             title=title,
             parentId=parent_id,
             body=ConfluencePageBody(
                 storage=ConfluencePageStorage(
                     representation=ConfluenceRepresentation.STORAGE,
-                    value=new_content,
+                    value=content,
                 )
             ),
         )
@@ -1009,23 +964,15 @@ class ConfluenceSession:
             response = self.session.delete(url, verify=True)
             response.raise_for_status()
 
-    def page_exists(
-        self,
-        title: str,
-        *,
-        space_id: str | None = None,
-        space_key: str | None = None,
-    ) -> str | None:
+    def page_exists(self, title: str, *, space_id: str | None = None) -> str | None:
         """
         Checks if a Confluence page exists with the given title.
 
         :param title: Page title. Pages in the same Confluence space must have a unique title.
-        :param space_key: Identifies the Confluence space.
-
+        :param space_id: Identifies the Confluence space.
         :returns: Confluence page ID of a matching page (if found), or `None`.
         """
 
-        space_id = self._get_space_id(space_id=space_id, space_key=space_key)
         path = "/pages"
         query = {"title": title}
         if space_id is not None:
@@ -1062,14 +1009,15 @@ class ConfluenceSession:
         """
 
         parent_page = self.get_page_properties(parent_id)
-        page_id = self.page_exists(title, space_id=parent_page.spaceId)
+        space_id = parent_page.spaceId
+        page_id = self.page_exists(title, space_id=space_id)
 
         if page_id is not None:
             LOGGER.debug("Retrieving existing page: %s", page_id)
             return self.get_page(page_id)
         else:
             LOGGER.debug("Creating new page with title: %s", title)
-            return self.create_page(parent_id, title, "")
+            return self.create_page(title=title, content="", parent_id=parent_id, space_id=space_id)
 
     def get_labels(self, page_id: str) -> list[ConfluenceIdentifiedLabel]:
         """
@@ -1133,6 +1081,23 @@ class ConfluenceSession:
             remove_labels.sort()
             self.remove_labels(page_id, remove_labels)
 
+    def get_content_property_for_page(self, page_id: str, key: str) -> ConfluenceIdentifiedContentProperty | None:
+        """
+        Retrieves a content property for a Confluence page.
+
+        :param page_id: The Confluence page ID.
+        :param key: The name of the property to fetch (with case-sensitive match).
+        :returns: The content property value, or `None` if not found.
+        """
+
+        path = f"/pages/{page_id}/properties"
+        results = self._fetch(path, query={"key": key})
+        properties = json_to_object(list[ConfluenceIdentifiedContentProperty], results)
+        if len(properties) == 1:
+            return properties.pop()
+        else:
+            return None
+
     def get_content_properties_for_page(self, page_id: str) -> list[ConfluenceIdentifiedContentProperty]:
         """
         Retrieves content properties for a Confluence page.

md2conf/attachment.py

@@ -40,6 +40,9 @@ class AttachmentCatalog:
         self.embedded_files[filename] = data
 
 
+_DISALLOWED_CHAR_REGEXP = re.compile(r"[^\-0-9A-Za-z_.]", re.UNICODE)
+
+
 def attachment_name(ref: Path | str) -> str:
     """
     Safe name for use with attachment uploads.
@@ -60,13 +63,11 @@ def attachment_name(ref: Path | str) -> str:
     if path.drive or path.root:
         raise ValueError(f"required: relative path; got: {ref}")
 
-    regexp = re.compile(r"[^\-0-9A-Za-z_.]", re.UNICODE)
-
     def replace_part(part: str) -> str:
         if part == "..":
             return "PAR"
         else:
-            return regexp.sub("_", part)
+            return _DISALLOWED_CHAR_REGEXP.sub("_", part)
 
     parts = [replace_part(p) for p in path.parts]
     return Path(*parts).as_posix().replace("/", "_")

md2conf/clio.py

@@ -0,0 +1,226 @@
+"""
+Publish Markdown files to Confluence wiki.
+
+Copyright 2022-2026, Levente Hunyadi
+
+:see: https://github.com/hunyadi/md2conf
+"""
+
+from argparse import ArgumentParser, Namespace
+from dataclasses import MISSING, Field, dataclass, fields, is_dataclass
+from types import NoneType, UnionType
+from typing import Any, Literal, TypeVar, cast, get_args, get_origin
+
+from .compatibility import LiteralString
+
+
+class BaseOption:
+    @staticmethod
+    def field_name() -> str:
+        return "argument"
+
+
+@dataclass
+class BooleanOption(BaseOption):
+    true_text: LiteralString
+    false_text: LiteralString
+
+
+def boolean_option(true_text: LiteralString, false_text: LiteralString) -> dict[str, Any]:
+    "Identifies a command-line argument as a boolean (on/off) flag."
+
+    return {BaseOption.field_name(): BooleanOption(true_text, false_text)}
+
+
+@dataclass
+class ValueOption(BaseOption):
+    text: LiteralString
+
+
+def value_option(text: LiteralString) -> dict[str, Any]:
+    "Identifies a command-line argument as an option that assigns a value."
+
+    return {BaseOption.field_name(): ValueOption(text)}
+
+
+class CompositeOption(BaseOption):
+    pass
+
+
+def composite_option() -> dict[str, Any]:
+    "Identifies a command-line argument as a data-class that needs to be unnested."
+
+    return {BaseOption.field_name(): CompositeOption()}
+
+
+T = TypeVar("T")
+
+
+def _has_metadata(field: Field[Any]) -> bool:
+    return field.metadata.get(BaseOption.field_name()) is not None
+
+
+def _get_metadata(field: Field[Any], tp: type[T]) -> T | None:
+    attrs = field.metadata.get(BaseOption.field_name())
+    if attrs is None:
+        return None
+    elif isinstance(attrs, tp):
+        return attrs
+    else:
+        raise TypeError(f"expected: {tp.__name__}; got: {type(attrs).__name__}")
+
+
+class _OptionTreeVisitor:
+    "Adds arguments to a command-line argument parser by recursively visiting fields of a composite type."
+
+    parser: ArgumentParser
+    prefixes: list[str]
+
+    def __init__(self, parser: ArgumentParser) -> None:
+        self.parser = parser
+        self.prefixes = []
+
+    def _get_arg_name(self, arg_name: str) -> str:
+        return f"--{'-'.join([*self.prefixes, arg_name])}"
+
+    def _get_field_name(self, field_name: str) -> str:
+        return "_".join([*self.prefixes, field_name])
+
+    def _add_value_field(self, field: Field[Any], field_type: Any) -> None:
+        arg_name = field.name.replace("_", "-")
+        value_opt = _get_metadata(field, ValueOption)
+        if value_opt is None:
+            return
+        help_text = value_opt.text
+        if field.default is not MISSING and field.default is not None:
+            help_text += f" (default: {field.default!s})"
+        if isinstance(field_type, type):
+            metavar = field_type.__name__.upper()
+        else:
+            metavar = None
+        self.parser.add_argument(
+            self._get_arg_name(arg_name),
+            dest=self._get_field_name(field.name),
+            default=field.default,
+            type=field_type,
+            help=help_text,
+            metavar=metavar,
+        )
+
+    def _add_field_as_argument(self, field: Field[Any]) -> None:
+        arg_name = field.name.replace("_", "-")
+        if field.type is bool:
+            bool_opt = _get_metadata(field, BooleanOption)
+            if bool_opt is None:
+                return
+            true_text = bool_opt.true_text
+            if field.default is True:
+                true_text += " (default)"
+            self.parser.add_argument(
+                self._get_arg_name(arg_name),
+                dest=self._get_field_name(field.name),
+                action="store_true",
+                default=field.default,
+                help=true_text,
+            )
+            if arg_name.startswith("skip-"):
+                inverse_arg_name = "keep-" + arg_name.removeprefix("skip-")
+            elif arg_name.startswith("keep-"):
+                inverse_arg_name = "skip-" + arg_name.removeprefix("keep-")
+            else:
+                inverse_arg_name = f"no-{arg_name}"
+            false_text = bool_opt.false_text
+            if field.default is False:
+                false_text += " (default)"
+            self.parser.add_argument(
+                self._get_arg_name(inverse_arg_name),
+                dest=self._get_field_name(field.name),
+                action="store_false",
+                help=false_text,
+            )
+            return
+
+        origin = get_origin(field.type)
+        if origin is Literal:
+            value_opt = _get_metadata(field, ValueOption)
+            if value_opt is None:
+                return
+            value_text = value_opt.text
+            if field.default is not MISSING and field.default is not None:
+                value_text += f" (default: {field.default!s})"
+            self.parser.add_argument(
+                self._get_arg_name(arg_name),
+                dest=self._get_field_name(field.name),
+                choices=get_args(field.type),
+                default=field.default,
+                help=value_text,
+            )
+
+        elif origin is UnionType:
+            union_types = list(get_args(field.type))
+            if len(union_types) != 2 or NoneType not in union_types:
+                raise TypeError(f"expected: `T` or `T | None` as argument type; got: {field.type}")
+            union_types.remove(NoneType)
+            required_type = union_types.pop()
+
+            self._add_value_field(field, required_type)
+
+        elif isinstance(field.type, type):
+            if hasattr(field.type, "__dataclass_fields__"):
+                composite_opt = _get_metadata(field, CompositeOption)
+                if composite_opt is None:
+                    return
+
+                self.prefixes.append(arg_name)
+                self.add_arguments(field.type)
+                self.prefixes.pop()
+
+            else:
+                self._add_value_field(field, field.type)
+
+        elif _has_metadata(field):
+            raise TypeError(f"expected: known argument type; got: {field.type}")
+
+    def add_arguments(self, options_type: type[Any]) -> None:
+        if is_dataclass(options_type):
+            for field in fields(options_type):
+                self._add_field_as_argument(field)
+
+
+def add_arguments(parser: ArgumentParser, options_type: type[Any]) -> None:
+    """
+    Adds arguments to a command-line argument parser.
+
+    :param parser: A command-line argument parser.
+    :param options_type: A data-class type that encapsulates configuration options.
+    """
+
+    _OptionTreeVisitor(parser).add_arguments(options_type)
+
+
+def _get_options(args: Namespace, options_type: type[T], prefixes: tuple[str, ...]) -> T:
+    params: dict[str, Any] = {}
+    if is_dataclass(options_type):  # always true, condition included for type checkers
+        for field in fields(options_type):
+            field_prefixes = (*prefixes, field.name)
+            if isinstance(field.type, type) and is_dataclass(field.type):
+                params[field.name] = _get_options(args, field.type, field_prefixes)
+            else:
+                field_param = getattr(args, "_".join(field_prefixes), MISSING)
+                if field_param is not MISSING:
+                    params[field.name] = field_param
+    return options_type(**params)
+
+
+def get_options(args: Namespace, options_type: type[T]) -> T:
+    """
+    Extracts configuration options from command-line arguments acquired by an argument parser.
+
+    :param args: Arguments acquired by a command-line argument parser.
+    :param options_type: A data-class type that encapsulates configuration options.
+    :returns: Configuration options as a data-class instance.
+    """
+
+    if not is_dataclass(options_type):
+        raise TypeError(f"expected: data-class as argument target; got: {type(options_type).__name__}")
+    return _get_options(args, cast(type[T], options_type), ())

md2conf/compatibility.py

@@ -8,6 +8,11 @@ Copyright 2022-2026, Levente Hunyadi
 
 import sys
 
+if sys.version_info >= (3, 11):
+    from typing import LiteralString as LiteralString  # noqa: F401
+else:
+    from typing_extensions import LiteralString as LiteralString  # noqa: F401
+
 if sys.version_info >= (3, 12):
     from typing import override as override  # noqa: F401
 else: