[ADD] util/report: util.add_report

Add a new function that replaces util.add_to_migration_reports.

The new function can automatically parse the provided data as a list of records.
It can also limit the number of displayed records to prevent the upgrade report from growing too large.

The structure of the note is now defined within the function itself, standardizing its appearance.

Author: diagnoza

src/util/report.py

@@ -126,6 +126,95 @@ def add_to_migration_reports(message, category="Other", format="text"):
         _logger.warning("Upgrade report is growing suspiciously long: %s characters so far.", migration_reports_length)
 
 
+def add_report(
+    header,
+    summary,
+    data=None,
+    columns=None,
+    links=None,
+    row_format=None,
+    limit=100,
+    report_format="html",
+):
+    """Append the upgrade report with a new entry.
+
+    The entry consists of a header (title) and a summary (body).
+    The entry can also display a list of records previously returned by an SQL query. In such case, in addition to the output of
+    the query passed as "data", parameters "row_format" and "columns" must also be provided.
+
+
+    :param str header: Title of a report entry.
+    :param str summary: Description of a report entry.
+    :param List[Tuple] data: Any data in the form of a list of tuples, e.g. the output of cr.fetchall().
+    :param Tuple[str] columns: Arbitrary names for each column in "data". All columns must be named and
+                              the order of these names must be the same as in "data".
+    :param Dict[str, Tuple[str, str, str]] links: Optional model/record links, e.g.:
+                                                  {
+                                                    "partner_link": ("res.partner", "id", "name"),
+                                                    "company_link": ("res.company", "company_id", "company_name"),
+                                                  }
+    :param str row_format: The way a row in a list is formatted, using named placeholders, e.g.:
+                           "Partner {partner_link} that lives in {city} works at company {company_link}."
+    :param int limit: The number of records that are going to be displayed in the report.
+    :param str report_format: Format of the input "summary"; must be one of {"text", "html", "md", "rst"}
+    """
+    assert report_format in {"text", "html", "md", "rst"}
+    if report_format == "md":
+        summary = md2html(dedent(summary))
+    elif report_format == "rst":
+        summary = rst2html(dedent(summary))
+
+    if data:
+        assert columns is not None
+        assert row_format is not None
+        rows = []
+
+        for row in data[:limit]:
+            row_dict = dict(zip(columns, row))
+
+            if links:
+                for link_name, (link_model, id_column, name_column) in links.items():
+                    row_dict[link_name] = get_anchor_link_to_record(
+                        link_model,
+                        row_dict[id_column],
+                        row_dict[name_column],
+                    )
+
+            row_text = row_format.format(**row_dict)
+            rows.append("<li>{}</li>".format(row_text))
+
+        rows = "<ul>\n" + "\n".join(rows) + "\n</ul>"
+
+        total = len(data)
+        disclaimer = "The total number of affected records is {}.".format(total)
+        if total > limit:
+            disclaimer += " This list is limited to {} records.".format(limit)
+
+        msg = """
+            <summary>
+                {}
+                <details>
+                    <i>{}</i>
+                    {}
+                </details>
+            </summary>
+        """.format(summary, disclaimer, rows)
+    else:
+        msg = """
+        <summary>
+            {}
+        </summary>
+        """.format(summary)
+
+    raw = False
+    if report_format != "text":
+        if Markup:
+            msg = Markup(msg)
+        else:
+            raw = True
+    migration_reports.setdefault(header, []).append((msg, raw))
+
+
 def announce_release_note(cr):
     filepath = os.path.join(os.path.dirname(__file__), "release-note.xml")
     with open(filepath, "rb") as fp: