markdown-to-confluence 0.1.10__tar.gz → 0.1.12__tar.gz

{markdown-to-confluence-0.1.10 → markdown_to_confluence-0.1.12}/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 → markdown_to_confluence-0.1.12}/PKG-INFO

@@ -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.10 → markdown_to_confluence-0.1.12}/README.md

@@ -5,6 +5,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.
@@ -23,6 +24,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),
@@ -31,7 +33,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.
@@ -39,6 +41,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/'
@@ -105,28 +108,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.10 → markdown_to_confluence-0.1.12}/markdown_to_confluence.egg-info/PKG-INFO

@@ -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.10 → markdown_to_confluence-0.1.12}/markdown_to_confluence.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ setup.py
 markdown_to_confluence.egg-info/PKG-INFO
 markdown_to_confluence.egg-info/SOURCES.txt
 markdown_to_confluence.egg-info/dependency_links.txt
+markdown_to_confluence.egg-info/entry_points.txt
 markdown_to_confluence.egg-info/requires.txt
 markdown_to_confluence.egg-info/top_level.txt
 markdown_to_confluence.egg-info/zip-safe
@@ -15,5 +16,9 @@ md2conf/api.py
 md2conf/application.py
 md2conf/converter.py
 md2conf/entities.dtd
+md2conf/processor.py
+md2conf/properties.py
 md2conf/py.typed
-tests/test_api.py
+tests/test_api.py
+tests/test_conversion.py
+tests/test_processor.py

markdown_to_confluence-0.1.12/markdown_to_confluence.egg-info/entry_points.txt

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

markdown_to_confluence-0.1.12/markdown_to_confluence.egg-info/requires.txt

@@ -0,0 +1,7 @@
+lxml>=5.2
+types-lxml>=2024.4.14
+markdown>=3.6
+types-markdown>=3.6
+pymdown-extensions>=10.8
+requests>=2.32
+types-requests>=2.32

{markdown-to-confluence-0.1.10 → markdown_to_confluence-0.1.12}/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"

markdown_to_confluence-0.1.12/md2conf/__main__.py

@@ -0,0 +1,140 @@
+import argparse
+import logging
+import os.path
+import sys
+import typing
+from pathlib import Path
+from typing import Optional
+
+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: Path
+    domain: str
+    path: str
+    username: str
+    apikey: str
+    space: str
+    loglevel: str
+    ignore_invalid_url: bool
+    generated_by: Optional[str]
+
+
+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)
+
+    # NOTE:  If we switch to modern type aware CLI tool like typer
+    #  the following line won't be necessary
+    args.mdpath = Path(args.mdpath)
+
+    logging.basicConfig(
+        level=getattr(logging, args.loglevel.upper(), logging.INFO),
+        format="%(asctime)s - %(levelname)s - %(funcName)s [%(lineno)d] - %(message)s",
+    )
+
+    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:
+            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)
+
+
+if __name__ == "__main__":
+    main()