Serialization¶

The single home for converting PatchTitle objects to and from their DataFrame and dict forms. DataManager (cache round-trip), Exporter (JSON output), and the trend-analysis diff path all share these functions instead of each re-implementing model_dump.

titles_to_df(titles: list[PatchTitle]) → DataFrame[source]¶

Build a DataFrame from PatchTitle objects.

Columns are the model’s snake_case field names. Callers that render reports re-case the columns for display; the diff path keeps them as-is.

Parameters:

titles (list[PatchTitle])

Return type:

DataFrame

df_to_titles(df: DataFrame) → tuple[list[PatchTitle], list[str]][source]¶

Build PatchTitle objects from DataFrame rows.

Column labels are normalized back to snake_case before validation. Returns the parsed titles alongside an error message for each row that failed to validate, leaving the decision of how to report them to the caller.

Parameters:

df (DataFrame)

Return type:

tuple[list[PatchTitle], list[str]]

titles_to_dict(titles: list[PatchTitle], report_title: str | None = None) → dict[source]¶

Convert PatchTitle objects into a JSON-serializable envelope.

The envelope has the shape:

{
    "generated_at": "2026-05-04T18:30:00+00:00",
    "report_title": "...",
    "title_count": 42,
    "titles": [<PatchTitle.model_dump(mode="json")>, ...]
}

Internal keys (title_id, name_id) are retained because JSON is a machine-to-machine transport; the human-facing PDF/Excel exports drop them via IGNORED_EXPORT_COLUMNS.

Parameters:
Return type:

dict