[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.

[aj-fuentes]

The usual formatting allows for shorter lines. Unless there is some rendering issue?

Suggested change

	util.report_with_list(summary="The following records were altered.",
	data=cr.fetchall(),
	columns=("id", "name", "city", "comment", "company_id", "company_name")
	row_format="Partner with id {partner_link} works at company {company_link} in {city}, ({comment})",
	links={"company_link": ("res.company", "company_id", "company_name"), "partner_link": ("res.partner", "id", "name")},
	category="Accounting"
	)
	total = cr.rowcount
	data = cr.fetchmany(20)
	util.report_with_list(
	summary="The following records were altered.",
	data=data,
	columns=("id", "name", "city", "comment", "company_id", "company_name")
	row_format="Partner with id {partner_link} works at company {company_link} in {city}, ({comment})",
	links={
	"company_link": ("res.company", "company_id", "company_name"),
	"partner_link": ("res.partner", "id", "name")
	},
	total=total,
	category="Accounting"
	)

EDIT: we can include as well in the example total=...

[aj-fuentes]

Try to keep the lines at max 90 chars (similar as we do for other docstrings here)

Suggested change

	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.
	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.

[aj-fuentes]

Some ideas to shorten this and make to the point.
Also use back-quote instead of double quotes to refer to code.

Suggested change

	:param list(tuple) data: data to report, each entry would be a row in the report.
	It could be empty, in which case only the summary is rendered.
	:param tuple(str) columns: names for each column in "data", can be referenced in "row_format".
	: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 dict(str, tuple(str, str, str)) links: optional model/record links spec,
	the keys can be referenced in "row_format".
	: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.
	:param int limit: the maximum number of records that are going to be displayed in the report.
	:param list(tuple) data: data to report, each entry would be a row in the report.
	It could be empty, in which case only the summary is rendered.
	:param tuple(str) columns: columns in `data`, can be referenced in `row_format`.
	:param str row_format: format for rows, can use any name in `columns` or `links`, e.g.:
	`"Partner {partner_link} that lives in {city} works at
	company {company_link}."`
	:param dict(str, tuple(str, str, str)) links: optional model/record links spec,
	to use in `row_format`.
	:param int total: optional total number of records.
	Taken as `len(data)` when `None` is passed.
	Useful when `data` was limited by the caller.
	:param int limit: maximum number of records to list in the report.
	If `data` contains more records the `total` number would be
	included in the report as well.

[aj-fuentes]

To avoid weird situation where the number of entries in data is lower than the limit, but we still got total, we should adapt the limit
Do not use the old-style or shortcut, we can be explicit here: None is a special value.

Suggested change

	total = total or len(data)
	limit = min(limit, len(data))
	total = len(data) if total is None else total

[KangOl]

It will fail. column doesn't have the expected type.

(a.k.a tests are missing)