[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,66 @@ 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)
 
 
+report = add_to_migration_reports
+
+
+def report_with_summary(summary, details, category="Other"):
+    """Append the upgrade report with a new entry.
+
+    :param str summary: Description of a report entry.
+    :param str details: Detailed description that is going to be folded by default.
+    :param str category: Title of a report entry.
+    """
+    msg = "<summary>{}<details>{}</details></summary>".format(summary, details)
+    report(message=msg, category=category, format="html")
+
+
+def report_with_list(summary, data, columns, row_format, links=None, total=None, limit=100, category="Other"):
+    """Append the upgrade report with a new entry that displays a list of records.
+
+    The entry consists of a category (title) and a summary (body).
+    The entry displays a list of records previously returned by an SQL query, or any list as long as it's passed as a Python List of Tuples.
+
+    :param str category: 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 maximum number of records that are going to be displayed in the report.
+    :param int total: If the original list was limited prior to calling this method, the original, total number of
+                      records can be provided with this parameter.
+    """
+
+    def row_to_html(row):
+        row_dict = dict(zip(columns, row))
+        row_dict.update(
+            {
+                link: get_anchor_link_to_record(rec_model, row_dict[id_col], row_dict[name_col])
+                for link, (rec_model, id_col, name_col) in links.items()
+            }
+        )
+        return "<li>{}</li>".format(row_format.format(**row_dict))
+
+    if not data:
+        row_to_html(columns)  # Validate the format is correct, including links
+        return report_with_summary(summary=summary, details="No records to display.", category=category)
+
+    total = total or len(data)
+    disclaimer = "The total number of affected records is {}.".format(total)
+    if total > limit:
+        disclaimer += " This list is limited to {} records.".format(limit)
+
+    rows = "<ul>\n" + "\n".join([row_to_html(row) for row in data[:limit]]) + "\n</ul>"
+    return report_with_summary(summary, "<i>{}</i>{}".format(disclaimer, rows), category)
+
+
 def announce_release_note(cr):
     filepath = os.path.join(os.path.dirname(__file__), "release-note.xml")
     with open(filepath, "rb") as fp: