markdown-to-confluence 0.1.10__py3-none-any.whl → 0.1.12__py3-none-any.whl

{markdown_to_confluence-0.1.10.dist-info → markdown_to_confluence-0.1.12.dist-info}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022-2023 Levente Hunyadi
+Copyright (c) 2022-2024 Levente Hunyadi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{markdown_to_confluence-0.1.10.dist-info → markdown_to_confluence-0.1.12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: markdown-to-confluence
-Version: 0.1.10
+Version: 0.1.12
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -21,13 +21,13 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: lxml >=4.9
-Requires-Dist: types-lxml >=2023.10.21
-Requires-Dist: markdown >=3.5
-Requires-Dist: types-markdown >=3.5
-Requires-Dist: pymdown-extensions >=10.3
-Requires-Dist: requests >=2.31
-Requires-Dist: types-requests >=2.31
+Requires-Dist: lxml >=5.2
+Requires-Dist: types-lxml >=2024.4.14
+Requires-Dist: markdown >=3.6
+Requires-Dist: types-markdown >=3.6
+Requires-Dist: pymdown-extensions >=10.8
+Requires-Dist: requests >=2.32
+Requires-Dist: types-requests >=2.32
 
 # Publish Markdown files to Confluence wiki
 
@@ -36,6 +36,7 @@ Contributors to software projects typically write documentation in Markdown form
 Replicating documentation to Confluence by hand is tedious, and a lack of automated synchronization with the project repositories where the documents live leads to outdated documentation.
 
 This Python package
+
 * parses Markdown files,
 * converts Markdown content into the Confluence Storage Format (XHTML),
 * invokes Confluence API endpoints to upload images and content.
@@ -54,6 +55,7 @@ This Python package
 ## Getting started
 
 In order to get started, you will need
+
 * your organization domain name (e.g. `instructure.atlassian.net`),
 * base path for Confluence wiki (typically `/wiki/` for managed Confluence, `/` for on-premise)
 * your Confluence username (e.g. `levente.hunyadi@instructure.com`) (only if required by your deployment),
@@ -62,7 +64,7 @@ In order to get started, you will need
 
 ### Obtaining an API token
 
-1. Log in to https://id.atlassian.com/manage/api-tokens.
+1. Log in to <https://id.atlassian.com/manage/api-tokens>.
 2. Click *Create API token*.
 3. From the dialog that appears, enter a memorable and concise *Label* for your token and click *Create*.
 4. Click *Copy to clipboard*, then paste the token to your script, or elsewhere to save.
@@ -70,6 +72,7 @@ In order to get started, you will need
 ### Setting up the environment
 
 Confluence organization domain, base path, username, API token and space key can be specified at runtime or set as Confluence environment variables (e.g. add to your `~/.profile` on Linux, or `~/.bash_profile` or `~/.zshenv` on MacOS):
+
 ```bash
 export CONFLUENCE_DOMAIN='instructure.atlassian.net'
 export CONFLUENCE_PATH='/wiki/'
@@ -136,28 +139,30 @@ Use the `--help` switch to get a full list of supported command-line options:
 
 ```console
 $ python3 -m md2conf --help
-usage: md2conf [-h] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE]
-               [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--generated-by GENERATED_BY] [--no-generated-by]
+usage: md2conf [-h] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE] [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE] [--generated-by GENERATED_BY]
+               [--no-generated-by] [--ignore-invalid-url] [--local]
                mdpath
 
 positional arguments:
   mdpath                Path to Markdown file or directory to convert and publish.
 
-options:
+optional arguments:
   -h, --help            show this help message and exit
   -d DOMAIN, --domain DOMAIN
                         Confluence organization domain.
-  -p PATH, --path PATH  Base path for Confluece wiki.
+  -p PATH, --path PATH  Base path for Confluence (default: '/wiki/').
   -u USERNAME, --username USERNAME
                         Confluence user name.
   -a APIKEY, --apikey APIKEY
                         Confluence API key. Refer to documentation how to obtain one.
   -s SPACE, --space SPACE
-                        Confluence space key for pages to be published. If omitted, will default to user
-                        space.
-  -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --loglevel {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                        Confluence space key for pages to be published. If omitted, will default to user space.
+  -l {debug,info,warning,error,critical}, --loglevel {debug,info,warning,error,critical}
                         Use this option to set the log verbosity.
+  -r ROOT_PAGE          Root Confluence page to create new pages. If omitted, will raise exception when creating new pages.
   --generated-by GENERATED_BY
                         Add prompt to pages (default: 'This page has been generated with a tool.').
   --no-generated-by     Do not add 'generated by a tool' prompt to pages.
+  --ignore-invalid-url  Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.
+  --local               Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.
 ```

markdown_to_confluence-0.1.12.dist-info/RECORD

@@ -0,0 +1,16 @@
+md2conf/__init__.py,sha256=SS79zE1Jss2UJQH39HX6zMvAPO2MGjq3jjHny4L6dvY,403
+md2conf/__main__.py,sha256=L0XaHfV3GOPnyceWxUGamZXPfQUL3Dfsf_VpWeF08Qo,4246
+md2conf/api.py,sha256=xYqQbdy-0d_mqv-zDT0DCcLs17HYLdY2LfWoY2jhMB8,14738
+md2conf/application.py,sha256=ksWeDQGQs6xvAS8wdghwBMgWsGI6KMQiwlH5qaKXGv4,5221
+md2conf/converter.py,sha256=xiaf5hQHXPE3psTTk_pHVip4NDfeU-hos3Kkl1Pju50,18236
+md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
+md2conf/processor.py,sha256=f0JG8jqjsGq2sbxMdHNz6EyZ1KQ92nCKKYU3fxP6C0o,3048
+md2conf/properties.py,sha256=oXvtPssbougM1BTE9ytcD_1Yjc3nd7DDSHqEr0QoZAU,1811
+md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markdown_to_confluence-0.1.12.dist-info/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
+markdown_to_confluence-0.1.12.dist-info/METADATA,sha256=HCmOX5YhQuc6v2szBgQa_VuGXaeZNKKBy8Q_Fi1GreQ,7875
+markdown_to_confluence-0.1.12.dist-info/WHEEL,sha256=cpQTJ5IWu9CdaPViMhC9YzF8gZuS5-vlfoFihTBC86A,91
+markdown_to_confluence-0.1.12.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.1.12.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.1.12.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.1.12.dist-info/RECORD,,

{markdown_to_confluence-0.1.10.dist-info → markdown_to_confluence-0.1.12.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.3)
+Generator: setuptools (70.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

markdown_to_confluence-0.1.12.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+md2conf = md2conf.__main__:main

md2conf/__init__.py

@@ -5,9 +5,9 @@ Parses Markdown files, converts Markdown content into the Confluence Storage For
 Confluence API endpoints to upload images and content.
 """
 
-__version__ = "0.1.10"
+__version__ = "0.1.12"
 __author__ = "Levente Hunyadi"
-__copyright__ = "Copyright 2022-2023, Levente Hunyadi"
+__copyright__ = "Copyright 2022-2024, Levente Hunyadi"
 __license__ = "MIT"
 __maintainer__ = "Levente Hunyadi"
 __status__ = "Production"

md2conf/__main__.py

@@ -3,6 +3,7 @@ import logging
 import os.path
 import sys
 import typing
+from pathlib import Path
 from typing import Optional
 
 import requests
@@ -10,89 +11,130 @@ import requests
 from .api import ConfluenceAPI
 from .application import Application
 from .converter import ConfluenceDocumentOptions
+from .processor import Processor
+from .properties import ConfluenceProperties
 
 
 class Arguments(argparse.Namespace):
-    mdpath: str
+    mdpath: Path
     domain: str
     path: str
     username: str
     apikey: str
     space: str
     loglevel: str
+    ignore_invalid_url: bool
     generated_by: Optional[str]
 
 
-parser = argparse.ArgumentParser()
-parser.prog = os.path.basename(os.path.dirname(__file__))
-parser.add_argument(
-    "mdpath", help="Path to Markdown file or directory to convert and publish."
-)
-parser.add_argument("-d", "--domain", help="Confluence organization domain.")
-parser.add_argument("-p", "--path", help="Base path for Confluece wiki.")
-parser.add_argument("-u", "--username", help="Confluence user name.")
-parser.add_argument(
-    "-a",
-    "--apikey",
-    help="Confluence API key. Refer to documentation how to obtain one.",
-)
-parser.add_argument(
-    "-s",
-    "--space",
-    help="Confluence space key for pages to be published. If omitted, will default to user space.",
-)
-parser.add_argument(
-    "-l",
-    "--loglevel",
-    choices=[
-        typing.cast(str, logging.getLevelName(level)).lower()
-        for level in (
-            logging.DEBUG,
-            logging.INFO,
-            logging.WARN,
-            logging.ERROR,
-            logging.CRITICAL,
-        )
-    ],
-    default=logging.getLevelName(logging.INFO),
-    help="Use this option to set the log verbosity.",
-)
-parser.add_argument(
-    "--generated-by",
-    default="This page has been generated with a tool.",
-    help="Add prompt to pages (default: 'This page has been generated with a tool.').",
-)
-parser.add_argument(
-    "--no-generated-by",
-    dest="generated_by",
-    action="store_const",
-    const=None,
-    help="Do not add 'generated by a tool' prompt to pages.",
-)
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.prog = os.path.basename(os.path.dirname(__file__))
+    parser.add_argument(
+        "mdpath", help="Path to Markdown file or directory to convert and publish."
+    )
+    parser.add_argument("-d", "--domain", help="Confluence organization domain.")
+    parser.add_argument(
+        "-p", "--path", help="Base path for Confluence (default: '/wiki/')."
+    )
+    parser.add_argument("-u", "--username", help="Confluence user name.")
+    parser.add_argument(
+        "-a",
+        "--apikey",
+        help="Confluence API key. Refer to documentation how to obtain one.",
+    )
+    parser.add_argument(
+        "-s",
+        "--space",
+        help="Confluence space key for pages to be published. If omitted, will default to user space.",
+    )
+    parser.add_argument(
+        "-l",
+        "--loglevel",
+        choices=[
+            typing.cast(str, logging.getLevelName(level)).lower()
+            for level in (
+                logging.DEBUG,
+                logging.INFO,
+                logging.WARN,
+                logging.ERROR,
+                logging.CRITICAL,
+            )
+        ],
+        default=logging.getLevelName(logging.INFO),
+        help="Use this option to set the log verbosity.",
+    )
+    parser.add_argument(
+        "-r",
+        dest="root_page",
+        help="Root Confluence page to create new pages. If omitted, will raise exception when creating new pages.",
+    )
+    parser.add_argument(
+        "--generated-by",
+        default="This page has been generated with a tool.",
+        help="Add prompt to pages (default: 'This page has been generated with a tool.').",
+    )
+    parser.add_argument(
+        "--no-generated-by",
+        dest="generated_by",
+        action="store_const",
+        const=None,
+        help="Do not add 'generated by a tool' prompt to pages.",
+    )
+    parser.add_argument(
+        "--ignore-invalid-url",
+        action="store_true",
+        default=False,
+        help="Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.",
+    )
+    parser.add_argument(
+        "--local",
+        action="store_true",
+        default=False,
+        help="Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.",
+    )
 
-args = Arguments()
-parser.parse_args(namespace=args)
+    args = Arguments()
+    parser.parse_args(namespace=args)
 
-logging.basicConfig(
-    level=getattr(logging, args.loglevel.upper(), logging.INFO),
-    format="%(asctime)s - %(levelname)s - %(funcName)s [%(lineno)d] - %(message)s",
-)
+    # NOTE:  If we switch to modern type aware CLI tool like typer
+    #  the following line won't be necessary
+    args.mdpath = Path(args.mdpath)
 
-try:
-    with ConfluenceAPI(
-        args.domain, args.path, args.username, args.apikey, args.space
-    ) as api:
-        Application(api, ConfluenceDocumentOptions(args.generated_by)).synchronize(
-            args.mdpath
-        )
-except requests.exceptions.HTTPError as err:
-    logging.error(err)
+    logging.basicConfig(
+        level=getattr(logging, args.loglevel.upper(), logging.INFO),
+        format="%(asctime)s - %(levelname)s - %(funcName)s [%(lineno)d] - %(message)s",
+    )
 
-    # print details for a response with JSON body
-    if err.response is not None:
+    options = ConfluenceDocumentOptions(
+        ignore_invalid_url=args.ignore_invalid_url,
+        generated_by=args.generated_by,
+        root_page_id=args.root_page,
+    )
+    properties = ConfluenceProperties(
+        args.domain, args.path, args.username, args.apikey, args.space
+    )
+    if args.local:
+        Processor(options, properties).process(args.mdpath)
+    else:
         try:
-            logging.error(err.response.json())
-        except requests.exceptions.JSONDecodeError:
-            pass
+            with ConfluenceAPI(properties) as api:
+                Application(
+                    api,
+                    options,
+                ).synchronize(args.mdpath)
+        except requests.exceptions.HTTPError as err:
+            logging.error(err)
+
+            # print details for a response with JSON body
+            if err.response is not None:
+                try:
+                    logging.error(err.response.json())
+                except requests.exceptions.JSONDecodeError:
+                    pass
+
+            sys.exit(1)
+
 
-    sys.exit(1)
+if __name__ == "__main__":
+    main()

md2conf/api.py

@@ -1,12 +1,11 @@
 import json
 import logging
 import mimetypes
-import os
-import os.path
 import sys
 import typing
 from contextlib import contextmanager
 from dataclasses import dataclass
+from pathlib import Path
 from types import TracebackType
 from typing import Dict, Generator, List, Optional, Type, Union
 from urllib.parse import urlencode, urlparse, urlunparse
@@ -14,6 +13,7 @@ from urllib.parse import urlencode, urlparse, urlunparse
 import requests
 
 from .converter import ParseError, sanitize_confluence
+from .properties import ConfluenceError, ConfluenceProperties
 
 # a JSON type with possible `null` values
 JsonType = Union[
@@ -56,7 +56,8 @@ else:
         "If the string starts with the prefix, return the string without the prefix; otherwise, return the original string."
 
         if string.startswith(prefix):
-            return string[len(prefix) :]
+            prefix_len = len(prefix)
+            return string[prefix_len:]
         else:
             return string
 
@@ -64,10 +65,6 @@ else:
 LOGGER = logging.getLogger(__name__)
 
 
-class ConfluenceError(RuntimeError):
-    pass
-
-
 @dataclass
 class ConfluenceAttachment:
     id: str
@@ -79,64 +76,32 @@ class ConfluenceAttachment:
 @dataclass
 class ConfluencePage:
     id: str
+    space_key: str
     title: str
     version: int
     content: str
 
 
 class ConfluenceAPI:
-    domain: str
-    base_path: str
-    space_key: str
-    user_name: Optional[str]
-    api_key: str
-
+    properties: ConfluenceProperties
     session: Optional["ConfluenceSession"] = None
 
-    def __init__(
-        self,
-        domain: Optional[str] = None,
-        base_path: Optional[str] = None,
-        user_name: Optional[str] = None,
-        api_key: Optional[str] = None,
-        space_key: Optional[str] = None,
-    ) -> None:
-        opt_domain = domain or os.getenv("CONFLUENCE_DOMAIN")
-        opt_base_path = base_path or os.getenv("CONFLUENCE_PATH")
-        opt_user_name = user_name or os.getenv("CONFLUENCE_USER_NAME")
-        opt_api_key = api_key or os.getenv("CONFLUENCE_API_KEY")
-        opt_space_key = space_key or os.getenv("CONFLUENCE_SPACE_KEY")
-
-        if not opt_domain:
-            raise ConfluenceError("Confluence domain not specified")
-        if not opt_base_path:
-            opt_base_path = "/wiki/"
-        if not opt_api_key:
-            raise ConfluenceError("Confluence API key not specified")
-        if not opt_space_key:
-            raise ConfluenceError("Confluence space key not specified")
-
-        if opt_domain.startswith(("http://", "https://")) or opt_domain.endswith("/"):
-            raise ConfluenceError(
-                "Confluence domain looks like a URL; only host name required"
-            )
-        if not opt_base_path.startswith("/") or not opt_base_path.endswith("/"):
-            raise ConfluenceError("Confluence base path must start and end with a '/'")
-
-        self.domain = opt_domain
-        self.base_path = opt_base_path
-        self.user_name = opt_user_name
-        self.api_key = opt_api_key
-        self.space_key = opt_space_key
+    def __init__(self, properties: Optional[ConfluenceProperties] = None) -> None:
+        self.properties = properties or ConfluenceProperties()
 
     def __enter__(self) -> "ConfluenceSession":
         session = requests.Session()
-        if self.user_name:
-            session.auth = (self.user_name, self.api_key)
+        if self.properties.user_name:
+            session.auth = (self.properties.user_name, self.properties.api_key)
         else:
-            session.headers.update({"Authorization": f"Bearer {self.api_key}"})
+            session.headers.update(
+                {"Authorization": f"Bearer {self.properties.api_key}"}
+            )
         self.session = ConfluenceSession(
-            session, self.domain, self.base_path, self.space_key
+            session,
+            self.properties.domain,
+            self.properties.base_path,
+            self.properties.space_key,
         )
         return self.session
 
@@ -197,10 +162,10 @@ class ConfluenceSession:
         response.raise_for_status()
 
     def get_attachment_by_name(
-        self, page_id: str, filename: str
+        self, page_id: str, filename: str, *, space_key: Optional[str] = None
     ) -> ConfluenceAttachment:
         path = f"/content/{page_id}/child/attachment"
-        query = {"spaceKey": self.space_key, "filename": filename}
+        query = {"spaceKey": space_key or self.space_key, "filename": filename}
         data = typing.cast(Dict[str, JsonType], self._invoke(path, query))
 
         results = typing.cast(List[JsonType], data["results"])
@@ -218,19 +183,24 @@ class ConfluenceSession:
     def upload_attachment(
         self,
         page_id: str,
-        attachment_path: str,
+        attachment_path: Path,
         attachment_name: str,
         comment: Optional[str] = None,
+        *,
+        space_key: Optional[str] = None,
+        force: bool = False,
     ) -> None:
         content_type = mimetypes.guess_type(attachment_path, strict=True)[0]
 
-        if not os.path.isfile(attachment_path):
+        if not attachment_path.is_file():
             raise ConfluenceError(f"file not found: {attachment_path}")
 
         try:
-            attachment = self.get_attachment_by_name(page_id, attachment_name)
+            attachment = self.get_attachment_by_name(
+                page_id, attachment_name, space_key=space_key
+            )
 
-            if attachment.file_size == os.path.getsize(attachment_path):
+            if not force and attachment.file_size == attachment_path.stat().st_size:
                 LOGGER.info("Up-to-date attachment: %s", attachment_name)
                 return
 
@@ -271,10 +241,18 @@ class ConfluenceSession:
         version = result["version"]["number"] + 1
 
         # ensure path component is retained in attachment name
-        self._update_attachment(page_id, attachment_id, version, attachment_name)
+        self._update_attachment(
+            page_id, attachment_id, version, attachment_name, space_key=space_key
+        )
 
     def _update_attachment(
-        self, page_id: str, attachment_id: str, version: int, attachment_title: str
+        self,
+        page_id: str,
+        attachment_id: str,
+        version: int,
+        attachment_title: str,
+        *,
+        space_key: Optional[str] = None,
     ) -> None:
         id = removeprefix(attachment_id, "att")
         path = f"/content/{page_id}/child/attachment/{id}"
@@ -283,24 +261,30 @@ class ConfluenceSession:
             "type": "attachment",
             "status": "current",
             "title": attachment_title,
-            "space": {"key": self.space_key},
+            "space": {"key": space_key or self.space_key},
             "version": {"minorEdit": True, "number": version},
         }
 
         LOGGER.info("Updating attachment: %s", attachment_id)
         self._save(path, data)
 
-    def get_page_id_by_title(self, title: str) -> str:
+    def get_page_id_by_title(
+        self,
+        title: str,
+        *,
+        space_key: Optional[str] = None,
+    ) -> str:
         """
-        Retrieve a Confluence wiki page details by title.
+        Look up a Confluence wiki page ID by title.
 
         :param title: The page title.
-        :returns: Confluence page info.
+        :param space_key: The Confluence space key (unless the default space is to be used).
+        :returns: Confluence page ID.
         """
 
         LOGGER.info("Looking up page with title: %s", title)
         path = "/content"
-        query = {"title": title, "spaceKey": self.space_key}
+        query = {"title": title, "spaceKey": space_key or self.space_key}
         data = typing.cast(Dict[str, JsonType], self._invoke(path, query))
 
         results = typing.cast(List[JsonType], data["results"])
@@ -311,12 +295,23 @@ class ConfluenceSession:
         id = typing.cast(str, result["id"])
         return id
 
-    def get_page(self, page_id: str) -> ConfluencePage:
+    def get_page(
+        self, page_id: str, *, space_key: Optional[str] = None
+    ) -> ConfluencePage:
+        """
+        Retrieve Confluence wiki page details.
+
+        :param page_id: The Confluence page ID.
+        :param space_key: The Confluence space key (unless the default space is to be used).
+        :returns: Confluence page info.
+        """
+
         path = f"/content/{page_id}"
         query = {
-            "spaceKey": self.space_key,
+            "spaceKey": space_key or self.space_key,
             "expand": "body.storage,version",
         }
+
         data = typing.cast(Dict[str, JsonType], self._invoke(path, query))
         version = typing.cast(Dict[str, JsonType], data["version"])
         body = typing.cast(Dict[str, JsonType], data["body"])
@@ -324,23 +319,43 @@ class ConfluenceSession:
 
         return ConfluencePage(
             id=page_id,
+            space_key=space_key or self.space_key,
             title=typing.cast(str, data["title"]),
             version=typing.cast(int, version["number"]),
             content=typing.cast(str, storage["value"]),
         )
 
-    def get_page_version(self, page_id: str) -> int:
+    def get_page_version(
+        self,
+        page_id: str,
+        *,
+        space_key: Optional[str] = None,
+    ) -> int:
+        """
+        Retrieve a Confluence wiki page version.
+
+        :param page_id: The Confluence page ID.
+        :param space_key: The Confluence space key (unless the default space is to be used).
+        :returns: Confluence page version.
+        """
+
         path = f"/content/{page_id}"
         query = {
-            "spaceKey": self.space_key,
+            "spaceKey": space_key or self.space_key,
             "expand": "version",
         }
         data = typing.cast(Dict[str, JsonType], self._invoke(path, query))
         version = typing.cast(Dict[str, JsonType], data["version"])
         return typing.cast(int, version["number"])
 
-    def update_page(self, page_id: str, new_content: str) -> None:
-        page = self.get_page(page_id)
+    def update_page(
+        self,
+        page_id: str,
+        new_content: str,
+        *,
+        space_key: Optional[str] = None,
+    ) -> None:
+        page = self.get_page(page_id, space_key=space_key)
 
         try:
             old_content = sanitize_confluence(page.content)
@@ -355,10 +370,89 @@ class ConfluenceSession:
             "id": page_id,
             "type": "page",
             "title": page.title,  # title needs to be unique within a space so the original title is maintained
-            "space": {"key": self.space_key},
+            "space": {"key": space_key or self.space_key},
             "body": {"storage": {"value": new_content, "representation": "storage"}},
             "version": {"minorEdit": True, "number": page.version + 1},
         }
 
         LOGGER.info("Updating page: %s", page_id)
         self._save(path, data)
+
+    def create_page(
+        self,
+        parent_page_id: str,
+        title: str,
+        new_content: str,
+        *,
+        space_key: Optional[str] = None,
+    ) -> ConfluencePage:
+        path = "/content/"
+        query = {
+            "type": "page",
+            "title": title,
+            "space": {"key": space_key or self.space_key},
+            "body": {"storage": {"value": new_content, "representation": "storage"}},
+            "ancestors": [{"type": "page", "id": parent_page_id}],
+        }
+
+        LOGGER.info("Creating page: %s", title)
+
+        url = self._build_url(path)
+        response = self.session.post(
+            url,
+            data=json.dumps(query),
+            headers={"Content-Type": "application/json"},
+        )
+        response.raise_for_status()
+
+        data = typing.cast(Dict[str, JsonType], response.json())
+        version = typing.cast(Dict[str, JsonType], data["version"])
+        body = typing.cast(Dict[str, JsonType], data["body"])
+        storage = typing.cast(Dict[str, JsonType], body["storage"])
+
+        return ConfluencePage(
+            id=typing.cast(str, data["id"]),
+            space_key=space_key or self.space_key,
+            title=typing.cast(str, data["title"]),
+            version=typing.cast(int, version["number"]),
+            content=typing.cast(str, storage["value"]),
+        )
+
+    def page_exists(
+        self, title: str, *, space_key: Optional[str] = None
+    ) -> Optional[str]:
+        path = "/content"
+        query = {
+            "type": "page",
+            "title": title,
+            "spaceKey": space_key or self.space_key,
+        }
+
+        LOGGER.info("Checking if page exists with title: %s", title)
+
+        url = self._build_url(path)
+        response = self.session.get(
+            url, params=query, headers={"Content-Type": "application/json"}
+        )
+        response.raise_for_status()
+
+        data = typing.cast(Dict[str, JsonType], response.json())
+        results = typing.cast(List, data["results"])
+
+        if len(results) == 1:
+            page_info = typing.cast(Dict[str, JsonType], results[0])
+            return typing.cast(str, page_info["id"])
+        else:
+            return None
+
+    def get_or_create_page(
+        self, title: str, parent_id: str, *, space_key: Optional[str] = None
+    ) -> ConfluencePage:
+        page_id = self.page_exists(title)
+
+        if page_id is not None:
+            LOGGER.debug("Retrieving existing page: %d", 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, "", space_key=space_key)

md2conf/application.py

@@ -1,13 +1,15 @@
 import logging
 import os.path
-from typing import Dict
+from pathlib import Path
+from typing import Dict, Optional
 
 from .api import ConfluenceSession
 from .converter import (
     ConfluenceDocument,
     ConfluenceDocumentOptions,
     ConfluencePageMetadata,
-    extract_page_id,
+    attachment_name,
+    extract_qualified_id,
 )
 
 LOGGER = logging.getLogger(__name__)
@@ -25,51 +27,42 @@ class Application:
         self.api = api
         self.options = options
 
-    def synchronize(self, path: str) -> None:
+    def synchronize(self, path: Path) -> None:
         "Synchronizes a single Markdown page or a directory of Markdown pages."
 
-        if os.path.isdir(path):
+        if path.is_dir():
             self.synchronize_directory(path)
-        elif os.path.isfile(path):
+        elif path.is_file():
             self.synchronize_page(path)
         else:
             raise ValueError(f"expected: valid file or directory path; got: {path}")
 
-    def synchronize_page(self, page_path: str) -> None:
+    def synchronize_page(self, page_path: Path) -> None:
         "Synchronizes a single Markdown page with Confluence."
 
-        self._synchronize_page(page_path, dict())
+        self._synchronize_page(page_path, {})
 
-    def synchronize_directory(self, dir: str) -> None:
+    def synchronize_directory(self, local_dir: Path) -> None:
         "Synchronizes a directory of Markdown pages with Confluence."
 
-        page_metadata: Dict[str, ConfluencePageMetadata] = dict()
-        LOGGER.info(f"Synchronizing directory: {dir}")
+        page_metadata: Dict[Path, ConfluencePageMetadata] = {}
+        LOGGER.info(f"Synchronizing directory: {local_dir}")
 
         # Step 1: build index of all page metadata
-        for root, directories, files in os.walk(dir):
+        # NOTE: Pathlib.walk() is implemented only in Python 3.12+
+        # so sticking for old os.walk
+        for root, directories, files in os.walk(local_dir):
             for file_name in files:
-                # check the file extension
-                _, file_extension = os.path.splitext(file_name)
-                if file_extension.lower() != ".md":
+                # Reconstitute Path object back
+                docfile = (Path(root) / file_name).absolute()
+
+                # Skip non-markdown files
+                if docfile.suffix.lower() != ".md":
                     continue
+                metadata = self._get_or_create_page(docfile)
 
-                # parse file
-                absolute_path = os.path.join(os.path.abspath(root), file_name)
-                with open(absolute_path, "r") as f:
-                    document = f.read()
-
-                id, document = extract_page_id(document)
-                confluence_page = self.api.get_page(id.page_id)
-                metadata = ConfluencePageMetadata(
-                    domain=self.api.domain,
-                    base_path=self.api.base_path,
-                    page_id=id.page_id,
-                    space_key=id.space_key or self.api.space_key,
-                    title=confluence_page.title or "",
-                )
-                LOGGER.debug(f"indexed {absolute_path} with metadata: {metadata}")
-                page_metadata[absolute_path] = metadata
+                LOGGER.debug(f"indexed {docfile} with metadata: {metadata}")
+                page_metadata[docfile] = metadata
 
         LOGGER.info(f"indexed {len(page_metadata)} pages")
 
@@ -79,10 +72,10 @@ class Application:
 
     def _synchronize_page(
         self,
-        page_path: str,
-        page_metadata: Dict[str, ConfluencePageMetadata],
+        page_path: Path,
+        page_metadata: Dict[Path, ConfluencePageMetadata],
     ) -> None:
-        base_path = os.path.dirname(page_path)
+        base_path = page_path.parent
 
         LOGGER.info(f"Synchronizing page: {page_path}")
         document = ConfluenceDocument(page_path, self.options, page_metadata)
@@ -93,12 +86,69 @@ class Application:
         else:
             self._update_document(document, base_path)
 
-    def _update_document(self, document: ConfluenceDocument, base_path: str) -> None:
+    def _get_or_create_page(
+        self, absolute_path: Path, title: Optional[str] = None
+    ) -> ConfluencePageMetadata:
+        """
+        Creates a new Confluence page if no page is linked in the Markdown document.
+        """
+
+        # parse file
+        with open(absolute_path, "r") as f:
+            document = f.read()
+
+        qualified_id, document = extract_qualified_id(document)
+        if qualified_id is not None:
+            confluence_page = self.api.get_page(
+                qualified_id.page_id, space_key=qualified_id.space_key
+            )
+        else:
+            if self.options.root_page_id is None:
+                raise ValueError(
+                    "expected: Confluence page ID to act as parent for Markdown files with no linked Confluence page"
+                )
+
+            # use file name without extension if no title is supplied
+            if title is None:
+                title = absolute_path.stem
+
+            confluence_page = self.api.get_or_create_page(
+                title, self.options.root_page_id
+            )
+            self._update_markdown(
+                absolute_path,
+                document,
+                confluence_page.id,
+                confluence_page.space_key,
+            )
+
+        return ConfluencePageMetadata(
+            domain=self.api.domain,
+            base_path=self.api.base_path,
+            page_id=confluence_page.id,
+            space_key=confluence_page.space_key or self.api.space_key,
+            title=confluence_page.title or "",
+        )
+
+    def _update_document(self, document: ConfluenceDocument, base_path: Path) -> None:
         for image in document.images:
             self.api.upload_attachment(
-                document.id.page_id, os.path.join(base_path, image), image, ""
+                document.id.page_id, base_path / image, attachment_name(image), ""
             )
 
         content = document.xhtml()
         LOGGER.debug(f"generated Confluence Storage Format document:\n{content}")
         self.api.update_page(document.id.page_id, content)
+
+    def _update_markdown(
+        self,
+        path: Path,
+        document: str,
+        page_id: str,
+        space_key: Optional[str],
+    ) -> None:
+        with open(path, "w") as file:
+            file.write(f"<!-- confluence-page-id: {page_id} -->\n")
+            if space_key:
+                file.write(f"<!-- confluence-space-key: {space_key} -->\n")
+            file.write(document)

md2conf/converter.py

@@ -207,28 +207,38 @@ class NodeVisitor:
         pass
 
 
-def _change_ext(path: str, target_ext: str) -> str:
-    root, source_ext = os.path.splitext(path)
-    return f"{root}{target_ext}"
+@dataclass
+class ConfluenceConverterOptions:
+    """
+    Options for converting an HTML tree into Confluence storage format.
+
+    :param ignore_invalid_url: When true, ignore invalid URLs in input, emit a warning and replace the anchor with
+        plain text; when false, raise an exception.
+    """
+
+    ignore_invalid_url: bool = False
 
 
 class ConfluenceStorageFormatConverter(NodeVisitor):
     "Transforms a plain HTML tree into the Confluence storage format."
 
-    path: str
-    base_path: str
+    options: ConfluenceConverterOptions
+    path: pathlib.Path
+    base_path: pathlib.Path
     links: List[str]
     images: List[str]
-    page_metadata: Dict[str, ConfluencePageMetadata]
+    page_metadata: Dict[pathlib.Path, ConfluencePageMetadata]
 
     def __init__(
         self,
-        path: str,
-        page_metadata: Dict[str, ConfluencePageMetadata],
+        options: ConfluenceConverterOptions,
+        path: pathlib.Path,
+        page_metadata: Dict[pathlib.Path, ConfluencePageMetadata],
     ) -> None:
         super().__init__()
+        self.options = options
         self.path = path
-        self.base_path = os.path.abspath(os.path.dirname(path)) + os.sep
+        self.base_path = path.parent
         self.links = []
         self.images = []
         self.page_metadata = page_metadata
@@ -255,15 +265,27 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         # convert the relative URL to absolute URL based on the base path value, then look up
         # the absolute path in the page metadata dictionary to discover the relative path
         # within Confluence that should be used
-        absolute_path = os.path.abspath(os.path.join(self.base_path, relative_url.path))
-        if not absolute_path.startswith(self.base_path):
-            raise DocumentError(f"relative URL points to outside base path: {url}")
+        absolute_path = (self.base_path / relative_url.path).absolute()
+        if not str(absolute_path).startswith(str(self.base_path)):
+            msg = f"relative URL {url} points to outside base path: {self.base_path}"
+            if self.options.ignore_invalid_url:
+                LOGGER.warning(msg)
+                anchor.attrib.pop("href")
+                return
+            else:
+                raise DocumentError(msg)
 
         relative_path = os.path.relpath(absolute_path, self.base_path)
 
         link_metadata = self.page_metadata.get(absolute_path)
         if link_metadata is None:
-            raise DocumentError(f"unable to find matching page for URL: {url}")
+            msg = f"unable to find matching page for URL: {url}"
+            if self.options.ignore_invalid_url:
+                LOGGER.warning(msg)
+                anchor.attrib.pop("href")
+                return
+            else:
+                raise DocumentError(msg)
 
         LOGGER.debug(
             f"found link to page {relative_path} with metadata: {link_metadata}"
@@ -287,10 +309,13 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         path: str = image.attrib["src"]
 
         # prefer PNG over SVG; Confluence displays SVG in wrong size, and text labels are truncated
-        if path and is_relative_url(path) and path.endswith(".svg"):
-            replacement_path = _change_ext(path, ".png")
-            if os.path.exists(os.path.join(self.base_path, replacement_path)):
-                path = replacement_path
+        if path and is_relative_url(path):
+            relative_path = pathlib.Path(path)
+            if (
+                relative_path.suffix == ".svg"
+                and (self.base_path / relative_path.with_suffix(".png")).exists()
+            ):
+                path = str(relative_path.with_suffix(".png"))
 
         self.images.append(path)
         caption = image.attrib["alt"]
@@ -300,7 +325,10 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
                 ET.QName(namespaces["ac"], "align"): "center",
                 ET.QName(namespaces["ac"], "layout"): "center",
             },
-            RI("attachment", {ET.QName(namespaces["ri"], "filename"): path}),
+            RI(
+                "attachment",
+                {ET.QName(namespaces["ri"], "filename"): attachment_name(path)},
+            ),
             AC("caption", HTML.p(caption)),
         )
 
@@ -364,6 +392,9 @@ class ConfluenceStorageFormatConverter(NodeVisitor):
         if class_name is None:
             raise DocumentError(f"unsupported admonition label: {class_list}")
 
+        for e in elem:
+            self.visit(e)
+
         # <p class="admonition-title">Note</p>
         if "admonition-title" in elem[0].attrib.get("class", "").split(" "):
             content = [
@@ -464,12 +495,11 @@ class ConfluenceQualifiedID:
     space_key: Optional[str] = None
 
 
-def extract_page_id(string: str) -> Tuple[ConfluenceQualifiedID, str]:
+def extract_qualified_id(string: str) -> Tuple[Optional[ConfluenceQualifiedID], str]:
     page_id, string = extract_value(r"<!--\s+confluence-page-id:\s*(\d+)\s+-->", string)
+
     if page_id is None:
-        raise DocumentError(
-            "Markdown document has no Confluence page ID associated with it"
-        )
+        return None, string
 
     # extract Confluence space key
     space_key, string = extract_value(
@@ -484,10 +514,14 @@ class ConfluenceDocumentOptions:
     """
     Options that control the generated page content.
 
+    :param ignore_invalid_url: When true, ignore invalid URLs in input, emit a warning and replace the anchor with
+        plain text; when false, raise an exception.
     :param show_generated: Whether to display a prompt "This page has been generated with a tool."
     """
 
+    ignore_invalid_url: bool = False
     generated_by: Optional[str] = "This page has been generated with a tool."
+    root_page_id: Optional[str] = None
 
 
 class ConfluenceDocument:
@@ -500,24 +534,33 @@ class ConfluenceDocument:
 
     def __init__(
         self,
-        path: str,
+        path: pathlib.Path,
         options: ConfluenceDocumentOptions,
-        page_metadata: Dict[str, ConfluencePageMetadata],
+        page_metadata: Dict[pathlib.Path, ConfluencePageMetadata],
     ) -> None:
         self.options = options
-        path = os.path.abspath(path)
+        path = path.absolute()
 
         with open(path, "r") as f:
-            html = markdown_to_html(f.read())
+            text = f.read()
 
         # extract Confluence page ID
-        self.id, html = extract_page_id(html)
+        qualified_id, text = extract_qualified_id(text)
+        if qualified_id is None:
+            raise ValueError("missing Confluence page ID")
+        self.id = qualified_id
 
         # extract 'generated-by' tag text
-        generated_by_tag, html = extract_value(
-            r"<!--\s+generated-by:\s*(.*)\s+-->", html
+        generated_by_tag, text = extract_value(
+            r"<!--\s+generated-by:\s*(.*)\s+-->", text
         )
 
+        # extract frontmatter
+        frontmatter, text = extract_value(r"(?ms)\A---$(.+?)^---$", text)
+
+        # convert to HTML
+        html = markdown_to_html(text)
+
         # parse Markdown document
         if self.options.generated_by is not None:
             generated_by = self.options.generated_by
@@ -534,7 +577,13 @@ class ConfluenceDocument:
             content = [html]
         self.root = elements_from_strings(content)
 
-        converter = ConfluenceStorageFormatConverter(path, page_metadata)
+        converter = ConfluenceStorageFormatConverter(
+            ConfluenceConverterOptions(
+                ignore_invalid_url=self.options.ignore_invalid_url
+            ),
+            path,
+            page_metadata,
+        )
         converter.visit(self.root)
         self.links = converter.links
         self.images = converter.images
@@ -543,6 +592,18 @@ class ConfluenceDocument:
         return _content_to_string(self.root)
 
 
+def attachment_name(name: str) -> str:
+    """
+    Safe name for use with attachment uploads.
+
+    Allowed characters:
+    * Alphanumeric characters: 0-9, a-z, A-Z
+    * Special characters: hyphen (-), underscore (_), period (.)
+    """
+
+    return re.sub(r"[^\-0-9A-Za-z_.]", "_", name)
+
+
 def sanitize_confluence(html: str) -> str:
     "Generates a sanitized version of a Confluence storage format XHTML document with no volatile attributes."
 

md2conf/processor.py

@@ -0,0 +1,91 @@
+import logging
+import os
+from pathlib import Path
+from typing import Dict
+
+from .converter import (
+    ConfluenceDocument,
+    ConfluenceDocumentOptions,
+    ConfluencePageMetadata,
+    extract_qualified_id,
+)
+from .properties import ConfluenceProperties
+
+LOGGER = logging.getLogger(__name__)
+
+
+class Processor:
+    options: ConfluenceDocumentOptions
+    properties: ConfluenceProperties
+
+    def __init__(
+        self, options: ConfluenceDocumentOptions, properties: ConfluenceProperties
+    ) -> None:
+        self.options = options
+        self.properties = properties
+
+    def process(self, path: Path) -> None:
+        "Processes a single Markdown file or a directory of Markdown files."
+
+        if path.is_dir():
+            self.process_directory(path)
+        elif path.is_file():
+            self.process_page(path, {})
+        else:
+            raise ValueError(f"expected: valid file or directory path; got: {path}")
+
+    def process_directory(self, local_dir: Path) -> None:
+        "Recursively scans a directory hierarchy for Markdown files."
+
+        page_metadata: Dict[Path, ConfluencePageMetadata] = {}
+        LOGGER.info(f"Synchronizing directory: {local_dir}")
+
+        # Step 1: build index of all page metadata
+        # NOTE: Pathlib.walk() is implemented only in Python 3.12+
+        # so sticking for old os.walk
+        for root, directories, files in os.walk(local_dir):
+            for file_name in files:
+                # Reconstitute Path object back
+                docfile = (Path(root) / file_name).absolute()
+
+                # Skip non-markdown files
+                if docfile.suffix.lower() != ".md":
+                    continue
+
+                metadata = self._get_page(docfile)
+                LOGGER.debug(f"indexed {docfile} with metadata: {metadata}")
+                page_metadata[docfile] = metadata
+
+        LOGGER.info(f"indexed {len(page_metadata)} pages")
+
+        # Step 2: Convert each page
+        for page_path in page_metadata.keys():
+            self.process_page(page_path, page_metadata)
+
+    def process_page(
+        self, path: Path, page_metadata: Dict[Path, ConfluencePageMetadata]
+    ) -> None:
+        "Processes a single Markdown file."
+
+        document = ConfluenceDocument(path, self.options, page_metadata)
+        content = document.xhtml()
+        with open(path.with_suffix(".csf"), "w") as f:
+            f.write(content)
+
+    def _get_page(self, absolute_path: Path) -> ConfluencePageMetadata:
+        "Extracts metadata from a Markdown file."
+
+        with open(absolute_path, "r") as f:
+            document = f.read()
+
+        qualified_id, document = extract_qualified_id(document)
+        if qualified_id is None:
+            raise ValueError("required: page ID for local output")
+
+        return ConfluencePageMetadata(
+            domain=self.properties.domain,
+            base_path=self.properties.base_path,
+            page_id=qualified_id.page_id,
+            space_key=qualified_id.space_key or self.properties.space_key,
+            title="",
+        )

md2conf/properties.py

@@ -0,0 +1,52 @@
+import os
+from typing import Optional
+
+
+class ConfluenceError(RuntimeError):
+    pass
+
+
+class ConfluenceProperties:
+    domain: str
+    base_path: str
+    space_key: str
+    user_name: Optional[str]
+    api_key: str
+
+    def __init__(
+        self,
+        domain: Optional[str] = None,
+        base_path: Optional[str] = None,
+        user_name: Optional[str] = None,
+        api_key: Optional[str] = None,
+        space_key: Optional[str] = None,
+    ) -> None:
+        opt_domain = domain or os.getenv("CONFLUENCE_DOMAIN")
+        opt_base_path = base_path or os.getenv("CONFLUENCE_PATH")
+        opt_user_name = user_name or os.getenv("CONFLUENCE_USER_NAME")
+        opt_api_key = api_key or os.getenv("CONFLUENCE_API_KEY")
+        opt_space_key = space_key or os.getenv("CONFLUENCE_SPACE_KEY")
+
+        if not opt_domain:
+            raise ConfluenceError("Confluence domain not specified")
+        if not opt_base_path:
+            opt_base_path = "/wiki/"
+        if not opt_api_key:
+            raise ConfluenceError("Confluence API key not specified")
+        if not opt_space_key:
+            raise ConfluenceError("Confluence space key not specified")
+
+        if opt_domain.startswith(("http://", "https://")) or opt_domain.endswith("/"):
+            raise ConfluenceError(
+                "Confluence domain looks like a URL; only host name required"
+            )
+        if not opt_base_path.startswith("/") or not opt_base_path.endswith("/"):
+            raise ConfluenceError("Confluence base path must start and end with a '/'")
+
+        self.domain = opt_domain
+        self.base_path = opt_base_path
+        self.user_name = opt_user_name
+        self.api_key = opt_api_key
+        self.space_key = opt_space_key
+        self.space_key = opt_space_key
+        self.space_key = opt_space_key

markdown_to_confluence-0.1.10.dist-info/RECORD

@@ -1,13 +0,0 @@
-md2conf/__init__.py,sha256=87hc-oGK6Iy7HpMb4r0ujxMFZTbmrMValBsbRy1xySA,403
-md2conf/__main__.py,sha256=vqSQ1jYCDXcPw7xG6MxbY5qDgwJxFBYPgp25CqniiNE,2639
-md2conf/api.py,sha256=qomqdn8sztLe5jBaiqbA-YqSt7W3Kp_2K4-amJhMYK4,11946
-md2conf/application.py,sha256=DOaPHuvWQNHmLuTWnTeLvWvgn4vvy3NN4eM-UGND2Qs,3670
-md2conf/converter.py,sha256=WDm_MlzGf3suTvSbbngUjODigWrlP8A6PpqqFRT0NZY,16410
-md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
-md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-markdown_to_confluence-0.1.10.dist-info/LICENSE,sha256=W_F6JttWaUq8-m1T7FrjMU0PYCTHYC-H4DUaPNZ7YGc,1077
-markdown_to_confluence-0.1.10.dist-info/METADATA,sha256=z4wxlc22eWiujPC-09-p9dE-OnrzEH4FAXKgIIC6MIo,7468
-markdown_to_confluence-0.1.10.dist-info/WHEEL,sha256=Xo9-1PvkuimrydujYJAjF7pCkriuXBpUPEjma1nZyJ0,92
-markdown_to_confluence-0.1.10.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
-markdown_to_confluence-0.1.10.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-markdown_to_confluence-0.1.10.dist-info/RECORD,,