mostlyright.core.formats

mostlyright.core.formats

Format converters for DataFrame interchange.

One dumps / loads pair per supported format. The dispatch layer (catalog adapters, MCP wire layer) selects a format module and calls its functions uniformly.

Supported formats:

• dataframe — identity passthrough (lossless by definition).
• parquet — Arrow-backed binary, lossless for canonical schemas.
• json — records-oriented string; lossy on dtype.
• csv — pandas-native string; lossy on dtype and null vs empty.
• toon — TOON v3.0 string; lossy per design doc §I.

See each submodule’s docstring for the full loss matrix.

mostlyright.core.formats.csv_dumps(df)

Serialize a DataFrame to a CSV string.

Drops the index (index=False) to match the wire shape the catalog adapters emit. Column order is preserved.

Phase 6 W2-T6: accepts pandas OR polars input; polars frames are converted to pandas at the boundary so the wire bytes stay identical regardless of caller backend.

• Return type: str
• Parameters: df (DataFrame)

mostlyright.core.formats.csv_loads(data)

Parse a CSV string back into a DataFrame.

Uses pandas’ default dtype inference — see module docstring for the loss cases callers must be aware of.

• Return type: DataFrame
• Parameters: data (str)

mostlyright.core.formats.df_dumps(df)

Return the DataFrame unchanged.

Provided for API symmetry with the other format modules. The caller receives the same object reference; callers that mutate must copy explicitly.

• Return type: DataFrame
• Parameters: df (DataFrame)

mostlyright.core.formats.df_loads(df)

Return the DataFrame unchanged.

Mirror of dumps for API symmetry. Accepts a DataFrame (not bytes or string) because the “dataframe” format is the in-memory form.

• Return type: DataFrame
• Parameters: df (DataFrame)

mostlyright.core.formats.json_dumps(df)

Serialize a DataFrame to JSON records.

Non-empty frames are encoded with orient='records' and date_format='iso' so timestamps survive as ISO-8601 strings. Empty frames are encoded as a {"columns": [...], "data": []} envelope so column names roundtrip — orient='records' on a zero-row frame would otherwise collapse to "[]".

Phase 6 W2-T6: accepts pandas OR polars input; polars frames are converted to pandas before serialization (output bytes are identical for the same row content).

• Return type: str
• Parameters: df (DataFrame)

mostlyright.core.formats.json_loads(data)

Parse a JSON string back into a DataFrame.

Accepts both the records form (list of row dicts) and the empty-frame envelope ({"columns": [...], "data": []}). Dtype inference for the records form is whatever pandas decides from the JSON values — the caller is responsible for casting if a specific dtype is required. See module docstring for the documented loss cases.

• Return type: DataFrame
• Parameters: data (str)

mostlyright.core.formats.parquet_dumps(df)

Serialize a DataFrame to a parquet byte payload.

Engine: pyarrow. Compression: zstd. The full DataFrame schema — column names, dtypes (including nullable Int64, boolean, and tz-aware Timestamp), and the index unless the caller drops it — is preserved on the wire.

• Return type: bytes
• Parameters: df (DataFrame)

mostlyright.core.formats.parquet_loads(data)

Parse a parquet byte payload back into a DataFrame.

Engine: pyarrow. No decompression-bomb protection at this layer — the MCP server enforces a per-payload uncompressed-size cap (1 GB default per design doc §E) before invoking this function, and the SDK caller is trusted to pass parquet they themselves produced. Adding a size cap here would push policy into the format layer; it lives at the trust boundary instead.

• Return type: DataFrame
• Parameters: data (bytes)

mostlyright.core.formats.toon_dumps(df)

Serialize a DataFrame as a TOON v3.0 tabular string.

Iterates the DataFrame column-by-column rather than row-by-row. df.iterrows() materializes each row as a Series, which upcasts every cell to the row’s common dtype — so an int64 column with a value above 2**53 sharing a row with a float64 cell would silently lose precision (int(2**60) → float(2**60)). Column-wise iteration preserves each column’s native dtype before per-cell coercion. See module docstring for the full loss matrix.

Phase 6 W2-T6: accepts pandas OR polars input; polars frames are converted to pandas at the boundary because the byte-pinned _toon encoder body is parity-locked (CLAUDE.md) and stays pandas-only.

• Return type: str
• Parameters: df (DataFrame)

mostlyright.core.formats.toon_loads(data)

Parse a TOON v3.0 tabular string back into a DataFrame.

Accepts only the tabular form dumps produces. Other TOON constructs (nested objects, expanded lists) are not supported here — the format module’s wire shape is strictly the tabular block.

• Return type: DataFrame
• Parameters: data (str)

Modules

csv	CSV format — pandas-native serialization.
dataframe	DataFrame format — identity passthrough.
json	JSON format — records-oriented serialization via pandas.
parquet	Parquet format — Arrow-backed lossless serialization.
toon	TOON format — DataFrame ↔ TOON tabular string.