openavmkit.reports

MarkdownReport

MarkdownReport(name)

A report generator that uses a Markdown template.

Attributes:

Name	Type	Description
name	str	Name of the report, corresponding to a Markdown template.
template	str	The raw Markdown template text.
rendered	str	The rendered Markdown text after variable substitution.
variables	dict	Dictionary of variables for substitution in the template.

Initialize the MarkdownReport by loading the Markdown template.

Parameters:

Name	Type	Description	Default
name	str	Name of the report template (without file extension).	required

Source code in openavmkit/reports.py

def __init__(self, name: str) -> None:
    """
    Initialize the MarkdownReport by loading the Markdown template.

    Parameters
    ----------
    name : str
        Name of the report template (without file extension).
    """
    self.name = name
    with importlib.resources.open_text(
        "openavmkit.resources.reports", f"{name}.md", encoding="utf-8"
    ) as file:
        self.template = file.read()
    self.variables = {}
    self.rendered = ""

get_var

get_var(key)

Get the value of a variable.

Parameters:

Name	Type	Description	Default
key	str	Variable key.	required

Returns:

Type	Description
Any or None	The value associated with key, or None if not set.

Source code in openavmkit/reports.py

def get_var(self, key: str):
    """
    Get the value of a variable.

    Parameters
    ----------
    key : str
        Variable key.

    Returns
    -------
    Any or None
        The value associated with `key`, or `None` if not set.
    """
    return self.variables.get(key)

render

render()

Render the report by substituting variables in the template.

Returns:

Type	Description
str	The rendered Markdown text with all variables replaced.

Source code in openavmkit/reports.py

def render(self) -> str:
    """
    Render the report by substituting variables in the template.

    Returns
    -------
    str
        The rendered Markdown text with all variables replaced.
    """
    self.rendered = self.template
    for key, value in self.variables.items():
        self.rendered = self.rendered.replace(f"{{{{{key}}}}}", str(value))
    return self.rendered

set_var

set_var(key, value, fmt=None)

Set a variable value with optional formatting.

Parameters:

Name	Type	Description	Default
key	str	Variable key.	required
value	Any	Value to be set.	required
fmt	str	Format string to apply to value.	None

Returns:

Type	Description
None

Source code in openavmkit/reports.py

def set_var(self, key: str, value, fmt: str = None):
    """
    Set a variable value with optional formatting.

    Parameters
    ----------
    key : str
        Variable key.
    value : Any
        Value to be set.
    fmt : str, optional
        Format string to apply to `value`.

    Returns
    -------
    None
    """
    if value is None:
        formatted_value = "<NULL>"
    elif fmt is not None:
        formatted_value = format(value, fmt)
    else:
        formatted_value = str(value)
    self.variables[key] = formatted_value

finish_report

finish_report(report, outpath, css_file, settings)

Render the report and export it in Markdown, HTML, and PDF formats.

Saves the rendered Markdown to disk and converts it to target formats using a specified CSS file.

Parameters:

Name	Type	Description	Default
report	MarkdownReport	MarkdownReport object to be finished.	required
outpath	str	Output file path (without extension).	required
css_file	str	Name of the CSS file (without extension) to style the report.	required
settings	dict	Settings dictionary.	required

Source code in openavmkit/reports.py

def finish_report(
    report: MarkdownReport, outpath: str, css_file: str, settings: dict
) -> None:
    """
    Render the report and export it in Markdown, HTML, and PDF formats.

    Saves the rendered Markdown to disk and converts it to target formats using a
    specified CSS file.

    Parameters
    ----------
    report : MarkdownReport
        MarkdownReport object to be finished.
    outpath : str
        Output file path (without extension).
    css_file : str
        Name of the CSS file (without extension) to style the report.
    settings : dict
        Settings dictionary.
    """
    formats = settings.get("analysis", {}).get("report", {}).get("formats", None)
    if formats is None:
        formats = ["pdf", "md"]

    report_text = report.render()
    os.makedirs(outpath, exist_ok=True)
    with open(f"{outpath}.md", "w", encoding="utf-8") as f:
        f.write(report_text)
    pdf_path = f"{outpath}.pdf"

    _markdown_to_pdf(report_text, pdf_path, formats=formats, css_file=css_file)

    if "md" not in formats:
        os.remove(f"{outpath}.md")

start_report

start_report(report_name, settings, model_group)

Create and initialize a MarkdownReport with basic variables set.

Parameters:

Name	Type	Description	Default
report_name	str	Name of the report template.	required
settings	dict	Settings dictionary.	required
model_group	str	Model group identifier.	required

Returns:

Type	Description
MarkdownReport	Initialized MarkdownReport object.

Source code in openavmkit/reports.py

def start_report(report_name: str, settings: dict, model_group: str) -> MarkdownReport:
    """
    Create and initialize a MarkdownReport with basic variables set.

    Parameters
    ----------
    report_name : str
        Name of the report template.
    settings : dict
        Settings dictionary.
    model_group : str
        Model group identifier.

    Returns
    -------
    MarkdownReport
        Initialized MarkdownReport object.
    """

    report = MarkdownReport(report_name)
    locality = settings.get("locality", {}).get("name")
    val_date = get_valuation_date(settings)
    val_date = val_date.strftime("%Y-%m-%d")

    model_group_obj = get_model_group(settings, model_group)
    model_group_name = model_group_obj.get("name", model_group)

    report.set_var("locality", locality)
    report.set_var("val_date", val_date)
    report.set_var("model_group", model_group_name)
    return report