[ADD] util/report: util.add_report

[diagnoza]

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.

Example usage

More examples will follow in odoo/upgrade, replacing the existing use of util.add_to_migration_reports.

Example 1

cr.execute(
        """
        SELECT p.id, p.name, p.city, p.comment, p.company_id, com.name FROM res_partner p
          JOIN res_company com
            ON p.company_id = com.id
        """
    )

summary = """
    This is a test of the utility method that is displaying a list of rows
    returned by an SQL query. The number of displayed rows is limited.
    """
row_format = "Partner with id {partner_link} works at company {company_link} in {city}, ({comment})"
columns = ("id", "name", "city", "comment", "company_id", "company_name")
links = {"company_link": ("res.company", "company_id", "company_name"), "partner_link": ("res.partner", "id", "name")}
util.add_report(header="Test of the new utility method", summary=summary, row_format=row_format, columns=columns, links=links, data=cr.fetchall())

Example 2

util.add_report(header="Simple note", summary="A detailed description of the change.")

Example 3

msg = """
This is some text in **bold**.  

This is a line  
that should break.

- Item one
- Item two
    - Sub-item

And some _italic_ text.
"""
util.add_report(header="MD note", summary=msg, report_format="md")

Example 4

msg = """
This is some text in **bold**.

| This is a line
| that should break.

* Item one
* Item two

  * Sub-item

And some *italic* text.
"""
util.add_report(header="RST note", summary=msg, report_format="rst")

Remaining details to discuss

1. The introduction of env var to control limit.
2. Enforce/assert the use of tuples instead of lists. Currently, it's possible to pass a list for columns (instead of a tuple) or a dictionary of lists for links (instead of a dictionary of tuples).
3. How to handle depreciation of add_to_migration_reports.
4. Indentation of the ir.ui.view record corresponding to the note is sometimes incorrect (previously there was the same issue):

[robodoo]

[KangOl]

upgradeci retry with always only crm

[aj-fuentes]

I think we can do some simplification here. Some suggestions below. Note that none of the suggestions were tested, take it as a guide.

[aj-fuentes]

Looks better. Please adapt the documentation to the same format we use elsewhere in this repo. Some suggestions above.

[diagnoza]

upgradeci retry

[aj-fuentes]

I think we shouldn't be explicit about the total unless it is explicitly passed. The reason is that maybe the caller just passed here a subset of the involved records in data, we cannot be sure that's the actual total number of affected records unless explicitly set.

Suggested change

	total = len(data) if total is None else total
	limit = min(limit, total) if limit != -1 else total
	disclaimer = "The total number of affected records is {}.".format(total)
	disclaimer = "The total number of affected records is {}.".format(total) if total else ""
	total = len(data) if total is None else total
	limit = min(limit, total) if limit != -1 else total

[diagnoza]

@aj-fuentes your latest suggestion is applied. Rebase not necessary because it's still up to date.

[diagnoza]

upgradeci retry

[diagnoza]

@aj-fuentes @KangOl it's ready for another look.

[diagnoza]

upgradeci retry

[aj-fuentes]

Once we generate the link items (which are already escaped) I think we need to escape the remaining values in the dict.
For example imagine that row_format is "{some_field}" and in the dict we get {"some_field": "<script>window.alert('escaped')</script>"}

Suggested change

	)
	)
	row_dict = {col: html_escape(val) for col, val in row_dict.items()}

cc: @KangOl