Options: Add --format=mrkdwn option, improving Slack messages

Author: amotl

CHANGES.md

@@ -8,6 +8,7 @@
 - GitHub/Backup: Added wrapper around `github-backup`
 - Options: Use `aika` for parsing time intervals.
   Also, rename command-line option `--timerange` to `--when`.
+- Options: Added `--format=mrkdwn` option, improving Slack messages
 
 ## v0.1.0, 2025-02-20
 - Started using `GH_TOKEN` environment variable instead of `GITHUB_TOKEN`,

docs/guide/options.md

@@ -31,4 +31,15 @@ or relative human-readable notations.
 - this month
 
 
+## Output options
+
+### Slack flavored Markdown
+
+The program can output two flavors of Markdown. Standard Markdown is default,
+while the [Slack `mrkdwn` format] can be produced using the `--format=mrkdwn`
+command-line option. Rapporto uses the [markdown-to-mrkdwn] package here.
+
+
 [aika]: https://pypi.org/project/aika/
+[markdown-to-mrkdwn]: https://pypi.org/project/markdown-to-mrkdwn/
+[Slack `mrkdwn` format]: https://api.slack.com/reference/surfaces/formatting#basic-formatting

pyproject.toml

@@ -101,6 +101,7 @@ dependencies = [
   "dataclasses-json<1",
   "github-backup<1",
   "importlib-metadata; python_version<'3.8'",
+  "markdown-to-mrkdwn<0.2",
   "munch<5",
   "pueblo<1",
   "python-dateutil<3",

src/rapporto/github/actions.py

@@ -62,9 +62,6 @@ def markdown(self):
 {mdc.render()}
         """.strip()  # noqa: E501
 
-    def print(self):
-        print(self.markdown)
-
 
 class GitHubActionsRequest:
     """

src/rapporto/github/activity.py

@@ -1,6 +1,8 @@
 import dataclasses
+import io
 import logging
 import typing as t
+from contextlib import redirect_stdout
 from operator import attrgetter
 from textwrap import dedent
 
@@ -112,14 +114,18 @@ def format_pr(item: "PullRequestMetadata"):
             f"comments: {item.comments_total}, files: {item.changed_files}, size: {item.code_size}"
         )
 
-    def print(self):
+    @property
+    def markdown(self) -> str:
         timerange = self.inquiry.created and f"for {self.inquiry.created}" or ""
-        print(f"# PPP report {timerange}")
-        # print("## Overview")
-        print(self.markdown_overview)
-        print()
-        print("*Top changes:*")
-        print(self.markdown_significant)
+        with redirect_stdout(io.StringIO()) as buffer:
+            print(f"# PPP report {timerange}")
+            # print("## Overview")
+            print(self.markdown_overview)
+            print()
+            print("*Top changes:*")
+            print(self.markdown_significant)
+        buffer.seek(0)
+        return buffer.read()
 
 
 @dataclass_json(undefined=Undefined.INCLUDE)

src/rapporto/github/attention.py

@@ -110,6 +110,3 @@ def markdown(self):
 Time range: {self.search.query_builder.timerange or "n/a"}
 {mdc.render()}
         """.strip()  # noqa: E501
-
-    def print(self):
-        print(self.markdown)

src/rapporto/github/cli.py

@@ -9,10 +9,12 @@
 from rapporto.github.attention import GitHubAttentionReport
 from rapporto.github.backup import GitHubBackup
 from rapporto.github.model import GitHubInquiry
+from rapporto.util import to_mrkdwn
 
 organization_option = click.option("--organization", "--org", type=str, required=False)
 author_option = click.option("--author", type=str, required=False)
 when_option = click.option("--when", type=str, required=False)
+format_option = click.option("--format", "format_", type=str, required=False, default="markdown")
 repository_option = click.option("--repository", type=str, required=False)
 repositories_file_option = click.option("--repositories-file", type=Path, required=False)
 
@@ -30,23 +32,35 @@ def cli(ctx: click.Context):
 @organization_option
 @author_option
 @when_option
+@format_option
 def activity(
     organization: t.Optional[str] = None,
     author: t.Optional[str] = None,
     when: t.Optional[str] = None,
+    format_: t.Optional[str] = None,
 ):
     """
     Activities of individual authors.
     """
     inquiry = GitHubInquiry(organization=organization, author=author, created=when)
     report = GitHubActivityReport(inquiry=inquiry)
-    report.print()
+    print_output(report, format_)
+
+
+def print_output(report, format_):
+    if format_ == "markdown":
+        print(report.markdown)
+    elif format_ == "mrkdwn":
+        print(to_mrkdwn(report.markdown))
+    else:
+        raise NotImplementedError(f"Unknown output format: {format_}")
 
 
 @cli.command(aliases=["ci"])
 @repository_option
 @repositories_file_option
-def actions(repository: str, repositories_file: Path = None):
+@format_option
+def actions(repository: str, repositories_file: Path = None, format_: t.Optional[str] = None):
     """
     CI/GHA failures.
     """
@@ -60,19 +74,24 @@ def actions(repository: str, repositories_file: Path = None):
         )
         raise SystemExit(1) from ex
     report = GitHubActionsReport(inquiry=inquiry)
-    report.print()
+    print_output(report, format_)
 
 
 @cli.command(aliases=["att"])
 @organization_option
 @when_option
-def attention(organization: t.Optional[str] = None, when: t.Optional[str] = None):
+@format_option
+def attention(
+    organization: t.Optional[str] = None,
+    when: t.Optional[str] = None,
+    format_: t.Optional[str] = None,
+):
     """
     Important items that deserve attention.
     """
     inquiry = GitHubInquiry(organization=organization, created=when)
     report = GitHubAttentionReport(inquiry=inquiry)
-    report.print()
+    print_output(report, format_)
 
 
 @cli.command(

src/rapporto/util.py

@@ -1,3 +1,6 @@
+from markdown_to_mrkdwn import SlackMarkdownConverter
+
+
 def sanitize_title(title: str) -> str:
     """
     Strip characters that are unfortunate in Markdown link titles.
@@ -12,3 +15,10 @@ def goosefeet(text: str) -> str:
     if " " in text:
         return f'"{text}"'
     return text
+
+
+mrkdwn_converter = SlackMarkdownConverter()
+
+
+def to_mrkdwn(markdown: str) -> str:
+    return mrkdwn_converter.convert(markdown)