coerce_report

Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

coerce_report(report: Report | None, *, writer: ResultWriter | None = None, retain: str = 'all', on_subject_complete: Callable[[Subject, HabitatMap, HabitatModel], None] | None = None, persist_subject_models: bool = True) → Report | None[source]

Build or complete a Report from the Study call-site kwargs.

report= is the primary API. The older writer= / retain= / on_subject_complete= kwargs still work: they construct an implicit Report, or fill a field the explicit Report left empty.

Parameters:

  • report – Explicit report, or None.

  • writer – Streaming writer from the call site.

  • retain – Retention mode from the call site ("all" means “not specified” when an explicit report is also given).

  • on_subject_complete – Optional callback from the call site.

  • persist_subject_models – When building an implicit report with a writer, also persist <subject_id>.habitatmodel.

Returns:

A completed Report, or None when nothing streams (historical in-memory default).

Raises:

HABITAPIError – If an explicit report and a kwarg disagree.