Merge pull request #21 from kieferro/comment-template

Add possibility to extend blocks of the comment template

Author: ewjoachim

README.md

@@ -229,6 +229,49 @@ jobs:
     # You typically don't have to change this unless you're already using this name for something else.
     COMMENT_FILENAME: python-coverage-comment-action.txt
 
+    # An alternative template for the comment for pull requests. See details below.
+    COMMENT_TEMPLATE: The coverage rate is `{{ coverage.info.percent_covered | pct }}{{ marker }}`
+```
+
+## Overriding the template
+
+By default, comments are generated from a
+[Jinja](https://jinja.palletsprojects.com) template that you can read
+[here](https://github.com/ewjoachim/python-coverage-comment-action/blob/v2/coverage_comment/default.md.j2).
+
+If you want to change this template, you can set ``COMMENT_TEMPLATE``. This is
+an advanced usage, so you're likely to run into more road bumps.
+
+You will need to follow some rules for your template to be valid:
+
+- Your template needs to be syntactically correct with Jinja2 rules
+- You may define a new template from scratch, but in this case you are required
+  to include ``{{ marker }}``, which includes an HTML comment (invisible on
+  GitHub) that the action uses to identify its own comments.
+- If you'd rather want to change parts of the default template, you can do so
+  by starting your comment with ``{% extends "base" %}``, and then override the
+  blocks (``{% block foo %}``) that you wish to change. If you're unsure how it
+  works, see [the Jinja
+  documentation](https://jinja.palletsprojects.com/en/3.0.x/templates/#template-inheritance)
+- In either case, you will most likely want to get yourself familiar with the
+  available context variables, the best is to read the code from
+  [here](https://github.com/ewjoachim/python-coverage-comment-action/blob/v2/coverage_comment/template.py).
+  Should those variables change, we'll do our best to bump the action's major version.
+
+### Examples
+In the first example, we change the emoji that illustrates coverage going down from
+`:down_arrow:` to `:sob:`:
+
+```jinja2
+{% extends "base" %}
+{% block emoji_coverage_down %}:sob:{% endblock emoji_coverage_down %}
+```
+
+In this second example, we replace the whole comment by something much shorter with the
+coverage (percentage) of the whole project from the PR build:
+
+```jinja2
+Coverage: {{ coverage.info.percent_covered | pct }}
 ```
 
 # Other topics

action.yml

@@ -18,7 +18,8 @@ inputs:
     required: false
   COMMENT_TEMPLATE:
     description: >
-      [Advanced] Specify a different template for the comments that will be written on the PR.
+      [Advanced] Specify a different template for the comments that will be written on
+      the PR. See the Action README documentation for how to use this properly.
     required: false
   BADGE_FILENAME:
     description: >
@@ -68,6 +69,7 @@ runs:
   env:
     GITHUB_TOKEN: ${{ inputs.GITHUB_TOKEN }}
     GITHUB_PR_RUN_ID: ${{ inputs.GITHUB_PR_RUN_ID }}
+    COMMENT_TEMPLATE: ${{ inputs.COMMENT_TEMPLATE }}
     BADGE_FILENAME: ${{ inputs.BADGE_FILENAME }}
     COMMENT_ARTIFACT_NAME: ${{ inputs.COMMENT_ARTIFACT_NAME }}
     COMMENT_FILENAME: ${{ inputs.COMMENT_FILENAME }}

coverage_comment/default.md.j2

@@ -1,33 +1,56 @@
-## Coverage report
+{% block title %}## Coverage report{% endblock title %}
+{% block coverage_evolution -%}
 {% if previous_coverage_rate -%}
-The coverage rate went from `{{ previous_coverage_rate | pct }}` to `{{ coverage.info.percent_covered | pct }}` {{
-    ":arrow_up:" if previous_coverage_rate < coverage.info.percent_covered else
-    ":arrow_down:" if previous_coverage_rate > coverage.info.percent_covered else
-    ":arrow_right:"
-}}
+{% block coverage_evolution_wording -%}
+The coverage rate went from `{{ previous_coverage_rate | pct }}` to `{{ coverage.info.percent_covered | pct }}`{{" "}}
+{%- endblock coverage_evolution_wording %}
+{%- block emoji_coverage -%}
+{%- if previous_coverage_rate < coverage.info.percent_covered -%}
+{%- block emoji_coverage_up -%}:arrow_up:{%- endblock emoji_coverage_up -%}
+{%- elif previous_coverage_rate > coverage.info.percent_covered -%}
+{%- block emoji_coverage_down -%}:arrow_down:{%- endblock emoji_coverage_down -%}
 {%- else -%}
-The coverage rate is `{{ coverage.info.percent_covered | pct }}`
+{%- block emoji_coverage_constant -%}:arrow_right:{%- endblock emoji_coverage_constant -%}
 {%- endif %}
+{%- endblock emoji_coverage -%}
+{%- else -%}
+{% block coverage_value_wording -%}
+The coverage rate is `{{ coverage.info.percent_covered | pct }}`.
+{%- endblock coverage_value_wording %}
+{%- endif %}
+{%- endblock coverage_evolution %}
+{% block branch_coverage -%}
 {% if coverage.meta.branch_coverage and coverage.info.num_branches -%}
-The branch rate is `{{ (coverage.info.covered_branches / coverage.info.num_branches) | pct }}`
+{% block branch_coverage_wording -%}
+The branch rate is `{{ (coverage.info.covered_branches / coverage.info.num_branches) | pct }}`.
+{% endblock branch_coverage_wording -%}
 {%- endif %}
+{% endblock branch_coverage -%}
 
+{% block diff_coverage_wording -%}
 `{{ diff_coverage.total_percent_covered | pct }}` of new lines are covered.
+{%- endblock diff_coverage_wording %}
 
+{% block coverage_by_file -%}
 {%if diff_coverage.files -%}
 <details>
-<summary>Diff Coverage details (click to unfold)</summary>
+<summary>{% block coverage_by_file_summary_wording -%}Diff Coverage details (click to unfold){% endblock coverage_by_file_summary_wording -%}</summary>
 
 {% for filename, diff_file_coverage in diff_coverage.files.items() -%}
-### {{ filename }}
-`{{ diff_file_coverage.percent_covered | pct }}` of new lines are covered (`{{ coverage.files[filename].info.percent_covered | pct }}` of the complete file)
-
+{% block coverage_single_file scoped -%}
+{% block coverage_single_file_title scoped %}### {{ filename }}{% endblock coverage_single_file_title %}
+{% block diff_coverage_single_file_wording scoped -%}
+`{{ diff_file_coverage.percent_covered | pct }}` of new lines are covered (`{{ coverage.files[filename].info.percent_covered | pct }}` of the complete file).
+{%- endblock diff_coverage_single_file_wording %}
 {%- if diff_file_coverage.violation_lines %}
+{% block single_file_missing_lines_wording scoped -%}
 {% set separator = joiner(", ") %}
 Missing lines: {% for line in diff_file_coverage.violation_lines %}{{ separator() }}`{{ line }}`{% endfor %}
-{% endif %}
-
-{% endfor %}
+{%- endblock single_file_missing_lines_wording %}
+{% endif -%}
+{%- endblock coverage_single_file -%}
+{%- endfor %}
 </details>
-{%- endif -%}
+{%- endif %}
+{%- endblock coverage_by_file %}
 {{ marker }}

coverage_comment/main.py

@@ -50,7 +50,7 @@ def action(
     github_session: httpx.Client,
     http_session: httpx.Client,
     git: subprocess.Git,
-):
+) -> int:
     log.debug(f"Operating on {config.GITHUB_REF}")
 
     event_name = config.GITHUB_EVENT_NAME
@@ -96,7 +96,7 @@ def generate_comment(
     github_session: httpx.Client,
     http_session: httpx.Client,
     git: subprocess.Git,
-):
+) -> int:
     log.info("Generating comment for PR")
 
     diff_coverage = coverage_module.get_diff_coverage_info(
@@ -113,12 +113,30 @@ def generate_comment(
     if previous_coverage_data_file:
         previous_coverage = badge.parse_badge(contents=previous_coverage_data_file)
 
-    comment = template.get_markdown_comment(
-        coverage=coverage,
-        diff_coverage=diff_coverage,
-        previous_coverage_rate=previous_coverage,
-        template=template.read_template_file(),
-    )
+    try:
+        comment = template.get_markdown_comment(
+            coverage=coverage,
+            diff_coverage=diff_coverage,
+            previous_coverage_rate=previous_coverage,
+            base_template=template.read_template_file(),
+            custom_template=config.COMMENT_TEMPLATE,
+        )
+    except template.MissingMarker:
+        log.error(
+            "Marker not found. This error can happen if you defined a custom comment "
+            "template that doesn't inherit the base template and you didn't include "
+            "``{{ marker }}``. The marker is necessary for this action to recognize "
+            "its own comment and avoid making new comments or overwriting someone else's "
+            "comment."
+        )
+        return 1
+    except template.TemplateError:
+        log.exception(
+            "There was a rendering error when computing the text of the comment to post "
+            "on the PR. Please see the traceback, in particular if you're using a custom "
+            "template."
+        )
+        return 1
 
     gh = github_client.GitHub(session=github_session)
 
@@ -152,7 +170,7 @@ def generate_comment(
     return 0
 
 
-def post_comment(config: settings.Config, github_session: httpx.Client):
+def post_comment(config: settings.Config, github_session: httpx.Client) -> int:
     log.info("Posting comment to PR")
 
     if not config.GITHUB_PR_RUN_ID:
@@ -212,7 +230,7 @@ def save_badge(
     coverage: coverage_module.Coverage,
     github_session: httpx.Client,
     git: subprocess.Git,
-):
+) -> int:
     gh = github_client.GitHub(session=github_session)
     is_default_branch = github.is_default_branch(
         github=gh,

coverage_comment/settings.py

@@ -27,6 +27,7 @@ class Config:
     GITHUB_REF: str
     GITHUB_EVENT_NAME: str
     GITHUB_PR_RUN_ID: int | None
+    COMMENT_TEMPLATE: str | None = None
     BADGE_FILENAME: pathlib.Path = pathlib.Path(
         "python-coverage-comment-action-badge.json"
     )

coverage_comment/template.py

@@ -1,27 +1,63 @@
 from importlib import resources
 
 import jinja2
+from jinja2.sandbox import SandboxedEnvironment
 
 from coverage_comment import coverage as coverage_module
 
 MARKER = """<!-- This comment was produced by python-coverage-comment-action -->"""
 
 
+class CommentLoader(jinja2.BaseLoader):
+    def __init__(self, base_template: str, custom_template: str | None):
+        self.base_template = base_template
+        self.custom_template = custom_template
+
+    def get_source(
+        self, environment: jinja2.Environment, template: str
+    ) -> tuple[str, str | None, bool]:
+        if template == "base":
+            return self.base_template, None, True
+
+        if self.custom_template and template == "custom":
+            return self.custom_template, None, True
+
+        raise jinja2.TemplateNotFound(template)
+
+
+class MissingMarker(Exception):
+    pass
+
+
+class TemplateError(Exception):
+    pass
+
+
 def get_markdown_comment(
     coverage: coverage_module.Coverage,
     diff_coverage: coverage_module.DiffCoverage,
     previous_coverage_rate: float | None,
-    template: str,
+    base_template: str,
+    custom_template: str | None = None,
 ):
-    env = jinja2.Environment()
+    loader = CommentLoader(base_template=base_template, custom_template=custom_template)
+    env = SandboxedEnvironment(loader=loader)
     env.filters["pct"] = pct
 
-    return env.from_string(template).render(
-        previous_coverage_rate=previous_coverage_rate,
-        coverage=coverage,
-        diff_coverage=diff_coverage,
-        marker=MARKER,
-    )
+    try:
+        comment = env.get_template("custom" if custom_template else "base").render(
+            previous_coverage_rate=previous_coverage_rate,
+            coverage=coverage,
+            diff_coverage=diff_coverage,
+            marker=MARKER,
+        )
+    except jinja2.exceptions.TemplateError as exc:
+        raise TemplateError from exc
+
+    if MARKER not in comment:
+        raise MissingMarker()
+
+    return comment
 
 
 def read_template_file() -> str:

tests/integration/test_main.py

@@ -181,6 +181,44 @@ def checker(payload):
     assert capsys.readouterr().out.strip() == expected_stdout
 
 
+def test_action__pull_request__post_comment__no_marker(
+    pull_request_config, session, in_integration_env, get_logs
+):
+    # There is an existing badge in this test, allowing to test the coverage evolution
+    session.register(
+        "GET",
+        "https://raw.githubusercontent.com/wiki/ewjoachim/foobar/python-coverage-comment-action-badge.json",
+    )(status_code=404)
+
+    result = main.action(
+        config=pull_request_config(COMMENT_TEMPLATE="""foo"""),
+        github_session=session,
+        http_session=session,
+        git=None,
+    )
+    assert result == 1
+    assert get_logs("ERROR", "Marker not found")
+
+
+def test_action__pull_request__post_comment__template_error(
+    pull_request_config, session, in_integration_env, get_logs
+):
+    # There is an existing badge in this test, allowing to test the coverage evolution
+    session.register(
+        "GET",
+        "https://raw.githubusercontent.com/wiki/ewjoachim/foobar/python-coverage-comment-action-badge.json",
+    )(status_code=404)
+
+    result = main.action(
+        config=pull_request_config(COMMENT_TEMPLATE="""{%"""),
+        github_session=session,
+        http_session=session,
+        git=None,
+    )
+    assert result == 1
+    assert get_logs("ERROR", "There was a rendering error")
+
+
 def test_action__push__non_default_branch(
     push_config, session, in_integration_env, get_logs
 ):

tests/unit/test_settings.py

@@ -33,6 +33,7 @@ def test_config__from_environ__ok():
             "BADGE_FILENAME": "bar",
             "COMMENT_ARTIFACT_NAME": "baz",
             "COMMENT_FILENAME": "qux",
+            "COMMENT_TEMPLATE": "footemplate",
             "MINIMUM_GREEN": "90",
             "MINIMUM_ORANGE": "50.8",
             "MERGE_COVERAGE_FILES": "true",
@@ -48,6 +49,7 @@ def test_config__from_environ__ok():
         BADGE_FILENAME=pathlib.Path("bar"),
         COMMENT_ARTIFACT_NAME="baz",
         COMMENT_FILENAME=pathlib.Path("qux"),
+        COMMENT_TEMPLATE="footemplate",
         MINIMUM_GREEN=90.0,
         MINIMUM_ORANGE=50.8,
         MERGE_COVERAGE_FILES=True,