pdstools.utils.report_utils._quarto¶

Quarto execution helpers: run, version detection, callouts, credits.

Functions¶

`_write_params_files`(→ None)	Write parameters to YAML files for Quarto processing.
`run_quarto`(, *, full_embed)	Run the Quarto command to generate the report.
`_set_command_options`(→ list[str])	Set the options for the Quarto command.
`_get_cmd_output`(→ list[str])	Get command output in an OS-agnostic way.
`_get_version_only`(→ str)	Extract version number from version string.
`get_quarto_with_version`(→ tuple[pathlib.Path, str])	Get Quarto executable path and version.
`get_pandoc_with_version`(→ tuple[pathlib.Path, str])	Get Pandoc executable path and version.
`quarto_print`(text)
`quarto_callout_info`(info)
`quarto_callout_important`(info)
`quarto_plot_exception`(plot_name, e)
`quarto_callout_no_prediction_data_warning`([extra])
`quarto_callout_no_predictor_data_warning`([extra])
`show_credits`([quarto_source])	Display a credits section with build metadata at the end of a report.

Module Contents¶

_write_params_files(temp_dir: pathlib.Path, params: dict | None = None, project: dict = {'type': 'default'}, analysis: dict | None = None, full_embed: bool = False) → None¶

Write parameters to YAML files for Quarto processing.

Parameters:

temp_dir (Path) – Directory where YAML files will be written
params (dict, optional) – Parameters to write to params.yml, by default None
project (dict, optional) – Project configuration to write to _quarto.yml, by default {“type”: “default”}
analysis (dict, optional) – Analysis configuration to write to _quarto.yml, by default None
full_embed (bool, default=False) – When True, embeds all resources (JavaScript libraries like Plotly, itables, etc.) for a fully standalone HTML (larger output). When False, loads JavaScript libraries from CDN and skips esbuild bundling (smaller output, but requires internet).

Return type:

None

run_quarto(qmd_file: str | None = None, output_filename: str | None = None, output_type: str | None = 'html', params: dict | None = None, project: dict = {'type': 'default'}, analysis: dict | None = None, temp_dir: pathlib.Path = Path(), *, full_embed: bool = False) → int¶

Run the Quarto command to generate the report.

Parameters:

qmd_file (str, optional) – Path to the Quarto markdown file to render, by default None
output_filename (str, optional) – Name of the output file, by default None
output_type (str, optional) – Type of output format (html, pdf, etc.), by default “html”
params (dict, optional) – Parameters to pass to Quarto execution, by default None
project (dict, optional) – Project configuration settings, by default {“type”: “default”}
analysis (dict, optional) – Analysis configuration settings, by default None
temp_dir (Path, optional) – Temporary directory for processing, by default Path(“.”)
full_embed (bool, default=False) – When True, fully embeds all JavaScript libraries (Plotly, itables, etc.) into the HTML output (larger file). When False, loads JavaScript libraries from CDN and skips esbuild bundling, avoiding the need for esbuild (see issue #620).

Returns:

Return code from the Quarto process (0 for success)

Return type:

int

Raises:

RuntimeError – If the Quarto process fails (non-zero return code), includes captured output
subprocess.SubprocessError – If the Quarto command fails to execute
FileNotFoundError – If required files are not found

_set_command_options(output_type: str | None = None, output_filename: str | None = None, execute_params: bool = False) → list[str]¶

Set the options for the Quarto command.

Parameters:

output_type (str, optional) – Output format type (html, pdf, etc.), by default None
output_filename (str, optional) – Name of the output file, by default None
execute_params (bool, optional) – Whether to include parameter execution flag, by default False

Returns:

list of command line options for Quarto

Return type:

list[str]

_get_cmd_output(args: list[str]) → list[str]¶

Get command output in an OS-agnostic way.

Parameters:: args (list[str])
Return type:: list[str]

_get_version_only(versionstr: str) → str¶

Extract version number from version string.

Parameters:: versionstr (str)
Return type:: str

get_quarto_with_version() → tuple[pathlib.Path, str]¶

Get Quarto executable path and version.

Return type:: tuple[pathlib.Path, str]

get_pandoc_with_version() → tuple[pathlib.Path, str]¶

Get Pandoc executable path and version.

Return type:: tuple[pathlib.Path, str]

quarto_print(text)¶

quarto_callout_info(info)¶

quarto_callout_important(info)¶

quarto_plot_exception(plot_name: str, e: Exception)¶

Parameters:

plot_name (str)
e (Exception)

quarto_callout_no_prediction_data_warning(extra='')¶

quarto_callout_no_predictor_data_warning(extra='')¶

show_credits(quarto_source: str | None = None)¶

Display a credits section with build metadata at the end of a report.

Prints a formatted block containing the generation timestamp, Quarto and Pandoc versions, and optionally the source notebook path.

Parameters:: quarto_source (str, optional) – Path or identifier of the source .qmd file. Include this for standalone reports where knowing the source is useful. Omit for Quarto website projects where pages are generated from templates.